Respuestas

Una lista devuelve sus registros en data y el estado de paginación en pagination. nextCursor es null en la última página. total aparece solo cuando lo pides con includeTotal.

{
  "data": [
    {
      "id": "5e8d1a9c",
      "orderNumber": "ORD-0412",
      "status": "reserved",
      "startDate": "2026-10-17T08:00:00.000Z",
      "endDate": "2026-10-19T17:00:00.000Z",
      "contact": { "id": "c71f40b2", "name": "Acme Rentals" },
      "grossPrice": "1234.50"
    }
  ],
  "pagination": { "nextCursor": "opaque-cursor", "hasMore": true }
}

Una lectura de detalle, una creación y una actualización devuelven el recurso en data. Las operaciones que crean un recurso responden 201; las lecturas y las actualizaciones responden 200.

Unas pocas operaciones también te informan, en meta, de lo que la llamada hizo en otros registros. POST /api/v1/orders/{orderId}/reserve informa meta.tasksCreated, las tareas de entrega y devolución que creó la reserva; POST /api/v1/orders/{orderId}/cancel informa meta.tasksDeleted. Ambas devuelven el pedido completo en data.

La mayoría de los borrados y las dos operaciones de archivado (PUT /api/v1/orders/{orderId}/archive y PUT /api/v1/projects/{projectId}/archive) responden 204 sin cuerpo. Cuatro borrados responden 200 y devuelven en su lugar el registro que han cambiado: DELETE /api/v1/contacts/{contactId}/addresses/{addressId} y DELETE /api/v1/contacts/{contactId}/related-contacts/{relatedContactId} devuelven el contacto, DELETE /api/v1/tags/{tagId}/assignments devuelve el resultado de la desasignación y DELETE /api/v1/projects/{projectId}/orders/{orderId} devuelve el proyecto. Una lectura condicional cuyo ETag está vigente responde 304, también sin cuerpo.

POST /api/v1/orders/line-items/returns es un lote. Responde 200 con un resultado por elemento, en el orden de la petición. Con atomic: false responde 207 y cada elemento lleva su propio status y error. Consulta la tabla de reintentos en Errores.

Los errores son application/problem+json y llevan type, title, status, code, detail y requestId, además de errors, requiredScope, requiredAddon o retryAfter cuando corresponden. Se describen en Errores.

Estas cabeceras provienen del documento OpenAPI, más la estándar Date.

Las cabeceras de cuota se explican en Límites de peticiones, Idempotent-Replay en Idempotencia y ETag en Concurrencia.

Las lecturas de detalle devuelven un ETag. Envía el que ya tienes en If-None-Match: si sigue vigente, la respuesta es 304 sin cuerpo y con la cabecera ETag, y tu copia está al día. Si el recurso cambió, recibes el 200 completo con un ETag nuevo.

# First read: note the ETag header.
curl -sS -D - -o /dev/null "https://app.filmo.io/api/v1/account" \
  -H "Authorization: Bearer $FILMO_API_KEY"

# Later: ask only for a newer version (paste the ETag you received, quotes included).
curl -sS -i "https://app.filmo.io/api/v1/account" \
  -H "Authorization: Bearer $FILMO_API_KEY" \
  -H 'If-None-Match: "<the ETag you received>"'

Una operación marcada como obsoleta lleva las cabeceras Deprecation y Sunset, y cada cuerpo JSON que devuelve lleva meta.warnings[] con una entrada cuyo code es deprecated. Registra esos avisos y configura alertas sobre ellos: el día de la retirada es al menos seis meses posterior a la entrada en vigor de la obsolescencia. Más adelante pueden añadirse entradas con otros códigos; ignora las que no conozcas.

{ "data": { "id": "5e8d1a9c" }, "meta": { "warnings": [{ "code": "deprecated" }] } }

Dentro de v1, Filmo añade propiedades a las respuestas y valores a las uniones, como los estados, sin previo aviso. Ignora las propiedades que no uses, trata un valor de enum desconocido como desconocido y no como un error, y no valides las respuestas con un esquema que rechace propiedades adicionales. Los clientes generados con enums cerrados se rompen con los cambios aditivos: consulta Versionado.