*Visión general › Para saber más*

# Capacidades y límites de la v1

> La API cubre la mayor parte del trabajo diario con pedidos, contactos, artículos, facturas y la agenda, y deja una lista corta de cosas a la app. Compruébalo aquí antes de diseñar una integración en torno a una función.

Filmo es software de alquiler, y la API expone los mismos registros que ve el equipo en la app, con algunas omisiones deliberadas. Esta página tiene cuatro partes: qué admite cada recurso, qué no está disponible, los límites que debe respetar una petición y las lagunas conocidas hoy.

## Qué admite cada recurso

La referencia de endpoints lista todas las operaciones de un recurso: si puedes listarlo, leerlo, crearlo, actualizarlo y borrarlo, y qué acciones tiene (reservar, cancelar, validar, anular…). Cada operación es además una herramienta MCP con el mismo permiso (scope) y los mismos límites; consulta [la visión general del MCP](https://docs.filmo.io/es/mcp/overview). La matriz de abajo los resume para cada recurso: las operaciones de listar, leer, crear, actualizar y eliminar, el número de otras acciones y el número de herramientas MCP. Se genera a partir del documento OpenAPI, así que siempre es el contrato vigente.

| Recurso | Listar | Leer | Crear | Actualizar | Borrar | Acciones | Herramientas MCP |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Abonos | Sí | Sí | — | — | — | 2 | 4 |
| Artículos | Sí | Sí | Sí | Sí | Sí | 5 | 13 |
| Calendario | — | — | — | — | — | 1 | 1 |
| Campos personalizados | Sí | — | — | — | — | 0 | 1 |
| Colecciones | Sí | — | Sí | Sí | — | 0 | 3 |
| Contactos | Sí | Sí | Sí | Sí | Sí | 9 | 14 |
| Contratos | Sí | Sí | — | — | — | 4 | 6 |
| CRM | Sí | Sí | Sí | Sí | — | 3 | 9 |
| Cuenta | — | — | — | — | — | 1 | 1 |
| Disponibilidad | Sí | — | Sí | Sí | Sí | 1 | 5 |
| Espacios | Sí | Sí | — | Sí | Sí | 2 | 6 |
| Etiquetas | Sí | — | Sí | — | Sí | 2 | 5 |
| Facturas | Sí | Sí | — | — | — | 5 | 7 |
| Facturas de proveedor | Sí | Sí | — | — | — | 2 | 4 |
| IA | — | — | — | — | — | 1 | 1 |
| Incidencias | Sí | Sí | Sí | Sí | — | 2 | 6 |
| Kits | Sí | Sí | Sí | Sí | — | 0 | 4 |
| Notas | Sí | — | Sí | — | — | 0 | 2 |
| Órdenes de compra | Sí | Sí | — | Sí | — | 2 | 5 |
| Partes de reparación | Sí | Sí | Sí | Sí | — | 0 | 4 |
| Pedidos | Sí | Sí | Sí | Sí | — | 6 | 10 |
| Personal | Sí | Sí | Sí | Sí | Sí | 1 | 6 |
| Planificador | Sí | — | — | — | — | 2 | 4 |
| Presupuestos | Sí | Sí | — | — | — | 2 | 4 |
| Proformas | Sí | Sí | — | — | — | 1 | 3 |
| Proyectos | Sí | Sí | Sí | Sí | — | 3 | 8 |
| Servicios | Sí | Sí | Sí | Sí | — | 0 | 4 |
| Servicios internos | Sí | Sí | Sí | Sí | — | 0 | 4 |
| Subalquileres | Sí | Sí | — | Sí | — | 0 | 3 |
| Tareas | Sí | Sí | Sí | Sí | Sí | 0 | 5 |
| Tesorería | Sí | Sí | Sí | Sí | — | 1 | 8 |
| Tipos de tarea | Sí | — | — | — | — | 0 | 1 |
| Usuarios | Sí | — | — | — | — | 0 | 1 |
| Vehículos | Sí | Sí | Sí | Sí | Sí | 1 | 6 |
| Workflows | Sí | — | — | — | — | 1 | 2 |

## No disponible en la v1

Son cosas que podrías esperar de la API y que no hace. Cada fila nombra dónde lo dice la especificación y qué hacer en su lugar.

| No disponible | Donde lo indica la especificación | Qué hacer en su lugar |
| --- | --- | --- |
| Precios, descuentos, seguro, fianzas, estado, unidades serializadas y notas al crear un pedido. El pedido se crea a cero. | `POST /api/v1/orders`: «the order is born at zero and the team prices it from the application» | Completa el pedido en la app. |
| Añadir, quitar o editar las líneas de un pedido existente. | `PATCH /api/v1/orders/{orderId}`: «It does NOT add, remove or edit lines» | Usa el editor de pedidos de la app. |
| Fijar tu propia referencia en un pedido. `OrderDto` tiene un campo de referencia externa; los cuerpos de creación y actualización no. | `OrderCreateBody` y `OrderUpdateBody` comparados con `OrderDto` | Mantén tu propia tabla con tu id frente al `id` de Filmo, o pon la referencia en la app. |
| Subir archivos, por ejemplo a una incidencia. | `POST /api/v1/incidents/{incidentId}/comments`: «v1 has no file upload» | Adjunta archivos en la app. |
| PDF de facturas y otros documentos. | Ninguna operación de la especificación devuelve un PDF. | Descarga el documento desde la app. |
| Redactar una factura o editar un presupuesto. Las facturas se pueden validar o anular; los presupuestos y las proformas solo cambian de estado. | Etiqueta facturas, presupuestos y proformas; `POST /api/v1/invoices/{invoiceId}/validate`, `PATCH /api/v1/quotes/{quoteId}/status`, `PATCH /api/v1/proformas/{proformaId}/status` | Redacta en la app. Para replicar una factura emitida en otro sistema, usa `PUT /api/v1/invoices/external/{originSystem}/{originExternalId}`. |
| Webhooks. Filmo no envía webhooks: la API no envía eventos. | La especificación no declara suscripciones a eventos. | Sondea de forma incremental; consulta la guía de sincronización. |
| Leer el estado de una ejecución de workflow. Puedes iniciar una ejecución y obtener su identificador; no hay ninguna operación para leerla después. | `POST /api/v1/workflows/{workflowId}/runs`; la única otra operación de workflows es `GET /api/v1/workflows` | Comprueba el resultado en la app. |
| Un registro de eliminaciones. Las eliminaciones son definitivas y no dejan rastro, y no hay filtro para registros eliminados. | Las descripciones de las operaciones de borrado, como `DELETE /api/v1/contacts/{contactId}`: "It is NOT reversible" | Reconcilia con barridos por ventanas y confirma con un GET antes de borrar en tu lado. |
| El desglose de impuestos, las líneas y el motivo de corrección de una nota de crédito. | `GET /api/v1/credit-notes/{creditNoteId}`: «the tax breakdown, the lines and the reason for the correction are not published» | Registra la nota de crédito por sus totales y completa el desglose en la app. |
| El identificador fiscal del cliente tal como estaba cuando se emitió la factura. `InvoiceDto.contact` solo lleva `id` y `name`; el identificador fiscal actual está en el contacto. | `InvoiceDto` y `ContactDto` | Guarda el identificador fiscal en tu lado cuando recibas la factura. |
| Tipo de impuesto por línea de factura y serie de la factura. | `DocumentLineDto` e `InvoiceDto` no tienen esos campos. | Usa `taxBreakdown` del detalle de la factura para los totales por impuesto; consulta la serie en la app. |
| Leer un pedido archivado. Responde 404 y no aparece en los listados. | `PUT /api/v1/orders/{orderId}/archive`: «an archived order is no longer visible to the API (its GET responds 404)» | Restáuralo con `PUT /api/v1/orders/{orderId}/archive` y `archived: false`, usando el id que guardaste. En una sincronización, trata un 404 como "archivado o borrado". |
| Guardar tu propio id en un contacto. Los contactos no tienen un campo dedicado de referencia externa; `contactNumber` es la referencia interna de la cuenta. | `ContactCreateBody`, `ContactUpdateBody` y `ContactDto` | Puedes usar `contactNumber` (hasta 50 caracteres, no único) con `POST /api/v1/contacts/lookup`, y también mantener tu propia tabla con tu id frente al `id` del contacto de Filmo. |
| Saber quién o qué cambió un registro. Ningún objeto tiene un campo `updatedBy`, y todo lo que escribe una clave se atribuye al administrador que es su propietario. | La sección Errors de la descripción de la API ("About the person behind the key") | Guarda un hash del último estado que escribiste, para poder ignorar tus propios cambios cuando sincronices. |

Algunos de estos tienen un tratamiento más extenso en otro sitio: [sincronizar datos](https://docs.filmo.io/es/rest-api/guides/syncing-data) para eliminaciones y registros archivados, y [datos excluidos por diseño](https://docs.filmo.io/es/further-reading/excluded-data) para costes, márgenes y datos personales.

La misma lista también se genera a partir de la especificación, así que una carencia que cierra una nueva versión desaparece de ella:

| Id | Alternativa |
| --- | --- |
| Importes, estado, unidades serializadas y notas al crear un pedido | `POST /api/v1/orders` crea un borrador a cero a partir del cliente, las fechas y los artículos solicitados. Los precios, descuentos, seguros, fianzas, estado, unidades serializadas concretas, accesorios y notas los completa el equipo en la app de Filmo. Reservar el pedido con `POST /api/v1/orders/{orderId}/reserve` es posible una vez que existe. |
| Añadir, quitar o editar las líneas de un pedido | `PATCH /api/v1/orders/{orderId}` cambia solo el cliente, el proyecto y las fechas. Edita las líneas en el editor de pedidos de la app de Filmo. `GET /api/v1/orders/{orderId}/lines` las lee. |
| Establecer una referencia externa al crear un pedido | `externalReference` se devuelve en las lecturas, pero el cuerpo de `POST /api/v1/orders` no lo acepta, ni tampoco el cuerpo de `PATCH /api/v1/orders/{orderId}`. Guarda tu referencia donde la API pueda escribirla: una nota en el pedido con `POST /api/v1/notes`, o una etiqueta asignada con `POST /api/v1/tags/{tagId}/assignments`. O defínela en la app de Filmo. Los proyectos son distintos: `externalReference` es escribible. |
| Subir archivos | `POST /api/v1/incidents/{incidentId}/comments` admite solo texto porque v1 no tiene subida de archivos. Adjunta los archivos en la app de Filmo. |
| PDF de facturas y otros documentos | Ninguna operación devuelve un PDF ni ningún otro archivo: todas las respuestas son `application/json`. Lee los datos del documento con `GET /api/v1/invoices/{invoiceId}` o `GET /api/v1/quotes/{quoteId}` y genéralo tú, o descarga el PDF desde la app de Filmo. |
| Componer borradores de factura y editar presupuestos | Las facturas se pueden validar (`POST /api/v1/invoices/{invoiceId}/validate`), anular (`POST /api/v1/invoices/{invoiceId}/void`) o reflejar desde un ERP (`PUT /api/v1/invoices/external/{originSystem}/{originExternalId}`); los presupuestos y las proformas solo cambian de estado (`PATCH /api/v1/quotes/{quoteId}/status`, `PATCH /api/v1/proformas/{proformaId}/status`). Compón y edita los borradores en la app de Filmo. |
| Eventos enviados a tu servidor (Filmo no envía webhooks) |  |
| Leer el estado de una ejecución de un workflow | `POST /api/v1/workflows/{workflowId}/runs` devuelve el identificador de la ejecución y el estado con el que nace (`queued`) y no espera a que termine. La API no tiene ninguna operación que lea una ejecución después. Comprueba el resultado en la app de Filmo, o a partir de los datos que cambia el workflow. |
| Un historial de registros eliminados |  |
| Desglose de impuestos, líneas y motivo de una nota de crédito | `GET /api/v1/credit-notes/{creditNoteId}` indica que el documento fiscal firmado, el desglose de impuestos, las líneas y el motivo de la corrección no se publican; `netPrice` y los demás totales sí. Registra la nota de crédito por sus totales y completa el desglose desde la app de Filmo. |
| El identificador fiscal del cliente en el momento de emitir una factura | `contact` contiene solo el `id` y el `name` del cliente. El identificador fiscal existe únicamente como el `nif` actual, que puede cambiar después de la factura. Guarda el identificador fiscal por tu lado la primera vez que recibas la factura. |
| Tipo de impuesto por línea y serie de una factura | Las líneas de `GET /api/v1/invoices/{invoiceId}/lines` y `GET /api/v1/quotes/{quoteId}/lines` no llevan tipo de impuesto, y ningún esquema de factura tiene un campo de serie. Los impuestos de una factura están en `taxBreakdown`, por tipo de impuesto para todo el documento. Lee la serie desde la app de Filmo. |
| Leer pedidos archivados | Un pedido archivado no es visible para la API: su GET responde 404, igual que uno eliminado, ninguna lista lo incluye y `PATCH /api/v1/orders/{orderId}` lo rechaza. Para recuperar un pedido, llama a `PUT /api/v1/orders/{orderId}/archive` con `archived: false` (responde 204, y el pedido vuelve a ser legible con su GET), o restáuralo en la app de Filmo. En una sincronización, trata un 404 sobre un pedido que tienes como archivado o eliminado, y no lo borres por tu lado sin confirmarlo. |
| Un identificador externo propio en un contacto | Los contactos no tienen un campo dedicado de identificador externo. `contactNumber` se puede escribir en `POST /api/v1/contacts` y `PATCH /api/v1/contacts/{contactId}`, pero no es único y Filmo no lo genera. Si lo usas como clave, acuerda un prefijo, comprueba si hay duplicados antes de escribir y trata más de una coincidencia en `POST /api/v1/contacts/lookup` como un conflicto que hay que resolver. O bien mantén en tu lado una tabla que relacione tu identificador con el `id` del contacto de Filmo. |
| Saber quién o qué hizo un cambio |  |

## Límites estrictos

El esquema de cada petición fija tamaños máximos. Una petición que supera un límite se rechaza con [`validation_error`](https://docs.filmo.io/es/rest-api/errors/validation_error), y `errors[]` nombra el campo que lo incumple. La tabla de abajo se genera a partir de la especificación, así que siempre está al día.

| Dónde | Límite | Valor |
| --- | --- | --- |
| `limit` | maximum | 500 |
| `cursor` | maxLength | 200 |
| `sort` | maxLength | 200 |
| `ContactUpdateBody.emails` | maxItems | 20 |
| `ContactUpdateBody.phoneNumbers` | maxItems | 20 |
| `ContactUpdateBody.websites` | maxItems | 20 |
| `ContactUpdateBody.addresses` | maxItems | 20 |
| `stockTypes` | maxItems | 50 |
| `collectionIds` | maxItems | 50 |
| `ItemCreateBody.tags` | maxItems | 50 |
| `ItemUpdateBody.tags` | maxItems | 50 |
| `AvailabilityCheckBody.items` | maxItems | 100 |
| `statuses` | maxItems | 50 |
| `contactIds` | maxItems | 50 |
| `projectIds` | maxItems | 50 |
| `OrderCreateBody.lines` | maxItems | 100 |
| `paymentStatuses` | maxItems | 50 |
| `orderIds` | maxItems | 50 |
| `operativeStatuses` | maxItems | 50 |
| `itemIds` | maxItems | 50 |
| `spaceIds` | maxItems | 50 |
| `inventoryTypes` | maxItems | 50 |
| `VehicleCreateBody.tags` | maxItems | 50 |
| `staffTypes` | maxItems | 50 |
| `StaffMemberCreateBody.tags` | maxItems | 50 |
| `types` | maxItems | 50 |
| `supplierIds` | maxItems | 50 |
| `StaffAvailabilityBody.tags` | maxItems | 50 |
| `StaffAvailabilityBody.staffIds` | maxItems | 100 |
| `VehicleAvailabilityBody.tags` | maxItems | 50 |
| `VehicleAvailabilityBody.vehicleIds` | maxItems | 100 |
| `tagIds` | maxItems | 50 |
| `entityTypes` | maxItems | 50 |
| `ServiceCreateBody.tags` | maxItems | 50 |
| `ServiceCreateBody.requirements` | maxItems | 20 |
| `ServiceCreateBody.requirements[].requiredTags` | maxItems | 20 |
| `ServiceUpdateBody.requirements[].requiredTags` | maxItems | 20 |
| `layers` | maxItems | 50 |
| `projectStatus` | maxItems | 50 |
| `orderStatus` | maxItems | 50 |
| `assignedToStaffIds` | maxItems | 200 |
| `scopes` | maxItems | 50 |
| `priorities` | maxItems | 50 |
| `severities` | maxItems | 50 |
| `assignedStaffIds` | maxItems | 50 |
| `relatedDocumentIds` | maxItems | 50 |
| `TaskCreateBody.assignedStaffIds` | maxItems | 50 |
| `TaskUpdateBody.assignedStaffIds` | maxItems | 50 |
| `invoiceIds` | maxItems | 50 |
| `ContactsLookupBody.references` | maxItems | 200 |
| `OrderLineItemsReturnBody.items` | maxItems | 500 |
| `triggerTypes` | maxItems | 50 |
| `InvoiceExternalUpsertBody.lines` | maxItems | 500 |

- Las listas que paginan devuelven como máximo 500 registros por página (`limit`, por defecto 50). `cursor` y `sort` aceptan como máximo 200 caracteres. Unas pocas listas pequeñas no tienen paginación y lo devuelven todo en una respuesta: comprueba si la operación tiene un parámetro `cursor`.
- Una pregunta a [`POST /api/v1/ai/ask`](https://docs.filmo.io/es/rest-api/endpoint-reference/ai/ask-the-ai-about-your-data) tiene como máximo 4000 caracteres, y el único modo hoy es una sola pasada: no hay conversación que continuar.
- Una actualización de contacto acepta como máximo 20 direcciones, 20 correos electrónicos, 20 teléfonos y 20 sitios web.
- Crear un pedido admite como máximo 100 líneas, y una comprobación de disponibilidad como máximo 100 artículos. Comprobar la disponibilidad de personal o vehículos admite como máximo 100 identificadores.
- Una búsqueda de contactos acepta como máximo 200 referencias.
- Una devolución por líneas y una factura externa aceptan como máximo 500 líneas cada una.
- Los filtros de listado que aceptan varios valores, como `statuses`, admiten hasta 50; [`assignedToStaffIds`](https://docs.filmo.io/es/rest-api/endpoint-reference/schedule/get-the-schedule-for-a-range#param-assignedToStaffIds) admite hasta 200.

Los límites de peticiones son otro asunto: 120 peticiones por minuto y clave, y 30 por minuto compartidas por las tres consultas de disponibilidad. Consulta [límites de peticiones](https://docs.filmo.io/es/rest-api/guides/rate-limits).

## Límites de la plataforma

Filmo ejecuta la API en una plataforma de alojamiento, y la plataforma limita lo grande que puede ser una petición o una respuesta y cuánto puede durar una llamada. Filmo no publica los límites de tamaño como parte del contrato, y salvo en una operación tampoco documenta ningún límite de duración, así que no diseñes en torno a un tamaño o una duración concretos.

- Mantén las peticiones pequeñas. Envía los cambios grandes como varias escrituras, cada una con su propia `Idempotency-Key`.
- Mantén las páginas en un tamaño que hayas medido. Una página de 500 registros de un objeto grande es una respuesta grande; si ves fallos, reduce `limit`.
- Por REST, [`POST /api/v1/ai/ask`](https://docs.filmo.io/es/rest-api/endpoint-reference/ai/ask-the-ai-about-your-data) puede tardar hasta 300 segundos y puede llevar decenas de segundos en preguntas que encadenan varias consultas. Permite un timeout de cliente largo, por encima de 300 segundos, y no reintentes antes de que venza. Por MCP, no des por hecho el mismo margen. Para el resto de operaciones no hay un límite de duración documentado: fija tus propios timeouts y gestiona un 504.
- La propia plataforma genera las respuestas 413, 502 y 504; nunca son `application/problem+json` y no tienen `code`. Ramifica según el estado HTTP, no según el cuerpo. Un 502 o un 504 en una escritura no te dice si la escritura se llevó a cabo: reinténtala con la misma `Idempotency-Key`.

## Carencias conocidas

Esta tabla recoge las limitaciones documentadas y la información o funcionalidad necesaria para resolver cada una. Las entradas se retiran cuando se resuelven.

| Hueco | Qué lo cerraría | Previsto |
| --- | --- | --- |
| Códigos de campo de los errores de validación | Los códigos de `errors[].code` de un `validation_error` no son una lista cerrada; hasta que el contrato la cierre, trata un código que no conozcas como un fallo de validación genérico. | — |
| Semántica de sincronización | Si un cambio en líneas, cobros o estado actualiza el `updatedAt` del padre, el retraso entre escribirlo y confirmarlo, la precisión del filtro, qué hace archivar o restaurar con `updatedAt` y una lápida o `deletedSince`; hasta entonces las guías recomiendan la opción conservadora. | — |
| El contrato de OAuth | Si el contrato OAuth ganará vinculación de audiencia (`resource`), un endpoint de revocación (RFC 7009) y clientes confidenciales. Hoy un token no tiene audiencia, no hay endpoint de revocación (el administrador revoca la conexión en los ajustes) y todos los clientes son públicos; las páginas de OAuth lo describen tal como funciona. | — |
| Límites de la plataforma | Los límites de la plataforma sobre el tamaño de una petición y de una respuesta, y sobre la duración de una llamada, que Filmo documenta solo para `askAi`; hasta entonces las páginas lo dicen y aconsejan peticiones pequeñas y páginas que hayas medido. | — |
| Clave externa de contactos y pedidos | El campo con el que compara `POST /contacts/lookup`, una referencia externa escribible en contactos y pedidos y, opcionalmente, un campo de origen del cambio; hasta entonces las guías emparejan por `email` o `contactNumber` y llevan una tabla de correspondencias. | — |
| Eventos que disparan las escrituras por la API | La correspondencia exacta entre cada endpoint y sus eventos de workflows, si una petición podrá suprimirlos alguna vez y la protección contra bucles de un workflow que llama a la API con una clave. Se sabe por el código que las escrituras por la API REST y por MCP lanzan los mismos eventos que la app, con `origin` igual a API o MCP; el trigger de un workflow puede filtrar por origen, pero una petición no puede suprimir eventos; y una cadena de workflows se corta a los diez saltos. Las páginas dicen lo que se sabe y marcan el resto como inferencia. | — |
| Integradores de muchas cuentas | Cuentas de socio o de desarrollo, y el proceso para aparecer en /integrations; hasta entonces la página es reducida. | — |
| Datos fiscales para la contabilidad | `taxBreakdown`, líneas y motivo de los abonos, una instantánea fiscal de la factura y el tipo de impuesto por línea; hasta entonces figuran en «No disponible en v1». | — |
| Requisitos de clientes MCP que el proveedor no documenta | La documentación de cada proveedor (planes, límites de herramientas, ajustes de organización); las páginas dicen «no documentado por el proveedor» donde no lo está. | — |

---

URL canónica: https://docs.filmo.io/es/further-reading/capabilities-and-limits  
Última actualización: 2026-10-09