Saltar al contenido
Crear cuenta Ingresar
Menú

API y SDK

Ayuda

Crear cuenta Ingresar
API y SDK
Ayuda
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 soporte

Las operaciones de 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 un documento soporte

POST /v1/support_documents · createSupportDocument

Genera un documento soporte (tipo 05): el respaldo de una compra a quien no está obligado a facturar (una persona natural, un campesino, un proveedor del exterior). Trevol valida a fondo ANTES de reservar un número, numera con el rango de documento soporte vigente más nuevo (o el del prefijo de numbering), firma con el certificado de la empresa y lo manda a la DIAN. Se genera, no se expide: no hay PDF, ZIP ni correo; el XML y la respuesta de la DIAN se descargan en las dos versiones. La empresa necesita su software registrado ante la DIAN (company_not_enabled con reason: missing_software) y un rango vigente con números libres (numbering_unavailable, no_resolution). La purchase_date de cada línea no puede ser posterior a hoy (DSFC02b/c). Cuenta como documento de facturación en el cobro.

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

  • external_idtexto
    Tu identificador del documento: único entre los documentos API de la empresa y el ambiente.
  • sellerSellerobligatorio
    Quien vende y no está obligado a facturar (el SNO). La empresa de la llave es la compradora: sus datos salen de la empresa. No hay customer.
  • itemslista de SupportItemobligatorio
    Las líneas (1 a 500). Retenciones solo por línea (withholdings: 05 ReteIVA, 06 ReteRenta); las del documento no se publican. 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
  • transmissionper_operation | weekly
    per_operation (por defecto, un documento por compra) o weekly (acumulado semanal con un mismo vendedor: cada línea lleva su purchase_date).
  • adjustment_noteSupportAdjustmentReference
    La nota de ajuste que originó este documento (opcional): {"id": "sda_…"} o {number, cuds, issue_date}.
  • numberingNumbering
    Opcional: el prefijo de la resolución de documento soporte que numera (una empresa con varios rangos). Sin él, la más nueva vigente. Si no existe, numbering_unavailable (no_resolution).

Respuestas

Estado Qué pasó
201 El documento (SupportDocument)
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. (SupportDocument)
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_documents

cURL
curl -X POST "https://api.trevol.si/v1/support_documents" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "OC-991",
  "seller": {
    "resident": true,
    "person_type": "natural",
    "document_type": "31",
    "document_number": "1020304050",
    "name": "PEREZ GOMEZ ANA MARIA",
    "address": "Vereda El Silencio, finca La Esperanza",
    "municipality_code": "25053",
    "postal_code": "252007",
    "tax_responsibilities": [
      "R-99-PN"
    ]
  },
  "items": [
    {
      "description": "Leche cruda",
      "unit": "LTR",
      "quantity": "120",
      "unit_price": "1800"
    }
  ],
  "payment": {
    "form": "cash",
    "methods": [
      {
        "code": "10"
      }
    ]
  },
  "notes": [
    "Compra de la semana 42 de octubre"
  ]
}'

Probar en el Playground

Respuesta201 Created
{
  "id": "sd_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
  "object": "support_document",
  "environment": "test",
  "status": "accepted",
  "number": "DS994001",
  "prefix": "DS",
  "external_id": "OC-991",
  "origin": "api",
  "cuds": "abababababababababababababababababababababababababababababababababababababababababababababababab",
  "qr": "https://catalogo-vpfe-hab.dian.gov.co/document/searchqr?documentkey=abababababababababababababababababababababababababababababababababababababababababababababababab",
  "issued_at": "2026-10-23T09:15:02-05:00",
  "seller": {
    "resident": true,
    "person_type": "natural",
    "document_type": "31",
    "document_number": "1020304050",
    "name": "PEREZ GOMEZ ANA MARIA",
    "address": "Vereda El Silencio, finca La Esperanza",
    "municipality_code": "25053",
    "postal_code": "252007",
    "tax_responsibilities": [
      "R-99-PN"
    ]
  },
  "items": [
    {
      "description": "Leche cruda",
      "unit": "LTR",
      "quantity": "120",
      "unit_price": "1800"
    }
  ],
  "payment": {
    "form": "cash",
    "methods": [
      {
        "code": "10"
      }
    ]
  },
  "transmission": "per_operation",
  "adjustment_note": null,
  "totals": {
    "subtotal": "216000.00",
    "discounts": "0.00",
    "line_extension": "216000.00",
    "tax_exclusive": "0.00",
    "taxes": [],
    "allowances": "0.00",
    "charges": "0.00",
    "rounding": "0.00",
    "total": "216000.00",
    "withholdings": [],
    "prepayments": "0.00",
    "net_payable": null,
    "items": [
      {
        "gross": "216000.00",
        "discount": "0.00",
        "line_extension": "216000.00"
      }
    ]
  },
  "dian": {
    "status_code": "00",
    "message": "Procesado Correctamente.",
    "rules": []
  },
  "delivery": {
    "status": null,
    "pdf": false,
    "zip": false,
    "xml": true,
    "email": null
  },
  "created_at": "2026-10-23T09:15:02-05:00",
  "updated_at": "2026-10-23T09:15:03-05:00"
}

