Saltar la navegación de la documentación

Español API 2026-10-22

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

Notas de ajuste del documento equivalente

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

Ver como Markdown

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 una nota de ajuste del documento equivalente

POST /v1/equivalent_document_adjustments · createEquivalentDocumentAdjustment

Genera la nota de ajuste de un documento equivalente: crédito (94) o débito (93) según note_type. El documento que ajusta es de Trevol (equivalent_document.id) o de otra plataforma. concept 1 a 5 (el 2 anula y lleva exactamente los valores del documento). Sin customer toma el del documento; en juegos el adquirente es la DIAN. Se expide como el documento: PDF, ZIP y correo.

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 (EquivalentDocumentAdjustmentInput, obligatorio)

external_idtexto
Tu identificador del documento: único entre los documentos API de la empresa y el ambiente.
customerCustomer
Opcional con equivalent_document.id: se toma el adquirente del documento (si viene, tiene que ser el mismo).
itemslista de EquivalentAdjustmentItemobligatorio
Las líneas (1 a 500). 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.
roundingbooleano o decimal
true = redondeo al peso; o un valor entre -2.00 y 2.00.
note_typecredit | debitobligatorio
"credit" (nota de ajuste crédito, 94) o "debit" (débito, 93).
concepttextoobligatorio
Concepto de la nota (tabla 16.6): "1" devolución parcial, "2" anulación del documento (lleva exactamente sus valores), "3" rebaja o descuento, "4" ajuste de precio, "5" otros.
descriptiontexto
Opcional (20 a 5000 caracteres). Sin ella, Trevol pone el texto de la tabla (el EXACTO en la nota débito: NADBF04).
equivalent_documentEquivalentDocumentReferenceobligatorio
El documento que ajusta: {"id": "pos_…"} (de Trevol: validado, de la empresa y el ambiente de la llave) o {number, cude, issue_date, document_type, total?} si es de otra plataforma (total hace falta para anularlo).

Respuestas

Estado	Qué pasó
201	El documento (EquivalentDocumentAdjustment)
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`. (EquivalentDocumentAdjustment)
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_document_adjustments

cURL

curl -X POST "https://api.trevol.si/v1/equivalent_document_adjustments" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "TIQ-1-DEV",
  "note_type": "credit",
  "concept": "1",
  "equivalent_document": {
    "id": "pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
  },
  "items": [
    {
      "description": "Devolución gaseosa",
      "unit": "94",
      "quantity": "1",
      "unit_price": "3000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    }
  ]
}'

Probar en el Playground

Calcular una nota de ajuste del documento equivalente sin emitirla

POST /v1/equivalent_document_adjustments/preview · previewEquivalentDocumentAdjustment

Valida y calcula la nota de ajuste sin reservar un número ni enviar nada.

Cuerpo (EquivalentDocumentAdjustmentInput, obligatorio)

external_idtexto
Tu identificador del documento: único entre los documentos API de la empresa y el ambiente.
customerCustomer
Opcional con equivalent_document.id: se toma el adquirente del documento (si viene, tiene que ser el mismo).
itemslista de EquivalentAdjustmentItemobligatorio
Las líneas (1 a 500). 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.
roundingbooleano o decimal
true = redondeo al peso; o un valor entre -2.00 y 2.00.
note_typecredit | debitobligatorio
"credit" (nota de ajuste crédito, 94) o "debit" (débito, 93).
concepttextoobligatorio
Concepto de la nota (tabla 16.6): "1" devolución parcial, "2" anulación del documento (lleva exactamente sus valores), "3" rebaja o descuento, "4" ajuste de precio, "5" otros.
descriptiontexto
Opcional (20 a 5000 caracteres). Sin ella, Trevol pone el texto de la tabla (el EXACTO en la nota débito: NADBF04).
equivalent_documentEquivalentDocumentReferenceobligatorio
El documento que ajusta: {"id": "pos_…"} (de Trevol: validado, de la empresa y el ambiente de la llave) o {number, cude, issue_date, document_type, total?} si es de otra plataforma (total hace falta para anularlo).

Respuestas

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

POST /v1/equivalent_document_adjustments/preview

cURL

curl -X POST "https://api.trevol.si/v1/equivalent_document_adjustments/preview" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "TIQ-1-DEV",
  "note_type": "credit",
  "concept": "1",
  "equivalent_document": {
    "id": "pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
  },
  "items": [
    {
      "description": "Devolución gaseosa",
      "unit": "94",
      "quantity": "1",
      "unit_price": "3000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    }
  ]
}'

Probar en el Playground

Reenviar una pendiente o en error

POST /v1/equivalent_document_adjustments/{id}/send · sendEquivalentDocumentAdjustment

Vuelve a enviar una nota de ajuste pending o error.

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 (EquivalentDocumentAdjustment)
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`. (EquivalentDocumentAdjustment)
409	Error (application/problem+json) (Problem)
Error	Error (application/problem+json) (Problem)

