Iniciar casos

Cada caso de un flujo arranca con la versión publicada y con sus variables de entrada (las marcadas como «Se pide al iniciar» en el lienzo). Puede arrancar de cinco formas, según de dónde llega el trabajo:

Forma	Cuándo conviene
A mano	Pruebas, o casos que alguien registra uno a uno.
Por API	Una aplicación propia que ya trabaja con la sesión de Zoan Cloud.
Disparador programado	Un caso a una hora fija: el cierre diario, el reporte del lunes.
Webhook	Otro sistema avisa cuando hay un caso nuevo (un formulario, un bot, el ERP).
Cola	Muchos casos del mismo tipo: un caso por cada ítem que llega a la cola.

En el monitor, cada caso muestra cómo empezó: A mano, Por API, Programado, Webhook o Cola.

Sin casos duplicados

Si quien inicia el caso manda una clave de idempotencia (un valor único por solicitud, como pedido-2024-0001), repetir la misma llamada devuelve el mismo caso en lugar de crear otro. Así, un sistema que reintenta porque no recibió respuesta no duplica el trabajo. Si la misma clave llega con datos distintos, se rechaza. Cada clave se recuerda durante 30 días.

A mano

1. Abre el flujo en el lienzo y pulsa Iniciar (aparece cuando el flujo tiene una versión publicada y tienes permiso para iniciar casos).
2. En Iniciar un caso, completa los datos de entrada que pide la versión publicada. Los obligatorios llevan *.
3. Si quieres, escribe una Clave de negocio (opcional) para encontrar el caso después; si la dejas vacía, se usa la que define el flujo.
4. Pulsa Iniciar. Verás el identificador del caso, su título, su clave y su estado. Con Iniciar otro arrancas el siguiente.

Por API

Para que tu ERP, CRM o backend inicie casos, usa la API de Zoan Cloud con la clave de una cuenta de servicio: POST /v1/environments/{envId}/flows/{flowId}/cases acepta las variables de entrada o los campos del formulario de inicio (validados igual que en el portal) y la cabecera Idempotency-Key. Con los avisos salientes, tu sistema se entera cuando el caso termina.

Una aplicación que ya usa la sesión de Zoan Cloud de una persona también puede iniciar casos con una llamada. La sesión debe ser de una persona con permiso para iniciar flujos. Para que un sistema externo inicie casos sin usuario y sin la API, usa un webhook.

curl -s -X POST "https://<tu-api>/environments/<ambiente>/orchestrations/<orquestacion>/instances" \
  -H "Authorization: Bearer <token-de-sesion>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-2024-0001" \
  -d '{"variables": {"numero_pedido": "PED-0001", "total": 250000}, "businessKey": "PED-0001"}'

• variables: solo las de entrada de la versión publicada. Una variable que no es de entrada, un tipo incorrecto o una obligatoria que falta responden 422 con el detalle por variable.
• businessKey (opcional): la clave de negocio del caso. Si no la mandas, se usa la plantilla del flujo.
• Clave de idempotencia (opcional): en la cabecera Idempotency-Key o en el campo idempotencyKey, hasta 500 caracteres.

Respuesta	Cuándo
201	Caso creado. El cuerpo trae id, status, business_key y title.
200	La clave de idempotencia ya se había usado con los mismos datos: devuelve ese caso.
409	El flujo no tiene versión publicada o está archivado.
422	Variables inválidas, o la clave de idempotencia ya se usó con otros datos.
429	Se alcanzó el cupo mensual de casos del plan.

Para consultar cómo va un caso: GET https://<tu-api>/environments/<ambiente>/orchestrations/<orquestacion>/instances/<id>.

Con un disparador programado

1. En el ambiente, abre Disparadores y pulsa Nuevo disparador.
2. En ¿Qué inicia?, elige Flujo, y como tipo, Programado.
3. Elige el Flujo (solo aparecen los que tienen una versión publicada), la expresión cron y la Zona horaria.
4. Si la versión pide variables de entrada, escribe sus valores en JSON: cada caso arrancará con ellos.
5. Ajusta los topes (ver Topes del disparador) y guarda.

Cada hora programada inicia un solo caso: aunque el aviso se procese dos veces, no se duplica.

Por webhook

Un webhook deja que otro sistema inicie un caso con una llamada HTTP, sin usuario ni token: la URL lleva una clave que es la autenticación.

1. En Centro › Robots › Disparadores › Nuevo disparador, elige Flujo y el tipo Webhook.
2. Elige el flujo, la espera máxima de una llamada síncrona (0 a 60 segundos) y, si quieres, valores por defecto para las variables de entrada.
3. Guarda. La fila del disparador muestra la URL con el botón para copiarla; el botón Cómo llamarlo muestra un ejemplo listo para pegar.

