> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payana.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Paso actual de un documento

> Consulta en qué paso de su flujo está parado un documento y qué decisión admite.

Un documento avanza por el flujo que configuró tu compañía: aprobarlo, clasificarlo, etiquetarlo. Este endpoint te dice **en cuál de esos pasos está parado ahora** y **qué puedes responder**, sin que necesites conocer cómo está armado el flujo.

<Info>
  Lo que devuelve en `options` es lo que aceptas enviar de vuelta. El `value` de cada opción es opaco: no intentes interpretarlo, devuélvelo tal cual en [Resolver un paso](/api-reference/workflow-steps/complete).
</Info>

## Las tres decisiones

El selector de ejemplos de la respuesta muestra las tres, más el caso en que no te corresponde decidir. En qué se diferencian:

|               | `kind`           | `multiple` | Qué hay en `options`                                  |
| ------------- | ---------------- | ---------- | ----------------------------------------------------- |
| Aprobación    | `approval`       | `false`    | Dos fijas: `approve` y `reject`                       |
| Clasificación | `classification` | `false`    | Los valores activos del campo que nombra `field_name` |
| Etiquetado    | `tagging`        | `true`     | Etiquetas de tu compañía                              |

<Warning>
  En etiquetado revisa **`options_complete`**. Cuando viene en `false`, el paso no restringe a un subconjunto: la lista es una muestra del catálogo y **cualquier etiqueta de tu compañía es válida**, aunque no aparezca ahí. Si tu interfaz solo ofrece lo que llegó en `options`, estarás recortando opciones válidas.
</Warning>

## Cuándo no hay nada que responder

<Warning>
  Un `204` significa que el documento no tiene ningún paso pendiente: o su flujo terminó, o nunca arrancó uno.

  Un `200` con `actionable: false` y `decision: null` es distinto: **hay** un paso pendiente, pero no te corresponde. Ocurre cuando lo está resolviendo un agente, o cuando su acción no se decide desde afuera — la causación, por ejemplo, se resuelve registrando el documento en tu ERP.
</Warning>

## Quién puede resolverlo

El campo `assignees` lista a los miembros de tu compañía habilitados para ese paso, e indica si alguno ya decidió. Al completar debes nombrar a uno de ellos: consulta [Resolver un paso](/api-reference/workflow-steps/complete).

<Tip>
  Cuando el flujo tiene un agente configurado, `recommendations` trae su sugerencia y el porqué. Puedes usarla para preseleccionar una opción en tu interfaz, o para decidir automáticamente cuando la confianza es alta.
</Tip>

<CardGroup cols={2}>
  <Card title="Resolver un paso" icon="circle-check" href="/api-reference/workflow-steps/complete">
    Envía la decisión que este endpoint te ofreció.
  </Card>

  <Card title="Flujos" icon="diagram-project" href="/flujos">
    Cómo se configuran los pasos por los que pasa un documento.
  </Card>
</CardGroup>


## OpenAPI

````yaml GET /workflow-steps/current
openapi: 3.1.0
info:
  title: Payana Accounts Payable API
  description: >-
    API pública para gestionar cuentas por pagar (payments) y beneficiarios
    (beneficiaries) en Payana, incluyendo notificaciones por webhooks cuando se
    procesan pagos.
  version: 1.0.0
servers:
  - url: https://api.prod.payana.cloud/public/api/v1
    description: Production
  - url: https://api.develop.payana.cloud/public/api/v1
    description: Develop
security:
  - apiKeyAuth: []
tags:
  - name: Payments
    description: Crear y listar pagos
  - name: Beneficiaries
    description: Crear, listar y consultar beneficiarios
  - name: Webhooks
    description: Eventos de webhooks enviados por Payana
  - name: Banks
    description: Listar y consultar bancos
  - name: Transactions In
    description: Transacciones entrantes (polling, mismo formato que webhooks)
  - name: Documents
    description: Listar, consultar y operar documentos (cuentas por pagar)
  - name: DIAN Events
    description: >-
      Encolar eventos DIAN (030 Acuse de recibo, 031 Reclamo, 032 Recibo del
      bien, 033 Aceptación expresa, 034 Aceptación tácita) para documentos
      identificados por CUFE. El procesamiento es asíncrono.
  - name: Fiscal Sync
    description: >-
      Disparar y consultar sincronización de documentos fiscales desde el SAT
      (México) o la DIAN (Colombia).
  - name: Workflow Steps
    description: >-
      Resolver el paso en que está parado un documento dentro de su flujo:
      aprobación, clasificación o etiquetado.
