Saltar al contenido

api.trevol.si/v1

Tu software emite. Trevol hace el resto. Una API en JSON para todos los documentos ante la DIAN.

Mandas los datos en JSON. Trevol valida, calcula impuestos y totales, numera, firma, envía a la DIAN y responde apenas la DIAN valida. El PDF y el correo salen enseguida, en segundo plano.

Las llaves de pruebas usan la habilitación real de la DIAN y no se cobran.

Ejemplo con datos ficticios: el registro de peticiones de platform.trevol.si en el entorno de Pruebas, con una factura que respondió 201 en 1,9 segundos, un evento RADIAN y dos consultas; y dos anotaciones, la respuesta 201 y el webhook firmado invoice.accepted.

Mandas JSON. Recibes la respuesta de la DIAN. Una llave por empresa y por ambiente, y pruebas contra la habilitación real.

La API v1 vive en https://api.trevol.si/v1. Cada empresa tiene sus llaves: tvl_test_ para la habilitación real de la DIAN y tvl_live_ para producción. Una llamada emite un documento y su respuesta trae la de la DIAN; lo que tarda, llega por webhook.

  • Nunca dos veces.

    La misma Idempotency-Key durante 7 días devuelve el mismo documento.

  • Pruebas de verdad.

    Las llaves tvl_test_ van a la habilitación real de tu empresa ante la DIAN, sin simulador, y no se cobran.

  • Errores que se entienden.

    application/problem+json (RFC 9457), con un catálogo público en platform.trevol.si/docs/errores.

  • Webhooks firmados.

    Con HMAC-SHA256 (Standard Webhooks), reintentos y reenvío manual.

Una ruta por documento. Con su vista previa, sus archivos y su respuesta de la DIAN.

Rutas de la API para emitir cada documento
DocumentoRutas
Factura electrónicaPOST /v1/invoices POST /v1/invoices/preview
Notas crédito y débitoPOST /v1/credit_notes POST /v1/debit_notes
Documento soportePOST /v1/support_documents POST /v1/support_document_adjustments
Documento equivalentePOST /v1/equivalent_documents POST /v1/equivalent_document_adjustments
Nómina electrónicaPOST /v1/payrolls POST /v1/payroll_adjustments
Eventos RADIANPOST /v1/radian_events

Y para cada documento: GET por id, …/send para reenviarlo y, según el tipo, …/pdf, …/xml, …/zip y …/dian_response. Además, GET /v1/company, /v1/events, /v1/requests y /v1/webhook_endpoints.

Todas las rutas

De la llave a tu primer documento. Cuatro pasos, en Pruebas y luego en Producción.

  1. 1

    Crea una llave

    En la consola, entorno Pruebas.

  2. 2

    Envía la petición

    Con Idempotency-Key.

  3. 3

    Recibe la respuesta

    201 accepted, o 422 con las reglas de la DIAN.

  4. 4

    Escucha los webhooks

    Cuando salen el PDF y el correo.

Una API que se comporta como esperas. JSON con campos en inglés, mensajes en español y errores con un código estable.

  • Hasta 10 llaves activas por empresa, de escritura o de solo lectura. Cada una se limita hasta a 10 direcciones IP y se revoca al instante.
  • POST …/preview calcula impuestos y totales sin numerar ni enviar.
  • GET /v1/company dice qué puede emitir esa llave ahora: documento soporte, equivalente, nómina y eventos RADIAN.
Ejemplo
curl https://api.trevol.si/v1/invoices \
  -H "Authorization: Bearer $TREVOL_LLAVE" \
  -H "Idempotency-Key: 6f1c2a7e-0b3d-4c2a-9d0e-1a2b3c4d5e6f" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "VENTA-2026-000123",
    "customer": {
      "document_type": "31",
      "document_number": "900373913",
      "name": "FICORP SAS",
      "person_type": "legal",
      "email": "facturas@ficorp.co",
      "municipality_code": "76001",
      "tax_responsibilities": ["O-13"]
    },
    "items": [{
      "code": "SA-LIC",
      "description": "Licencia anual",
      "quantity": "1",
      "unit_price": "150000",
      "taxes": [{"code": "01", "rate": "19"}]
    }],
    "payment": {
      "form": "credit",
      "term_days": 30,
      "methods": [{"code": "47"}]
    }
  }'
HTTP/1.1 201 Created
Location: /v1/invoices/inv_08cd6774e31e401c9fa0fbf92b3fbdc0
Request-Id: req_8f0bd4b74c070af09ae4e620

{
  "id": "inv_08cd6774e31e401c9fa0fbf92b3fbdc0",
  "object": "invoice",
  "environment": "test",
  "status": "accepted",
  "number": "SETP994307051",
  "prefix": "SETP",
  "external_id": "VENTA-2026-000123",
  "cufe": "52cede538652…",
  "qr": "NumFac: SETP994307051 …",
  "issued_at": "2026-10-21T22:09:36-05:00",
  "customer": { … },
  "items": [ … ],
  "totals": {
    "subtotal": "150000.00", "discounts": "0.00", "line_extension": "150000.00",
    "taxes": [{"code": "01", "name": "IVA", "rate": "19.00", "base": "150000.00", "amount": "28500.00"}],
    "total": "178500.00", …
  },
  "dian": {"status_code": "00", "message": "Procesado Correctamente.", "rules": []},
  "delivery": {"status": "pending", "pdf": false, "zip": false, "xml": true, "email": {"status": "pending", "to": null, "detail": null}}
}
POST /trevol HTTP/1.1
Content-Type: application/json
User-Agent: Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks)
webhook-id: evt_8c1e0f0a7d3b4a6f9e2d1c0b5a4f3e2d
webhook-timestamp: 1761163445
webhook-signature: v1,K5oZfzN0ZGxPpoGxC2c0vL1o0U3q6Qh2oA0h1c8l8bE=

