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 soporte

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

Ver como Markdown

Documento soporte en adquisiciones a no obligados a facturar (05) y su nota de ajuste (95). Se generan, no se expiden: sin PDF, ZIP ni 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 soporte

POST /v1/support_document_adjustments · createSupportDocumentAdjustment

Genera la nota de ajuste de un documento soporte (95): corrige o anula una compra ya validada. El documento que ajusta es de Trevol (support_document.id) o de otra plataforma (number, cuds, issue_date y total). concept 1 a 5; el 2 anula y lleva exactamente los valores del documento. Sin seller hereda el del documento de Trevol. La suma de las notas no puede pasar del saldo del documento. Un documento soporte rechazado no se ajusta: se corrige con PUT.

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

external_idtexto
Tu identificador del documento: único entre los documentos API de la empresa y el ambiente.
sellerSeller
Opcional con support_document.id: se toma el vendedor del documento soporte (si viene, tiene que ser el mismo).
itemslista de SupportAdjustmentItemobligatorio
Las líneas de la nota (1 a 500): sin retenciones ni fecha de compra. Máximo 500.
paymentPayment
noteslista de texto
Máximo 10.
referencesReferences
allowance_chargeslista de AllowanceCharge
Descuentos y recargos globales (no tocan las bases). Máximo 20.
currencySupportCurrency
concepttextoobligatorio
Concepto de la nota de ajuste (tabla 16.2.4): "1" devolución parcial, "2" anulación del documento soporte (lleva exactamente sus valores), "3" rebaja o descuento, "4" ajuste de precio, "5" otros.
descriptiontextoobligatorio
Qué se corrige y por qué (de 20 a 5000 caracteres, NSBF04).
support_documentSupportDocumentReferenceobligatorio
El documento soporte que ajusta: {"id": "sd_…"} (de Trevol: validado, de la empresa y el ambiente de la llave) o {number, cuds, issue_date, total?} si es de otra plataforma (total hace falta para anularlo).

Respuestas

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

cURL

curl -X POST "https://api.trevol.si/v1/support_document_adjustments" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "OC-991-ANULA",
  "concept": "2",
  "description": "Anulación: la compra de leche se registró dos veces en el ERP",
  "support_document": {
    "id": "sd_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
  },
  "items": [
    {
      "description": "Leche cruda",
      "unit": "LTR",
      "quantity": "120",
      "unit_price": "1800"
    }
  ]
}'

Probar en el Playground

Calcular una nota de ajuste del documento soporte sin emitirla

POST /v1/support_document_adjustments/preview · previewSupportDocumentAdjustment

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

Cuerpo (SupportDocumentAdjustmentInput, obligatorio)

external_idtexto
Tu identificador del documento: único entre los documentos API de la empresa y el ambiente.
sellerSeller
Opcional con support_document.id: se toma el vendedor del documento soporte (si viene, tiene que ser el mismo).
itemslista de SupportAdjustmentItemobligatorio
Las líneas de la nota (1 a 500): sin retenciones ni fecha de compra. Máximo 500.
paymentPayment
noteslista de texto
Máximo 10.
referencesReferences
allowance_chargeslista de AllowanceCharge
Descuentos y recargos globales (no tocan las bases). Máximo 20.
currencySupportCurrency
concepttextoobligatorio
Concepto de la nota de ajuste (tabla 16.2.4): "1" devolución parcial, "2" anulación del documento soporte (lleva exactamente sus valores), "3" rebaja o descuento, "4" ajuste de precio, "5" otros.
descriptiontextoobligatorio
Qué se corrige y por qué (de 20 a 5000 caracteres, NSBF04).
support_documentSupportDocumentReferenceobligatorio
El documento soporte que ajusta: {"id": "sd_…"} (de Trevol: validado, de la empresa y el ambiente de la llave) o {number, cuds, issue_date, 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/support_document_adjustments/preview

cURL

curl -X POST "https://api.trevol.si/v1/support_document_adjustments/preview" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "OC-991-ANULA",
  "concept": "2",
  "description": "Anulación: la compra de leche se registró dos veces en el ERP",
  "support_document": {
    "id": "sd_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
  },
  "items": [
    {
      "description": "Leche cruda",
      "unit": "LTR",
      "quantity": "120",
      "unit_price": "1800"
    }
  ]
}'

Probar en el Playground

Reenviar una pendiente o en error

POST /v1/support_document_adjustments/{id}/send · sendSupportDocumentAdjustment

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

POST /v1/support_document_adjustments/{id}/send

cURL

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

Probar en el Playground

Listar (nota de ajuste del documento soporte)

GET /v1/support_document_adjustments · listSupportDocumentAdjustments

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

cURL

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

Probar en el Playground

Una nota de ajuste del documento soporte

GET /v1/support_document_adjustments/{id} · retrieveSupportDocumentAdjustment

La nota de ajuste del documento soporte, con support_document (el documento que ajusta).

Respuestas

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

GET /v1/support_document_adjustments/{id}

cURL

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

Probar en el Playground

Archivo xml

GET /v1/support_document_adjustments/{id}/xml · downloadSupportDocumentAdjustmentXml

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

cURL

curl "https://api.trevol.si/v1/support_document_adjustments/sda_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/xml" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o support_document_adjustment_xml.xml

Probar en el Playground

Archivo dian_response

GET /v1/support_document_adjustments/{id}/dian_response · downloadSupportDocumentAdjustmentDianResponse

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

cURL

curl "https://api.trevol.si/v1/support_document_adjustments/sda_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/dian_response" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o support_document_adjustment_dian_response.xml

Probar en el Playground

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

PUT /v1/support_document_adjustments/{id} · correctSupportDocumentAdjustment

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

external_idtexto
Tu identificador del documento: único entre los documentos API de la empresa y el ambiente.
sellerSeller
Opcional con support_document.id: se toma el vendedor del documento soporte (si viene, tiene que ser el mismo).
itemslista de SupportAdjustmentItemobligatorio
Las líneas de la nota (1 a 500): sin retenciones ni fecha de compra. Máximo 500.
paymentPayment
noteslista de texto
Máximo 10.
referencesReferences
allowance_chargeslista de AllowanceCharge
Descuentos y recargos globales (no tocan las bases). Máximo 20.
currencySupportCurrency
concepttextoobligatorio
Concepto de la nota de ajuste (tabla 16.2.4): "1" devolución parcial, "2" anulación del documento soporte (lleva exactamente sus valores), "3" rebaja o descuento, "4" ajuste de precio, "5" otros.
descriptiontextoobligatorio
Qué se corrige y por qué (de 20 a 5000 caracteres, NSBF04).
support_documentSupportDocumentReferenceobligatorio
El documento soporte que ajusta: {"id": "sd_…"} (de Trevol: validado, de la empresa y el ambiente de la llave) o {number, cuds, issue_date, total?} si es de otra plataforma (total hace falta para anularlo).

Respuestas

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

PUT /v1/support_document_adjustments/{id}

cURL

curl -X PUT "https://api.trevol.si/v1/support_document_adjustments/sda_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "OC-991-ANULA",
  "concept": "2",
  "description": "Anulación: la compra de leche se registró dos veces en el ERP",
  "support_document": {
    "id": "sd_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
  },
  "items": [
    {
      "description": "Leche cruda",
      "unit": "LTR",
      "quantity": "120",
      "unit_price": "1800"
    }
  ]
}'

Probar en el Playground