Registro de cambios

2026-10-22

Qué cambió. Con la DIAN sin contestar, la creación de un documento responde 202 Accepted con status: "processing" (o sending, si otra petición o el fondo lo está enviando) en lugar del 503 dian_unavailable. El 202 trae Location y Retry-After: 30. Trevol termina el documento por su cuenta (pregunta a la DIAN por el CUFE y, si hace falta, lo reenvía) y avisa por webhook con ….accepted, ….rejected o ….error. Repetir la petición con la misma Idempotency-Key sobre un documento que Trevol está resolviendo no envía nada: responde otro 202 con el estado actual (o el 201 si ya se validó). En los eventos RADIAN, la falta del evento anterior en la DIAN (previous_event_pending) pasa a ser un 202 processing.

A quién afecta. A las llaves creadas desde esta versión (nacen en 2026-10-22) y a quien mande Trevol-Version: 2026-10-22. Las llaves anteriores siguen en 2026-10-21 mientras no mandes el encabezado.

Cómo migrar. Trata el 202 como un resultado, no como un error: guarda el id y el número, no crees otro documento para la misma venta y espera el webhook (o consulta con GET). Los SDK ya lo hacen: devuelven el modelo con su status y no reintentan un 202. Un SDK fija Trevol-Version en 2026-10-22; si todavía no quieres cambiar, crea el cliente con apiVersion: '2026-10-21' (o la opción equivalente de tu lenguaje).

2026-10-21

Qué cambió. La primera versión pública de la API v1: facturas, notas crédito y débito, llaves por empresa y ambiente, idempotencia, errores application/problem+json. Con la DIAN sin contestar responde 503 dian_unavailable (el documento queda en error y Trevol lo verifica en segundo plano, solo consulta).

A quién afecta. A las llaves creadas antes del 22 de octubre de 2026 y a quien mande Trevol-Version: 2026-10-21.

Cómo migrar. No hace falta migrar para seguir como hasta ahora. Cuando quieras el 202 processing, manda Trevol-Version: 2026-10-22 (más arriba).

Sin versión nueva

Estos cambios son aditivos o de texto: valen igual para las dos versiones y no piden migrar nada.

2026-11-01: el ejemplo principal de factura es una venta nacional

Solo cambian los ejemplos de la especificación y de la documentación: el primer ejemplo de POST /v1/invoices, POST /v1/invoices/preview y PUT /v1/invoices/{id} pasa a ser una venta nacional en pesos (cliente con NIT, dos ítems con IVA del 19 %, pago a crédito a 30 días), y la exportación en dólares queda como segundo ejemplo. Los fragmentos de código, los SDK de referencia y las colecciones de Postman, Insomnia y Bruno se regeneraron con ese ejemplo. La API no cambia.

2026-11-01: la documentación se muda a platform.trevol.si

• El type de los errores cambia de dirección. Antes https://trevol.si/api/errores#<code>; ahora https://platform.trevol.si/docs/errores#<code>, con un ancla por cada code. Es lo único que cambia en el cuerpo de un error. A quién afecta: a quien compare el type como texto (programa contra code, que no cambia). Las direcciones viejas del sitio dejan de existir, sin redirecciones.
• Hasta siete días después del despliegue, una repetición con la misma Idempotency-Key de un error 4xx guardado antes puede traer todavía la dirección anterior en el type.
• El User-Agent de los webhooks pasa a Trevol-Webhooks/1.0 (+https://platform.trevol.si/docs/webhooks).
• Especificación OpenAPI: cada operación tiene su operationId (por ejemplo createInvoice), los listados de documentos declaran el sobre de lista ({object, data, has_more, next_cursor}), las respuestas declaran las cabeceras Request-Id, Trevol-Version e Idempotent-Replayed, y todos los cuerpos de petición tienen ejemplo. Problem.request_id deja de ser obligatorio en el esquema (el borde de la API no siempre lo tiene).
• Corrección de la especificación: check_digit de GET /v1/company se declaraba texto, pero la API siempre lo ha devuelto como número (por ejemplo 6). La especificación ahora dice integer (o null), como en customer, seller y el emisor de una factura recibida. La respuesta no cambia.
• Nuevo: SDK en siete lenguajes, colecciones de Postman, Insomnia y Bruno (Descargas), esta documentación con ejemplos por lenguaje, un servidor MCP y llms.txt (Para IA).

2026-10-31: el saldo por la API

Tres rutas nuevas: GET /v1/balance, GET /v1/balance/transactions y POST /v1/balance/top_ups, y los códigos de error top_up_below_minimum, top_up_above_maximum y top_ups_unavailable. Ver Saldo.

2026-10-23: aceptación tácita por CUFE

POST /v1/radian_events admite el evento 034 sobre una factura emitida fuera de Trevol, identificada por su CUFE (invoice: {cufe}), y GET /v1/radian_events/tacit_acceptance?cufe=… la consulta antes. Ver Eventos RADIAN.

2026-10-22 y 2026-10-23: documento soporte, documento equivalente, nómina y RADIAN

Se suman a la API el documento soporte (05) y su nota de ajuste (95), los documentos equivalentes (POS 20 y otros nueve tipos) con su nota de ajuste, la nómina electrónica (102) y su nota de ajuste (103) y los eventos RADIAN 030 a 034, con sus tipos de evento de webhook nuevos y los códigos de error duplicate_document, previous_event_pending y tacit_acceptance_not_due. Los webhooks creados antes con ["*"] siguen recibiendo solo los 22 tipos de entonces hasta que guardes de nuevo su lista de eventos. Ver Webhooks.

2026-10-22: webhooks y eventos

POST /v1/webhook_endpoints y sus rutas (rotar secreto, probar, entregas), GET /v1/events y su reenvío, y el registro de peticiones (GET /v1/requests). Avisos firmados con Standard Webhooks. Ver Webhooks.

2026-10-21: la primera API

Facturas, notas crédito y débito, GET /v1/company y GET /v1/dian/acquirer. Ver Facturas.