Saltar la navegación de la documentación

Español API 2026-10-22

Documentación · Referencia · API v1 · versión 2026-10-22

Documento equivalente

Las operaciones de Documento equivalente de la API de Trevol: parámetros, cuerpo, respuestas y ejemplos de código.

Documento equivalente electrónico (tiquete POS 20 y los tipos 25, 27, 30, 35, 40, 45, 50, 55 y 60) y su nota de ajuste (crédito 94 y débito 93). Se expiden como la factura: PDF, ZIP y correo.

Los ejemplos son peticiones con cURL. La llave va en TREVOL_API_KEY; los cuerpos de ejemplo son los de la especificación. Los errores comunes están en Errores.

Emitir un documento equivalente

POST /v1/equivalent_documents · createEquivalentDocument

Genera un documento equivalente electrónico: el tiquete POS (20, por defecto) o cualquiera de los otros nueve tipos de la tabla 16.3 (document_type: 25 cine, 27 espectáculos, 30 juegos, 35 transporte, 40 peajes, 45 extracto, 50 tiquete aéreo, 55 bolsa de valores, 60 servicios públicos; cada uno con su información propia en extension). El POS lleva su caja en pos.register y, si la empresa tiene varias cajas, el prefijo de su resolución en numbering.prefix. Se expide como la factura: PDF, ZIP y correo después del 201 (espera equivalent_document.delivered o consulta delivery.status). La contingencia 07 (documento físico) se pide con contingency; la 08 (la DIAN no contestó) la decide Trevol y responde 202 con status: contingency. En habilitación, el set de pruebas por tipo es automático: mientras la DIAN lo valida responde 202 validating en las dos versiones y reintentar no vuelve a mandarlo. Cómo se calcula el CUDE del POS depende del despliegue del servicio, no de la empresa.

Respuestas. 201 la DIAN lo validó (status: accepted). 202 solo en la versión 2026-10-22: la DIAN no contestó (processing), otra petición lo está enviando (sending) o, en habilitación, el set de pruebas todavía lo valida (validating, en las dos versiones); trae Location y Retry-After, y el resultado llega por GET y por webhook: no crees otro documento para la misma operación. 422 validation_error (se revisó a fondo ANTES de reservar: no se gastó el número, y errors[] dice el campo), dian_rejected (con document y las reglas traducidas; corrige con PUT y el mismo número), company_not_enabled o numbering_unavailable (con reason). 402 insufficient_balance (producción sin saldo: queda pending con su número). 409 external_id_in_use o duplicate_document (con existing_id). 503 dian_unavailable en la 2026-10-21. Pide Idempotency-Key: repetir la misma devuelve lo mismo sin enviar nada.

Parámetros

Idempotency-Keycabeceratextoobligatorio
Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).

Cuerpo (EquivalentDocumentInput, obligatorio)

external_idtexto
Tu identificador del documento: único entre los documentos API de la empresa y el ambiente.
customerCustomer
El adquirente. Para consumidor final: {"final_consumer": true}. La relación de juegos (30) no lleva customer: el adquirente es la DIAN.
itemslista de EquivalentItemobligatorio
Las líneas (1 a 500). Retenciones solo como autorretenciones del emisor (self_withholding: true). Máximo 500.
paymentPayment
noteslista de texto
Máximo 10.
periodPeriod
referencesReferences
allowance_chargeslista de AllowanceCharge
Descuentos y recargos globales (no tocan las bases). Máximo 20.
prepaymentslista de Prepayment
Anticipos (informativos: no restan del total). Máximo 20.
withholdingslista de Withholding
Retenciones (informativas): 05 ReteIVA, 06 ReteRenta, 07 ReteICA. Máximo 10.
roundingbooleano o decimal
true = redondeo al peso; o un valor entre -2.00 y 2.00.
document_typetexto
Tipo de documento equivalente (tabla 16.3): "20" tiquete POS (por defecto), "25" boleta de cine, "27" espectáculos públicos, "30" juegos localizados y no localizados (se acepta "32"), "35" transporte de pasajeros, "40" peajes, "45" extracto, "50" tiquete aéreo, "55" bolsa de valores o "60" servicios públicos.
operation_typetexto
Tipo de operación (CustomizationID, tabla 16.4.1) del tipo de documento. Por defecto, el primero del tipo ("10" en el POS).
posPos
Obligatorio en el tiquete POS (20) y prohibido en los demás: la caja que expide el tiquete y, opcional, los beneficios del comprador.
extensionExtension
La información propia del tipo, con UNA clave, la de su document_type: cinema (25), show (27), games (30), transport (35), air (50), stock_exchange (55) o public_services (60). Prohibida en el POS (20), peajes (40) y extracto (45).
prefixtexto
Solo en los tipos sin resolución (todos menos el POS): el prefijo del consecutivo propio (1 a 4 letras o dígitos). Por defecto, el del tipo (DEC, DEEP, DEJL, DETT, DEP, EXT, DETA, DEBV, SPD).
origin_noteOriginNote
La nota de ajuste que dio origen a este documento (opcional).
contingencyContingency
Solo la contingencia 07 (el emisor transcribe un documento físico): physical_document con number, date y type. La 08 (la DIAN no contestó) no se pide: la decide Trevol y el documento responde 202 con status: contingency.
numberingNumbering
Solo en el POS: el prefijo de la resolución POS que numera (una empresa con varias cajas o establecimientos tiene varias). Sin él, la más nueva vigente. Si no existe, numbering_unavailable (no_resolution).

