Empezar

Crea una llave de pruebas y emite tu primera factura contra la habilitación real de la DIAN, en cURL o en siete lenguajes.

Ver como Markdown

En cinco pasos pasas de cero a una factura validada por la DIAN en el ambiente de pruebas.

1. Crea tu cuenta y tu empresa

Crea tu cuenta y tu empresa en app.trevol.si y termina su habilitación ante la DIAN (Trevol la hace por ti). Para emitir, la empresa tiene que estar habilitada; hasta entonces la API responde 422 company_not_enabled.

2. Crea una llave de pruebas

En la consola, con el entorno Pruebas, crea una llave. Empieza por tvl_test_ y se muestra una sola vez: guárdala como un secreto en tu servidor. Más en Llaves y entornos.

Con una sesión abierta en la consola, esta documentación te muestra tu empresa, tu entorno y el prefijo de tu llave, y el botón «Crear una llave para probar» crea una de Pruebas sin salir de aquí.

Guarda la llave en una variable de entorno. Los ejemplos de toda la documentación la leen de TREVOL_API_KEY:

Shell

export TREVOL_API_KEY="tvl_test_…"

3. Revisa que la llave funciona

GET /v1/company devuelve la empresa de la llave y sus capabilities: lo que esa llave puede emitir ahora (rangos de documento soporte y POS, el estado de la nómina en su ambiente, si hay representante legal para los eventos RADIAN). Sirve para saber, antes de pedir, qué le falta a la empresa.

GET /v1/company

cURL

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

Probar en el Playground

4. Calcula sin emitir

POST /v1/invoices/preview recibe el mismo cuerpo que la factura y devuelve los impuestos y los totales sin numerar ni enviar nada (no pide Idempotency-Key). Úsalo para comprobar tus datos.

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

5. Emite tu primera factura

POST /v1/invoices valida, numera, firma, envía a la DIAN y responde apenas la DIAN valida. Idempotency-Key es obligatoria: los SDK la generan por ti y la repiten en los reintentos; con cURL pon un UUID nuevo por documento.

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

El ejemplo es una venta nacional

El primer ejemplo de la especificación es una venta nacional en pesos (COP): un cliente persona jurídica con NIT, dos ítems con IVA del 19 % y pago a crédito a 30 días. La factura de exportación en dólares es el segundo ejemplo de la operación. Para consumidor final: "customer": {"final_consumer": true}.

La respuesta trae status: "accepted" cuando la DIAN valida (201). Si la DIAN no contesta, recibes un 202 con status: "processing" y Trevol termina el documento y te avisa por webhook: no crees otro documento para esa venta (Estados y respuestas).

El PDF, el ZIP y el correo al comprador se hacen enseguida en segundo plano: delivery.status llega pending. Entérate con el evento invoice.delivered o consulta el documento; si pides el PDF antes, se genera al momento (Archivos).

Después

Mira la petición en la consola, en Registro (con su Request-Id).
Recibe el resultado por webhook en lugar de preguntar.
Manda siempre un external_id tuyo y una Idempotency-Key derivada de tu venta (Idempotencia).
Cuando todo funcione, crea una llave de producción (tvl_live_…): emite con la resolución de numeración de la empresa y cada documento validado se descuenta del saldo.