curl -s -X POST "https://<tu-api>/public/triggers/wk_...?wait=25" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: solicitud-0001" \
  -d '{"numero_solicitud": "SOL-0001", "cliente": "Cliente de ejemplo"}'

• Cuerpo: cada clave llega como variable de entrada. Los valores guardados en el disparador son los por defecto; lo que llega en el cuerpo manda. Una clave que no es variable de entrada se rechaza.
• Idempotency-Key: manda un valor único por solicitud; si la llamada se repite, recibes el mismo caso en vez de iniciar otro.
• ?wait=N (o la cabecera X-Zoan-Wait): segundos que la llamada espera a que el caso termine o se detenga en un incidente, hasta el tope del disparador.

La respuesta trae instance_id, status y business_key:

Respuesta	Cuándo
200	El caso terminó dentro de la espera (completed o cancelled) o quedó con un incidente (incident).
202	El caso sigue en curso (running o waiting), o no se pidió espera.
404	La clave no existe o se regeneró.
409	El disparador está apagado o pausado, el flujo no tiene versión publicada o el plan no incluye flujos.
422	Variables inválidas, o la clave de idempotencia ya se usó con otros datos.
429	Demasiadas llamadas, el disparador llegó a su máximo en curso o se acabó el cupo mensual del plan.

Consultar el estado. Con el instance_id de la respuesta: GET https://<tu-api>/public/triggers/wk_.../instances/<instance_id>. Solo responde por casos que inició ese mismo disparador.

Trata la URL como una contraseña

Quien tenga la URL puede iniciar casos. Si se filtra, pulsa Regenerar clave: la URL anterior deja de funcionar al instante.

Qué devuelve al terminar

Cuando el caso termina, la respuesta agrega outputs solo con las variables que el flujo declara como salida del webhook, nunca el resto de sus datos. Hoy esa lista (webhookOutput) se define en la definición en JSON del flujo: descárgala desde el lienzo, agrégala e impórtala.

Con una cola

Con una cola, cada ítem que llega inicia un caso con sus datos. Es la forma natural de procesar lotes: facturas, pedidos o solicitudes que otro proceso o sistema va dejando en una cola de trabajo.

1. En Centro › Robots › Disparadores › Nuevo disparador, elige Flujo y el tipo Cola.
2. Elige el flujo y la Cola vigilada.
3. Ajusta el Máximo en curso para no saturar a los sistemas y personas de los que depende el proceso, y guarda.

Cómo se comporta:

• Datos del caso. Los campos del contenido del ítem con el nombre de una variable de entrada llegan como esa variable; los demás se ignoran. Si falta alguno, se usa el valor por defecto del disparador. La referencia del ítem es la clave de negocio del caso.
• La cola queda dedicada al flujo. Los robots ya no toman ítems de ella, y no admite un segundo disparador.
• El ítem se cierra con el resultado del caso. Si el caso llega a un fin Completado, el ítem queda exitoso; si llega a un fin Rechazado por una regla de negocio o se cancela, el ítem queda fallido. Mientras el caso tiene un incidente, el ítem sigue en curso y muestra Con incidente hasta que alguien lo resuelva.
• Cada reintento es un caso nuevo. Si reintentas un ítem desde la cola, se inicia otro caso con sus datos.
• Datos inválidos. Si el contenido del ítem no encaja en las variables de entrada, el ítem queda fallido con el motivo y no se inicia nada.
• Sin cupo. Si se acaba el cupo mensual del plan, los ítems esperan en la cola y se inician cuando vuelve a haber cupo.

En la vista de la cola, cada ítem muestra el estado de su caso (Flujo en curso, Con incidente, Flujo terminado…) con un enlace al detalle.

Topes del disparador

Los disparadores que inician flujos tienen dos topes, que se ajustan al crearlos o después con Valores por defecto y topes:

• Máximo en curso (opcional): no inicia más casos mientras haya esta cantidad en curso o en espera. Vacío, sin tope. Con una cola, los ítems siguen esperando; con un webhook, la llamada recibe 429.
• Pausar con incidentes (por defecto, 20): al llegar a este número de casos con incidente, el disparador se pausa para no acumular más. Resuelve los incidentes en el monitor y vuelve a activarlo.

Cuando un disparador no puede iniciar un caso por un motivo propio (el flujo se archivó, perdió su versión publicada, el ambiente está inactivo, se acabó el cupo), la fila del disparador lo muestra con un aviso y la fecha.

Siguientes pasos

• Monitor e incidentes: seguir cada caso y resolver lo que se detuvo.
• Disparadores por webhook y programados para procesos RPA.