curl --request POST \
  --url https://api.prod.payana.cloud/public/api/v1/events/single \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "document_fiscal_reference": "9d3b1c0a8e2f4b6e9a8c7d1e2f3a4b5c6d7e8f901a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d",
  "event_type": "030"
}
'

{
  "document_fiscal_reference": "9d3b1c0a8e2f4b6e9a8c7d1e2f3a4b5c6d7e8f901a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d",
  "message": "receipt event sent successfully and is being processed"
}

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

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

{
  "message": "Document not found",
  "code": "document_not_found"
}

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

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

DIAN Events

Send DIAN Event (Single)

Valida y encola un único evento DIAN (030 Acuse de recibo, 031 Reclamo, 032 Recibo del bien, 033 Aceptación expresa, 034 Aceptación tácita) para el documento identificado por su CUFE (document_fiscal_reference).

El procesamiento es asíncrono: la respuesta 200 indica que el evento fue persistido localmente en estado processing y encolado en background — no que la DIAN ya lo haya aceptado. El estado final se puede consultar con GET /documents?fields=invoice_reception_events (más adelante también vía webhook).

Los eventos de reclamo (031) requieren response_code_list_id y description_claim, y solo pueden enviarse por este endpoint (no se aceptan en /events/batch).

POST

events

single

curl --request POST \
  --url https://api.prod.payana.cloud/public/api/v1/events/single \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "document_fiscal_reference": "9d3b1c0a8e2f4b6e9a8c7d1e2f3a4b5c6d7e8f901a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d",
  "event_type": "030"
}
'

{
  "document_fiscal_reference": "9d3b1c0a8e2f4b6e9a8c7d1e2f3a4b5c6d7e8f901a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d",
  "message": "receipt event sent successfully and is being processed"
}

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

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

{
  "message": "Document not found",
  "code": "document_not_found"
}

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

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

Authorizations

api-key

string

header

required

API key provista por Payana.

Body

application/json

document_fiscal_reference

string

required

CUFE (Código Único de Factura Electrónica) emitido por la DIAN. Hash SHA-384 representado como exactamente 96 caracteres hexadecimales.

Required string length: 96

Pattern: ^[a-fA-F0-9]{96}$

Example:

"9d3b1c0a8e2f4b6e9a8c7d1e2f3a4b5c6d7e8f901a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d"

event_type

enum<string>

required

Código del evento DIAN: 030 Acuse de recibo, 031 Reclamo, 032 Recibo del bien o servicio, 033 Aceptación expresa, 034 Aceptación tácita.

Available options:

030,

031,

032,

033,

034

response_code_list_id

enum<string>

Requerido cuando event_type=031.

Available options:

01,

02,

03,

04

description_claim

string

Descripción libre del reclamo. Requerido cuando event_type=031.

Response

Evento aceptado y encolado para procesamiento asíncrono.

document_fiscal_reference

string

Mismo CUFE recibido en el request.

message

string

Example:

"receipt event sent successfully and is being processed"

⌘I