Calcular un documento soporte sin emitirlo

POST /v1/support_documents/preview · previewSupportDocument

Valida y calcula los totales del documento soporte sin reservar un número ni enviar nada. No pide Idempotency-Key y no se cobra.

Cuerpo (SupportDocumentInput, obligatorio)

  • external_idtexto
    Tu identificador del documento: único entre los documentos API de la empresa y el ambiente.
  • sellerSellerobligatorio
    Quien vende y no está obligado a facturar (el SNO). La empresa de la llave es la compradora: sus datos salen de la empresa. No hay customer.
  • itemslista de SupportItemobligatorio
    Las líneas (1 a 500). Retenciones solo por línea (withholdings: 05 ReteIVA, 06 ReteRenta); las del documento no se publican. 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
  • transmissionper_operation | weekly
    per_operation (por defecto, un documento por compra) o weekly (acumulado semanal con un mismo vendedor: cada línea lleva su purchase_date).
  • adjustment_noteSupportAdjustmentReference
    La nota de ajuste que originó este documento (opcional): {"id": "sda_…"} o {number, cuds, issue_date}.
  • numberingNumbering
    Opcional: el prefijo de la resolución de documento soporte que numera (una empresa con varios rangos). 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/support_documents/preview

cURL
curl -X POST "https://api.trevol.si/v1/support_documents/preview" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "OC-991",
  "seller": {
    "resident": true,
    "person_type": "natural",
    "document_type": "31",
    "document_number": "1020304050",
    "name": "PEREZ GOMEZ ANA MARIA",
    "address": "Vereda El Silencio, finca La Esperanza",
    "municipality_code": "25053",
    "postal_code": "252007",
    "tax_responsibilities": [
      "R-99-PN"
    ]
  },
  "items": [
    {
      "description": "Leche cruda",
      "unit": "LTR",
      "quantity": "120",
      "unit_price": "1800"
    }
  ],
  "payment": {
    "form": "cash",
    "methods": [
      {
        "code": "10"
      }
    ]
  },
  "notes": [
    "Compra de la semana 42 de octubre"
  ]
}'

Probar en el Playground

Reenviar una pendiente o en error

POST /v1/support_documents/{id}/send · sendSupportDocument

Vuelve a enviar un documento soporte pending o error (por ejemplo, después de recargar saldo).

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

POST /v1/support_documents/{id}/send

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

Probar en el Playground

Respuesta200 OK
{
  "id": "sd_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
  "object": "support_document",
  "environment": "test",
  "status": "accepted",
  "number": "DS994001",
  "prefix": "DS",
  "external_id": "OC-991",
  "origin": "api",
  "cuds": "abababababababababababababababababababababababababababababababababababababababababababababababab",
  "qr": "https://catalogo-vpfe-hab.dian.gov.co/document/searchqr?documentkey=abababababababababababababababababababababababababababababababababababababababababababababababab",
  "issued_at": "2026-10-23T09:15:02-05:00",
  "seller": {
    "resident": true,
    "person_type": "natural",
    "document_type": "31",
    "document_number": "1020304050",
    "name": "PEREZ GOMEZ ANA MARIA",
    "address": "Vereda El Silencio, finca La Esperanza",
    "municipality_code": "25053",
    "postal_code": "252007",
    "tax_responsibilities": [
      "R-99-PN"
    ]
  },
  "items": [
    {
      "description": "Leche cruda",
      "unit": "LTR",
      "quantity": "120",
      "unit_price": "1800"
    }
  ],
  "payment": {
    "form": "cash",
    "methods": [
      {
        "code": "10"
      }
    ]
  },
  "transmission": "per_operation",
  "adjustment_note": null,
  "totals": {
    "subtotal": "216000.00",
    "discounts": "0.00",
    "line_extension": "216000.00",
    "tax_exclusive": "0.00",
    "taxes": [],
    "allowances": "0.00",
    "charges": "0.00",
    "rounding": "0.00",
    "total": "216000.00",
    "withholdings": [],
    "prepayments": "0.00",
    "net_payable": null,
    "items": [
      {
        "gross": "216000.00",
        "discount": "0.00",
        "line_extension": "216000.00"
      }
    ]
  },
  "dian": {
    "status_code": "00",
    "message": "Procesado Correctamente.",
    "rules": []
  },
  "delivery": {
    "status": null,
    "pdf": false,
    "zip": false,
    "xml": true,
    "email": null
  },
  "created_at": "2026-10-23T09:15:02-05:00",
  "updated_at": "2026-10-23T09:15:03-05:00"
}

