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 débito

Las operaciones de Notas débito de la API de Trevol: parámetros, cuerpo, respuestas y ejemplos de código.

Notas débito electrónicas.

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 débito

POST /v1/debit_notes · createDebitNote

Parámetros

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

Cuerpo (NoteInput, obligatorio)

external_idtexto
Tu identificador del documento: único entre los documentos API de la empresa y el ambiente.
customerCustomer
itemslista de Itemobligatorio
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.
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.
concepttextoobligatorio
Concepto de corrección: NC 1–6, ND 1–4.
descriptiontexto
invoiceInvoiceReference

Respuestas

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

cURL

curl -X POST "https://api.trevol.si/v1/debit_notes" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "INT-2026-000012",
  "concept": "1",
  "description": "Intereses de mora de la factura de septiembre",
  "invoice": {
    "id": "inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
  },
  "items": [
    {
      "description": "Intereses de mora",
      "unit": "94",
      "quantity": "1",
      "unit_price": "45000"
    }
  ]
}'

Probar en el Playground

Calcular una nota débito sin emitirla

POST /v1/debit_notes/preview · previewDebitNote

Cuerpo (NoteInput, obligatorio)

external_idtexto
Tu identificador del documento: único entre los documentos API de la empresa y el ambiente.
customerCustomer
itemslista de Itemobligatorio
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.
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.
concepttextoobligatorio
Concepto de corrección: NC 1–6, ND 1–4.
descriptiontexto
invoiceInvoiceReference

Respuestas

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

POST /v1/debit_notes/preview

cURL

curl -X POST "https://api.trevol.si/v1/debit_notes/preview" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "INT-2026-000012",
  "concept": "1",
  "description": "Intereses de mora de la factura de septiembre",
  "invoice": {
    "id": "inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
  },
  "items": [
    {
      "description": "Intereses de mora",
      "unit": "94",
      "quantity": "1",
      "unit_price": "45000"
    }
  ]
}'

Probar en el Playground

Reenviar una pendiente o en error

POST /v1/debit_notes/{id}/send · sendDebitNote

Respuestas

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

POST /v1/debit_notes/{id}/send

cURL

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

Probar en el Playground

Listar (nota débito)

GET /v1/debit_notes · listDebitNotes

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/debit_notes

cURL

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

Probar en el Playground

Una nota débito

GET /v1/debit_notes/{id} · retrieveDebitNote

Respuestas

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

GET /v1/debit_notes/{id}

cURL

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

Probar en el Playground

Archivo pdf

GET /v1/debit_notes/{id}/pdf · downloadDebitNotePdf

Respuestas

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

GET /v1/debit_notes/{id}/pdf

cURL

curl "https://api.trevol.si/v1/debit_notes/dn_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/pdf" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o debit_note_pdf.pdf

Probar en el Playground

Archivo xml

GET /v1/debit_notes/{id}/xml · downloadDebitNoteXml

Respuestas

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

GET /v1/debit_notes/{id}/xml

cURL

curl "https://api.trevol.si/v1/debit_notes/dn_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/xml" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o debit_note_xml.xml

Probar en el Playground

Archivo zip

GET /v1/debit_notes/{id}/zip · downloadDebitNoteZip

Respuestas

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

GET /v1/debit_notes/{id}/zip

cURL

curl "https://api.trevol.si/v1/debit_notes/dn_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/zip" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o debit_note_zip.zip

Probar en el Playground

Archivo dian_response

GET /v1/debit_notes/{id}/dian_response · downloadDebitNoteDianResponse

Respuestas

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

GET /v1/debit_notes/{id}/dian_response

cURL

curl "https://api.trevol.si/v1/debit_notes/dn_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/dian_response" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o debit_note_dian_response.xml

Probar en el Playground

Corregir una nota débito rechazada (mismo número) y reenviarla

PUT /v1/debit_notes/{id} · correctDebitNote

Parámetros

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

Cuerpo (NoteInput, obligatorio)

external_idtexto
Tu identificador del documento: único entre los documentos API de la empresa y el ambiente.
customerCustomer
itemslista de Itemobligatorio
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.
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.
concepttextoobligatorio
Concepto de corrección: NC 1–6, ND 1–4.
descriptiontexto
invoiceInvoiceReference

Respuestas

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

PUT /v1/debit_notes/{id}

cURL

curl -X PUT "https://api.trevol.si/v1/debit_notes/dn_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "INT-2026-000012",
  "concept": "1",
  "description": "Intereses de mora de la factura de septiembre",
  "invoice": {
    "id": "inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
  },
  "items": [
    {
      "description": "Intereses de mora",
      "unit": "94",
      "quantity": "1",
      "unit_price": "45000"
    }
  ]
}'

Probar en el Playground