Respuestas

Estado	Qué pasó
201	El documento (EquivalentDocument)
202	Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`. (EquivalentDocument)
402	Error (application/problem+json) (Problem)
409	Error (application/problem+json) (Problem)
422	Error (application/problem+json) (Problem)
429	Error (application/problem+json) (Problem)
503	Error (application/problem+json) (Problem)
Error	Error (application/problem+json) (Problem)

POST /v1/equivalent_documents

cURL

curl -X POST "https://api.trevol.si/v1/equivalent_documents" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "TIQ-1",
  "customer": {
    "final_consumer": true
  },
  "pos": {
    "register": {
      "plate": "CJ-01",
      "location": "Local 1, Jamundí",
      "cashier": "PEREZ ANA",
      "type": "Caja principal"
    }
  },
  "numbering": {
    "prefix": "POS2"
  },
  "payment": {
    "form": "cash",
    "methods": [
      {
        "code": "10"
      }
    ]
  },
  "items": [
    {
      "description": "Gaseosa 400 ml",
      "code": "GAS-1",
      "unit": "94",
      "quantity": "2",
      "unit_price": "3000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    },
    {
      "description": "Almuerzo",
      "unit": "94",
      "quantity": "1",
      "unit_price": "18000"
    }
  ]
}'

Probar en el Playground

Respuesta201 Created

{
  "id": "pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
  "object": "equivalent_document",
  "environment": "test",
  "status": "accepted",
  "number": "POS2994001",
  "prefix": "POS2",
  "external_id": "TIQ-1",
  "origin": "api",
  "cude": "abababababababababababababababababababababababababababababababababababababababababababababababab",
  "qr": "https://catalogo-vpfe-hab.dian.gov.co/document/searchqr?documentkey=abababababababababababababababababababababababababababababababababababababababababababababababab",
  "issued_at": "2026-10-23T09:15:02-05:00",
  "customer": {
    "final_consumer": true
  },
  "items": [
    {
      "description": "Gaseosa 400 ml",
      "code": "GAS-1",
      "unit": "94",
      "quantity": "2",
      "unit_price": "3000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    },
    {
      "description": "Almuerzo",
      "unit": "94",
      "quantity": "1",
      "unit_price": "18000"
    }
  ],
  "payment": {
    "form": "cash",
    "methods": [
      {
        "code": "10"
      }
    ]
  },
  "document_type": "20",
  "operation_type": "22",
  "pos": {
    "register": {
      "plate": "CJ-01",
      "location": "Local 1, Jamundí",
      "cashier": "PEREZ ANA",
      "type": "Caja principal"
    }
  },
  "contingency": null,
  "totals": {
    "subtotal": "24000.00",
    "discounts": "0.00",
    "line_extension": "24000.00",
    "tax_exclusive": "6000.00",
    "taxes": [
      {
        "code": "01",
        "name": "IVA",
        "rate": "19.00",
        "base": "6000.00",
        "amount": "1140.00"
      }
    ],
    "allowances": "0.00",
    "charges": "0.00",
    "rounding": "0.00",
    "total": "25140.00",
    "withholdings": [],
    "prepayments": "0.00",
    "net_payable": null,
    "items": [
      {
        "gross": "6000.00",
        "discount": "0.00",
        "line_extension": "6000.00"
      },
      {
        "gross": "18000.00",
        "discount": "0.00",
        "line_extension": "18000.00"
      }
    ]
  },
  "dian": {
    "status_code": "00",
    "message": "Procesado Correctamente.",
    "rules": []
  },
  "delivery": {
    "status": "pending",
    "pdf": false,
    "zip": false,
    "xml": true,
    "email": {
      "status": "pending",
      "to": null,
      "detail": null
    }
  },
  "created_at": "2026-10-23T09:15:02-05:00",
  "updated_at": "2026-10-23T09:15:03-05:00"
}

Calcular un documento equivalente sin emitirlo

POST /v1/equivalent_documents/preview · previewEquivalentDocument

Valida y calcula los totales sin reservar un número ni enviar nada. No pide Idempotency-Key.

Cuerpo (EquivalentDocumentInput, obligatorio)

external_idtexto
Tu identificador del documento: único entre los documentos API de la empresa y el ambiente.
customerCustomer
El adquirente. Para consumidor final: {"final_consumer": true}. La relación de juegos (30) no lleva customer: el adquirente es la DIAN.
itemslista de EquivalentItemobligatorio
Las líneas (1 a 500). Retenciones solo como autorretenciones del emisor (self_withholding: true). Máximo 500.
paymentPayment
noteslista de texto
Máximo 10.
periodPeriod
referencesReferences
allowance_chargeslista de AllowanceCharge
Descuentos y recargos globales (no tocan las bases). Máximo 20.
prepaymentslista de Prepayment
Anticipos (informativos: no restan del total). Máximo 20.
withholdingslista de Withholding
Retenciones (informativas): 05 ReteIVA, 06 ReteRenta, 07 ReteICA. Máximo 10.
roundingbooleano o decimal
true = redondeo al peso; o un valor entre -2.00 y 2.00.
document_typetexto
Tipo de documento equivalente (tabla 16.3): "20" tiquete POS (por defecto), "25" boleta de cine, "27" espectáculos públicos, "30" juegos localizados y no localizados (se acepta "32"), "35" transporte de pasajeros, "40" peajes, "45" extracto, "50" tiquete aéreo, "55" bolsa de valores o "60" servicios públicos.
operation_typetexto
Tipo de operación (CustomizationID, tabla 16.4.1) del tipo de documento. Por defecto, el primero del tipo ("10" en el POS).
posPos
Obligatorio en el tiquete POS (20) y prohibido en los demás: la caja que expide el tiquete y, opcional, los beneficios del comprador.
extensionExtension
La información propia del tipo, con UNA clave, la de su document_type: cinema (25), show (27), games (30), transport (35), air (50), stock_exchange (55) o public_services (60). Prohibida en el POS (20), peajes (40) y extracto (45).
prefixtexto
Solo en los tipos sin resolución (todos menos el POS): el prefijo del consecutivo propio (1 a 4 letras o dígitos). Por defecto, el del tipo (DEC, DEEP, DEJL, DETT, DEP, EXT, DETA, DEBV, SPD).
origin_noteOriginNote
La nota de ajuste que dio origen a este documento (opcional).
contingencyContingency
Solo la contingencia 07 (el emisor transcribe un documento físico): physical_document con number, date y type. La 08 (la DIAN no contestó) no se pide: la decide Trevol y el documento responde 202 con status: contingency.
numberingNumbering
Solo en el POS: el prefijo de la resolución POS que numera (una empresa con varias cajas o establecimientos tiene varias). Sin él, la más nueva vigente. Si no existe, numbering_unavailable (no_resolution).

Respuestas

Estado	Qué pasó
200	Totales (Preview)
Error	Error (application/problem+json) (Problem)

POST /v1/equivalent_documents/preview

cURL

curl -X POST "https://api.trevol.si/v1/equivalent_documents/preview" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "TIQ-1",
  "customer": {
    "final_consumer": true
  },
  "pos": {
    "register": {
      "plate": "CJ-01",
      "location": "Local 1, Jamundí",
      "cashier": "PEREZ ANA",
      "type": "Caja principal"
    }
  },
  "numbering": {
    "prefix": "POS2"
  },
  "payment": {
    "form": "cash",
    "methods": [
      {
        "code": "10"
      }
    ]
  },
  "items": [
    {
      "description": "Gaseosa 400 ml",
      "code": "GAS-1",
      "unit": "94",
      "quantity": "2",
      "unit_price": "3000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    },
    {
      "description": "Almuerzo",
      "unit": "94",
      "quantity": "1",
      "unit_price": "18000"
    }
  ]
}'

Probar en el Playground

Reenviar una pendiente o en error

POST /v1/equivalent_documents/{id}/send · sendEquivalentDocument

Vuelve a enviar un documento equivalente pending o error. En contingencia devuelve el documento (lo reenvía Trevol). Con el set de pruebas en curso (validating) solo consulta: no lo vuelve a mandar.

Sin cuerpo. Con un documento accepted responde 200 con el documento tal cual; con uno que la DIAN todavía verifica no reenvía nada (202); con uno rejected es 409 invalid_state (se corrige con PUT). No pide Idempotency-Key (reintentarlo es seguro).

Respuestas

Estado	Qué pasó
200	El documento (EquivalentDocument)
202	Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`. (EquivalentDocument)
409	Error (application/problem+json) (Problem)
Error	Error (application/problem+json) (Problem)

