*Workflows › Introducción*

# Workflows

> Un workflow es una automatización que construyes en la app de Filmo: un trigger inicia una ejecución y los pasos hacen el trabajo, uno tras otro. Desde la API y MCP puedes listar los workflows de una cuenta e iniciar una ejecución.

## Qué hace un workflow

- Cuando se reserva un pedido, ponlo en el calendario, abre la tarea de preparación y avisa al almacén.
- Cuando se valida una factura, espera a su fecha de vencimiento, avisa al cliente si sigue sin pagar y escala una semana después.
- Cada día laborable a las 07:00, pregunta a Neo qué sale y qué vuelve hoy, y publícalo donde lo lee el equipo.
- Cuando se registra un pago, añádelo a la factura en tu software de contabilidad, y deja una tarea si no se puede contabilizar.
- Cuando llega un email, archiva las facturas, deriva las peticiones y deja un resumen en el chat.

Cada una de estas es una [plantilla](https://docs.filmo.io/es/workflows/templates). Para ver cómo encajan las piezas, lee [Cómo funcionan los workflows](https://docs.filmo.io/es/workflows/concepts); para crear uno ahora, empieza con el [guía rápida](https://docs.filmo.io/es/workflows/quickstart).

**Cómo empieza y termina una ejecución**
- Trigger → Cola de ejecuciones: Insertar una ejecución: queued Un botón, la API, una agenda, un webhook, un evento o una señal. El run apunta a la versión publicada del workflow, nunca al borrador.
- Cola de ejecuciones → Worker: Kick: execute El latido de cada minuto es la red de seguridad: un aviso perdido se recoge en el minuto siguiente.
- El worker reclama la ejecución: estado running, un lease de 300 segundos
- Reproduce el diario y luego ejecuta los pasos. Cada unidad de trabajo se registra una vez; una ejecución reanudada reproduce lo que ya hizo en lugar de hacerlo de nuevo.
- Worker → Cola de ejecuciones: completed · failed Terminal. Un paso fallido termina la ejecución como fallida; no hay reintento automático de un paso.
- Worker → Cola de ejecuciones: waiting + una hora de reanudación Un paso de espera, o un backoff de reintento tras un error del motor. El siguiente tick después de esa hora la devuelve a la cola.
- Worker → Cola de ejecuciones: paused La plataforma la detuvo antes de un paso: no queda crédito o hay un problema de pago. Solo Reanudar la devuelve a la vida.

## Cómo empieza un workflow

Cada workflow tiene un trigger. Estos son los siete tipos; la lista de la API informa de seis de ellos en el `type` del trigger (un workflow iniciado solo por otro workflow, como uno que nunca se publicó, vuelve sin tipo). Consulta [Triggers](https://docs.filmo.io/es/workflows/triggers) para cada uno.

| Tipo de trigger | El workflow se inicia cuando |
| --- | --- |
| `manual` | Una persona, o la API o MCP, lo ejecuta. Puede declarar un formulario. |
| `schedule` | Lo dice una agenda (una expresión cron y una zona horaria). |
| `webhook` | Una petición llega a la dirección del workflow. |
| `event` | Algo ocurre en Filmo o en una cuenta conectada. El evento se indica en el trigger. |
| `signal` | Otro workflow le envía una señal. |
| `entity` | Una persona lo ejecuta desde la página de un registro. El tipo de registro se nombra en el trigger. |
| `workflow` | Un paso de otro workflow lo inicia. No tiene botón ni API. |

La API y el MCP están pensados para iniciar workflows con un trigger manual.

## Qué puedes hacer desde la API y MCP

| Para | API REST | Herramienta MCP | Permiso (scope) |
| --- | --- | --- | --- |
| Listar los workflows y ver cómo empieza cada uno | `GET /api/v1/workflows` | `filmo_workflows_list` | `workflows:read` |
| Iniciar una ejecución de un workflow | `POST /api/v1/workflows/{workflowId}/runs` | `filmo_workflows_run` | `workflows:run` |

La lista devuelve cada workflow con la forma en que se inicia y, si es manual, el formulario de ejecución: los campos que la ejecución exige en `payload`, leídos de la versión publicada. Nunca devuelve la definición del workflow. Solo los administradores pueden leerla, y los workflows vienen ordenados por nombre.

Iniciar una ejecución pone en cola la versión publicada del workflow, igual que hace el botón Ejecutar workflow con un trigger manual (el botón además publica antes un borrador con cambios; la API nunca lo hace). La llamada devuelve el identificador de la ejecución y el estado con el que nace, `queued`. No espera a que la ejecución termine, y la API no tiene ninguna operación ni herramienta que lea una ejecución: su progreso solo se ve en la app de Filmo. Si el workflow declara un formulario de ejecución, sus campos son obligatorios en `payload`, y una petición a la que le falte uno responde 400 y no inicia nada. Un workflow que nunca se ha guardado responde 409.

Al iniciar una ejecución conviene enviar una `Idempotency-Key` propia: dos peticiones con la misma clave devuelven la misma ejecución en lugar de iniciar dos. Sin ella, dos peticiones son dos ejecuciones. Consulta la guía de idempotencia en la pestaña de la API REST.

Los detalles, con los scopes, los errores y la forma de conocer el resultado, están en [Workflows desde la API y MCP](https://docs.filmo.io/es/workflows/api-and-mcp).

## Qué desencadena una escritura a través de la API

- Una escritura hecha por la API o MCP sigue el mismo camino que el mismo cambio en la app. Un workflow cuyo trigger es un evento se inicia de verdad cuando ocurre ese cambio, no solo cuando alguien trabaja en la app. El evento llega al workflow con su `origin` fijado en API o MCP.
- Eso se cumple cuando la acción que hay detrás del endpoint es uno de los eventos del catálogo. Qué endpoints corresponden a uno no se enumera aquí endpoint por endpoint.
- El evento se envía después de la respuesta, una vez por cambio, y no se reintenta si falla. Un `Idempotency-Key` repetido devuelve la respuesta almacenada y no vuelve a enviar el evento.
- No puedes pedir que una petición no desencadene workflows. Lo que sí puedes hacer es comprobar qué workflows están activos antes de cargar o importar datos y, en un workflow, filtrar un trigger de evento según el origen del cambio.
- Algunos cambios no tienen evento, como la mayoría de las actualizaciones de artículos y precios, notas, etiquetas y el planificador.
- Una escritura hecha por un workflow puede iniciar otros workflows. Filmo detiene una cadena de workflows en un límite de profundidad de diez y no inicia un workflow que ya está en la cadena. Se espera que un workflow que llama a la API con una clave inicie una cadena nueva, porque la llamada llega a Filmo como una petición de la API; así que mantén esa llamada lejos de los datos que inician el workflow, o los dos pueden entrar en bucle.

Para mantener otro sistema sincronizado con Filmo, la guía [Sincronizar datos](https://docs.filmo.io/es/rest-api/guides/syncing-data#push) explica cómo montar push con un workflow cuyo trigger es un evento y cuyo paso es una petición HTTP a tu endpoint; la guía [Enviar cambios a tu propio sistema](https://docs.filmo.io/es/workflows/guides/push-to-your-system) lo construye.

## Siguientes pasos

- **[Guía rápida](https://docs.filmo.io/es/workflows/quickstart)**: Crea un workflow a partir de una plantilla, publícalo y observa una ejecución.
- **[El editor](https://docs.filmo.io/es/workflows/editor)**: El lienzo, la paleta, el guardado automático, Publicar y el interruptor Live.
- **[Datos y expresiones](https://docs.filmo.io/es/workflows/data-and-expressions)**: Cómo lee un paso lo que produjo uno anterior.
- **[Runs](https://docs.filmo.io/es/workflows/runs)**: Estados, el visor de runs, errores, reintentos y límites.
- **[Iniciar una ejecución](https://docs.filmo.io/es/rest-api/overview)**: La operación para iniciar una ejecución, junto con el resto de la API REST.
- **[Sincronizar datos](https://docs.filmo.io/es/rest-api/guides/syncing-data#push)**: Sondeo y push, con un workflow que llama a tu endpoint.

---

URL canónica: https://docs.filmo.io/es/workflows/overview  
Última actualización: 2026-10-09