> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Guía de diseño de workflows
> Diseña workflows de Flowker con confianza — tipos de nodo, aristas, patrones reales, transiciones de estado y mejores prácticas de orquestación.
Diseña workflows en Flowker con claridad y control. Esta guía recorre los tipos de nodos, edges, patrones del mundo real, transiciones de estado, límites técnicos y mejores prácticas para ayudarte a construir orquestaciones confiables y mantenibles.
## Tipos de nodos
***
Todo workflow se construye a partir de nodos. Cada nodo tiene un `type` que define cómo Flowker lo procesa en tiempo de ejecución.
### trigger
El punto de entrada de un workflow. Todo workflow debe comenzar con un nodo trigger. Cuando la ejecución comienza, el motor ingresa por este nodo y empieza a enrutar desde él.
```json theme={null}
{
"id": "node-trigger",
"type": "trigger",
"name": "Payment Received"
}
```
### executor
Llama a un executor externo: un servicio HTTP, API o proveedor registrado en Flowker. Este es el bloque de construcción principal para integrarse con motores de fraude, proveedores de pago, servicios de notificación y otros sistemas externos.
```json theme={null}
{
"id": "node-fraud-check",
"type": "executor",
"name": "Check Fraud Score"
}
```
### conditional
Evalúa una expresión contra el contexto de ejecución y enruta hacia diferentes ramas según el resultado. Usa nodos conditional para implementar lógica de ramificación, por ejemplo, dirigir hacia un flujo de aprobación cuando el riesgo es alto, o continuar directamente cuando es bajo.
```json theme={null}
{
"id": "node-risk-decision",
"type": "conditional",
"name": "Evaluate Risk Score"
}
```
### action
Representa operaciones internas del workflow que no involucran llamadas externas, como transformar datos, emitir eventos o registrar cambios de estado.
```json theme={null}
{
"id": "node-record-approval",
"type": "action",
"name": "Record Approval Decision"
}
```
## Edges
***
Los edges conectan nodos y definen las rutas de ejecución. Cada edge incluye los siguientes campos:
| Campo | Descripción |
| -------------- | --------------------------------------------------------------------- |
| `id` | Identificador único del edge. |
| `source` | ID del nodo de origen. |
| `target` | ID del nodo de destino. |
| `sourceHandle` | Puerto de salida del nodo de origen donde se origina el edge. |
| `condition` | Expresión que debe evaluarse como verdadera para que el edge se siga. |
| `label` | Etiqueta legible utilizada para visualización y depuración. |
### Ejemplo de edge
```json theme={null}
{
"id": "edge-approved",
"source": "node-risk-decision",
"target": "node-process-payment",
"sourceHandle": "approved",
"condition": "node-risk-decision.riskScore < 70",
"label": "Approved"
}
```
El campo `condition` se evalúa contra el contexto de ejecución. Si se omite, el edge siempre se sigue cuando el nodo de origen se completa exitosamente.
## Transiciones de estado
***
Los workflows siguen un ciclo de vida bien definido. Comprender estas transiciones es clave para desplegar y evolucionar workflows de manera segura.
* **draft** — El estado inicial. Todas las modificaciones (agregar nodos, editar edges, cambiar configuración) solo están permitidas en estado `draft`.
* **active** — Un workflow que ha sido activado. Puede ser ejecutado. No se permiten modificaciones mientras está activo.
* **inactive** — Un workflow que ha sido desactivado. Ya no puede ser ejecutado, pero puede moverse de vuelta a `draft` para edición.
### Reglas
* Solo un workflow en `draft` puede ser activado (transición: `draft → active`).
* Solo un workflow en `active` puede ser desactivado (transición: `active → inactive`).
* Solo un workflow en `inactive` puede moverse de vuelta a draft (transición: `inactive → draft`).
* Intentar una transición inválida devuelve el error `FLK-0102`.
* Intentar modificar un workflow que no está en `draft` devuelve el error `FLK-0103`.
### Mover un workflow inactivo de vuelta a draft
Si desactivaste un workflow y quieres editarlo de nuevo, muévelo de vuelta a `draft` llamando a [`POST /v1/workflows/{id}/draft`](/es/reference/flowker/move-workflow-to-draft). Esto hace que el workflow sea editable sin necesidad de clonarlo.
Esto es útil cuando desactivaste un workflow por error o cuando quieres iterar sobre un workflow existente en lugar de crear una copia.
Solo los workflows inactivos pueden moverse a draft. Si necesitas modificar un workflow activo sin sacarlo de línea, usa el enfoque de clone descrito a continuación.
### Iterar de forma segura con clone
Para modificar un workflow activo, primero clónalo. La clonación crea un nuevo `draft` desde cualquier estado, copiando todos los nodos y edges. Luego puedes actualizar, probar y activar sin impactar la versión actual.
Este es el enfoque recomendado para el versionado en producción.
## Límites técnicos
***
| Límite | Valor | Código de error |
| ------------------------------------------ | ----- | --------------- |
| Máximo de nodos por workflow | 100 | `FLK-0113` |
| Máximo de edges por workflow | 200 | `FLK-0114` |
| Máximo del payload de entrada de ejecución | 1 MB | `FLK-0506` |
Ten en cuenta estos límites al diseñar flujos complejos. Los workflows con más de \~50 nodos generalmente indican que el flujo debería dividirse en workflows más pequeños y componibles.
## Patrones comunes
***
### Secuencial
El patrón más simple. Los nodos se ejecutan en una secuencia lineal. Úsalo cuando cada paso depende del anterior y no se requiere ramificación.
**Ejemplo: Orquestación de pagos**
```json theme={null}
{
"nodes": [
{ "id": "n1", "type": "trigger", "name": "Payment Initiated" },
{ "id": "n2", "type": "executor", "name": "Validate Payment Data" },
{ "id": "n3", "type": "executor", "name": "Route to Provider" },
{ "id": "n4", "type": "executor", "name": "Send Confirmation Notification" }
],
"edges": [
{ "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
{ "id": "e2", "source": "n2", "target": "n3", "label": "Valid" },
{ "id": "e3", "source": "n3", "target": "n4", "label": "Routed" }
]
}
```
### Ramificación condicional
Un nodo `conditional` evalúa una expresión y enruta la ejecución en consecuencia. Cada edge de salida lleva su propia `condition`.
**Ejemplo: Verificación antifraude**
```json theme={null}
{
"nodes": [
{ "id": "n1", "type": "trigger", "name": "Transaction Received" },
{ "id": "n2", "type": "executor", "name": "Get Fraud Score" },
{ "id": "n3", "type": "conditional", "name": "Evaluate Score" },
{ "id": "n4", "type": "executor", "name": "Approve Transaction" },
{ "id": "n5", "type": "executor", "name": "Reject Transaction" }
],
"edges": [
{ "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
{ "id": "e2", "source": "n2", "target": "n3", "label": "Score received" },
{
"id": "e3",
"source": "n3",
"target": "n4",
"sourceHandle": "approved",
"condition": "n2.fraudScore < 70",
"label": "Approved"
},
{
"id": "e4",
"source": "n3",
"target": "n5",
"sourceHandle": "rejected",
"condition": "n2.fraudScore >= 70",
"label": "Rejected"
}
]
}
```
## Ejemplos del mundo real
***
### Verificación antifraude
Una transacción llega, se obtiene una puntuación de fraude y la ejecución se enruta hacia aprobación o rechazo.
```json theme={null}
{
"nodes": [
{ "id": "n1", "type": "trigger", "name": "Transaction Received" },
{ "id": "n2", "type": "executor", "name": "Get Fraud Score" },
{ "id": "n3", "type": "conditional", "name": "Evaluate Fraud Score" },
{ "id": "n4", "type": "executor", "name": "Approve Transaction" },
{ "id": "n5", "type": "executor", "name": "Reject and Notify" }
],
"edges": [
{ "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
{ "id": "e2", "source": "n2", "target": "n3", "label": "Score received" },
{
"id": "e3",
"source": "n3",
"target": "n4",
"sourceHandle": "approved",
"condition": "n2.fraudScore < 70",
"label": "Low risk"
},
{
"id": "e4",
"source": "n3",
"target": "n5",
"sourceHandle": "rejected",
"condition": "n2.fraudScore >= 70",
"label": "High risk"
}
]
}
```
### Orquestación de pagos
Un flujo lineal que valida los datos de pago entrantes, los enruta al proveedor adecuado y envía una confirmación.
```json theme={null}
{
"nodes": [
{ "id": "n1", "type": "trigger", "name": "Payment Initiated" },
{ "id": "n2", "type": "executor", "name": "Validate Payment Data" },
{ "id": "n3", "type": "executor", "name": "Route to Payment Provider" },
{ "id": "n4", "type": "executor", "name": "Send Confirmation" }
],
"edges": [
{ "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
{ "id": "e2", "source": "n2", "target": "n3", "label": "Valid" },
{ "id": "e3", "source": "n3", "target": "n4", "label": "Payment routed" }
]
}
```
### Onboarding KYC
Los documentos de un cliente son verificados por un servicio externo. Un nodo conditional evalúa si se requiere revisión manual. Si es así, se activa una acción de aprobación manual antes de activar la cuenta.
```json theme={null}
{
"nodes": [
{ "id": "n1", "type": "trigger", "name": "Onboarding Started" },
{ "id": "n2", "type": "executor", "name": "Run Document Check" },
{ "id": "n3", "type": "conditional", "name": "Manual Review Required?" },
{ "id": "n4", "type": "action", "name": "Request Manual Approval" },
{ "id": "n5", "type": "executor", "name": "Activate Account" }
],
"edges": [
{ "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
{ "id": "e2", "source": "n2", "target": "n3", "label": "Check complete" },
{
"id": "e3",
"source": "n3",
"target": "n4",
"sourceHandle": "review",
"condition": "n2.reviewRequired == true",
"label": "Needs review"
},
{
"id": "e4",
"source": "n3",
"target": "n5",
"sourceHandle": "clear",
"condition": "n2.reviewRequired == false",
"label": "Auto-approved"
},
{ "id": "e5", "source": "n4", "target": "n5", "label": "Approved" }
]
}
```
### Flujo de aprobación manual
Una solicitud se envía para revisión. Una acción de aprobación espera una decisión. Un nodo conditional luego enruta hacia el camino de aprobación o rechazo.
```json theme={null}
{
"nodes": [
{ "id": "n1", "type": "trigger", "name": "Request Submitted" },
{ "id": "n2", "type": "executor", "name": "Submit for Review" },
{ "id": "n3", "type": "action", "name": "Await Approval Decision" },
{ "id": "n4", "type": "conditional", "name": "Decision Received" },
{ "id": "n5", "type": "executor", "name": "Process Approved Request" },
{ "id": "n6", "type": "executor", "name": "Notify Rejection" }
],
"edges": [
{ "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
{ "id": "e2", "source": "n2", "target": "n3", "label": "Submitted" },
{ "id": "e3", "source": "n3", "target": "n4", "label": "Decision received" },
{
"id": "e4",
"source": "n4",
"target": "n5",
"sourceHandle": "approved",
"condition": "n3.decision == 'approved'",
"label": "Approved"
},
{
"id": "e5",
"source": "n4",
"target": "n6",
"sourceHandle": "rejected",
"condition": "n3.decision == 'rejected'",
"label": "Rejected"
}
]
}
```
## Mejores prácticas
***
### Convenciones de nomenclatura de nodos
Usa nombres descriptivos y orientados a la acción que comuniquen lo que hace el nodo, no de qué tipo es.
* **correcto**: `Validate Payment Data`, `Get Fraud Score`, `Notify Customer`, `Await Approval`
* **incorrecto**: `executor1`, `conditional node`, `node3`
Los buenos nombres hacen que los workflows sean legibles sin necesidad de abrir la configuración del nodo. También aparecen en los registros de auditoría y las trazas de ejecución, lo que hace que la depuración sea significativamente más rápida.
### Expresiones de condición en edges
Las condiciones en los edges se evalúan contra el contexto de ejecución. Mantenlas simples y explícitas:
* Usa comparaciones directas de campos: `.status == 'approved'`
* Usa comparaciones numéricas: `.riskScore < 70`
* Usa campos booleanos: `.reviewRequired == true`
Evita expresiones complejas que sean difíciles de leer o depurar. Si la lógica no es trivial, considera enrutar a través de un nodo `conditional` que encapsule la decisión con un nombre claro.
Una expresión inválida devuelve `FLK-0105`. Siempre valida las expresiones antes de activar un workflow.
### Estrategias de manejo de errores
Diseña los workflows para manejar los fallos de forma explícita:
* Agrega rutas de rechazo desde nodos `conditional` para cada punto de decisión que pueda fallar.
* Usa nodos `executor` separados para lógica de reintentos o proveedores de respaldo.
* Nombra las rutas de error de forma clara (por ejemplo, `Reject and Notify`, `Fallback to Manual Review`) para que los registros de auditoría sean autoexplicativos.
### Evitar ciclos
Flowker utiliza una protección contra ciclos basada en DFS en tiempo de ejecución. Si se detecta un ciclo durante la ejecución, el workflow falla con `FLK-0508`. Los ciclos no se detectan en tiempo de diseño, por lo que debes validar la estructura de edges antes de activar.
Reglas para prevenir ciclos:
* Los edges siempre deben apuntar hacia adelante en el flujo, nunca de vuelta a un nodo previamente ejecutado.
* Revisa el grafo visualmente antes de activar cualquier workflow con rutas de ramificación o convergencia.
* Si se necesita un reintento o bucle, modélalo como una invocación de workflow separada, no como un edge de retorno en el grafo actual.
### Versionado mediante clone
Nunca edites un workflow activo directamente. En su lugar:
Clona el workflow (crea un nuevo `draft` con todos los nodos y edges copiados).
Realiza tus cambios en el borrador.
Prueba el borrador con ejecuciones de prueba.
Activa la nueva versión.
Desactiva la versión anterior si ya no es necesaria.
Esto preserva el historial de ejecución de la versión activa y te proporciona una ruta de reversión limpia si la nueva versión tiene problemas.
## Crear workflows a partir de templates
***
En lugar de construir un workflow desde cero, puedes crearlo a partir de un template pre-construido en el catálogo. Los templates proporcionan estructuras listas de nodos y edges para patrones comunes — validación de pagos, verificaciones de fraude, flujos de onboarding y más.
Llama a [`POST /v1/workflows/from-template`](/es/reference/flowker/create-workflow-from-template) con el ID del template, un nombre para el nuevo workflow y cualquier parámetro que el template requiera. El resultado es un nuevo workflow con estado `draft` que puedes revisar, personalizar y activar.
```json theme={null}
POST /v1/workflows/from-template
{
"templateId": "payment-validation",
"params": {
"providerConfigId": "a1b2c3d4-e5f6-4789-a012-345678901234",
"currency": "USD"
},
"name": "Payment Validation - USD",
"description": "Valida pagos USD antes de la escritura en el ledger"
}
```
Para descubrir templates disponibles y sus parámetros obligatorios, usa los endpoints [Listar templates del catálogo](/es/reference/flowker/list-catalog-templates) y [Consultar template del catálogo](/es/reference/flowker/get-catalog-template). El endpoint de detalle del template devuelve un JSON Schema que describe los parámetros esperados, incluyendo opciones dinámicas para campos que referencian configuraciones de provider.
## Referencia de errores
***
Los siguientes códigos de error son relevantes para el diseño y la ejecución de workflows:
| Código | Descripción |
| ---------- | -------------------------------------------------------------------- |
| `FLK-0102` | Transición de estado inválida |
| `FLK-0103` | El workflow no puede ser modificado — no está en estado draft |
| `FLK-0105` | Expresión condicional inválida |
| `FLK-0113` | Demasiados nodos — el máximo es 100 |
| `FLK-0114` | Demasiados edges — el máximo es 200 |
| `FLK-0506` | Payload de entrada de ejecución demasiado grande — el máximo es 1 MB |
| `FLK-0508` | Ciclo detectado durante la ejecución del workflow |