POST /v1/equivalent_documents/{id}/send

cURL

curl -X POST "https://api.trevol.si/v1/equivalent_documents/pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/send" \
  -H "Authorization: Bearer $TREVOL_API_KEY"

Probar en el Playground

Respuesta200 OK

{
  "id": "pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
  "object": "equivalent_document",
  "environment": "test",
  "status": "accepted",
  "number": "POS2994001",
  "prefix": "POS2",
  "external_id": "TIQ-1",
  "origin": "api",
  "cude": "abababababababababababababababababababababababababababababababababababababababababababababababab",
  "qr": "https://catalogo-vpfe-hab.dian.gov.co/document/searchqr?documentkey=abababababababababababababababababababababababababababababababababababababababababababababababab",
  "issued_at": "2026-10-23T09:15:02-05:00",
  "customer": {
    "final_consumer": true
  },
  "items": [
    {
      "description": "Gaseosa 400 ml",
      "code": "GAS-1",
      "unit": "94",
      "quantity": "2",
      "unit_price": "3000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    },
    {
      "description": "Almuerzo",
      "unit": "94",
      "quantity": "1",
      "unit_price": "18000"
    }
  ],
  "payment": {
    "form": "cash",
    "methods": [
      {
        "code": "10"
      }
    ]
  },
  "document_type": "20",
  "operation_type": "22",
  "pos": {
    "register": {
      "plate": "CJ-01",
      "location": "Local 1, Jamundí",
      "cashier": "PEREZ ANA",
      "type": "Caja principal"
    }
  },
  "contingency": null,
  "totals": {
    "subtotal": "24000.00",
    "discounts": "0.00",
    "line_extension": "24000.00",
    "tax_exclusive": "6000.00",
    "taxes": [
      {
        "code": "01",
        "name": "IVA",
        "rate": "19.00",
        "base": "6000.00",
        "amount": "1140.00"
      }
    ],
    "allowances": "0.00",
    "charges": "0.00",
    "rounding": "0.00",
    "total": "25140.00",
    "withholdings": [],
    "prepayments": "0.00",
    "net_payable": null,
    "items": [
      {
        "gross": "6000.00",
        "discount": "0.00",
        "line_extension": "6000.00"
      },
      {
        "gross": "18000.00",
        "discount": "0.00",
        "line_extension": "18000.00"
      }
    ]
  },
  "dian": {
    "status_code": "00",
    "message": "Procesado Correctamente.",
    "rules": []
  },
  "delivery": {
    "status": "pending",
    "pdf": false,
    "zip": false,
    "xml": true,
    "email": {
      "status": "pending",
      "to": null,
      "detail": null
    }
  },
  "created_at": "2026-10-23T09:15:02-05:00",
  "updated_at": "2026-10-23T09:15:03-05:00"
}

Listar (documento equivalente)

GET /v1/equivalent_documents · listEquivalentDocuments

Paginación por cursor (limit hasta 100, starting_after) y filtros status, external_id, created_from y created_to. status=error trae también los que están en verificación (processing). Además, document_type filtra por tipo.

Parámetros

limitconsultaentero
starting_afterconsultatexto
statusconsultatexto
external_idconsultatexto
created_fromconsultatexto
created_toconsultatexto
document_typeconsulta20 | 25 | 27 | 30 | 35 | 40 | 45 | 50 | 55 | 60

Respuestas

Estado	Qué pasó
200	{object: list, data, has_more, next_cursor} (objeto)
Error	Error (application/problem+json) (Problem)

GET /v1/equivalent_documents

cURL

curl "https://api.trevol.si/v1/equivalent_documents?limit=100" \
  -H "Authorization: Bearer $TREVOL_API_KEY"

Probar en el Playground

Un documento equivalente

GET /v1/equivalent_documents/{id} · retrieveEquivalentDocument

El documento equivalente tal como se emitió. contingency dice si salió en contingencia (07 u 08) y, en la 08, cuándo se mandó el respaldo POS.

Respuestas

Estado	Qué pasó
200	El documento (EquivalentDocument)
Error	Error (application/problem+json) (Problem)

GET /v1/equivalent_documents/{id}

cURL

curl "https://api.trevol.si/v1/equivalent_documents/pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b" \
  -H "Authorization: Bearer $TREVOL_API_KEY"

Probar en el Playground

Respuesta200 OK

{
  "id": "pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
  "object": "equivalent_document",
  "environment": "test",
  "status": "accepted",
  "number": "POS2994001",
  "prefix": "POS2",
  "external_id": "TIQ-1",
  "origin": "api",
  "cude": "abababababababababababababababababababababababababababababababababababababababababababababababab",
  "qr": "https://catalogo-vpfe-hab.dian.gov.co/document/searchqr?documentkey=abababababababababababababababababababababababababababababababababababababababababababababababab",
  "issued_at": "2026-10-23T09:15:02-05:00",
  "customer": {
    "final_consumer": true
  },
  "items": [
    {
      "description": "Gaseosa 400 ml",
      "code": "GAS-1",
      "unit": "94",
      "quantity": "2",
      "unit_price": "3000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    },
    {
      "description": "Almuerzo",
      "unit": "94",
      "quantity": "1",
      "unit_price": "18000"
    }
  ],
  "payment": {
    "form": "cash",
    "methods": [
      {
        "code": "10"
      }
    ]
  },
  "document_type": "20",
  "operation_type": "22",
  "pos": {
    "register": {
      "plate": "CJ-01",
      "location": "Local 1, Jamundí",
      "cashier": "PEREZ ANA",
      "type": "Caja principal"
    }
  },
  "contingency": null,
  "totals": {
    "subtotal": "24000.00",
    "discounts": "0.00",
    "line_extension": "24000.00",
    "tax_exclusive": "6000.00",
    "taxes": [
      {
        "code": "01",
        "name": "IVA",
        "rate": "19.00",
        "base": "6000.00",
        "amount": "1140.00"
      }
    ],
    "allowances": "0.00",
    "charges": "0.00",
    "rounding": "0.00",
    "total": "25140.00",
    "withholdings": [],
    "prepayments": "0.00",
    "net_payable": null,
    "items": [
      {
        "gross": "6000.00",
        "discount": "0.00",
        "line_extension": "6000.00"
      },
      {
        "gross": "18000.00",
        "discount": "0.00",
        "line_extension": "18000.00"
      }
    ]
  },
  "dian": {
    "status_code": "00",
    "message": "Procesado Correctamente.",
    "rules": []
  },
  "delivery": {
    "status": "pending",
    "pdf": false,
    "zip": false,
    "xml": true,
    "email": {
      "status": "pending",
      "to": null,
      "detail": null
    }
  },
  "created_at": "2026-10-23T09:15:02-05:00",
  "updated_at": "2026-10-23T09:15:03-05:00"
}

Archivo pdf

GET /v1/equivalent_documents/{id}/pdf · downloadEquivalentDocumentPdf

La representación gráfica (application/pdf). Si todavía no se hizo, se genera en el momento.

Respuestas

Estado	Qué pasó
200	pdf (archivo)
Error	Error (application/problem+json) (Problem)

GET /v1/equivalent_documents/{id}/pdf

cURL

curl "https://api.trevol.si/v1/equivalent_documents/pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/pdf" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o equivalent_document_pdf.pdf

Probar en el Playground

Archivo xml

GET /v1/equivalent_documents/{id}/xml · downloadEquivalentDocumentXml

El XML firmado que se mandó a la DIAN (application/xml).

Respuestas

Estado	Qué pasó
200	xml (archivo)
Error	Error (application/problem+json) (Problem)

GET /v1/equivalent_documents/{id}/xml

cURL

curl "https://api.trevol.si/v1/equivalent_documents/pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/xml" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o equivalent_document_xml.xml

Probar en el Playground

Archivo zip

GET /v1/equivalent_documents/{id}/zip · downloadEquivalentDocumentZip

El ZIP de entrega con el XML firmado y el PDF (application/zip).

Respuestas

Estado	Qué pasó
200	zip (archivo)
Error	Error (application/problem+json) (Problem)

GET /v1/equivalent_documents/{id}/zip

cURL

curl "https://api.trevol.si/v1/equivalent_documents/pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/zip" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o equivalent_document_zip.zip

Probar en el Playground

Archivo dian_response

GET /v1/equivalent_documents/{id}/dian_response · downloadEquivalentDocumentDianResponse

El ApplicationResponse con que la DIAN contestó (application/xml).

Respuestas

Estado	Qué pasó
200	dian_response (archivo)
Error	Error (application/problem+json) (Problem)

GET /v1/equivalent_documents/{id}/dian_response

cURL

curl "https://api.trevol.si/v1/equivalent_documents/pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/dian_response" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o equivalent_document_dian_response.xml

Probar en el Playground

Corregir un documento equivalente rechazado (mismo número) y reenviarlo

PUT /v1/equivalent_documents/{id} · correctEquivalentDocument

Corrige un documento equivalente rechazado con el mismo número y lo vuelve a enviar. Con el set de pruebas en curso responde 409 invalid_state.

Solo si el documento está rejected, error o pending. Uno accepted no se corrige (se ajusta con una nota) y uno que la DIAN todavía verifica es 409 invalid_state: espera el resultado. El external_id y la numeración no se cambian. Pide Idempotency-Key.

Parámetros

Idempotency-Keycabeceratextoobligatorio
Obligatoria: 1 a 255 caracteres ASCII visibles, única por pedido (7 días).

Cuerpo (EquivalentDocumentInput, obligatorio)

external_idtexto
Tu identificador del documento: único entre los documentos API de la empresa y el ambiente.
customerCustomer
El adquirente. Para consumidor final: {"final_consumer": true}. La relación de juegos (30) no lleva customer: el adquirente es la DIAN.
itemslista de EquivalentItemobligatorio
Las líneas (1 a 500). Retenciones solo como autorretenciones del emisor (self_withholding: true). Máximo 500.
paymentPayment
noteslista de texto
Máximo 10.
periodPeriod
referencesReferences
allowance_chargeslista de AllowanceCharge
Descuentos y recargos globales (no tocan las bases). Máximo 20.
prepaymentslista de Prepayment
Anticipos (informativos: no restan del total). Máximo 20.
withholdingslista de Withholding
Retenciones (informativas): 05 ReteIVA, 06 ReteRenta, 07 ReteICA. Máximo 10.
roundingbooleano o decimal
true = redondeo al peso; o un valor entre -2.00 y 2.00.
document_typetexto
Tipo de documento equivalente (tabla 16.3): "20" tiquete POS (por defecto), "25" boleta de cine, "27" espectáculos públicos, "30" juegos localizados y no localizados (se acepta "32"), "35" transporte de pasajeros, "40" peajes, "45" extracto, "50" tiquete aéreo, "55" bolsa de valores o "60" servicios públicos.
operation_typetexto
Tipo de operación (CustomizationID, tabla 16.4.1) del tipo de documento. Por defecto, el primero del tipo ("10" en el POS).
posPos
Obligatorio en el tiquete POS (20) y prohibido en los demás: la caja que expide el tiquete y, opcional, los beneficios del comprador.
extensionExtension
La información propia del tipo, con UNA clave, la de su document_type: cinema (25), show (27), games (30), transport (35), air (50), stock_exchange (55) o public_services (60). Prohibida en el POS (20), peajes (40) y extracto (45).
prefixtexto
Solo en los tipos sin resolución (todos menos el POS): el prefijo del consecutivo propio (1 a 4 letras o dígitos). Por defecto, el del tipo (DEC, DEEP, DEJL, DETT, DEP, EXT, DETA, DEBV, SPD).
origin_noteOriginNote
La nota de ajuste que dio origen a este documento (opcional).
contingencyContingency
Solo la contingencia 07 (el emisor transcribe un documento físico): physical_document con number, date y type. La 08 (la DIAN no contestó) no se pide: la decide Trevol y el documento responde 202 con status: contingency.
numberingNumbering
Solo en el POS: el prefijo de la resolución POS que numera (una empresa con varias cajas o establecimientos tiene varias). Sin él, la más nueva vigente. Si no existe, numbering_unavailable (no_resolution).

Respuestas

Estado	Qué pasó
200	El documento (EquivalentDocument)
202	Versión 2026-10-22: la DIAN no contestó (`status: processing`; Trevol termina el documento y avisa por webhook; no crees otro documento para la misma venta, y si repites con la misma Idempotency-Key respondemos sin enviar) o el documento se está enviando (`status: sending`); también la contingencia (`status: contingency`). Lleva `Location` y, salvo la contingencia, `Retry-After: 30`. En 2026-10-21 la DIAN sin contestar es un 503 `dian_unavailable`. (EquivalentDocument)
409	Error (application/problem+json) (Problem)
Error	Error (application/problem+json) (Problem)

PUT /v1/equivalent_documents/{id}

cURL

curl -X PUT "https://api.trevol.si/v1/equivalent_documents/pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "TIQ-1",
  "customer": {
    "final_consumer": true
  },
  "pos": {
    "register": {
      "plate": "CJ-01",
      "location": "Local 1, Jamundí",
      "cashier": "PEREZ ANA",
      "type": "Caja principal"
    }
  },
  "numbering": {
    "prefix": "POS2"
  },
  "payment": {
    "form": "cash",
    "methods": [
      {
        "code": "10"
      }
    ]
  },
  "items": [
    {
      "description": "Gaseosa 400 ml",
      "code": "GAS-1",
      "unit": "94",
      "quantity": "2",
      "unit_price": "3000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    },
    {
      "description": "Almuerzo",
      "unit": "94",
      "quantity": "1",
      "unit_price": "18000"
    }
  ]
}'

Probar en el Playground

Respuesta200 OK

{
  "id": "pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
  "object": "equivalent_document",
  "environment": "test",
  "status": "accepted",
  "number": "POS2994001",
  "prefix": "POS2",
  "external_id": "TIQ-1",
  "origin": "api",
  "cude": "abababababababababababababababababababababababababababababababababababababababababababababababab",
  "qr": "https://catalogo-vpfe-hab.dian.gov.co/document/searchqr?documentkey=abababababababababababababababababababababababababababababababababababababababababababababababab",
  "issued_at": "2026-10-23T09:15:02-05:00",
  "customer": {
    "final_consumer": true
  },
  "items": [
    {
      "description": "Gaseosa 400 ml",
      "code": "GAS-1",
      "unit": "94",
      "quantity": "2",
      "unit_price": "3000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    },
    {
      "description": "Almuerzo",
      "unit": "94",
      "quantity": "1",
      "unit_price": "18000"
    }
  ],
  "payment": {
    "form": "cash",
    "methods": [
      {
        "code": "10"
      }
    ]
  },
  "document_type": "20",
  "operation_type": "22",
  "pos": {
    "register": {
      "plate": "CJ-01",
      "location": "Local 1, Jamundí",
      "cashier": "PEREZ ANA",
      "type": "Caja principal"
    }
  },
  "contingency": null,
  "totals": {
    "subtotal": "24000.00",
    "discounts": "0.00",
    "line_extension": "24000.00",
    "tax_exclusive": "6000.00",
    "taxes": [
      {
        "code": "01",
        "name": "IVA",
        "rate": "19.00",
        "base": "6000.00",
        "amount": "1140.00"
      }
    ],
    "allowances": "0.00",
    "charges": "0.00",
    "rounding": "0.00",
    "total": "25140.00",
    "withholdings": [],
    "prepayments": "0.00",
    "net_payable": null,
    "items": [
      {
        "gross": "6000.00",
        "discount": "0.00",
        "line_extension": "6000.00"
      },
      {
        "gross": "18000.00",
        "discount": "0.00",
        "line_extension": "18000.00"
      }
    ]
  },
  "dian": {
    "status_code": "00",
    "message": "Procesado Correctamente.",
    "rules": []
  },
  "delivery": {
    "status": "pending",
    "pdf": false,
    "zip": false,
    "xml": true,
    "email": {
      "status": "pending",
      "to": null,
      "detail": null
    }
  },
  "created_at": "2026-10-23T09:15:02-05:00",
  "updated_at": "2026-10-23T09:15:03-05:00"
}