Esperas

Muchos procesos necesitan esperar: dos días hábiles antes de recordarle algo a un cliente, la fecha de vencimiento de una factura o la confirmación de un pago que llega de otro sistema. Con los pasos de espera de Zoan Flow, el caso hace justo eso sin trucos ni robots dando vueltas:

• No ocupa robots ni workers. Mientras espera, el caso solo queda guardado; tus robots siguen libres para otro trabajo y la espera no consume capacidad.
• El tiempo del negocio. Las duraciones pueden contar solo el horario laboral de la organización, y las fechas se leen en su zona horaria.
• Nada se pierde. Las esperas sobreviven a reinicios y actualizaciones de Zoan Cloud: el caso sigue en el momento justo.
• Otro sistema avisa y el caso sigue. Tu ERP, tu pasarela de pagos o un robot envían una señal y el caso continúa con los datos que trae.
• Un plan B si el aviso no llega. Con un tiempo máximo y la salida Vencida, el caso escala o toma otro camino en lugar de quedarse quieto.

Hay dos pasos de espera:

Paso	Espera…	Ejemplo
Esperar	Un tiempo o hasta una fecha.	Esperar 2 días hábiles antes de enviar un recordatorio.
Esperar evento	Una señal con nombre, enviada desde el portal, la API o un robot.	Esperar la confirmación del pago, con un tope de 24 horas.

Los dos se agregan desde la paleta del lienzo y tienen exactamente una salida normal; Esperar evento puede tener además la salida Vencida.

Esperar

Esperar detiene el caso y lo deja seguir cuando se cumple el tiempo. En el panel de propiedades eliges cómo se calcula:

Modo	Qué configuras	Cuándo sigue el caso
Una duración	Una cantidad entera (1 o más) en minutos, horas o días. Opcional: contar solo el horario laboral.	Cuando pasa ese tiempo desde que el caso llegó al paso.
Una fecha y hora fija	AAAA-MM-DD o AAAA-MM-DD HH:mm.	En esa fecha y hora. Una fecha sola vence a las 00:00 de ese día.
La fecha de una variable	Una variable del flujo de tipo Fecha o Fecha y hora.	En la fecha que tenga esa variable en el caso, por ejemplo fecha_vencimiento.

Cómo se cuenta el tiempo:

• Zona horaria de la organización. Las fechas y horas, fijas o de una variable, se leen en la zona horaria de tu organización. Una Fecha y hora que ya trae su zona se respeta tal cual.
• Horario laboral. Con contar solo el horario laboral, la espera usa el mismo horario laboral que los plazos de las tareas (Administración › Organización y SSO › Plazos de atención de tareas (SLA)): fuera de la jornada el reloj no corre, y cada día cuenta como un día laboral completo. Con una jornada de lunes a viernes, «2 días» desde un viernes en la tarde vencen el martes en la tarde. Si la organización no tiene horario laboral, cuenta las 24 horas.
• Una fecha que ya pasó no detiene el caso: sigue de inmediato.
• Hasta un año. Una espera puede durar hasta 366 días; en horario laboral, hasta un año de trabajo (250 días, 2000 horas o 120 000 minutos laborales). Una duración más larga no se puede publicar; si una fecha fija o de variable cae más allá (o el horario laboral la lleva más allá de un año), el caso queda con el incidente timer_too_far.
• Fechas y horas sin zona. Una fecha y hora sin zona horaria (por ejemplo 2026-12-24T18:00) se entiende en la zona horaria de tu organización. Si la fecha llega con zona (…Z o -05:00), se respeta tal cual.
• Una variable sin valor o con una fecha que no sirve deja el caso con el incidente timer_invalid. Corrige la variable y reintenta el paso.

Ejemplo: recordar después de 2 días hábiles

Un flujo envía una cotización y, si el cliente no ha respondido, le recuerda dos días hábiles después.

flowchart LR
  A([Inicio]) --> E[Integración<br/>Enviar cotización]
  E --> W[Esperar<br/>2 días, horario laboral]
  W --> R[Integración<br/>Enviar recordatorio]
  R --> F([Fin])

Con contar solo el horario laboral, una cotización enviada un jueves a las 4:00 p. m. recibe el recordatorio el lunes a las 4:00 p. m., y nadie recibe correos el fin de semana.

Esperar evento

Esperar evento detiene el caso hasta que llega una señal con un nombre que tú defines, por ejemplo pago-confirmado u orden-recibida. La señal la envía otro sistema, una persona desde el portal o un robot (ver Enviar una señal), y puede traer datos que el caso guarda en sus variables.

