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. 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 para eliminaciones y registros archivados, y datos excluidos por diseño 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, 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 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 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.

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 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á.	—

Para saber más
Archivar y eliminar
Filmo tiene varias maneras de retirar un registro de uso, y no son intercambiables. Algunas se pueden deshacer y otras no; consulta esta página antes de llamar a una operación destructiva.
Para saber más
Datos que la API deja fuera
La API pública deja fuera a propósito los datos sensibles para el negocio: costes, márgenes, códigos de acceso, documentos fiscales internos y nóminas o datos personales del personal. Trata un campo que no está en el esquema de respuesta como no disponible.
Guías
Sincronizar datos
Filmo v1 no envía webhooks, así que mantienes otro sistema sincronizado consultando periódicamente: lee lo que cambió en ventanas de tiempo semiabiertas y ejecuta un barrido aparte para encontrar lo que se eliminó. No sigas el cursor de paginación para decidir qué cambió o qué desapareció.
Guías
Lista de comprobación de salida a producción
Repasa estas ocho comprobaciones antes de que tu integración funcione con datos de producción. Cada una remite a la guía que la explica.

¿Te ha resultado útil esta página?

Qué admite cada recurso

No disponible en la v1

Límites estrictos

Límites de la plataforma

Carencias conocidas

Páginas relacionadas

Archivar y eliminar

Datos que la API deja fuera

Sincronizar datos

Lista de comprobación de salida a producción