Documentación · Documentos · API v1 · versión 2026-10-22
Facturas
Emitir una factura electrónica por la API de Trevol, corregirla si la DIAN la rechaza, consultarla y descargar sus archivos.
La factura electrónica de venta se pide con POST /v1/invoices. Trevol valida los datos, calcula los impuestos y los totales, numera con la resolución de la empresa, firma, envía a la DIAN y responde apenas la DIAN valida.
POST /v1/invoices
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"
]
}'- Consumidor final:
"customer": {"final_consumer": true}. - Calcular sin emitir:
POST /v1/invoices/previewcon el mismo cuerpo (no numera ni pideIdempotency-Key). - Precios sin impuestos:
unit_priceva antes de IVA; Trevol calcula impuestos, retenciones y totales. - La factura cubre todo lo del Anexo técnico 1.9: impuestos porcentuales y nominales, descuentos y recargos, retenciones, muestras gratis, anticipos y redondeo, y también la exportación, la moneda extranjera, el AIU, los mandatos, el transporte de carga, los notarios, las divisas y el sector salud (Operaciones especiales). Quedan fuera la contingencia 03 y 04 de la factura y los eventos RADIAN 035 a 051.
POST /v1/invoices/preview
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"
]
}'Qué responde
201 cuando la DIAN valida, 422 dian_rejected con document cuando la rechaza, 422 validation_error si Trevol la rechaza antes de numerar (no se gasta ningún número), 402 sin saldo, y con la DIAN sin contestar un 202 processing (versión 2026-10-22) o un 503 dian_unavailable (2026-10-21). Todo está en Estados y respuestas. Idempotency-Key es obligatoria (Idempotencia) y external_id es opcional.
Rechazos y reintentos
- Rechazado por la DIAN: corrige con
PUT /v1/invoices/{id}(cuerpo completo, nuevaIdempotency-Key). Sale con el mismo número. Un rechazo no bloquea los demás envíos.
PUT /v1/invoices/{id}
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"
]
}'- Pendiente o en error:
POST /v1/invoices/{id}/sendlo vuelve a enviar (por ejemplo, después de recargar saldo).
POST /v1/invoices/{id}/send
curl -X POST "https://api.trevol.si/v1/invoices/inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b/send" \
-H "Authorization: Bearer $TREVOL_API_KEY"- Validado: ya no se cambia; se corrige con una nota crédito o débito.
GET /v1/invoices/{id}
curl "https://api.trevol.si/v1/invoices/inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b" \
-H "Authorization: Bearer $TREVOL_API_KEY"GET /v1/invoices lista por cursor (limit, starting_after, y los filtros status, external_id, created_from y created_to); ver Paginación. GET /v1/dian/acquirer?document_type=31&document_number=… devuelve lo que la DIAN tiene del adquiriente (nombre y correo).
Archivos
GET /v1/invoices/{id}/pdf, /xml, /zip y /dian_response entregan los archivos en binario (Archivos).
Más documentos
Todo lo que Trevol emite se pide igual: POST con Idempotency-Key, los mismos estados, errores, webhooks y archivos. Cada familia tiene su página: notas crédito y débito, documento soporte, documento equivalente, nómina electrónica y eventos RADIAN.