Probar tu integración

No hay sandbox ni claves de prueba: todas las claves empiezan por fk_live_ y actúan sobre los datos reales de la cuenta que las emitió. Cada paso siguiente es una forma de reducir lo que puede tocar una prueba.

Crea una clave solo con los scopes :read que necesita la integración, más account:read, y haz con ella toda tu lectura, paginación y análisis. Una clave de solo lectura no puede cambiar nada, así que un error en tu código tampoco. El Permisos (scopes) tiene recetas por tipo de integración. También puedes probar lecturas desde la Referencia de OpenAPI.

Prueba las escrituras en una cuenta aparte que solo contenga datos ficticios (nombres como Acme Rentals, emails en example.com), no en la cuenta de un cliente real. Usa una cuenta de prueba gratuita: sirve para probar la API. Un administrador crea en ella las claves de API y conecta OAuth y MCP como en cualquier otra cuenta, y la prueba desbloquea todos los add-ons. Conoce sus condiciones.

• La prueba dura 14 días y no necesita tarjeta. Cuando expira, puede ser prorrogable una vez, por 7 días.
• Un periodo de prueba desbloquea todos los add-ons mientras dura (trial). Cuando termina, las operaciones que hay detrás de un add-on responden 402 addon_required mientras las demás siguen funcionando, así que un test que pasó durante el periodo de prueba puede fallar después. Las claves y las conexiones OAuth no se revocan cuando termina el periodo de prueba, y la autenticación no mira el periodo de prueba: comprueba la clave, su dueño y el acceso del dueño a la cuenta.
• Los datos de una cuenta de prueba se purgan unos 30 días después de que acabe la prueba. No guardes ahí nada que necesites.
• Trata la cuenta de prueba como una real. Validar una factura o una nota de crédito es irreversible y consume números de la numeración de la cuenta, también en una cuenta de prueba: valida solo lo que necesite una prueba.

Una escritura a través de la API sigue la misma ruta que un cambio hecho en la app, así que dispara los workflows de eventos de la cuenta. No puedes suprimirlo por petición: no hay cabecera ni indicador para ello. Esos workflows pueden enviar emails a clientes o llamar a terceros, así que esta comprobación es obligatoria antes de la primera escritura. Los eventos se disparan después de la respuesta y en la medida de lo posible; la mayoría de las escrituras de negocio (pedidos, facturas, pagos, presupuestos, contactos, tareas, proyectos) disparan uno, mientras que algunas ediciones, como las asignaciones de etiquetas o los cambios de precio de artículos, no disparan ninguno.

1. 1

   Listar los workflows activos que empiezan con un evento o una entidad

   Llama a GET /api/v1/workflows con isActive puesto a true y triggerTypes puesto a event,entity. La clave necesita workflows:read, y solo los administradores pueden listar workflows.

2. 2

   Lee qué hace cada uno

   Para cada workflow, trigger indica qué evento o entidad lo inicia. Ábrelo en la app para ver qué envía.

3. 3

   Páusalos o excluye la API

   Pausa los que podrían llegar a un cliente o a un tercero mientras pruebas. Como alternativa, filtra el trigger de cada workflow por origin para excluir api (y mcp, si también pruebas por MCP), de modo que ignore lo que escribe tu clave. Reanúdalos o restáuralos después.

Si también pruebas por MCP, un asistente escribe con el mismo efecto. Lee Escrituras seguras antes de dejar que escriba una sola vez.

BASE="${FILMO_BASE_URL:-https://app.filmo.io}"

curl -sS -G "$BASE/api/v1/workflows" \
  -H "Authorization: Bearer $FILMO_API_KEY" \
  --data-urlencode "isActive=true" \
  --data-urlencode "triggerTypes=event,entity" \
  --data-urlencode "limit=500"

const base = process.env.FILMO_BASE_URL ?? "https://app.filmo.io";

const url = new URL(base + "/api/v1/workflows");
url.searchParams.set("isActive", "true");
url.searchParams.set("triggerTypes", "event,entity");
url.searchParams.set("limit", "500");

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.FILMO_API_KEY}` },
});
if (!res.ok) throw new Error("HTTP " + res.status + " " + (await res.text()));
const { data, pagination } = await res.json();

for (const workflow of data) {
  const starts = workflow.trigger.event ?? workflow.trigger.entity;
  console.log(workflow.name, "-", workflow.trigger.type, starts);
}
if (pagination.hasMore) console.warn("More workflows: follow pagination.nextCursor");

import os

import requests

base = os.environ.get("FILMO_BASE_URL", "https://app.filmo.io")

res = requests.get(
    base + "/api/v1/workflows",
    headers={"Authorization": f"Bearer {os.environ['FILMO_API_KEY']}"},
    params={"isActive": "true", "triggerTypes": "event,entity", "limit": "500"},
    timeout=30,
)
res.raise_for_status()
body = res.json()

for workflow in body["data"]:
    trigger = workflow["trigger"]
    print(workflow["name"], "-", trigger["type"], trigger["event"] or trigger["entity"])
if body["pagination"]["hasMore"]:
    print("More workflows: follow pagination.nextCursor")

No llames a estas operaciones desde una prueba contra una cuenta que tenga datos reales. No se pueden deshacer, producen documentos fiscales o avisan a personas.

• Validar o anular una factura, una nota de crédito, un contrato o una factura de proveedor.
• Cancelar o firmar un contrato.
• Recibe una orden de compra, devuelve líneas de pedido o registra un pago.
• Ejecuta un workflow.
• Cancelar un pedido o quitar su reserva.
• Eliminar un registro.
• Crea una nota que mencione a usuarios: les notifica.

La tabla se genera a partir de las mismas listas que alimentan las insignias de las páginas de operación, así que no pueden discrepar.

Prefiere una cuenta aparte. Si la única cuenta es la real, reduce el riesgo:

• Haz antes la comprobación de automatizaciones de arriba.
• Marca cada registro que crees para poder encontrarlo, evitarlo y limpiarlo. Crea una etiqueta como api-test con POST /api/v1/tags y asóciala a cada registro de prueba, y da a los registros de prueba un prefijo de nombre evidente. Excluye esa etiqueta y ese prefijo de tus informes y de las consultas propias de la integración.
• Usa un contacto ficticio (un email en example.com) para los pedidos y notas de prueba, de modo que ningún cliente reciba nada.
• No llames nunca a las operaciones de la tabla anterior.
• Usa una clave limitada a los permisos de la prueba y revócala cuando termines.

Sin sandbox, la única forma sin riesgo de probar escrituras, idempotencia y rutas de error es un servidor simulado construido a partir del archivo OpenAPI:

npm install --global @stoplight/prism-cli
prism mock -d https://docs.filmo.io/openapi.json

Los campos decimales llegan como cadenas de relleno, no como importes reales. Consulta Archivo OpenAPI y clientes generados para ver los detalles y los límites de un mock.

• 401: llama con una clave incorrecta y comprueba que tu código avisa en lugar de reintentar.
• 403: llama a una operación con una clave que no tiene su permiso y lee requiredScope del cuerpo.
• 429: baja tu propio límite en una prueba para forzarlo y comprueba que esperas a Retry-After.
• Un timeout durante una escritura: corta la petición después de enviarla, luego reintenta con el mismo Idempotency-Key y confirma que solo existe un registro.

No todos los registros se pueden borrar, y algunos cambios no se pueden deshacer. Archivar un pedido lo hace invisible para la API: su GET responde 404. Consulta qué es posible para cada tipo de registro en Archivar y eliminar antes de crear datos de prueba que luego querrás borrar.