{"id":"evt_8c1e0f0a7d3b4a6f9e2d1c0b5a4f3e2d","object":"event","type":"invoice.accepted","timestamp":"2026-10-22T20:04:05Z",
 "environment":"test","api_version":"2026-10-22",
 "data":{"object":"invoice","id":"inv_08cd6774e31e401c9fa0fbf92b3fbdc0","status":"accepted","environment":"test",
         "number":"SETP994307051","prefix":"SETP","external_id":"VENTA-2026-000123","origin":"api","cufe":"52cede538652…",
         "issued_at":"2026-10-22T15:04:05-05:00","total":"178500.00","invoice":null,
         "dian":{"status_code":"00","rules":[]},"delivery":{"pdf":false,"zip":false,"email":{"status":"pending"}}}}

Consola en platform.trevol.si: llaves, webhooks firmados, registro y playgroundAbrir la consola

mediana por documento validado1
1,9 s
de idempotencia
7 días
tipos de evento de webhook2
49

Cuando la DIAN tarda o la red falla. Y cuando quieres calcular antes de emitir.

La DIAN no contesta

Con la versión 2026-10-22, la respuesta es 202 processing y Trevol termina el documento por su cuenta; el resultado llega por consulta y por webhook.

Versión
2026-10-22
Respuesta
202
Un reintento por un corte de red

Repetir la petición con la misma Idempotency-Key devuelve el mismo documento, con la cabecera Idempotent-Replayed: true; con otro cuerpo, 422 idempotency_key_reused.

Clave
7 días
Repetida
El mismo documento
Calcular antes de emitir

POST /v1/invoices/preview devuelve impuestos y totales sin numerar ni enviar a la DIAN.

Número
No se gasta
DIAN
No se envía

La misma lista de la app web. Sin mensualidad; las pruebas no se cobran.

Cada documento se cobra cuando la DIAN lo valida, sin mensualidad. Facturas, notas, POS, documentos equivalentes y documentos soporte comparten el conteo del mes de tu cuenta.

$ 500 → $ 15

por documento validado, según el consumo de tu cuenta

Del 1 al 10: $ 500 c/u

Nómina electrónica

Ver la tabla completa

Cada documento de nómina se cobra cuando la DIAN lo valida, con su propio conteo. Cada nota de ajuste cuenta como un empleado más.

$ 2.000 → $ 50

por empleado, según los empleados de tu cuenta en el mes

Del 1 al 2: $ 2.000 c/u

Eventos RADIAN

Ver la tabla completa

Cada evento se cobra cuando la DIAN lo valida, con la tabla de facturación y su propio conteo del mes. Una factura recibida suele llevar tres eventos (030, 032 y 033).

$ 500 → $ 15

por evento validado

Del 1 al 10: $ 500 c/u

El saldo es de tu cuenta: lo consumen las llaves de todas tus empresas.

Las pruebas de habilitación no se cobran. Si la DIAN rechaza un documento, no pagas: lo apartado vuelve a tu saldo.

Preguntas sobre la API. Y sobre las llaves y las pruebas.

¿Las pruebas por la API son reales?

Sí. Las llaves tvl_test_ usan la habilitación real de tu empresa ante la DIAN, sin simulador, y no se cobran.

¿Cuántas llaves puedo tener?

Hasta 10 activas por empresa, de escritura o de solo lectura. Cada una se puede limitar hasta a 10 direcciones IP y revocar al instante.

¿Qué pasa si la DIAN no contesta?

Con la versión 2026-10-22, la respuesta es 202 processing: Trevol termina el documento por su cuenta y el resultado llega por consulta y por webhook. No crees otro documento para la misma operación.

¿Puedo vincular empresas por la API?

Todavía no: las empresas se vinculan en la app. Cada llave es de una empresa.

¿Cuánto guarda el registro de peticiones?

30 días, sin los cuerpos de las peticiones. Los eventos de webhook también se guardan 30 días.

Todas las preguntas

Lo que rodea a la API. La app, el conector y el catálogo de errores.

  • App web

    app.trevol.si

    Emite desde app.trevol.si, sin instalar nada.

  • Conector ContaPyme

    Compatible con ContaPyme®

    Apruebas en ContaPyme y Trevol emite ante la DIAN.

  • Errores de la API

    https://platform.trevol.si/docs/errores

    Cada código, con su explicación.

Tu primera llamada, contra la DIAN de verdad.

Sin plan, sin mensualidad y con precios publicados. Empiezas con $ 2.000 de saldo y las pruebas de habilitación no se cobran.

Cómo empezar

Cuenta, empresa y habilitación ante la DIAN, en tres pasos.

Ver los pasos

Documentación

La guía y la referencia de la API v1.

Leer la documentación

Notas

  1. Prueba de punta a punta del 23 de octubre de 2026 contra la habilitación de la DIAN, medida desde el cliente: 28 documentos de todas las familias. La mediana fue 1,9 s. Los tiempos dependen de la DIAN.
  2. Según la especificación OpenAPI, sin contar webhook.test; incluye los avisos de saldo, numeración y certificado.