Flujos y operaciones

Conceptos comunes de flujos y operaciones, estructura, estados y transiciones, compartidos por todos los productos de Zertiban.

Los conceptos de flujo (flow) y operación (operation) constituyen la base funcional de todos los productos de Zertiban. Cualquier integración construida sobre la plataforma se modela sobre esta misma estructura común, independientemente del tipo de operación o caso de uso implementado.

La arquitectura está diseñada para desacoplar el contexto de negocio global del conjunto de acciones concretas que realiza el usuario final. Esto permite construir experiencias más flexibles, trazables y escalables, donde múltiples operaciones pueden agruparse y gestionarse bajo un mismo contexto transaccional.

El sistema diferencia entre:

• Flow → contexto de negocio agregado.
• Operation → acción individual ejecutada por el usuario final.

Ambas entidades tienen identificadores, estados, eventos webhook y ciclos de vida independientes, aunque relacionados entre sí.

¿Qué es un flujo (flow)?

Un flujo es el contenedor de negocio que agrupa una o varias operaciones relacionadas. Se crea mediante una única llamada al API (POST /flow/v1/flows/*) y recibe un identificador único denominado flowUuid.

El flujo representa el contexto global de una interacción de negocio. Por ejemplo:

• Un proceso de cobro con múltiples operaciones.
• Una experiencia transaccional compuesta por varias acciones del usuario.
• Un conjunto de operaciones asociadas a un mismo proceso funcional.

El estado del flujo refleja el resultado agregado de todas las operaciones que contiene.

Características principales

• Tiene su propio ciclo de vida independiente.
• Puede referenciarse mediante un externalId para conciliación con sistemas externos.
• Todas las operaciones del flujo comparten configuración visual, expiración y comportamiento funcional.
• Genera eventos webhook flow.* cuando cambia su estado agregado.
• Permite agrupar múltiples operaciones bajo una única experiencia de usuario.

Estructura de un flujo

Cada flujo puede contener una o múltiples operaciones configuradas individualmente.

Flujo (Flow)
  ├── Operación 1
  ├── Operación 2
  └── Operación N

Modelo síncrono y asíncrono

La API de Zertiban combina procesamiento síncrono y notificaciones asíncronas para simplificar la integración.

• Síncrono: la llamada al API devuelve inmediatamente toda la información necesaria para operar: URLs de operación, identificadores, documentos y metadatos operativos. No es necesario realizar polling ni esperar procesamiento adicional para comenzar la interacción con el usuario final.
• Asíncrono: los cambios de estado se notifican en tiempo real mediante webhooks. El sistema cliente recibe automáticamente eventos cuando un usuario abre una operación, una operación se completa, una operación caduca o un flujo alcanza un estado terminal. El uso de webhooks reduce la latencia de conciliación y evita integraciones basadas en polling continuo.

Estados del flujo

El flujo agrega el estado de todas las operaciones contenidas. Su estado representa el resultado global del proceso de negocio.

Estado	Descripción	Terminal
CREATED	El flujo ha sido creado. Ninguna operación ha sido abierta aún.	No
IN_PROGRESS	Al menos una operación está actualmente en proceso.	No
COMPLETED	Todas las operaciones han finalizado correctamente.	Sí
PARTIALLY_COMPLETED	Al menos una operación se ha completado correctamente, pero no todas.	Sí
NOT_COMPLETED	Ninguna operación ha finalizado correctamente. Resultado mixto sin completados.	Sí
REJECTED	Todas las operaciones han sido rechazadas.	Sí
EXPIRED	Todas las operaciones han caducado.	Sí
CANCELLED	Todas las operaciones han sido canceladas.	Sí

Transiciones de estado

Desde	Hacia	Disparador
CREATED	IN_PROGRESS	Una operación pasa a OPENED
IN_PROGRESS	COMPLETED	Todas las operaciones alcanzan COMPLETED
IN_PROGRESS	PARTIALLY_COMPLETED	Todas las operaciones son terminales y al menos una está COMPLETED, pero no todas
IN_PROGRESS	NOT_COMPLETED	Todas las operaciones son terminales, ninguna COMPLETED, con resultados mixtos
IN_PROGRESS	REJECTED	Todas las operaciones quedan en REJECTED
CREATED / IN_PROGRESS	EXPIRED	Todas las operaciones quedan en EXPIRED
CREATED / IN_PROGRESS	CANCELLED	Todas las operaciones quedan en CANCELLED

Los estados terminales son definitivos y no admiten nuevas transiciones posteriores.

¿Qué es una operación?

Una operación representa la acción concreta ejecutada por el usuario final dentro de un flujo. Dependiendo del producto de Zertiban, una operación puede corresponder a un pago individual, una autorización bancaria o cualquier interacción transaccional aislada.

Cada operación dispone de:

• Su propio operationUuid.
• Su URL independiente.
• Su ciclo de vida específico.
• Sus propios eventos webhook.

Esto permite monitorizar y reconciliar individualmente cada interacción realizada por el usuario.

Características principales

• Puede referenciarse mediante un externalId propio.
• Un mismo flujo puede contener operaciones de distinto tipo.
• Genera eventos webhook operation.* cuando cambia de estado.
• Tiene estados terminales independientes del resto de operaciones del flujo.

Estados de la operación

Cada operación evoluciona a través de distintos estados funcionales. Los estados COMPLETED, REJECTED, EXPIRED y CANCELLED son terminales: una vez alcanzados, no se producen más transiciones.

Estado	Descripción	Terminal	Webhook
CREATED	La operación ha sido creada. La URL está activa pero el usuario aún no ha accedido.	No	OPERATION_CREATED
OPENED	El usuario ha accedido y la operación está en curso.	No	OPERATION_OPENED
COMPLETED	La operación ha finalizado correctamente.	Sí	OPERATION_COMPLETED
REJECTED	El usuario o el banco han rechazado la operación.	Sí	OPERATION_REJECTED
EXPIRED	La operación ha caducado antes de completarse.	Sí	OPERATION_EXPIRED
CANCELLED	La operación ha sido cancelada por API o sistema.	Sí	OPERATION_CANCELLED

Transiciones de estado

Desde	Hacia	Disparador
CREATED	OPENED	El usuario abre la URL
CREATED	EXPIRED	Se alcanza la fecha de expiración (expirationOffset)
CREATED	CANCELLED	PUT/flow/v1/operations/{operationUuid}/cancel
OPENED	COMPLETED	El usuario completa correctamente la operación
OPENED	REJECTED	El usuario o el banco rechazan la operación
OPENED	EXPIRED	Se alcanza la fecha de expiración
OPENED	CANCELLED	PUT/flow/v1/operations/{operationUuid}/cancel (solo si no existen transacciones pendientes)

Los estados terminales son definitivos y no admiten nuevas transiciones posteriores.

Recomendaciones de integración

Zertiban recomienda utilizar siempre webhooks como mecanismo principal de sincronización de estados. Aunque los estados pueden consultarse mediante API, el uso de polling introduce mayor latencia de conciliación, incremento innecesario de tráfico y procesamiento redundante.

Webhooks como mecanismo principal.

Los webhooks permiten reaccionar en tiempo real a cualquier cambio de estado tanto de operaciones como de flujos, facilitando integraciones más eficientes, consistentes y escalables.