Iniciar procesos y entregar mensajes

Los procesos que puedes iniciar y los mensajes que esperan los define el banco. En esta guía usamos como ejemplo un proceso de alta de cliente con aprobación de cumplimiento (clave altaClienteAprobacion) y un mensaje de resultado de verificación (kyc_result). Los datos son ficticios.

1. Obtener un token

El token es un JWT de 15 minutos (la instalación puede cambiarlo). La credencial va en Authorization: Basic o en el cuerpo, en formulario o JSON.

curl -s -X POST https://orquestador.banco.example/api/v1/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials

{
  "access_token": "<JWT>",
  "token_type": "Bearer",
  "expires_in": 900,
  "roles": ["ORQ_OPERATOR"]
}

Tras varios intentos fallidos, la credencial o la dirección de origen quedan bloqueadas temporalmente: 429 con codigo ACCESO_BLOQUEADO y reintentarEnSegundos.

2. Iniciar una instancia

Se inicia siempre la versión vigente (activa) del proceso.

curl -s -X POST "https://orquestador.banco.example/api/v1/process-instances/altaClienteAprobacion:start" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: solicitud-100-alta" \
  -H "Content-Type: application/json" \
  -d '{
    "businessKey": "solicitud-100",
    "variables": {
      "cliente": {
        "customerTypeCode": "NATURAL", "documentType": "V", "documentNumber": "12345678",
        "firstName": "Ana", "lastName": "Ejemplo"
      },
      "productoDeposito": "PRD-AHO-VES",
      "moneda": "VES"
    }
  }'

Campo	Notas
businessKey	Tu identificador de negocio (hasta 255 caracteres). Sirve para correlacionar mensajes después.
variables	Objeto JSON con las variables que el proceso espera.

Respuesta 201:

{
  "id": "5c1e9a72-3b4d-11f1-9a0e-0242ac120004",
  "processKey": "altaClienteAprobacion",
  "definitionVersion": 3,
  "businessKey": "solicitud-100",
  "ended": false
}

Idempotencia

Idempotency-Key es opcional pero recomendada: 8 a 100 caracteres [A-Za-z0-9._:-], propia de tu cliente.

Situación	Respuesta
Primera vez	201, cabecera Idempotent-Replayed: false.
Misma clave y misma petición	200 con la instancia original, Idempotent-Replayed: true.
Misma clave y petición distinta	422 IDEMPOTENCIA_CUERPO_DISTINTO.
Clave con formato inválido	400 IDEMPOTENCY_KEY_INVALIDA.

3. Iniciar por mensaje

Si el proceso del banco empieza con un evento de mensaje, inícialo por el nombre del mensaje en lugar de la clave del proceso. El cuerpo y la idempotencia son los mismos que en el paso 2.

curl -s -X POST "https://orquestador.banco.example/api/v1/messages/solicitud_recibida:start" \
  -H "Authorization: Bearer $TOKEN" -H "Idempotency-Key: solicitud-101-msg" \
  -H "Content-Type: application/json" \
  -d '{ "businessKey": "solicitud-101", "variables": { "canal": "WEB" } }'

Si ningún proceso vigente empieza con ese mensaje: 404 SIN_INICIO_POR_MENSAJE.

4. Entregar un mensaje a una instancia en espera

Cuando el proceso se detiene a esperar algo de tu lado (por ejemplo, el resultado de una verificación), entrégale el mensaje.

curl -s -X POST "https://orquestador.banco.example/api/v1/messages/kyc_result:deliver" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "businessKey": "solicitud-100", "variables": { "kycAprobado": true } }'

{
  "processInstanceId": "5c1e9a72-3b4d-11f1-9a0e-0242ac120004",
  "executionId": "5c2f0b14-3b4d-11f1-9a0e-0242ac120004",
  "message": "kyc_result"
}

La correlación se hace por businessKey o por processInstanceId (al menos uno).

codigo	HTTP	Cuándo
CORRELACION_REQUERIDA	400	No enviaste businessKey ni processInstanceId.
SIN_ESPERA_DEL_MENSAJE	404	Ninguna instancia activa espera ese mensaje, o businessKey y processInstanceId no coinciden.
CORRELACION_AMBIGUA	409	Más de una instancia espera el mensaje con ese businessKey: precisa processInstanceId.

5. Seguir una instancia

curl -s https://orquestador.banco.example/api/v1/process-instances/5c1e9a72-3b4d-11f1-9a0e-0242ac120004 \
  -H "Authorization: Bearer $TOKEN"

La respuesta trae el estado, las actividades activas, el recorrido (history), los incidentes y las variables.

Reintentar incidentes

Un incidente aparece cuando una tarea automática (por ejemplo, una llamada al core) agota sus reintentos. Cada llamada del orquestador al core lleva su propia clave de idempotencia, así que reintentar no duplica lo que ya se aplicó.

# Un incidente concreto, con 3 reintentos (de 1 a 10)
curl -s -X POST "https://orquestador.banco.example/api/v1/process-instances/5c1e9a72-3b4d-11f1-9a0e-0242ac120004/incidents/7d3a0c55-3b4d-11f1-9a0e-0242ac120004:retry" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{ "retries": 3 }'

# Todos los incidentes de la instancia
curl -s -X POST "https://orquestador.banco.example/api/v1/process-instances/5c1e9a72-3b4d-11f1-9a0e-0242ac120004/incidents:retry-all" \
  -H "Authorization: Bearer $TOKEN"

zsh

En zsh escribe la ruta entre comillas o con llaves ("${ID}:retry"): $ID:r… se interpreta como un modificador de variable.