*API REST › Introducción*

# Resumen de la API REST

> La API REST v1 de Filmo es una API JSON sobre HTTPS en `https://app.filmo.io/api/v1`. Te autenticas con una clave de API y todas las respuestas usan el mismo sobre.

## URL base y una primera llamada

Todas las rutas de esta referencia empiezan por `/api/v1`, en el origen `https://app.filmo.io`: por ejemplo, [`GET /api/v1/orders`](https://docs.filmo.io/es/rest-api/endpoint-reference/orders/list-orders). Las peticiones y las respuestas correctas son JSON (`application/json`); los errores son `application/problem+json`.

Una buena primera llamada es [`GET /api/v1/account`](https://docs.filmo.io/es/rest-api/endpoint-reference/account/get-the-account). Necesita el scope [`account:read`](https://docs.filmo.io/es/rest-api/guides/scopes#account:read) y devuelve la cuenta, la zona horaria en la que se leen las fechas sin hora y los scopes de la clave que usaste. Para crear una clave, un administrador abre la sección API y MCP de los ajustes de la cuenta en Filmo (*Ajustes → API y MCP*); consulta [Autenticación](https://docs.filmo.io/es/rest-api/guides/authentication).

*Tu primera llamada*

**cURL**

```bash
curl -sS --fail-with-body "${FILMO_BASE_URL:-https://app.filmo.io}/api/v1/account" \
  -H "Authorization: Bearer $FILMO_API_KEY"
```

**Node**

```javascript
const base = process.env.FILMO_BASE_URL ?? "https://app.filmo.io";
const res = await fetch(base + "/api/v1/account", {
  headers: { Authorization: `Bearer ${process.env.FILMO_API_KEY}` },
});
if (!res.ok) throw new Error(res.status + " " + (await res.text()));
const { data } = await res.json();
console.log(data.name, data.timezone, data.currency);
```

**Python**

```python
import os
import requests

base = os.environ.get("FILMO_BASE_URL", "https://app.filmo.io")
res = requests.get(
    base + "/api/v1/account",
    headers={"Authorization": f"Bearer {os.environ['FILMO_API_KEY']}"},
    timeout=30,
)
res.raise_for_status()
data = res.json()["data"]
print(data["name"], data["timezone"], data["currency"])
```

Para un recorrido guiado desde una clave nueva hasta tu primera escritura, sigue la [guía rápida](https://docs.filmo.io/es/quickstart). El archivo OpenAPI y los clientes que puedes generar a partir de él se tratan en [Archivo OpenAPI y clientes generados](https://docs.filmo.io/es/rest-api/guides/openapi-and-clients); la referencia de cada operación está en la [Referencia de OpenAPI](https://docs.filmo.io/es/rest-api/openapi).

## Envoltorio de la respuesta

Cada respuesta de la API tiene una de tres formas.

| Tipo | Forma | Se usa para |
| --- | --- | --- |
| Lista | `{ "data": [ … ], "pagination": { "nextCursor", "hasMore", "total"? } }` | Colecciones como pedidos o contactos. |
| Recurso único | `{ "data": { … } }` | Lecturas de detalle, creaciones y actualizaciones. |
| Error | Un problema RFC 9457 en `application/problem+json`: `type`, `title`, `status`, `code`, `detail`, `requestId` | Cualquier 4xx o 5xx que produzca la API. |

Las respuestas de la API llevan una cabecera `X-Request-Id`, y los cuerpos de error la repiten como `requestId`. Cítala cuando contactes con soporte. Los endpoints de OAuth son la excepción: no la devuelven. Las cabeceras, el objeto `meta` adicional que devuelven algunas operaciones y los estados en uso están en [Respuestas](https://docs.filmo.io/es/rest-api/guides/responses); todos los códigos de error están en [Errores](https://docs.filmo.io/es/rest-api/guides/errors).

## Convenciones de un vistazo

| Tema | Regla |
| --- | --- |
| URL base | `https://app.filmo.io/api/v1` |
| Autenticación | `Authorization: Bearer <API key>`. Solo los administradores crean claves. |
| Dinero | Cadenas decimales con dos decimales (`"1234.50"`), nunca números de coma flotante. |
| Fechas | ISO 8601. Las escrituras toman un instante con desplazamiento; las respuestas usan UTC. |
| Paginación | Cursor opaco. Tamaño de página `limit`: 50 por defecto, 500 como máximo. |
| Límites de peticiones | 120 peticiones por minuto por clave, y 30 por minuto compartidas por las tres comprobaciones de disponibilidad. |
| Reintentos | Envía `Idempotency-Key` en las escrituras. Una clave se recuerda durante 24 horas. |
| Concurrencia | Las lecturas de detalle devuelven un `ETag`; envíalo de vuelta como `If-Match` para no sobrescribir un cambio más reciente. |
| Versionado | Cambios aditivos dentro de v1; los cambios incompatibles siguen los plazos de aviso documentados. |

- **[Autenticación](https://docs.filmo.io/es/rest-api/guides/authentication)**: Claves bearer, quién posee una clave y cómo revocarla.
- **[OAuth](https://docs.filmo.io/es/rest-api/guides/oauth)**: Cuándo usar OAuth en lugar de una clave.
- **[Permisos (scopes)](https://docs.filmo.io/es/rest-api/guides/scopes)**: Qué habilita cada permiso.
- **[Respuestas](https://docs.filmo.io/es/rest-api/guides/responses)**: Variantes del sobre, cabeceras y estados.
- **[Tipos de datos](https://docs.filmo.io/es/rest-api/guides/data-types)**: Dinero, fechas, nulls y mapas.
- **[Paginación](https://docs.filmo.io/es/rest-api/guides/pagination)**: Recorre una lista con el cursor.
- **[Filtrado y orden](https://docs.filmo.io/es/rest-api/guides/filtering-and-sorting)**: `sort`, ventanas de fechas, filtros de listas y búsqueda.
- **[Errores](https://docs.filmo.io/es/rest-api/guides/errors)**: Todos los códigos y cuándo reintentar.
- **[Límites de peticiones](https://docs.filmo.io/es/rest-api/guides/rate-limits)**: Cuotas, cabeceras y espera creciente.
- **[Idempotencia](https://docs.filmo.io/es/rest-api/guides/idempotency)**: Reintenta una escritura sin duplicarla.
- **[Concurrencia](https://docs.filmo.io/es/rest-api/guides/concurrency)**: Bloqueo optimista con `ETag` e `If-Match`.
- **[Versionado](https://docs.filmo.io/es/rest-api/guides/versioning)**: Qué cambia dentro de v1 y qué no cambia nunca.
- **[Pruebas](https://docs.filmo.io/es/rest-api/guides/testing)**: Prueba llamadas sin dañar los datos de producción.
- **[Sincronizar datos](https://docs.filmo.io/es/rest-api/guides/syncing-data)**: Mantén otro sistema al día mediante consultas periódicas.
- **[Pasar a producción](https://docs.filmo.io/es/rest-api/guides/going-live)**: La lista de comprobación antes de producción.

## Antes de empezar

- Pide a un administrador de la empresa de alquiler que cree la clave y decide quién la posee: [Autenticación](https://docs.filmo.io/es/rest-api/guides/authentication).
- Da a la clave solo los permisos que usa la integración: [Permisos (scopes)](https://docs.filmo.io/es/rest-api/guides/scopes).
- Lee qué cubre v1, y qué no cubre, en [Capacidades y límites](https://docs.filmo.io/es/further-reading/capabilities-and-limits).
- Comprueba qué add-ons tiene tu cuenta: la API y el MCP están incluidos en cualquier plan de pago y no son un add-on, pero un recurso que pertenece a un módulo con un add-on que no has contratado responde 402 [`addon_required`](https://docs.filmo.io/es/rest-api/errors/addon_required). Consulta [Planes y add-ons](https://docs.filmo.io/es/concepts/plans-and-add-ons).
- Una clave trabaja sobre los datos en vivo de la cuenta a la que pertenece. Lee [Pruebas](https://docs.filmo.io/es/rest-api/guides/testing) antes de tu primera escritura.
- Antes de pasar a producción, repasa [Pasar a producción](https://docs.filmo.io/es/rest-api/guides/going-live).

## Versionado y compatibilidad

Consulta la versión del contrato que devuelve [`GET /api/v1/account`](https://docs.filmo.io/es/rest-api/endpoint-reference/account/get-the-account) o la publicada en el archivo OpenAPI. Las reglas de compatibilidad y los plazos de aviso están documentados en [Versionado](https://docs.filmo.io/es/rest-api/guides/versioning).

## Mantener tus datos sincronizados

v1 no envía webhooks. Para mantener otro sistema sincronizado con Filmo, haz polling incremental: pide a cada lista que tenga filtros `updated*` los registros que han cambiado desde tu último recorrido. [Sincronizar datos](https://docs.filmo.io/es/rest-api/guides/syncing-data) describe un algoritmo que no se salta registros y cómo detectar eliminaciones.

## Úsalo desde un asistente de IA

Cada operación es también una herramienta MCP en `https://app.filmo.io/api/v1/mcp`, con la misma clave y los mismos permisos (scopes). Consulta la [Resumen de MCP](https://docs.filmo.io/es/mcp/overview).

---

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