Sección	Qué configuras
Nombre de la señal	Minúsculas, números, ., _ y -, hasta 100 caracteres; empieza por letra o número. Por ejemplo, pago-confirmado.
Datos de la señal	Qué dato de la señal va a qué variable del flujo. Cada fila es una ruta dentro de data (admite puntos, como pago.referencia) y una variable declarada. Marca opcional si el dato puede no venir.
Tiempo máximo	Opcional: Duración (cuánto esperar como máximo desde que el caso llega al paso, en minutos, horas o días, hasta 366 días) o Fecha de una variable (la fecha de una variable del caso más un margen opcional). La duración o el margen pueden contar solo el horario laboral.

Datos que llegan con tipo validado

Cada dato de la señal se guarda en su variable con el tipo que declaraste, con la misma conversión que los datos de inicio de un caso: un número que llega como "1850000" queda como número, una fecha como fecha. Si falta un dato que no es opcional o no cuadra con el tipo, la señal se rechaza con un mensaje claro (por ejemplo, «Los datos de la señal no sirven: «total» debe ser un número.») y el caso sigue esperando. Así, quien envía la señal sabe al instante que debe corregirla, y el flujo nunca sigue con datos a medias.

Tiempo máximo según una fecha del caso

Cuando el plazo depende del caso, elige Fecha de una variable: el paso vence en la fecha de una variable de tipo Fecha o Fecha y hora más un margen opcional. Por ejemplo, «fecha estimada de entrega + 2 días»: cada caso espera según su propia fecha, sin calcularla en otro paso.

• La fecha se lee igual que en Esperar hasta la fecha de una variable: una fecha sola cuenta desde las 00:00 de ese día y una fecha y hora sin zona se lee en la zona horaria de la organización.
• El margen es una cantidad entera de minutos, horas o días. Con contar el margen solo en horario laboral, el margen corre solo dentro de la jornada, como una duración de Esperar. Sin margen, vence justo en la fecha de la variable.
• Si la fecha ya pasó cuando el caso llega al paso, el tiempo máximo vence de inmediato: el caso sigue por Vencida (o queda con el incidente message_expired si no la tiene).
• Si la variable no tiene valor o no es una fecha válida, el caso queda con el incidente timer_invalid, que nombra la variable. No se usa otro plazo en su lugar: corrige la variable con Editar variables y reintenta el paso.
• Hasta un año. Si la fecha más el margen cae a más de un año de cuando el caso llega al paso, el caso queda con el incidente timer_too_far.

El monitor, la API y Mis solicitudes muestran hasta cuándo espera el caso con la fecha ya calculada.

Tiempo máximo y la salida Vencida

Con un Tiempo máximo, agrega una segunda conexión desde el paso y márcala como la salida Vencida, igual que en las tareas de persona. Si la señal no llega a tiempo, el caso sigue por ahí: puedes crear una tarea para que alguien revise, avisar al cliente o tomar otro camino.

Si el paso tiene tiempo máximo pero no tiene salida Vencida, al validar verás un aviso, y al vencer el caso queda con el incidente message_expired para que una persona decida. La salida Vencida solo se puede usar si el paso tiene tiempo máximo.

Varias ramas esperando la misma señal

Si en ramas paralelas del caso hay varios pasos esperando la misma señal, una sola señal les llega a todos y cada rama sigue por su cuenta.

La señal llega cuando el caso ya espera

Una señal se entrega a los pasos que la están esperando en ese momento: si llega antes de que el caso alcance el paso «Esperar evento», la respuesta es 409 SIGNAL_NOT_EXPECTED y quien la envía puede reintentar más tarde (con la misma clave de idempotencia, sin riesgo de duplicar). Por eso conviene que el sistema externo avise después de que el caso pidió lo que espera, o que reintente ante ese 409.

Ejemplo: confirmación de un pago con tope de 24 horas

Un flujo de pedidos genera el enlace de pago y espera a que la pasarela confirme. Si en 24 horas no hay confirmación, una persona de cartera revisa el pedido.

flowchart LR
  A([Inicio]) --> L[Integración<br/>Generar enlace de pago]
  L --> W[Esperar evento<br/>pago-confirmado · máx. 24 h]
  W --> D[Robot<br/>Despachar pedido]
  W -- Vencida --> P[Persona<br/>Revisar pago pendiente]
  D --> F([Fin])
  P --> F

