Integraciones con varias cuentas

Esta guía es para equipos que construyen un producto, como un CRM, un paquete de contabilidad, un sitio de reservas o una herramienta de inventario, que se conecta a muchas empresas de alquiler. Ese es el caso para el que se diseñó la API: las integraciones de terceros. Si integras con la cuenta de una sola empresa, bastan el inicio rápido y la guía de sincronización.

Una credencial pertenece a una suscripción de Filmo, así que una misma credencial nunca puede servir a dos clientes. Puedes obtenerla de dos maneras.

El token que emite OAuth es una clave de API de corta duración que funciona en toda la API REST y en MCP, y viaja igual, como token Bearer. Un servidor de terceros puede usarlo hoy: se registra como cliente público, lleva al administrador por el flujo de código de autorización con PKCE e intercambia el código por tokens. OAuth es viable ya, y una clave es más sencilla cuando no hay ninguna persona delante del flujo. Consulta OAuth para ver el flujo.

• No hay concesión client_credentials, ni cliente confidencial, ni secreto de cliente. Tu cliente es público: se registra de forma dinámica y se autentica solo con PKCE.
• Cada conexión necesita el consentimiento de un administrador de esa cuenta. No puedes conectar una cuenta sin uno.
• Una autorización cubre una suscripción, que el administrador elige mientras da su consentimiento, y los scopes concedidos pueden diferir de los que solicitaste (menos, o adicionales que el administrador marcó). Un cliente con varias cuentas de facturación necesita una autorización, o una clave, para cada una de ellas.
• Una suscripción puede tener 50 claves sin revocar (las caducadas cuentan, y también las conexiones OAuth); el límite impide crear una clave nueva a mano.

Sigue recomendando una clave o una conexión por cliente, y no compartas nunca una credencial entre dos cuentas o dos entornos.

La primera llamada de cualquier integración es GET /api/v1/account, con el scope account:read. Hazla cuando un cliente se conecte y conserva lo que devuelve.

Lo que una credencial puede ver depende de cómo modela Filmo cada recurso (Cuentas y aislamiento). Hay dos reglas que importan para una integración.

Nada se amplía entre cuentas de facturación hermanas, ni de una cuenta principal a sus cuentas de facturación, y ninguna operación cruza datos entre organizaciones. Así que, para leer los pedidos y las facturas de todas las cuentas de facturación de una organización, conecta cada una de ellas. Al combinar sus datos, deduplica los recursos heredados por id: el mismo contacto aparece a través de cada cuenta de facturación que lo hereda.

Cada clave tiene 120 peticiones por minuto, y las tres consultas de disponibilidad comparten otras 30 por minuto en la misma clave. Los límites son los mismos para todos los planes (Límites de peticiones). Una credencial es la unidad del límite, así que da a cada cliente su propia cola, lee RateLimit-Remaining y RateLimit-Reset para dosificarla y espera Retry-After segundos tras un 429. Los workers que atienden al mismo cliente comparten un único presupuesto.

OAuth tiene sus propios límites, contados por dirección IP y no por credencial. Registrar un cliente permite 5 peticiones por minuto por IP, y el endpoint de tokens 120 por minuto por IP, así que las renovaciones de todos tus clientes comparten ese presupuesto cuando salen del mismo servidor. Un 429 de un endpoint de OAuth lleva Retry-After: espera ese tiempo, y decide por el estado y la cabecera, no por el cuerpo, porque el cuerpo no siempre nombra el límite.

Esta sección se aplica si usas conexiones OAuth. Con claves de API no hay nada que refrescar.

El token de acceso caduca en 1 hora y el token de refresco rota en cada uso: cada intercambio devuelve un token de refresco nuevo, y el token de acceso anterior deja de funcionar al instante. Si un worker presenta un token de refresco que ya rotó, Filmo responde con el mismo par cuando la petición viene del mismo cliente en los 10 segundos posteriores a la rotación. Pasada esa ventana, reutilizarlo revoca toda la cadena, el token de acceso y todos los tokens de refresco, y responde invalid_grant. Entonces el cliente tiene que dar su consentimiento de nuevo. Dos workers que refrescan en el mismo momento suelen recibir el mismo par, pero un worker que llega pasados más de 10 segundos destruye la conexión para todos, así que serializa el refresco de todos modos.

