Saltar la navegación de la documentación

Español API 2026-10-22

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

Facturas

Las operaciones de Facturas de la API de Trevol: parámetros, cuerpo, respuestas y ejemplos de código.

Emitir, consultar, corregir y reenviar facturas electrónicas, incluidas la exportación, la moneda extranjera, el AIU, los mandatos, el transporte, los notarios, las divisas y el sector salud.

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 factura

POST /v1/invoices · createInvoice

Valida, numera, firma y envía una factura a la DIAN. Además de la factura nacional acepta la exportación (document_type: "02"), la moneda extranjera (currency), los términos de entrega (delivery_terms), el AIU, los mandatos, el transporte de carga, los notarios, las divisas y el sector salud (operation_type). El envío físico de la mercancía va en shipment (no en delivery: ese es el estado del PDF, el ZIP y el correo en la respuesta). Las notas crédito y débito no admiten estos campos.

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 (InvoiceInput, 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.
document_typetexto
Tipo de factura (tabla 13.1.3): "01" venta (por defecto) o "02" exportación. La contingencia (03/04) todavía no está disponible en la API.
operation_typetexto
Tipo de operación (tabla 13.1.5.1): "10" estándar (por defecto), "09" AIU, "11" mandatos, "12" transporte de carga, "14" notarios, "15" compra o "16" venta de divisas, o "SS-CUFE" (sector salud, con interoperability).
currencyCurrency
Moneda extranjera: los valores del pedido van en ESA moneda; la factura y el CUFE van en pesos (× la tasa). Sin currency, la factura es en pesos.
cop_totalsbooleano
Con currency: informa la moneda y la tasa en la interoperabilidad («Exportación» / «Factura de Venta»).
delivery_termsDeliveryTerms
Condiciones de entrega de la exportación (tabla 13.3.7: INCOTERM).
shipmentShipment
El envío físico de la mercancía (fecha, dirección y transportador). No se llama delivery: esa clave de la respuesta es el estado de los archivos y del correo.
due_diligencetexto
Debida diligencia (tabla 18.3: "01"–"04"). Obligatoria en la compra y venta de divisas (15/16) y prohibida en los demás tipos de operación.
interoperabilityInteroperability
Grupo de interoperabilidad (Suplemento H). Obligatorio con operation_type "SS-CUFE".

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

cURL

curl -X POST "https://api.trevol.si/v1/invoices" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "VENTA-2026-000123",
  "customer": {
    "document_type": "31",
    "document_number": "900123456",
    "name": "COMERCIALIZADORA ANDINA SAS",
    "person_type": "legal",
    "email": "[email protected]",
    "address": "Calle 72 # 10-34, Oficina 501",
    "municipality_code": "11001"
  },
  "items": [
    {
      "code": "LIC-ANUAL",
      "description": "Licencia anual de software",
      "quantity": "2",
      "unit_price": "150000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    },
    {
      "code": "SOP-MES",
      "description": "Soporte técnico mensual",
      "quantity": "1",
      "unit_price": "80000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    }
  ],
  "payment": {
    "form": "credit",
    "term_days": 30
  },
  "notes": [
    "Gracias por su compra"
  ]
}'

Probar en el Playground

Calcular una factura sin emitirla

POST /v1/invoices/preview · previewInvoice

Cuerpo (InvoiceInput, 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.
document_typetexto
Tipo de factura (tabla 13.1.3): "01" venta (por defecto) o "02" exportación. La contingencia (03/04) todavía no está disponible en la API.
operation_typetexto
Tipo de operación (tabla 13.1.5.1): "10" estándar (por defecto), "09" AIU, "11" mandatos, "12" transporte de carga, "14" notarios, "15" compra o "16" venta de divisas, o "SS-CUFE" (sector salud, con interoperability).
currencyCurrency
Moneda extranjera: los valores del pedido van en ESA moneda; la factura y el CUFE van en pesos (× la tasa). Sin currency, la factura es en pesos.
cop_totalsbooleano
Con currency: informa la moneda y la tasa en la interoperabilidad («Exportación» / «Factura de Venta»).
delivery_termsDeliveryTerms
Condiciones de entrega de la exportación (tabla 13.3.7: INCOTERM).
shipmentShipment
El envío físico de la mercancía (fecha, dirección y transportador). No se llama delivery: esa clave de la respuesta es el estado de los archivos y del correo.
due_diligencetexto
Debida diligencia (tabla 18.3: "01"–"04"). Obligatoria en la compra y venta de divisas (15/16) y prohibida en los demás tipos de operación.
interoperabilityInteroperability
Grupo de interoperabilidad (Suplemento H). Obligatorio con operation_type "SS-CUFE".

Respuestas

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

POST /v1/invoices/preview

cURL

curl -X POST "https://api.trevol.si/v1/invoices/preview" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "VENTA-2026-000123",
  "customer": {
    "document_type": "31",
    "document_number": "900123456",
    "name": "COMERCIALIZADORA ANDINA SAS",
    "person_type": "legal",
    "email": "[email protected]",
    "address": "Calle 72 # 10-34, Oficina 501",
    "municipality_code": "11001"
  },
  "items": [
    {
      "code": "LIC-ANUAL",
      "description": "Licencia anual de software",
      "quantity": "2",
      "unit_price": "150000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    },
    {
      "code": "SOP-MES",
      "description": "Soporte técnico mensual",
      "quantity": "1",
      "unit_price": "80000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    }
  ],
  "payment": {
    "form": "credit",
    "term_days": 30
  },
  "notes": [
    "Gracias por su compra"
  ]
}'

Probar en el Playground

Reenviar una pendiente o en error

POST /v1/invoices/{id}/send · sendInvoice

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

cURL

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

Probar en el Playground

Listar (factura)

GET /v1/invoices · listInvoices

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

cURL

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

Probar en el Playground

Una factura

GET /v1/invoices/{id} · retrieveInvoice

Respuestas

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

GET /v1/invoices/{id}

cURL

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

Probar en el Playground

Archivo pdf

GET /v1/invoices/{id}/pdf · downloadInvoicePdf

Respuestas

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

GET /v1/invoices/{id}/pdf

cURL

curl "https://api.trevol.si/v1/invoices/inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/pdf" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o invoice_pdf.pdf

Probar en el Playground

Archivo xml

GET /v1/invoices/{id}/xml · downloadInvoiceXml

Respuestas

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

GET /v1/invoices/{id}/xml

cURL

curl "https://api.trevol.si/v1/invoices/inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/xml" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o invoice_xml.xml

Probar en el Playground

Archivo zip

GET /v1/invoices/{id}/zip · downloadInvoiceZip

Respuestas

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

GET /v1/invoices/{id}/zip

cURL

curl "https://api.trevol.si/v1/invoices/inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/zip" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o invoice_zip.zip

Probar en el Playground

Archivo dian_response

GET /v1/invoices/{id}/dian_response · downloadInvoiceDianResponse

Respuestas

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

GET /v1/invoices/{id}/dian_response

cURL

curl "https://api.trevol.si/v1/invoices/inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/dian_response" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -o invoice_dian_response.xml

Probar en el Playground

¿Procede ya la aceptación tácita (034) de esta factura?

GET /v1/invoices/{id}/tacit_acceptance · retrieveInvoiceTacitAcceptance

Consulta GetStatusEvent (con el certificado de la empresa) y aplica la regla de los 3 días hábiles; no envía nada. Usa el mismo historial que el envío del 034 (POST /v1/radian_events), así que la consulta y el envío no se contradicen. 404 si la factura no es de la empresa y el ambiente de la llave; 422 si no está validada, no es a crédito o es de consumidor final; 429 con más de 30 consultas por minuto por llave; 503 si la DIAN no contesta (reintentable).

Respuestas

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

GET /v1/invoices/{id}/tacit_acceptance

cURL

curl "https://api.trevol.si/v1/invoices/inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/tacit_acceptance" \
  -H "Authorization: Bearer $TREVOL_API_KEY"

Probar en el Playground

Respuesta200 OK

{
  "object": "tacit_acceptance",
  "invoice_id": "inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
  "cufe": "abababababababababababababababababababababababababababababababababababababababababababababababab",
  "number": "FE1234",
  "allowed": false,
  "available_from": "2026-10-27",
  "rules": [
    {
      "code": "LGC14",
      "severity": "rejection",
      "local": true,
      "message": "Faltan días hábiles para la aceptación tácita.",
      "explanation": "Pasan 3 días hábiles desde el recibo del bien o servicio (evento 032)."
    }
  ]
}

Corregir una factura rechazada (mismo número) y reenviarla

PUT /v1/invoices/{id} · correctInvoice

Parámetros

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

Cuerpo (InvoiceInput, 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.
document_typetexto
Tipo de factura (tabla 13.1.3): "01" venta (por defecto) o "02" exportación. La contingencia (03/04) todavía no está disponible en la API.
operation_typetexto
Tipo de operación (tabla 13.1.5.1): "10" estándar (por defecto), "09" AIU, "11" mandatos, "12" transporte de carga, "14" notarios, "15" compra o "16" venta de divisas, o "SS-CUFE" (sector salud, con interoperability).
currencyCurrency
Moneda extranjera: los valores del pedido van en ESA moneda; la factura y el CUFE van en pesos (× la tasa). Sin currency, la factura es en pesos.
cop_totalsbooleano
Con currency: informa la moneda y la tasa en la interoperabilidad («Exportación» / «Factura de Venta»).
delivery_termsDeliveryTerms
Condiciones de entrega de la exportación (tabla 13.3.7: INCOTERM).
shipmentShipment
El envío físico de la mercancía (fecha, dirección y transportador). No se llama delivery: esa clave de la respuesta es el estado de los archivos y del correo.
due_diligencetexto
Debida diligencia (tabla 18.3: "01"–"04"). Obligatoria en la compra y venta de divisas (15/16) y prohibida en los demás tipos de operación.
interoperabilityInteroperability
Grupo de interoperabilidad (Suplemento H). Obligatorio con operation_type "SS-CUFE".

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

cURL

curl -X PUT "https://api.trevol.si/v1/invoices/inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "VENTA-2026-000123",
  "customer": {
    "document_type": "31",
    "document_number": "900123456",
    "name": "COMERCIALIZADORA ANDINA SAS",
    "person_type": "legal",
    "email": "[email protected]",
    "address": "Calle 72 # 10-34, Oficina 501",
    "municipality_code": "11001"
  },
  "items": [
    {
      "code": "LIC-ANUAL",
      "description": "Licencia anual de software",
      "quantity": "2",
      "unit_price": "150000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    },
    {
      "code": "SOP-MES",
      "description": "Soporte técnico mensual",
      "quantity": "1",
      "unit_price": "80000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    }
  ],
  "payment": {
    "form": "credit",
    "term_days": 30
  },
  "notes": [
    "Gracias por su compra"
  ]
}'

Probar en el Playground