La pasarela (o tu ERP) envía la señal pago-confirmado con { "referencia": "PAY-88213", "total": 1850000 }; el paso guarda referencia y total en las variables del caso y el robot despacha el pedido con esos datos.

Enviar una señal

Una señal es un aviso con nombre dirigido a un caso: «a este caso le llegó pago-confirmado, con estos datos». Solo se acepta si el caso tiene un paso Esperar evento abierto con ese nombre.

Necesitas el permiso orchestration:signal (o orchestration:operate). Ver Permisos y planes.

Desde el portal

En el detalle del caso, mientras un paso espera un evento, usa Enviar señal: eliges la señal que el caso espera y, si hace falta, escribes sus datos. Es útil para destrabar un caso cuando el aviso llegó por otro medio (por ejemplo, el cliente envió el comprobante por correo). Para enviar datos, además necesitas Ver datos de flujos (orchestration:read_data), porque escriben variables del caso.

Con la API v1

Tu sistema envía la señal con una clave de cuenta de servicio:

curl -s -X POST "https://api.cloud.zoansoftware.com/v1/environments/$ENV/cases/$CASE/signals" \
  -H "Authorization: Bearer zk_0123456789ab_EJEMPLOxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pago-PAY-88213" \
  -d '{ "name": "pago-confirmado", "data": { "referencia": "PAY-88213", "total": 1850000 } }'

{
  "case_id": "3b7f2c10-8e4d-4a91-b6c5-0d2e9f7a1c38",
  "signal": "pago-confirmado",
  "delivered_to": [ { "step_id": "a1d5e7c2-4b90-4f38-9e61-7c2b0d8f5a14", "element_id": "esperar_pago" } ],
  "status": "running",
  "received_at": "2026-10-19T15:04:22Z",
  "duplicate": false
}

Con la misma clave de idempotencia (cabecera Idempotency-Key o campo idempotency_key), puedes repetir el envío sin miedo: si la pasarela reintenta su aviso, recibe la misma respuesta con "duplicate": true y el caso no avanza dos veces. El detalle del endpoint y sus errores está en API de Zoan Cloud.

Desde un robot

Un robot que corre dentro del caso (un paso de robot del flujo) avisa con la actividad «Enviar señal a un caso» del paquete de Tareas humanas: indica el nombre de la señal y, si quieres, los datos y una clave de idempotencia. Usa la identidad de su propia ejecución, sin claves que guardar, y solo llega al caso donde corre (por ejemplo, para que una rama paralela que espera documentos-listos siga en cuanto el robot termina esa parte).

Para avisar a otro caso (por ejemplo, un robot que vigila un buzón y avisa al caso correcto cuando llega el comprobante de pago), llama a la API v1 con una clave de cuenta de servicio guardada como credencial.

Respuestas

La API responde así; el portal muestra los mismos motivos en un mensaje:

Respuesta	Qué significa
200	La señal llegó; delivered_to dice a qué pasos.
200 con "duplicate": true	Ya se había recibido con esa clave de idempotencia; no se aplicó otra vez.
404	El caso no existe o está en otro ambiente.
409 SIGNAL_NOT_EXPECTED	El caso no está esperando esa señal.
409 CASE_ENDED	El caso ya terminó.
409 IDEMPOTENCY_CONFLICT	La misma clave de idempotencia se usó con otro nombre u otros datos.
409 INSTANCE_BUSY	El caso está ocupado en este momento; reintenta en unos segundos.
422 SIGNAL_DATA_INVALID	Los datos no sirven para las variables del paso; el caso sigue esperando.

Esperas y bucles

Un bucle en el diagrama (por ejemplo, «revisar el estado → si no está listo, volver a revisar») solo se puede publicar si pasa por al menos una tarea: un robot, una persona, un paso de IA o una integración, para que el caso no dé vueltas sin esperar a nadie. Si la tarea del bucle es automática y rápida, agrega una espera para que el caso revise cada cierto tiempo en lugar de repetir sin pausa.

En el monitor

Mientras solo tiene esperas abiertas, el caso queda En espera y el paso dice Esperando hasta… o Esperando el evento…, con su vencimiento. Ver Monitor e incidentes.

Cancelar caso también cancela sus esperas: el caso no seguirá cuando venza el tiempo ni aceptará señales.

Siguientes pasos

• Diseñar en el lienzo: el resto de los pasos.
• API de Zoan Cloud: cuentas de servicio, claves y el endpoint de señales.
• Monitor e incidentes: seguir y destrabar casos.