*API REST › Guías*

# Probar tu integración

> Empieza con una clave de solo lectura, revisa las automatizaciones de la cuenta antes de la primera escritura y mantén las operaciones irreversibles fuera de cualquier cuenta que contenga datos reales.

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.

## Empezar con una clave de solo lectura

Crea una clave solo con los scopes `:read` que necesita la integración, más [`account:read`](https://docs.filmo.io/es/rest-api/guides/scopes#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)](https://docs.filmo.io/es/rest-api/guides/scopes) tiene recetas por tipo de integración. También puedes probar lecturas desde la [Referencia de OpenAPI](https://docs.filmo.io/es/rest-api/openapi).

## Una cuenta separada para las escrituras

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`](https://docs.filmo.io/es/rest-api/objects/account#response-trial)). Cuando termina, las operaciones que hay detrás de un add-on responden 402 [`addon_required`](https://docs.filmo.io/es/rest-api/errors/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.

## Antes de escribir: comprueba las automatizaciones

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. **Listar los workflows activos que empiezan con un evento o una entidad** Llama a [`GET /api/v1/workflows`](https://docs.filmo.io/es/rest-api/endpoint-reference/workflows/list-workflows) con [`isActive`](https://docs.filmo.io/es/rest-api/endpoint-reference/workflows/list-workflows#param-isActive) puesto a `true` y [`triggerTypes`](https://docs.filmo.io/es/rest-api/endpoint-reference/workflows/list-workflows#param-triggerTypes) puesto a `event,entity`. La clave necesita [`workflows:read`](https://docs.filmo.io/es/rest-api/guides/scopes#workflows:read), y solo los administradores pueden listar workflows.
2. **Lee qué hace cada uno** Para cada workflow, [`trigger`](https://docs.filmo.io/es/rest-api/objects/workflow#response-trigger) indica qué evento o entidad lo inicia. Ábrelo en la app para ver qué envía.
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](https://docs.filmo.io/es/mcp/guides/safe-writes) antes de dejar que escriba una sola vez.

**cURL**

```bash
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"
```

**Node**

```javascript
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");
```

**Python**

```python
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")
```

## Nunca en producción

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.

| Operación | Permiso |
| --- | --- |
| `DELETE /api/v1/contacts/{contactId}` | `contacts:write` |
| `DELETE /api/v1/contacts/{contactId}/addresses/{addressId}` | `contacts:write` |
| `DELETE /api/v1/items/{itemId}` | `items:write` |
| `DELETE /api/v1/spaces/{spaceId}` | `spaces:write` |
| `DELETE /api/v1/vehicles/{vehicleId}` | `vehicles:write` |
| `DELETE /api/v1/staff/{staffId}` | `staff:write` |
| `DELETE /api/v1/tags/{tagId}` | `tags:write` |
| `DELETE /api/v1/availability/unavailabilities/{unavailabilityId}` | `availability:write` |
| `POST /api/v1/notes` | `notes:write` |
| `DELETE /api/v1/tasks/{taskId}` | `tasks:write` |
| `POST /api/v1/purchase-orders/{purchaseOrderId}/receive` | `purchase-orders:write` |
| `POST /api/v1/treasury/payments` | `treasury:write` |
| `POST /api/v1/orders/{orderId}/cancel` | `orders:write` |
| `POST /api/v1/orders/line-items/returns` | `orders:write` |
| `POST /api/v1/workflows/{workflowId}/runs` | `workflows:run` |
| `POST /api/v1/invoices/{invoiceId}/validate` | `invoices:write` |
| `POST /api/v1/invoices/{invoiceId}/void` | `invoices:write` |
| `POST /api/v1/credit-notes/{creditNoteId}/validate` | `invoices:write` |
| `POST /api/v1/credit-notes/{creditNoteId}/void` | `invoices:write` |
| `POST /api/v1/contracts/{contractId}/validate` | `contracts:write` |
| `POST /api/v1/contracts/{contractId}/sign` | `contracts:write` |
| `POST /api/v1/contracts/{contractId}/void` | `contracts:write` |
| `POST /api/v1/contracts/{contractId}/cancel` | `contracts:write` |
| `POST /api/v1/supplier-invoices/{supplierInvoiceId}/validate` | `supplier-invoices:write` |
| `POST /api/v1/supplier-invoices/{supplierInvoiceId}/void` | `supplier-invoices:write` |

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.

## Si debes probar en producción

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`](https://docs.filmo.io/es/rest-api/endpoint-reference/tags/create-a-tag) 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.

## Simular la API en local

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:

```bash
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](https://docs.filmo.io/es/rest-api/guides/openapi-and-clients) para ver los detalles y los límites de un mock.

## Ejercita las rutas de fallo

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

## Limpiar

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](https://docs.filmo.io/es/further-reading/archiving-and-deleting) antes de crear datos de prueba que luego querrás borrar.

---

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