API de Trevol

1. Cómo empezar

1. Crea tu cuenta y tu empresa en app.trevol.si y termina su habilitación ante la DIAN (Trevol la hace por ti).
2. Crea una llave de pruebas en la app: Integraciones → API → Nueva llave, ambiente Pruebas. La llave (tvl_test_…) se muestra una sola vez.
3. Emite tu primera factura contra la habilitación real de la DIAN: sin validez legal y sin costo.

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

Cuando tu integración 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 de tu saldo.

2. Llaves y seguridad

• Authorization: Bearer tvl_test_… (habilitación de la DIAN) o tvl_live_… (producción).
• Permisos: «Emitir y consultar» o «Solo consultar».
• IP permitidas (opcional): hasta 10 direcciones o redes; la llave solo sirve desde ellas.
• Solo el titular de la cuenta crea o revoca llaves, y cada vez le avisamos por correo. Revocar es inmediato.
• Guarda la llave como un secreto en tu servidor: nunca en una página web ni en una app de celular. Trevol solo guarda su huella (sha256).

3. Convenciones

• Dirección: https://api.trevol.si/v1. JSON en UTF-8; campos en inglés y mensajes en español.
• Montos: en los pedidos, número o texto decimal con punto ("150000.50"); en las respuestas, siempre texto con 2 decimales. Las cantidades admiten hasta 6 decimales.
• Precios sin impuestos: unit_price va antes de IVA; Trevol calcula impuestos, retenciones y totales.
• Códigos de la DIAN como texto: "01", "31", "47".
• Identificadores con prefijo: inv_ factura, cn_ nota crédito, dn_ nota débito.
• Fechas ISO 8601; issued_at en hora de Bogotá (-05:00).
• Un campo desconocido es un error: no se ignora en silencio.
• Trevol-Version: 2026-10-21 (opcional) y Request-Id en cada respuesta.

4. Emitir una factura

Es síncrono: en la misma petición Trevol valida, numera, firma, envía a la DIAN y espera su respuesta.

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": "ERP-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": "ERP-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": {"pdf": true, "zip": true, "xml": true, "email": {"status": "sent", "to": "facturas@ficorp.co"}}
}

Para consumidor final: "customer": {"final_consumer": true}. Para calcular sin emitir: POST /v1/invoices/preview con el mismo cuerpo (no numera ni pide Idempotency-Key).

La fase 1 cubre la factura de venta nacional con todo lo del Anexo técnico 1.9 (impuestos porcentuales y nominales, descuentos y recargos, retenciones, muestras gratis, anticipos, redondeo) y las notas crédito y débito. Exportación, moneda extranjera, documento soporte, POS, nómina y eventos RADIAN llegan en las fases siguientes.

5. Estados y respuestas

status: pending (numerado, sin enviar) · sending · accepted · rejected · error (no se pudo enviar) · contingency. Todos los errores: catálogo de errores.

6. Idempotencia

• Idempotency-Key es obligatoria al crear o corregir un documento: un UUID nuevo por documento.
• Repetir la misma clave con el mismo cuerpo (durante 7 días) devuelve la misma respuesta con Idempotent-Replayed: true, sin volver a emitir.
• La misma clave con otro cuerpo es idempotency_key_reused: nunca te devolvemos otro documento en silencio.
• Si la primera petición no terminó (402, 503), el reintento con la misma clave sigue con el mismo documento y el mismo número.
• external_id (opcional): tu identificador; repetido es external_id_in_use con el id del que ya existe.

7. Rechazos, reintentos y notas

• Rechazado por la DIAN: corrige con PUT /v1/invoices/{id} (cuerpo completo, nueva Idempotency-Key). Sale con el mismo número. Un rechazo no bloquea los demás envíos.
• Pendiente o en error: POST /v1/invoices/{id}/send lo vuelve a enviar (por ejemplo, después de recargar saldo).
• Validado: ya no se cambia; se corrige con una nota crédito o débito.

curl https://api.trevol.si/v1/credit_notes \
  -H "Authorization: Bearer $TREVOL_LLAVE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice": {"id": "inv_08cd6774e31e401c9fa0fbf92b3fbdc0"},
    "concept": "1",
    "description": "Devolución parcial",
    "items": [{"description": "Devolución de una licencia", "quantity": "1", "unit_price": "50000",
               "taxes": [{"code": "01", "rate": "19"}]}]
  }'

Con una factura de Trevol, la nota usa su cliente si no envías customer. Trevol revisa antes de numerar que la nota crédito no pase del saldo de la factura. Conceptos: NC 1–6, ND 1–4 (tabla de la DIAN).

8. Consultar, listar y archivos

• GET /v1/invoices/{id}: el documento.
• GET /v1/invoices?limit=20&starting_after=inv_…: lista por cursor (también status, external_id, created_from, created_to).
• GET /v1/invoices/{id}/pdf, /xml, /zip y /dian_response: los archivos en binario, listos para guardar.
• GET /v1/dian/acquirer?document_type=31&document_number=…: lo que la DIAN tiene del adquiriente (nombre y correo).

9. Límites

Por llave: 120 envíos por minuto, 20.000 al día y 600 consultas por minuto; por empresa, 50.000 envíos al día entre todas sus llaves. Al pasarse: rate_limited con Retry-After.

10. Rutas

11. Campos

Generados de la especificación OpenAPI.

Factura (cuerpo de POST y PUT /v1/invoices)

Cliente (customer)

Línea (items[])

Impuesto de la línea (items[].taxes[])

Descuento o recargo de la línea

Retención de la línea

Muestra gratis

Identificación estándar del artículo

Pago (payment)

Medio de pago

Periodo

Referencias

Documento referenciado

Descuento o recargo global

Anticipo

Retención del documento

Nota crédito o débito (cuerpo)