Listar (documento soporte)

GET /v1/support_documents · listSupportDocuments

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_documents

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

Probar en el Playground

Un documento soporte

GET /v1/support_documents/{id} · retrieveSupportDocument

El documento soporte tal como se emitió: lo que mandaste, los totales, el CUDS y la respuesta de la DIAN. delivery no aplica (status: null).

Respuestas

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

GET /v1/support_documents/{id}

cURL
curl "https://api.trevol.si/v1/support_documents/sd_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b" \
  -H "Authorization: Bearer $TREVOL_API_KEY"

Probar en el Playground

Respuesta200 OK
{
  "id": "sd_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
  "object": "support_document",
  "environment": "test",
  "status": "accepted",
  "number": "DS994001",
  "prefix": "DS",
  "external_id": "OC-991",
  "origin": "api",
  "cuds": "abababababababababababababababababababababababababababababababababababababababababababababababab",
  "qr": "https://catalogo-vpfe-hab.dian.gov.co/document/searchqr?documentkey=abababababababababababababababababababababababababababababababababababababababababababababababab",
  "issued_at": "2026-10-23T09:15:02-05:00",
  "seller": {
    "resident": true,
    "person_type": "natural",
    "document_type": "31",
    "document_number": "1020304050",
    "name": "PEREZ GOMEZ ANA MARIA",
    "address": "Vereda El Silencio, finca La Esperanza",
    "municipality_code": "25053",
    "postal_code": "252007",
    "tax_responsibilities": [
      "R-99-PN"
    ]
  },
  "items": [
    {
      "description": "Leche cruda",
      "unit": "LTR",
      "quantity": "120",
      "unit_price": "1800"
    }
  ],
  "payment": {
    "form": "cash",
    "methods": [
      {
        "code": "10"
      }
    ]
  },
  "transmission": "per_operation",
  "adjustment_note": null,
  "totals": {
    "subtotal": "216000.00",
    "discounts": "0.00",
    "line_extension": "216000.00",
    "tax_exclusive": "0.00",
    "taxes": [],
    "allowances": "0.00",
    "charges": "0.00",
    "rounding": "0.00",
    "total": "216000.00",
    "withholdings": [],
    "prepayments": "0.00",
    "net_payable": null,
    "items": [
      {
        "gross": "216000.00",
        "discount": "0.00",
        "line_extension": "216000.00"
      }
    ]
  },
  "dian": {
    "status_code": "00",
    "message": "Procesado Correctamente.",
    "rules": []
  },
  "delivery": {
    "status": null,
    "pdf": false,
    "zip": false,
    "xml": true,
    "email": null
  },
  "created_at": "2026-10-23T09:15:02-05:00",
  "updated_at": "2026-10-23T09:15:03-05:00"
}

Archivo xml

GET /v1/support_documents/{id}/xml · downloadSupportDocumentXml

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

cURL
curl "https://api.trevol.si/v1/support_documents/sd_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/xml" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o support_document_xml.xml

Probar en el Playground

Archivo dian_response

GET /v1/support_documents/{id}/dian_response · downloadSupportDocumentDianResponse

El ApplicationResponse con que la DIAN contestó (application/xml), en las dos versiones.

Respuestas

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

GET /v1/support_documents/{id}/dian_response

cURL
curl "https://api.trevol.si/v1/support_documents/sd_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/dian_response" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o support_document_dian_response.xml

