curl --request POST \
--url https://api.prod.payana.cloud/public/api/v1/workflow-steps/{reference}/complete \
--header 'Content-Type: application/json' \
--header 'api-key: <api-key>' \
--data '
{
"decision": "approve",
"acting_user_email": "[email protected]"
}
'{
"step": {
"reference": "550e8400-e29b-41d4-a716-446655440042",
"action": "document.approval",
"status": "completed",
"completed_at": "2026-08-05T14:03:11.000Z",
"decision": {
"kind": "approval",
"values": [
"approve"
],
"labels": [
"Aprobar"
]
},
"acted_by": {
"email": "[email protected]",
"name": "Ana Gómez"
}
}
}{
"status": 422,
"code": "invalid_decision",
"message": "Decision value not offered by this step: maybe"
}{
"status": 422,
"code": "invalid_decision",
"message": "Decision value not offered by this step: maybe"
}{
"status": 422,
"code": "invalid_decision",
"message": "Decision value not offered by this step: maybe"
}{
"status": 422,
"code": "invalid_decision",
"message": "Decision value not offered by this step: maybe"
}{
"status": 422,
"code": "invalid_decision",
"message": "Decision value not offered by this step: maybe"
}{
"status": 422,
"code": "invalid_decision",
"message": "Decision value not offered by this step: maybe"
}Flujos de documentos
Resolver un paso
Aprueba, clasifica o etiqueta un documento desde tu integración, a nombre de un miembro de tu compañía.
POST
/
workflow-steps
/
{reference}
/
complete
curl --request POST \
--url https://api.prod.payana.cloud/public/api/v1/workflow-steps/{reference}/complete \
--header 'Content-Type: application/json' \
--header 'api-key: <api-key>' \
--data '
{
"decision": "approve",
"acting_user_email": "[email protected]"
}
'{
"step": {
"reference": "550e8400-e29b-41d4-a716-446655440042",
"action": "document.approval",
"status": "completed",
"completed_at": "2026-08-05T14:03:11.000Z",
"decision": {
"kind": "approval",
"values": [
"approve"
],
"labels": [
"Aprobar"
]
},
"acted_by": {
"email": "[email protected]",
"name": "Ana Gómez"
}
}
}{
"status": 422,
"code": "invalid_decision",
"message": "Decision value not offered by this step: maybe"
}{
"status": 422,
"code": "invalid_decision",
"message": "Decision value not offered by this step: maybe"
}{
"status": 422,
"code": "invalid_decision",
"message": "Decision value not offered by this step: maybe"
}{
"status": 422,
"code": "invalid_decision",
"message": "Decision value not offered by this step: maybe"
}{
"status": 422,
"code": "invalid_decision",
"message": "Decision value not offered by this step: maybe"
}{
"status": 422,
"code": "invalid_decision",
"message": "Decision value not offered by this step: maybe"
}Envía una de las opciones que devolvió Paso actual de un documento y Payana avanza el flujo.
El registro de actividad del documento deja constancia de que la decisión entró por integración, además de a nombre de quién — así queda distinguible de esa persona actuando desde Payana.
No envíes ramas del flujo ni estados internos: envía un
value de decision.options. Payana lo traduce a lo que el paso necesita — la rama, la etiqueta, el valor del campo.A nombre de quién
acting_user_email es obligatorio, y debe ser uno de los assignees del paso.Tu api-key identifica a tu compañía, no a una persona. Como una aprobación queda registrada a nombre de alguien, debes indicar de quién: no existe un “usuario del sistema” al que atribuirla.1
Consulta el paso
GET /workflow-steps/current?entity_reference=… te da la referencia del paso, sus opciones y sus assignees.2
Elige una opción y quién decide
Un
value de options (o varios, si multiple es true), y el email de un assignee.3
Envía la decisión
POST /workflow-steps/{reference}/complete.Un
200 con status: completed significa que el paso se resolvió y el flujo avanzó.Cuando faltan otros
Si el paso exige que decidan todos sus responsables, la respuesta vuelve con
status: pending. No es un error: tu decisión quedó registrada y el paso espera a los demás. Consulta GET /workflow-steps/current para ver quiénes faltan en assignees (acted: false).Errores frecuentes
403 · not_assigned
403 · not_assigned
El miembro que indicaste no está habilitado para ese paso. Consulta
assignees antes de decidir; la lista cambia si reconfiguran el flujo.409 · step_not_pending
409 · step_not_pending
Alguien más ya lo resolvió, desde Payana o desde otra llamada. Vuelve a consultar el paso actual del documento.
422 · invalid_decision
422 · invalid_decision
El valor no está entre los que el paso ofrece. En etiquetado sin restricción (
options_complete: false) también se rechaza una etiqueta que no exista en tu compañía.422 · unsupported_step
422 · unsupported_step
El paso no se decide desde esta API — está en manos de un agente, o su acción se resuelve por otra vía.
GET /workflow-steps/current lo anticipa con actionable: false.Paso actual de un documento
De dónde salen las opciones que envías aquí.
Aprobar documento
Aprobación directa, sin pasar por el flujo.
Authorizations
API key provista por Payana.
Path Parameters
Referencia del paso, tal como la devuelve GET /workflow-steps/current.
Body
application/json
Uno de los decision.options[].value del paso; una lista cuando decision.multiple es true. No es una rama del motor: la rama la deriva Payana del contrato de la acción.
Example:
"approve"
El miembro de tu compañía a nombre de quien se registra la decisión. Obligatorio: la api-key identifica a la compañía, no a una persona. Debe estar en assignees.
Motivo libre que queda registrado con la completación.
Maximum string length:
2000Response
Paso resuelto, o decisión registrada a la espera de las demás
Show child attributes
Show child attributes