POST /v1/equivalent_document_adjustments/{id}/send

cURL

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

Probar en el Playground

Listar (nota de ajuste del documento equivalente)

GET /v1/equivalent_document_adjustments · listEquivalentDocumentAdjustments

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

Parámetros

limitconsultaentero
starting_afterconsultatexto
statusconsultatexto
external_idconsultatexto
created_fromconsultatexto
created_toconsultatexto

Respuestas

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

GET /v1/equivalent_document_adjustments

cURL

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

Probar en el Playground

Una nota de ajuste del documento equivalente

GET /v1/equivalent_document_adjustments/{id} · retrieveEquivalentDocumentAdjustment

La nota de ajuste del documento equivalente, con equivalent_document (el documento que ajusta).

Respuestas

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

GET /v1/equivalent_document_adjustments/{id}

cURL

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

Probar en el Playground

Archivo pdf

GET /v1/equivalent_document_adjustments/{id}/pdf · downloadEquivalentDocumentAdjustmentPdf

La representación gráfica (application/pdf).

Respuestas

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

GET /v1/equivalent_document_adjustments/{id}/pdf

cURL

curl "https://api.trevol.si/v1/equivalent_document_adjustments/posa_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/pdf" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o equivalent_document_adjustment_pdf.pdf

Probar en el Playground

Archivo xml

GET /v1/equivalent_document_adjustments/{id}/xml · downloadEquivalentDocumentAdjustmentXml

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_document_adjustments/{id}/xml

cURL

curl "https://api.trevol.si/v1/equivalent_document_adjustments/posa_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/xml" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o equivalent_document_adjustment_xml.xml

Probar en el Playground

Archivo zip

GET /v1/equivalent_document_adjustments/{id}/zip · downloadEquivalentDocumentAdjustmentZip

El ZIP de entrega (application/zip).

Respuestas

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

GET /v1/equivalent_document_adjustments/{id}/zip

cURL

curl "https://api.trevol.si/v1/equivalent_document_adjustments/posa_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/zip" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o equivalent_document_adjustment_zip.zip

Probar en el Playground

Archivo dian_response

GET /v1/equivalent_document_adjustments/{id}/dian_response · downloadEquivalentDocumentAdjustmentDianResponse

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_document_adjustments/{id}/dian_response

cURL

curl "https://api.trevol.si/v1/equivalent_document_adjustments/posa_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/dian_response" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o equivalent_document_adjustment_dian_response.xml

Probar en el Playground

Corregir una nota de ajuste del documento equivalente rechazada (mismo número) y reenviarla

PUT /v1/equivalent_document_adjustments/{id} · correctEquivalentDocumentAdjustment

Corrige una nota de ajuste rechazada con el mismo número y la vuelve a enviar.

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 (EquivalentDocumentAdjustmentInput, obligatorio)

external_idtexto
Tu identificador del documento: único entre los documentos API de la empresa y el ambiente.
customerCustomer
Opcional con equivalent_document.id: se toma el adquirente del documento (si viene, tiene que ser el mismo).
itemslista de EquivalentAdjustmentItemobligatorio
Las líneas (1 a 500). 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.
roundingbooleano o decimal
true = redondeo al peso; o un valor entre -2.00 y 2.00.
note_typecredit | debitobligatorio
"credit" (nota de ajuste crédito, 94) o "debit" (débito, 93).
concepttextoobligatorio
Concepto de la nota (tabla 16.6): "1" devolución parcial, "2" anulación del documento (lleva exactamente sus valores), "3" rebaja o descuento, "4" ajuste de precio, "5" otros.
descriptiontexto
Opcional (20 a 5000 caracteres). Sin ella, Trevol pone el texto de la tabla (el EXACTO en la nota débito: NADBF04).
equivalent_documentEquivalentDocumentReferenceobligatorio
El documento que ajusta: {"id": "pos_…"} (de Trevol: validado, de la empresa y el ambiente de la llave) o {number, cude, issue_date, document_type, total?} si es de otra plataforma (total hace falta para anularlo).

Respuestas

Estado	Qué pasó
200	El documento (EquivalentDocumentAdjustment)
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`. (EquivalentDocumentAdjustment)
409	Error (application/problem+json) (Problem)
Error	Error (application/problem+json) (Problem)

PUT /v1/equivalent_document_adjustments/{id}

cURL

curl -X PUT "https://api.trevol.si/v1/equivalent_document_adjustments/posa_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "TIQ-1-DEV",
  "note_type": "credit",
  "concept": "1",
  "equivalent_document": {
    "id": "pos_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
  },
  "items": [
    {
      "description": "Devolución gaseosa",
      "unit": "94",
      "quantity": "1",
      "unit_price": "3000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    }
  ]
}'

Probar en el Playground