paths:
  /workflow-steps/current:
    get:
      tags:
        - Workflow Steps
      summary: Paso actual de un documento
      description: >-
        Devuelve el único paso pendiente del documento, junto con la decisión
        que admite: aprobar/rechazar, los valores activos de un campo
        personalizado, o el catálogo de etiquetas.


        - El `value` de cada opción es opaco: es exactamente lo que devuelves al
        completar.

        - `recommendations` trae la sugerencia del agente cuando dejó una.

        - Un paso en manos de un agente, o cuya acción no admite decisión por
        esta API, vuelve con `actionable: false` y `decision: null`.

        - Devuelve `204` cuando el documento no tiene ningún paso pendiente.
      parameters:
        - name: entity_reference
          in: query
          required: true
          description: Referencia interna del documento en Payana (UUID).
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Paso pendiente encontrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  step:
                    $ref: '#/components/schemas/WorkflowStepView'
              examples:
                aprobacion:
                  summary: Aprobación — dos opciones fijas
                  value:
                    step:
                      reference: 550e8400-e29b-41d4-a716-446655440042
                      status: pending
                      actionable: true
                      created_at: '2026-08-01T10:00:00.000Z'
                      entity:
                        type: document
                        reference: b4d1689c-e729-478b-a15b-339ad050192f
                        document_number: FE-1234
                        concept: Servicios profesionales
                        amount_cents: '1234500'
                        amount_currency: COP
                        issue_date: '2026-07-01'
                        expiration_date: '2026-07-31'
                        third_party:
                          - type: beneficiary
                            name: ACME S.A.S.
                            reference: a1b2c3d4-0000-4000-8000-000000000001
                      assignees:
                        - email: ana@acme.co
                          name: Ana Gómez
                          acted: false
                      action: document.approval
                      decision:
                        kind: approval
                        multiple: false
                        field_name: null
                        options:
                          - value: approve
                            label: Aprobar
                          - value: reject
                            label: Rechazar
                        options_complete: true
                      recommendations:
                        - value: approve
                          confidence_level: high
                          rationale: >-
                            El monto y el proveedor coinciden con la orden de
                            compra.
                clasificacion:
                  summary: Clasificación — un valor de un campo personalizado
                  value:
                    step:
                      reference: 550e8400-e29b-41d4-a716-446655440042
                      status: pending
                      actionable: true
                      created_at: '2026-08-01T10:00:00.000Z'
                      entity:
                        type: document
                        reference: b4d1689c-e729-478b-a15b-339ad050192f
                        document_number: FE-1234
                        concept: Servicios profesionales
                        amount_cents: '1234500'
                        amount_currency: COP
                        issue_date: '2026-07-01'
                        expiration_date: '2026-07-31'
                        third_party:
                          - type: beneficiary
                            name: ACME S.A.S.
                            reference: a1b2c3d4-0000-4000-8000-000000000001
                      assignees:
                        - email: ana@acme.co
                          name: Ana Gómez
                          acted: false
                      action: document.classify
                      decision:
                        kind: classification
                        multiple: false
                        field_name: Centro de costo
                        options:
                          - value: '451'
                            label: Administración
                          - value: '452'
                            label: Ventas
                          - value: '453'
                            label: Operaciones
                        options_complete: true
                      recommendations:
                        - value: '451'
                          confidence_level: low
                          rationale: >-
                            El proveedor facturó a Administración las últimas
                            tres veces, pero el concepto no lo confirma.
                etiquetado:
                  summary: Etiquetado — varias, y la lista no es el límite
                  value:
                    step:
                      reference: 550e8400-e29b-41d4-a716-446655440042
                      status: pending
                      actionable: true
                      created_at: '2026-08-01T10:00:00.000Z'
                      entity:
                        type: document
                        reference: b4d1689c-e729-478b-a15b-339ad050192f
                        document_number: FE-1234
                        concept: Servicios profesionales
                        amount_cents: '1234500'
                        amount_currency: COP
                        issue_date: '2026-07-01'
                        expiration_date: '2026-07-31'
                        third_party:
                          - type: beneficiary
                            name: ACME S.A.S.
                            reference: a1b2c3d4-0000-4000-8000-000000000001
                      assignees:
                        - email: ana@acme.co
                          name: Ana Gómez
                          acted: false
                      action: document.tag
                      decision:
                        kind: tagging
                        multiple: true
                        field_name: null
                        options:
                          - value: '88'
                            label: Urgente
                          - value: '91'
                            label: Nómina
                          - value: '104'
                            label: Recurrente
                        options_complete: false
                      recommendations:
                        - value: '88'
                          confidence_level: high
                          rationale: Vence en tres días.
                        - value: '104'
                          confidence_level: low
                          rationale: El proveedor factura todos los meses.
                no_accionable:
                  summary: Hay un paso, pero lo está resolviendo un agente
                  value:
                    step:
                      reference: 550e8400-e29b-41d4-a716-446655440042
                      status: pending
                      actionable: false
                      created_at: '2026-08-01T10:00:00.000Z'
                      entity:
                        type: document
                        reference: b4d1689c-e729-478b-a15b-339ad050192f
                        document_number: FE-1234
                        concept: Servicios profesionales
                        amount_cents: '1234500'
                        amount_currency: COP
                        issue_date: '2026-07-01'
                        expiration_date: '2026-07-31'
                        third_party:
                          - type: beneficiary
                            name: ACME S.A.S.
                            reference: a1b2c3d4-0000-4000-8000-000000000001
                      assignees: []
                      action: document.classify
                      decision: null
                      recommendations: []
        '204':
          description: El documento no tiene ningún paso pendiente
        '400':
          description: '`entity_reference` ausente o mal formado (`invalid_input`)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowStepError'
        '401':
          description: Header `api-key` ausente o inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowStepError'
        '403':
          description: Tu compañía no tiene habilitada esta API (`feature_not_enabled`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowStepError'
        '404':
          description: >-
            La referencia no corresponde a un documento de tu compañía
            (`entity_not_found`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowStepError'
components:
  schemas:
    WorkflowStepView:
      type: object
      required:
        - reference
        - action
        - status
        - actionable
        - created_at
        - entity
        - decision
        - recommendations
        - assignees
      properties:
        reference:
          type: string
          format: uuid
          description: Referencia del paso. Es lo que va en el path al completar.
        action:
          type: string
          nullable: true
          example: document.approval
          description: >-
            La familia de la acción, sin la versión que Payana fija
            internamente. Siempre resuelves la vigente y no puedes pedir otra.
        status:
          type: string
          example: pending
        actionable:
          type: boolean
          description: >-
            `false` cuando el paso está en manos de un agente, o su acción no
            admite decisión por esta API. `decision` viene `null` en ese caso.
        created_at:
          type: string
          format: date-time
        entity:
          type: object
          properties:
            type:
              type: string
              example: document
            reference:
              type: string
              nullable: true
              format: uuid
            document_number:
              type: string
              nullable: true
              example: FE-1234
            concept:
              type: string
              nullable: true
            amount_cents:
              type: string
              nullable: true
              example: '1234500'
            amount_currency:
              type: string
              nullable: true
              example: COP
            issue_date:
              type: string
              nullable: true
              example: '2026-07-01'
            expiration_date:
              type: string
              nullable: true
              example: '2026-07-31'
            third_party:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    example: beneficiary
                  name:
                    type: string
                  reference:
                    type: string
        decision:
          allOf:
            - $ref: '#/components/schemas/WorkflowStepDecision'
          nullable: true
        recommendations:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowStepRecommendation'
        assignees:
          type: array
          description: >-
            Quiénes pueden resolver el paso. `acting_user_email` debe ser uno de
            estos.
          items:
            type: object
            required:
              - email
              - name
              - acted
            properties:
              email:
                type: string
                format: email
              name:
                type: string
                nullable: true
              acted:
                type: boolean
                description: '`true` si ya emitió su decisión.'
    WorkflowStepError:
      type: object
      required:
        - status
        - code
        - message
      description: >-
        Error de los endpoints de workflow steps. `code` es un token estable en
        snake_case; `message` es texto para humanos y puede cambiar.
      properties:
        status:
          type: integer
          example: 422
        code:
          type: string
          example: invalid_decision
        message:
          type: string
          example: 'Decision value not offered by this step: maybe'
    WorkflowStepDecision:
      type: object
      required:
        - kind
        - multiple
        - field_name
        - options
        - options_complete
      properties:
        kind:
          type: string
          enum:
            - approval
            - classification
            - tagging
          description: Qué clase de decisión admite el paso.
        multiple:
          type: boolean
          description: '`true` solo en etiquetado: puedes enviar varios valores.'
        field_name:
          type: string
          nullable: true
          description: >-
            Nombre del campo personalizado, en pasos de clasificación. `null` en
            el resto.
        options:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowStepDecisionOption'
        options_complete:
          type: boolean
          description: >-
            `false` cuando el paso acepta valores fuera de los listados:
            `options` es una muestra acotada del catálogo, no el conjunto
            aceptado. Ocurre en etiquetado sin restricción, donde cualquier
            etiqueta de tu compañía es válida.
    WorkflowStepRecommendation:
      type: object
      required:
        - value
        - confidence_level
        - rationale
      description: >-
        Sugerencia del agente, cuando dejó una. Aprobación y clasificación traen
        a lo sumo una; etiquetado puede traer varias.
      properties:
        value:
          type: string
          description: Uno de los `options[].value`.
        confidence_level:
          type: string
          nullable: true
          enum:
            - high
            - low
            - null
        rationale:
          type: string
          nullable: true
    WorkflowStepDecisionOption:
      type: object
      required:
        - value
        - label
      description: >-
        Una opción que el paso ofrece. `value` es opaco: es exactamente lo que
        devuelves en `decision` al completar.
      properties:
        value:
          type: string
          example: '451'
        label:
          type: string
          example: Administración
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: api-key
      description: API key provista por Payana.

````