Los endpoints de OAuth responden en el formato plano de OAuth, { "error", "error_description" }, no en el formato de problema del resto de la API. El error_description está en español: decide por error y muestra tu propio texto.

1. 1

   Serializar la renovación por cliente

   Toma un bloqueo para la conexión de ese cliente durante todo el refresco: un bloqueo de fila en la base de datos, un bloqueo consultivo o un bloqueo con caducidad en un almacén compartido. No refresques nunca fuera de él.

2. 2

   Lee los tokens guardados después de obtener el bloqueo

   Puede que otro worker haya renovado mientras esperabas. Si el token de acceso guardado sigue siendo válido, úsalo y libera el bloqueo.

3. 3

   Renueva con el refresh token guardado

   Llama a POST /api/v1/oauth/token con grant_type=refresh_token, el refresh_token y tu client_id. La respuesta trae un nuevo refresh_token, válido otros 30 días.

4. 4

   Guarda los dos tokens nuevos antes que nada

   Escribe el nuevo token de acceso y el nuevo token de refresco en el almacenamiento antes de usar el token de acceso y antes de liberar el bloqueo. Si pierdes el nuevo token de refresco, la conexión se pierde.

5. 5

   Renueva antes de que caduque, no al recibir un 401

   Renueva unos minutos antes de que se cumpla la hora, para que los hilos de petición rara vez compitan por el bloqueo.

Trata invalid_grant como definitivo: el refresh token ha caducado, se ha revocado o ya se usó, o el administrador que dio el consentimiento ya no es administrador. No lo reintentes. Marca la conexión como que necesita atención y pide al administrador del cliente que vuelva a dar su consentimiento.

Trata cada fallo como el estado de una conexión: deja de llamar con esa credencial, conserva las marcas de agua, avisa al administrador del cliente y reanuda cuando se reconecte. No reintentes en bucle.

Entrega esta lista al administrador que conecta tu producto. Rellena los scopes según tus propias necesidades y no pidas más.

1. 1

   Elige un propietario dedicado

   Una clave actúa como el administrador que la crea, y lo que escribe se atribuye a esa persona. Depende de ese administrador, que ya tiene un puesto en la cuenta, y deja de funcionar si esa persona se va o deja de ser administradora. Créala desde una cuenta de administrador que vaya a durar, no desde una persona que pueda marcharse.

2. 2

   Abrir los ajustes de API y MCP

   En la app es Ajustes → API y MCP. Solo los administradores pueden crear claves.

3. 3

   Crear una clave para la integración

   Ponle el nombre de tu producto y dale solo los permisos que enumeres, por ejemplo account:read más los permisos de lectura y escritura de los recursos que sincronices. Los permisos (scopes) están en la referencia de scopes.

4. 4

   Entrégala una sola vez, por un canal seguro

   La clave se muestra una sola vez. Recíbela en tu formulario de incorporación o en un gestor de secretos compartido, nunca por email ni por chat.

5. 5

   Explicar la revocación

   Revocar la clave en esos mismos ajustes corta el acceso al instante. Cuéntale al administrador qué deja de funcionar cuando lo haga y qué hacer si la persona propietaria de la clave se va.

Filmo no ofrece sandbox ni clave de prueba, y esta guía no describe ningún tipo de cuenta de partner o de desarrollador. Desarrolla y ejecuta tus pruebas contra una cuenta de Filmo aparte que tenga datos ficticios (contactos en example.com, nombres de artículo inventados), con su propia clave guardada separada de la de cualquier cliente. Una prueba gratuita de 14 días, sin tarjeta, puede servir para eso. Nunca desarrolles contra la cuenta de un cliente. Las escrituras disparan los workflows de eventos de la cuenta, así que comprueba cuáles están activos antes de escribir; consulta Pruebas y la guía de sincronización.

Si estás creando un producto para muchos clientes de Filmo y quieres hablar con Filmo al respecto, consulta Soporte.