Resolver un paso - payana-docs

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"
}

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.

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.

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.

Consulta el paso

GET /workflow-steps/current?entity_reference=… te da la referencia del paso, sus opciones y sus assignees.

Elige una opción y quién decide

Un value de options (o varios, si multiple es true), y el email de un assignee.

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

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

Alguien más ya lo resolvió, desde Payana o desde otra llamada. Vuelve a consultar el paso actual del documento.

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

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

string

header

required

API key provista por Payana.

Path Parameters

reference

string<uuid>

required

Referencia del paso, tal como la devuelve GET /workflow-steps/current.

Body

application/json

decision

required

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"

acting_user_email

string<email>

required

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.

comment

string

Motivo libre que queda registrado con la completación.

Maximum string length: 2000

Response

Paso resuelto, o decisión registrada a la espera de las demás

step

object

Show child attributes

⌘I

​A nombre de quién

​Cuando faltan otros

​Errores frecuentes

Paso actual de un documento

Aprobar documento

Authorizations

Path Parameters

Body

Response

A nombre de quién

Cuando faltan otros

Errores frecuentes