Saltar la navegación de la documentación

Español API 2026-10-22

Documentación · Documentos · API v1 · versión 2026-10-22

Eventos RADIAN

Acuse de recibo, reclamo, recibo del bien, aceptación expresa y aceptación tácita de facturas por la API de Trevol.

Registra ante la DIAN los eventos de una factura: el acuse de recibo (030), el reclamo (031), el recibo del bien o servicio (032) y la aceptación expresa (033) de una factura que te emitieron, y la aceptación tácita (034) de una factura tuya a crédito.

Los cinco eventos

`event_code`	Evento	Sobre	Cómo se identifica la factura
`030`	Acuse de recibo	Una factura recibida	`invoice` (CUFE, número, emisor)
`031`	Reclamo	Una factura recibida	`invoice` y `claim` (obligatorio)
`032`	Recibo del bien o servicio	Una factura recibida	`invoice`
`033`	Aceptación expresa	Una factura recibida	`invoice`
`034`	Aceptación tácita	Una factura propia a crédito, validada y no de consumidor final	`invoice_id` (`inv_…`, de Trevol) o `invoice: {cufe}` (también las que emitiste con otro software)

Los eventos 035 a 051 (aval, endosos, pago, cesión…) necesitan un participante RADIAN habilitado y no están disponibles: validation_error en event_code.

Antes de emitir

Los eventos 030 y 032 los firma el representante legal de la empresa: se registra en la app. Sin él, 422 company_not_enabled con reason: "missing_legal_representative". GET /v1/company → capabilities.radian_events dice qué tienes.
Se comprueba antes de numerar. El NIT del emisor de una factura recibida no puede ser el de tu empresa (invoice.issuer.nit).

Enviar un evento

POST /v1/radian_events

cURL

curl -X POST "https://api.trevol.si/v1/radian_events" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "ERP-ACUSE-OJ1234",
  "event_code": "030",
  "invoice": {
    "cufe": "cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
    "number": "OJ1234",
    "type": "01",
    "issuer": {
      "nit": "890330031",
      "check_digit": 3,
      "document_type": "31",
      "name": "OSPINA Y ASOCIADOS SAS"
    }
  }
}'

Probar en el Playground

Respuesta201 Created

{
  "id": "rev_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
  "object": "radian_event",
  "environment": "test",
  "status": "accepted",
  "event_code": "030",
  "number": "AR994000123",
  "prefix": "AR",
  "external_id": "ERP-ACUSE-OJ1234",
  "origin": "api",
  "cude": "abababababababababababababababababababababababababababababababababababababababababababababababab",
  "issued_at": "2026-10-23T09:15:02-05:00",
  "invoice": {
    "cufe": "cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
    "number": "OJ1234",
    "type": "01",
    "issuer": {
      "nit": "890330031",
      "check_digit": 3,
      "document_type": "31",
      "name": "OSPINA Y ASOCIADOS SAS"
    }
  },
  "claim": null,
  "software": "own",
  "provider": "company",
  "dian": {
    "status_code": "02",
    "message": "Documento validado por la DIAN",
    "rules": []
  },
  "already_registered": false,
  "already_registered_elsewhere": false,
  "tacit": false,
  "created_at": "2026-10-23T09:15:02-05:00",
  "updated_at": "2026-10-23T09:15:03-05:00"
}

El reclamo (031) lleva su concepto:

POST /v1/radian_events

cURL

curl -X POST "https://api.trevol.si/v1/radian_events" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "ERP-RECLAMO-OJ1234",
  "event_code": "031",
  "invoice": {
    "cufe": "cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
    "number": "OJ1234",
    "type": "01",
    "issuer": {
      "nit": "890330031",
      "check_digit": 3,
      "document_type": "31",
      "name": "OSPINA Y ASOCIADOS SAS"
    }
  },
  "claim": {
    "code": "02",
    "note": "Faltaron dos cajas"
  }
}'

Probar en el Playground

Respuesta201 Created

