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 crédito

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

Notas crédito 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 crédito

POST /v1/credit_notes · createCreditNote

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

cURL

curl -X POST "https://api.trevol.si/v1/credit_notes" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "DEV-2026-000045",
  "concept": "1",
  "description": "Devolución de una unidad por empaque dañado",
  "invoice": {
    "id": "inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
  },
  "items": [
    {
      "description": "Café especial 500 g",
      "code": "CAF-500",
      "unit": "94",
      "quantity": "1",
      "unit_price": "32000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    }
  ]
}'

Probar en el Playground

Calcular una nota crédito sin emitirla

POST /v1/credit_notes/preview · previewCreditNote

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/credit_notes/preview

cURL

curl -X POST "https://api.trevol.si/v1/credit_notes/preview" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "DEV-2026-000045",
  "concept": "1",
  "description": "Devolución de una unidad por empaque dañado",
  "invoice": {
    "id": "inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
  },
  "items": [
    {
      "description": "Café especial 500 g",
      "code": "CAF-500",
      "unit": "94",
      "quantity": "1",
      "unit_price": "32000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    }
  ]
}'

Probar en el Playground

Reenviar una pendiente o en error

POST /v1/credit_notes/{id}/send · sendCreditNote

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/credit_notes/{id}/send

cURL

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

Probar en el Playground

Listar (nota crédito)

GET /v1/credit_notes · listCreditNotes

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

cURL

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

Probar en el Playground

Una nota crédito

GET /v1/credit_notes/{id} · retrieveCreditNote

Respuestas

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

GET /v1/credit_notes/{id}

cURL

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

Probar en el Playground

Archivo pdf

GET /v1/credit_notes/{id}/pdf · downloadCreditNotePdf

Respuestas

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

GET /v1/credit_notes/{id}/pdf

cURL

curl "https://api.trevol.si/v1/credit_notes/cn_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/pdf" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o credit_note_pdf.pdf

Probar en el Playground

Archivo xml

GET /v1/credit_notes/{id}/xml · downloadCreditNoteXml

Respuestas

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

GET /v1/credit_notes/{id}/xml

cURL

curl "https://api.trevol.si/v1/credit_notes/cn_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/xml" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o credit_note_xml.xml

Probar en el Playground

Archivo zip

GET /v1/credit_notes/{id}/zip · downloadCreditNoteZip

Respuestas

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

GET /v1/credit_notes/{id}/zip

cURL

curl "https://api.trevol.si/v1/credit_notes/cn_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/zip" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o credit_note_zip.zip

Probar en el Playground

Archivo dian_response

GET /v1/credit_notes/{id}/dian_response · downloadCreditNoteDianResponse

Respuestas

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

GET /v1/credit_notes/{id}/dian_response

cURL

curl "https://api.trevol.si/v1/credit_notes/cn_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/dian_response" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o credit_note_dian_response.xml

Probar en el Playground

Corregir una nota crédito rechazada (mismo número) y reenviarla

PUT /v1/credit_notes/{id} · correctCreditNote

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

cURL

curl -X PUT "https://api.trevol.si/v1/credit_notes/cn_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "DEV-2026-000045",
  "concept": "1",
  "description": "Devolución de una unidad por empaque dañado",
  "invoice": {
    "id": "inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
  },
  "items": [
    {
      "description": "Café especial 500 g",
      "code": "CAF-500",
      "unit": "94",
      "quantity": "1",
      "unit_price": "32000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    }
  ]
}'

Probar en el Playground