*API REST › Guías*

# Archivo OpenAPI y clientes generados

> Filmo publica toda su API como un archivo OpenAPI 3.1. Úsalo para generar un cliente tipado, para importar la API en Postman, Insomnia o Bruno, o para ejecutar un servidor mock en tu máquina.

## Descargar el archivo

- JSON: `https://docs.filmo.io/openapi.json`
- YAML: `https://docs.filmo.io/openapi.yaml`

Ambos ficheros describen el mismo contrato. La versión y la fecha de la instantánea con la que se construye esta documentación figuran en la [Referencia de OpenAPI](https://docs.filmo.io/es/rest-api/openapi) junto con un índice de todos los esquemas. La política de compatibilidad se describe en [Versionado](https://docs.filmo.io/es/rest-api/guides/versioning). Sea cual sea el servidor que elija tu herramienta, envía las peticiones a `https://app.filmo.io`.

## Qué contiene el archivo

- Es OpenAPI 3.1. Un valor anulable se escribe como `type: ["string", "null"]`, y las uniones usan `anyOf`. Las herramientas que solo entienden 3.0 interpretan mal ambos.
- Cada operación tiene un `operationId` estable, el nombre que usan los documentos ([`GET /api/v1/orders`](https://docs.filmo.io/es/rest-api/endpoint-reference/orders/list-orders), [`POST /api/v1/orders`](https://docs.filmo.io/es/rest-api/endpoint-reference/orders/create-an-order)).
- Los nombres de esquema terminan en `Dto` para lo que devuelve la API y en `Body` para lo que envías (`OrderUpdateBody`). Los clientes generados los exponen como nombres de tipo.
- El dinero es una cadena decimal como `"1234.50"`, nunca un número flotante. Guárdalo como cadena o como tipo decimal en tu cliente.
- Cada operación indica su permiso (scope) en `x-required-scope` y sus cuotas en `x-rateLimit`.

## Generar un cliente

### Tipos de TypeScript con openapi-typescript

```bash
npx openapi-typescript https://docs.filmo.io/openapi.json -o filmo.d.ts
```

Combina los tipos con un pequeño envoltorio de fetch como openapi-fetch. Las claves de ruta incluyen el prefijo `/api/v1`.

*client.ts*

```typescript
import createClient from "openapi-fetch";
import type { paths } from "./filmo";

const client = createClient<paths>({
  baseUrl: process.env.FILMO_BASE_URL ?? "https://app.filmo.io",
  headers: { Authorization: `Bearer ${process.env.FILMO_API_KEY}` },
});

const { data, error } = await client.GET("/api/v1/account");
if (error) throw new Error(error.code);
console.log(data.data.name);
```

### Otros lenguajes con openapi-generator

OpenAPI Generator cubre `typescript-fetch`, `python`, `csharp`, `java`, `php` y `go`, entre otros. Fija la ruta base en `https://app.filmo.io` en la configuración generada y envía la clave como token bearer.

```bash
npx @openapitools/openapi-generator-cli generate \
  -i https://docs.filmo.io/openapi.json \
  -g typescript-fetch \
  -o ./filmo-client
```

### Python con openapi-python-client

```bash
openapi-python-client generate --url https://docs.filmo.io/openapi.json
```

Las respuestas de disponibilidad son uniones: cada entrada es uno de varios esquemas con nombre (un resultado, o una entrada que indica que no se encontró el artículo o el recurso). Los generadores difieren en cómo manejan `anyOf`, así que genera el cliente y prueba las operaciones de disponibilidad antes de fiarte de ellas. El estado de cada generador, con la versión probada y los problemas conocidos, está en la tabla de Generadores que probamos.

## Generadores que probamos

Filmo ejecuta generadores contra el archivo. Para cada herramienta, la tabla indica la versión probada, las opciones usadas, el resultado y los problemas conocidos.

| Herramienta | Versión | Fecha | Opciones | Resultado | Problemas conocidos |
| --- | --- | --- | --- | --- | --- |
| openapi-typescript | 7.13.0 | 2026-10-09 | valores por defecto (`openapi-typescript <spec> -o schema.ts`) | Genera y compila | — |
| openapi-python-client | 0.29.1 | 2026-10-09 | valores por defecto (`generate --path <spec>`) | Genera y compila | — |
| openapi-generator (typescript-fetch) | 7.17.0 | 2026-10-09 | `-g typescript-fetch` | Genera y compila | — |
| openapi-generator (python) | 7.17.0 | 2026-10-09 | `-g python` | Genera y compila | Compila, con un SyntaxWarning (secuencia de escape no válida `\&`) en `setup.py`: el generador pega `info.description` en un literal de cadena. |
| openapi-generator (csharp) | 7.17.0 | 2026-10-09 | `-g csharp` | Genera; no se compiló (no hay dotnet en el entorno de verificación) | No se compiló: no hay dotnet en el entorno de verificación. |
| openapi-generator (java) | 7.17.0 | 2026-10-09 | `-g java` (biblioteca okhttp-gson por defecto) | Genera y compila | — |
| openapi-generator (java, native) | 7.17.0 | 2026-10-09 | `-g java --library native` | Genera y compila | — |
| openapi-generator (php) | 7.17.0 | 2026-10-09 | `-g php` | Genera y pasa `php -l` | — |
| openapi-generator (go) | 7.17.0 | 2026-10-09 | `-g go` | Genera y compila | — |

## Impórtalo en Postman, Insomnia o Bruno

1. **Importar por enlace** En el diálogo de importación de tu herramienta, elige la opción de importar desde un enlace o URL y pega `https://docs.filmo.io/openapi.json`. Importar el archivo descargado también funciona.
2. **Definir la URL base** Comprueba el servidor que ha elegido el importador y ponlo en `https://app.filmo.io`.
3. **Añade la clave** Elige la autenticación con bearer token y guarda la clave como variable secreta o valor de entorno, nunca en la propia colección.
4. **Haz tu primera llamada** Ejecuta [`GET /api/v1/account`](https://docs.filmo.io/es/rest-api/endpoint-reference/account/get-the-account) para confirmar la clave y ver sus permisos (scopes).

Si un importador muestra tipos extraños, la causa suele ser la notación `type: [..., "null"]` o `anyOf`. La petición sigue funcionando.

## Haz tolerantes los clientes generados

- Enums cerrados: un nuevo estado o tipo puede llegar dentro de v1 como cambio aditivo. Si tu generador puede asignar los valores de enum desconocidos a un valor de reserva, actívalo; si no, envuelve el análisis de la respuesta para que un solo valor desconocido no haga fallar toda la llamada.
- Validación estricta de la respuesta: no rechaces las propiedades desconocidas.
- Regenera a propósito. Lee antes el changelog, luego regenera y revisa el diff del código generado.

## Simular la API en local con Prism

Prism sirve una API falsa a partir del archivo OpenAPI. Úsalo para ejercitar tu análisis, tu gestión de errores y tus rutas de escritura sin tocar datos reales.

```bash
npm install --global @stoplight/prism-cli
prism mock -d https://docs.filmo.io/openapi.json

# In another terminal. Prism listens on port 4010 by default.
curl -s http://127.0.0.1:4010/api/v1/account -H "Authorization: Bearer $FILMO_API_KEY"
```

Un mock devuelve datos generados. Los campos decimales vuelven como cadenas de relleno, como `"string"`, no como importes del estilo `"1234.50"`, y el mock no guarda nada, así que no puede mostrar repeticiones idempotentes, cambios de ETag ni los límites de peticiones reales. Para eso, sigue la guía de pruebas.

Más sobre formas seguras de probar: [Pruebas](https://docs.filmo.io/es/rest-api/guides/testing).

---

URL canónica: https://docs.filmo.io/es/rest-api/guides/openapi-and-clients  
Última actualización: 2026-10-09