{
  "id": "rev_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
  "object": "radian_event",
  "environment": "test",
  "status": "accepted",
  "event_code": "030",
  "number": "AR994000123",
  "prefix": "AR",
  "external_id": "ERP-ACUSE-OJ1234",
  "origin": "api",
  "cude": "abababababababababababababababababababababababababababababababababababababababababababababababab",
  "issued_at": "2026-10-23T09:15:02-05:00",
  "invoice": {
    "cufe": "cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
    "number": "OJ1234",
    "type": "01",
    "issuer": {
      "nit": "890330031",
      "check_digit": 3,
      "document_type": "31",
      "name": "OSPINA Y ASOCIADOS SAS"
    }
  },
  "claim": null,
  "software": "own",
  "provider": "company",
  "dian": {
    "status_code": "02",
    "message": "Documento validado por la DIAN",
    "rules": []
  },
  "already_registered": false,
  "already_registered_elsewhere": false,
  "tacit": false,
  "created_at": "2026-10-23T09:15:02-05:00",
  "updated_at": "2026-10-23T09:15:03-05:00"
}

La aceptación tácita (034)

Procede cuando pasan 3 días hábiles desde el recibo del bien o servicio (032) sin que el comprador reclame ni acepte. Para no gastar un evento en vano, pregunta primero:

GET /v1/invoices/{id}/tacit_acceptance

cURL

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

Probar en el Playground

Respuesta200 OK

{
  "object": "tacit_acceptance",
  "invoice_id": "inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
  "cufe": "abababababababababababababababababababababababababababababababababababababababababababababababab",
  "number": "FE1234",
  "allowed": false,
  "available_from": "2026-10-27",
  "rules": [
    {
      "code": "LGC14",
      "severity": "rejection",
      "local": true,
      "message": "Faltan días hábiles para la aceptación tácita.",
      "explanation": "Pasan 3 días hábiles desde el recibo del bien o servicio (evento 032)."
    }
  ]
}

Solo lee: consulta a la DIAN con el certificado de la empresa y no envía nada; usa el mismo historial que el envío, y tiene su propio límite de 30 consultas por minuto por llave. Cuando procede, se pide con invoice_id en lugar de invoice:

POST /v1/radian_events

cURL

curl -X POST "https://api.trevol.si/v1/radian_events" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "ERP-TACITA-FE1234",
  "event_code": "034",
  "invoice_id": "inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b"
}'

Probar en el Playground

Respuesta201 Created

{
  "id": "rev_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
  "object": "radian_event",
  "environment": "test",
  "status": "accepted",
  "event_code": "030",
  "number": "AR994000123",
  "prefix": "AR",
  "external_id": "ERP-ACUSE-OJ1234",
  "origin": "api",
  "cude": "abababababababababababababababababababababababababababababababababababababababababababababababab",
  "issued_at": "2026-10-23T09:15:02-05:00",
  "invoice": {
    "cufe": "cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
    "number": "OJ1234",
    "type": "01",
    "issuer": {
      "nit": "890330031",
      "check_digit": 3,
      "document_type": "31",
      "name": "OSPINA Y ASOCIADOS SAS"
    }
  },
  "claim": null,
  "software": "own",
  "provider": "company",
  "dian": {
    "status_code": "02",
    "message": "Documento validado por la DIAN",
    "rules": []
  },
  "already_registered": false,
  "already_registered_elsewhere": false,
  "tacit": false,
  "created_at": "2026-10-23T09:15:02-05:00",
  "updated_at": "2026-10-23T09:15:03-05:00"
}

Si todavía no procede, el envío responde 422 tacit_acceptance_not_due con la fecha (available_from) y las reglas; el evento queda en error con su número y se reintenta con POST /v1/radian_events/{id}/send cuando proceda.

La aceptación tácita de una factura que no emitiste con Trevol

Las facturas que emitiste antes, con otro software, también admiten el 034: Trevol las conoce por la sincronización con la DIAN. En lugar de invoice_id, identifica la factura por su CUFE en invoice (exactamente uno de los dos). number es opcional: si lo mandas, tiene que ser el de esa factura.

POST /v1/radian_events

cURL

curl -X POST "https://api.trevol.si/v1/radian_events" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "ERP-TACITA-FE4722",
  "event_code": "034",
  "invoice": {
    "cufe": "abababababababababababababababababababababababababababababababababababababababababababababababab",
    "number": "FE4722"
  }
}'