Probar en el Playground

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

PUT /v1/support_documents/{id} · correctSupportDocument

Corrige un documento soporte rechazado con el mismo número y lo 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 (SupportDocumentInput, obligatorio)

  • external_idtexto
    Tu identificador del documento: único entre los documentos API de la empresa y el ambiente.
  • sellerSellerobligatorio
    Quien vende y no está obligado a facturar (el SNO). La empresa de la llave es la compradora: sus datos salen de la empresa. No hay customer.
  • itemslista de SupportItemobligatorio
    Las líneas (1 a 500). Retenciones solo por línea (withholdings: 05 ReteIVA, 06 ReteRenta); las del documento no se publican. 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
  • transmissionper_operation | weekly
    per_operation (por defecto, un documento por compra) o weekly (acumulado semanal con un mismo vendedor: cada línea lleva su purchase_date).
  • adjustment_noteSupportAdjustmentReference
    La nota de ajuste que originó este documento (opcional): {"id": "sda_…"} o {number, cuds, issue_date}.
  • numberingNumbering
    Opcional: el prefijo de la resolución de documento soporte que numera (una empresa con varios rangos). Sin él, la más nueva vigente. Si no existe, numbering_unavailable (no_resolution).

Respuestas

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

PUT /v1/support_documents/{id}

cURL
curl -X PUT "https://api.trevol.si/v1/support_documents/sd_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "OC-991",
  "seller": {
    "resident": true,
    "person_type": "natural",
    "document_type": "31",
    "document_number": "1020304050",
    "name": "PEREZ GOMEZ ANA MARIA",
    "address": "Vereda El Silencio, finca La Esperanza",
    "municipality_code": "25053",
    "postal_code": "252007",
    "tax_responsibilities": [
      "R-99-PN"
    ]
  },
  "items": [
    {
      "description": "Leche cruda",
      "unit": "LTR",
      "quantity": "120",
      "unit_price": "1800"
    }
  ],
  "payment": {
    "form": "cash",
    "methods": [
      {
        "code": "10"
      }
    ]
  },
  "notes": [
    "Compra de la semana 42 de octubre"
  ]
}'

Probar en el Playground

Respuesta200 OK
{
  "id": "sd_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
  "object": "support_document",
  "environment": "test",
  "status": "accepted",
  "number": "DS994001",
  "prefix": "DS",
  "external_id": "OC-991",
  "origin": "api",
  "cuds": "abababababababababababababababababababababababababababababababababababababababababababababababab",
  "qr": "https://catalogo-vpfe-hab.dian.gov.co/document/searchqr?documentkey=abababababababababababababababababababababababababababababababababababababababababababababababab",
  "issued_at": "2026-10-23T09:15:02-05:00",
  "seller": {
    "resident": true,
    "person_type": "natural",
    "document_type": "31",
    "document_number": "1020304050",
    "name": "PEREZ GOMEZ ANA MARIA",
    "address": "Vereda El Silencio, finca La Esperanza",
    "municipality_code": "25053",
    "postal_code": "252007",
    "tax_responsibilities": [
      "R-99-PN"
    ]
  },
  "items": [
    {
      "description": "Leche cruda",
      "unit": "LTR",
      "quantity": "120",
      "unit_price": "1800"
    }
  ],
  "payment": {
    "form": "cash",
    "methods": [
      {
        "code": "10"
      }
    ]
  },
  "transmission": "per_operation",
  "adjustment_note": null,
  "totals": {
    "subtotal": "216000.00",
    "discounts": "0.00",
    "line_extension": "216000.00",
    "tax_exclusive": "0.00",
    "taxes": [],
    "allowances": "0.00",
    "charges": "0.00",
    "rounding": "0.00",
    "total": "216000.00",
    "withholdings": [],
    "prepayments": "0.00",
    "net_payable": null,
    "items": [
      {
        "gross": "216000.00",
        "discount": "0.00",
        "line_extension": "216000.00"
      }
    ]
  },
  "dian": {
    "status_code": "00",
    "message": "Procesado Correctamente.",
    "rules": []
  },
  "delivery": {
    "status": null,
    "pdf": false,
    "zip": false,
    "xml": true,
    "email": null
  },
  "created_at": "2026-10-23T09:15:02-05:00",
  "updated_at": "2026-10-23T09:15:03-05:00"
}