Documentación · API v1 · versión 2026-10-22
Documentación de la API Emite ante la DIAN desde tu software, en JSON.
Emite facturas, notas, documento soporte, documentos equivalentes, nómina y eventos RADIAN ante la DIAN desde tu propio software, con la API de Trevol.
Explora la API
- Emitir una facturaUna sola petición: Trevol valida, numera, firma, envía a la DIAN y responde apenas la DIAN valida.
- Notas crédito y débitoUn documento validado ya no se cambia: se corrige con una nota crédito o débito.
- Documento soporteCompras a quien no está obligado a facturar (05) y su nota de ajuste (95).
- Tiquete POS y documento equivalenteEl tiquete POS (20), los otros nueve documentos equivalentes y su nota de ajuste.
- Nómina electrónicaUn 102 por trabajador; Trevol calcula los totales, numera, firma y envía a la DIAN.
- Eventos RADIANAcuse de recibo, reclamo, recibo del bien y aceptación expresa de una factura que te emitieron.
- Exportación y operaciones especialesExportación, moneda extranjera, AIU, mandatos, transporte de carga, notarios, divisas y sector salud.
- Estados y respuestasQué responde la API cuando la DIAN valida, rechaza o no contesta.
- Saldo y recargasConsulta el saldo prepago, sus movimientos y prepara una recarga.
- Nota de ajuste de nóminaReemplazar o eliminar una nómina ya enviada (103).
- Aceptación tácita (034)De una factura tuya a crédito, 3 días hábiles después del recibo del bien sin reclamo.
- Aceptación tácita por CUFETambién para las facturas que emitiste antes con otro software.
- Cómo empezarSin costo en pruebasCrea una llave de pruebas y emite tu primera factura contra la habilitación real de la DIAN.
- Llaves y entornosCada llave es de una sola empresa y un solo ambiente, con sus permisos e IP permitidas.
- WebhooksAvisos firmados cuando un documento se valida, se rechaza, queda en error o se entrega.
- IdempotenciaRepetir una petición con la misma Idempotency-Key devuelve la misma respuesta, sin volver a emitir.
- ErroresCada error trae un código estable, el estado HTTP, un detalle en español y si se puede reintentar.
- Límites120 envíos por minuto y 20.000 al día por llave; 50.000 al día por empresa.
Herramientas y referencia
- ConsolaLlaves, webhooks, registro de peticiones y el Playground.
- Referencia de la APILas 109 operaciones de la API v1, por recurso, con ejemplos.
- ObjetosLos 146 objetos de la especificación, campo por campo.
- Especificación OpenAPI 3.1La API v1 completa, en JSON.
- Catálogo de erroresLos 30 códigos, con su estado HTTP y cuándo pasan.
- Reglas de la DIANLas 282 reglas que Trevol explica en español, con cómo corregirlas.
Con la API de Trevol emites facturas electrónicas, notas crédito y débito, documento soporte, documentos equivalentes (POS), nómina electrónica y eventos RADIAN ante la DIAN desde tu propio software. Tú mandas los datos en JSON; Trevol valida, calcula los impuestos y los totales, numera, firma, envía a la DIAN y entrega el PDF y el correo en los documentos que los llevan.
Las llaves de pruebas (tvl_test_…) emiten contra la habilitación real de la DIAN: sin validez legal y sin costo. Cuando tu integración funcione, creas una llave de producción (tvl_live_…).
Los SDK se publican pronto
Hay SDK en Node.js, Python, PHP, Java, C#, Go y Ruby, y colecciones para Postman, Insomnia y Bruno. Los SDK todavía no están publicados: mientras tanto usa cURL o la especificación OpenAPI. Los ejemplos de cada página están en cURL por ahora.
Empieza aquí
| Quiero… | Ve a |
|---|---|
| Emitir mi primera factura en pruebas | Empezar |
| Crear una llave y entender los entornos | Llaves y entornos |
| Instalar un SDK o importar una colección | SDK y herramientas |
| Enterarme cuando la DIAN valida un documento | Webhooks |
| Entender qué responde la API en cada caso | Estados y respuestas |
| Evitar documentos duplicados al reintentar | Idempotencia |
| Resolver un error | Errores |
Qué puedes emitir
| Documento | Guía | Referencia |
|---|---|---|
| Factura de venta, exportación y operaciones especiales | Facturas, Operaciones especiales | Facturas |
| Notas crédito y débito | Notas crédito y débito | Notas crédito, Notas débito |
| Documento soporte (05) y su nota de ajuste (95) | Documento soporte | Documento soporte |
| Tiquete POS (20), otros nueve documentos equivalentes y su ajuste | Documento equivalente | Documento equivalente |
| Nómina electrónica (102) y su ajuste (103) | Nómina electrónica | Nómina |
| Eventos RADIAN 030 a 034 | Eventos RADIAN | Eventos RADIAN |
| Saldo y recargas | Saldo | Saldo |
Herramientas
- La consola: crea llaves y webhooks, mira el registro de peticiones y el consumo, y prueba la API con el Playground.
- Referencia de la API: cada operación con sus parámetros, su cuerpo y ejemplos de código.
openapi.json: la especificación OpenAPI 3.1 completa.- Para IA: cada página en Markdown,
llms.txty un servidor MCP de solo lectura. - Registro de cambios: qué cambió en cada versión de la API.