Probar en el Playground

Respuesta201 Created

{
  "id": "rev_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
  "object": "radian_event",
  "environment": "test",
  "status": "accepted",
  "event_code": "030",
  "number": "AR994000123",
  "prefix": "AR",
  "external_id": "ERP-ACUSE-OJ1234",
  "origin": "api",
  "cude": "abababababababababababababababababababababababababababababababababababababababababababababababab",
  "issued_at": "2026-10-23T09:15:02-05:00",
  "invoice": {
    "cufe": "cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
    "number": "OJ1234",
    "type": "01",
    "issuer": {
      "nit": "890330031",
      "check_digit": 3,
      "document_type": "31",
      "name": "OSPINA Y ASOCIADOS SAS"
    }
  },
  "claim": null,
  "software": "own",
  "provider": "company",
  "dian": {
    "status_code": "02",
    "message": "Documento validado por la DIAN",
    "rules": []
  },
  "already_registered": false,
  "already_registered_elsewhere": false,
  "tacit": false,
  "created_at": "2026-10-23T09:15:02-05:00",
  "updated_at": "2026-10-23T09:15:03-05:00"
}

La consulta previa también va por CUFE, con la misma respuesta y el mismo límite (las dos consultas comparten las 30 por minuto):

GET /v1/radian_events/tacit_acceptance

cURL

curl "https://api.trevol.si/v1/radian_events/tacit_acceptance?cufe=abababababababababababababababababababababababababababababababababababababababababababababababab" \
  -H "Authorization: Bearer $TREVOL_API_KEY"

Probar en el Playground

Respuesta200 OK

{
  "object": "tacit_acceptance",
  "cufe": "abababababababababababababababababababababababababababababababababababababababababababababababab",
  "number": "FE4722",
  "allowed": true,
  "available_from": "2025-05-14",
  "rules": []
}

La factura tiene que ser tuya (de la empresa y el ambiente de la llave), una factura electrónica de venta (01), aprobada por la DIAN, a crédito y no de consumidor final, con su XML ya leído por la sincronización. Si no, 422 validation_error en invoice.cufe con el motivo; no se gasta ningún número. Un CUFE que no es de tu empresa es «no existe», sin decir si es de otra.
La sincronización trae las facturas de producción: con una llave de pruebas, el 034 va sobre una factura de Trevol (invoice_id).
Si el CUFE es de una factura de Trevol, es lo mismo que mandar su invoice_id: la respuesta trae invoice.id. Si no, invoice trae solo cufe y number.
Las mismas reglas de siempre: el 030 y el 032 del comprador en la DIAN, sin reclamo, aceptación expresa ni otro 034, y 3 días hábiles desde el 032. Un 034 vivo sobre esa factura (por la API, por la app o de antes) es 409 duplicate_document.

Lo que hay que saber

Un rechazo es final. El siguiente intento es otro evento con otro número (un POST nuevo, con otra Idempotency-Key). No hay PUT.
Un evento vivo por factura y código. Otro POST del mismo código sobre la misma factura es 409 duplicate_document con el existing_id (rev_…), lo haya creado la API o la app. Para reintentar ese evento: POST /v1/radian_events/{id}/send.
El orden de la DIAN. La DIAN pide el evento anterior antes del siguiente. Si todavía no lo muestra, en la versión 2026-10-21 es 409 previous_event_pending (no se envió nada; reintenta con POST …/send); en la 2026-10-22 es un 202 processing y Trevol lo manda cuando aparezca.
El 98 de la DIAN («en proceso de validación») es 202 con status: "validating" en las dos versiones: Trevol solo consulta; no reenvíes.
already_registered: true (con 201) significa que la DIAN ya mostraba el CUDE de este evento. Si la factura ya tenía ese evento por otro camino, es 422 dian_rejected con document.already_registered_elsewhere: true.
Solo se descarga el …/xml. Se cobra con la lista de eventos del canal API.
El external_id es único entre los eventos (aparte de las facturas y las nóminas).
Los avisos (webhooks) son un resumen sin nombres ni NIT de quien emitió la factura. Los avisos «todavía no procede» y «falta el evento anterior» no emiten radian_event.error.

Referencia: Eventos RADIAN.