*API REST › Guías*

# Integraciones con varias cuentas

> Da a cada cuenta de cliente su propia credencial, guárdala con la zona horaria y la moneda de esa cuenta, y trata una credencial que falla como el estado de una conexión, no de todo tu producto. OAuth está disponible para un servidor que ejecutes tú, y las claves de API son más sencillas para el trabajo entre servidores.

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 por cuenta de cliente

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.

|  | Clave de API | Conexión OAuth |
| --- | --- | --- |
| Quién la crea | Un administrador del cliente, en los ajustes de API y MCP de la app (Ajustes → API y MCP). | Un administrador del cliente, en la pantalla de consentimiento. Ahí es donde se elige la suscripción. Solo los permisos de lectura empiezan seleccionados; los permisos de escritura, `workflows:run` y `ai:ask` empiezan sin seleccionar aunque los pidas, y el administrador activa los que acepta. |
| Vida útil | Hasta que se revoca, o hasta la caducidad que fijaste al crearla. Por defecto no caduca. | El token de acceso dura 1 hora. El token de refresco dura 30 días, que se vuelven a contar en cada rotación, así que una conexión que se refresca al menos cada 30 días sigue viva. |
| Permisos | Los scopes elegidos al crearla. | Los scopes realmente concedidos, que pueden diferir de los solicitados (menos, o extras que el administrador marcó). |
| Revocación | En los mismos ajustes (Ajustes → API y MCP). Deja de funcionar al instante. | La misma pantalla, donde aparece como una única integración conectada. El token de acceso deja de funcionar al instante y el token de refresco ya no se puede canjear. |
| Idoneidad | Lo más sencillo para integraciones de servidor a servidor: un secreto por cliente, sin nada que renovar. | Funciona para REST desde tu servidor, al precio de un ciclo de renovación y del consentimiento de un administrador de cada cuenta. |

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](https://docs.filmo.io/es/rest-api/guides/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.

## Qué guardar de cada cliente

La primera llamada de cualquier integración es [`GET /api/v1/account`](https://docs.filmo.io/es/rest-api/endpoint-reference/account/get-the-account), con el scope [`account:read`](https://docs.filmo.io/es/rest-api/guides/scopes#account:read). Hazla cuando un cliente se conecte y conserva lo que devuelve.

| Guardar | Por qué |
| --- | --- |
| La credencial, cifrada | Una clave, o los tokens de acceso y de refresco de una conexión OAuth. Solo se muestra una vez. |
| `timezone` | Las fechas sin hora de los filtros se leen en esta zona horaria, y la necesitas para mostrar las horas a las personas como las ve el cliente. |
| `currency` | La moneda de la cuenta. Un documento puede llevar la suya. |
| `apiKey` | El id, el nombre y los scopes concedidos de la clave. Compara los scopes con los que necesitas siempre que una llamada responda 403. |
| `addons` | Un recurso detrás de un add-on que no figura en la lista responde 402. |
| El estado de la conexión | Activa, o requiere atención, con la hora de la última llamada correcta y el último `X-Request-Id` que viste. |
| Una marca de agua por lista | Consulta la guía de sincronización. Las marcas de agua pertenecen al cliente, no a tu producto. |

## Aislamiento entre las cuentas de un cliente

Lo que una credencial puede ver depende de cómo modela Filmo cada recurso ([Cuentas y aislamiento](https://docs.filmo.io/es/concepts/accounts-and-tenancy)). Hay dos reglas que importan para una integración.

| Semántica | Recursos | Qué ve la credencial |
| --- | --- | --- |
| Heredado de la cuenta principal | Contactos, proyectos, etiquetas y campos personalizados, y la lectura de un pedido por id. | Una cuenta de facturación también ve estos recursos de su cuenta principal. Una cuenta completa, o una suscripción fuera de cualquier organización, ve los suyos. |
| Igualdad estricta de suscripción | Todo lo demás, incluidos artículos, espacios, facturas, presupuestos, tareas, vehículos, personal, subalquileres, órdenes de compra, contratos, la lista de pedidos y la disponibilidad. | Exactamente la suscripción a la que pertenece la credencial. |

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.

## Presupuesto de peticiones

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](https://docs.filmo.io/es/rest-api/guides/rate-limits)). 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.

## OAuth: renovar sin romper la conexión

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. **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. **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. **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. **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. **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.

## Cuando la conexión de un cliente deja de funcionar

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.

| Respuesta | Significado | Qué hacer |
| --- | --- | --- |
| 401 `api_key_invalid`, `api_key_revoked`, `api_key_expired` | La clave no se reconoce (una clave copiada mal o truncada acaba aquí también: revisa primero tu valor), fue revocada o ha caducado. | Comprueba que el valor que envías está completo. Si lo está, pide al administrador una clave nueva o que dé su consentimiento de nuevo. En una conexión OAuth, un 401 `api_key_expired` significa que el access token ha caducado: renuévalo antes de concluir que algo va mal. |
| 401 `api_key_owner_inactive`, `api_key_owner_not_admin` | La clave está bien; la persona propietaria se fue de la cuenta, fue desactivada o dejó de ser administradora. | Pide a un administrador que siga siéndolo que vuelva a emitir la clave o que dé su consentimiento de nuevo. Lo mismo vale para las conexiones OAuth. |
| 401 `unauthorized` | Falta la cabecera `Authorization: Bearer`. | Corrige tu petición. No hay ningún problema por parte del cliente. |
| 403 `insufficient_scope` | La credencial carece del permiso (scope) que indica `requiredScope`. | Pide una clave nueva o un nuevo consentimiento con ese scope. |
| 403 `forbidden` | El propietario de la credencial carece de un permiso que exige la operación. | Lo concede un administrador de la cuenta. |
| 402 `addon_required` | La cuenta del cliente no ha contratado el add-on indicado en `requiredAddon`. | Desactiva la función para ese cliente y explica por qué. |
| 429 `rate_limited` | La cuota de la clave se agotó. | Espera `Retry-After` segundos (el cuerpo del problema repite el valor en `retryAfter`). |

## Lista de entrega para el administrador del cliente

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

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. **Abrir los ajustes de API y MCP** En la app es Ajustes → API y MCP. Solo los administradores pueden crear claves.
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`](https://docs.filmo.io/es/rest-api/guides/scopes#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](https://docs.filmo.io/es/rest-api/guides/scopes).
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. **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.

## Cuentas de desarrollo

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](https://docs.filmo.io/es/rest-api/guides/testing) 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](https://docs.filmo.io/es/further-reading/support).

---

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