> ## 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.

# Send DIAN Events (Batch)

> Valida y encola el producto cruzado de `events_type` × `documents_fiscal_reference`. El procesamiento es **atómico por evento**: si uno falla, los demás del batch se procesan igual.

Los eventos de **reclamo (`031`) no se aceptan acá** — deben enviarse uno por uno via `POST /events/single`.

Igual que en `/events/single`, la respuesta `200` significa que los eventos fueron persistidos en estado `processing` y encolados, no que la DIAN los haya aceptado.



## OpenAPI

````yaml POST /events/batch
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:
  /events/batch:
    post:
      tags:
        - DIAN Events
      summary: Queue DIAN receipt events for multiple documents
      description: >-
        Valida y encola el producto cruzado de `events_type` ×
        `documents_fiscal_reference`. El procesamiento es **atómico por
        evento**: si uno falla, los demás del batch se procesan igual.


        Los eventos de **reclamo (`031`) no se aceptan acá** — deben enviarse
        uno por uno via `POST /events/single`.


        Igual que en `/events/single`, la respuesta `200` significa que los
        eventos fueron persistidos en estado `processing` y encolados, no que la
        DIAN los haya aceptado.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchDianEventsRequest'
            example:
              documents_fiscal_reference:
                - >-
                  9d3b1c0a8e2f4b6e9a8c7d1e2f3a4b5c6d7e8f901a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d
                - >-
                  1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f809
              events_type:
                - '030'
                - '032'
      responses:
        '200':
          description: Eventos aceptados y encolados.
          content:
            application/json:
              schema:
                type: object
                properties:
                  documents_fiscal_reference:
                    type: array
                    items:
                      type: string
                  message:
                    type: string
                    example: >-
                      multiple receipt events sent successfully and are being
                      processed
              example:
                documents_fiscal_reference:
                  - >-
                    9d3b1c0a8e2f4b6e9a8c7d1e2f3a4b5c6d7e8f901a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d
                  - >-
                    1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f809
                message: >-
                  multiple receipt events sent successfully and are being
                  processed
        '400':
          description: >-
            Validación de schema fallida (p. ej. más de 200 CUFEs, CUFE mal
            formado) o `events_type` incluye `031`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: >-
                  Claim events (031) cannot be sent in a batch; use the single
                  endpoint instead
                code: claim_not_allowed_in_batch
        '401':
          description: Header `api-key` ausente o inválido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    BatchDianEventsRequest:
      type: object
      required:
        - documents_fiscal_reference
        - events_type
      properties:
        documents_fiscal_reference:
          type: array
          minItems: 1
          maxItems: 200
          description: >-
            Listado de CUFEs (1..200). Cada entrada debe cumplir el formato
            CUFE.
          items:
            $ref: '#/components/schemas/Cufe'
        events_type:
          type: array
          minItems: 1
          description: >-
            Tipos de evento DIAN a encolar para cada documento. El evento `031`
            (Reclamo) no se acepta en batch.
          items:
            type: string
            enum:
              - '030'
              - '032'
              - '033'
              - '034'
    ErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          const: false
        error:
          $ref: '#/components/schemas/ErrorObject'
      example:
        success: false
        error:
          code: VALIDATION_ERROR
          message: The request contains invalid data
          details:
            amount:
              - Amount must be greater than 0
            beneficiary_id:
              - Beneficiary does not exist
    Cufe:
      type: string
      description: >-
        CUFE (Código Único de Factura Electrónica) emitido por la DIAN. Hash
        SHA-384 representado como exactamente 96 caracteres hexadecimales.
      pattern: ^[a-fA-F0-9]{96}$
      minLength: 96
      maxLength: 96
      example: >-
        9d3b1c0a8e2f4b6e9a8c7d1e2f3a4b5c6d7e8f901a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d
    ErrorObject:
      type: object
      required:
        - code
        - message
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
        details:
          anyOf:
            - $ref: '#/components/schemas/ErrorDetails'
            - type: 'null'
    ErrorCode:
      type: string
      enum:
        - VALIDATION_ERROR
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - CONFLICT
        - RATE_LIMITED
        - INTERNAL_ERROR
    ErrorDetails:
      type: object
      additionalProperties:
        type: array
        items:
          type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: api-key
      description: API key provista por Payana.

````