Eventos RADIAN

1. Los cinco eventos

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.

2. 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).

3. Enviar un evento

Envía un evento RADIAN sobre 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 RECIBIDA (invoice), o la aceptación tácita (034) de una factura PROPIA a crédito (invoice_id, de Trevol). Los eventos 035 a 051 necesitan un participante RADIAN y no están disponibles. El 030 y el 032 necesitan el representante legal de la empresa (lo firma): se configura en la app. Un rechazo es final: el siguiente intento es otro evento, con otro número (POST nuevo). Un evento vivo del mismo código sobre la misma factura es 409 duplicate_document con existing_id: reintenta ese con POST …/send. already_registered: true (con 201) solo 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 already_registered_elsewhere: true. La DIAN pide el evento anterior antes del siguiente: en la 2026-10-21 es 409 previous_event_pending; en la 2026-10-22, 202 processing y Trevol lo manda cuando aparezca. Si la DIAN contesta 98 («en proceso de validación») es 202 validating: no reenvíes. Para saber si el 034 procede antes de pedirlo, usa GET /v1/invoices/{id}/tacit_acceptance.

curl https://api.trevol.si/v1/radian_events \
  -H "Authorization: Bearer $TREVOL_LLAVE" \
  -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"
    }
  }
}'

HTTP/1.1 201 Created
Location: /v1/radian_events/rev_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b

{
  "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:

curl https://api.trevol.si/v1/radian_events \
  -H "Authorization: Bearer $TREVOL_LLAVE" \
  -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"
  }
}'

4. 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:

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

HTTP/1.1 200 OK

{
  "object": "tacit_acceptance",
  "invoice_id": "inv_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
  "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:

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

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

HTTP/1.1 422
Content-Type: application/problem+json

{
  "type": "https://trevol.si/api/errores#tacit_acceptance_not_due",
  "title": "La aceptación tácita todavía no procede",
  "status": 422,
  "code": "tacit_acceptance_not_due",
  "detail": "La aceptación tácita (034) todavía no procede para esta factura.",
  "retryable": 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)."
    }
  ],
  "request_id": "req_5b1c5b1c5b1c5b1c5b1c5b1c"
}

5. 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).

Las respuestas son las de toda la API: 201 cuando la DIAN valida, 422 dian_rejected con document cuando la rechaza, 422 validation_error si Trevol lo rechaza antes de numerar (no se gasta ningún número), 402 sin saldo, y con la DIAN sin contestar un 202 processing (versión 2026-10-22) o un 503 dian_unavailable (2026-10-21). Idempotency-Key es obligatoria al crear o corregir, y external_id es opcional.

6. Rutas

7. Avisos (webhooks)

Salen por cualquier camino. El data es 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.

{
  "id": "evt_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
  "object": "event",
  "type": "radian_event.rejected",
  "timestamp": "2026-10-23T14:15:03Z",
  "environment": "test",
  "api_version": "2026-10-22",
  "data": {
    "object": "radian_event",
    "id": "rev_3f0c1a2b3f0c1a2b3f0c1a2b3f0c1a2b",
    "status": "rejected",
    "environment": "test",
    "event_code": "031",
    "number": "RC994000124",
    "prefix": "RC",
    "external_id": "ERP-RECLAMO-OJ1234",
    "origin": "api",
    "cude": "abababababababababababababababababababababababababababababababababababababababababababababababab",
    "issued_at": "2026-10-23T09:15:02-05:00",
    "invoice": {
      "cufe": "cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
      "number": "OJ1234",
      "id": null
    },
    "dian": {
      "status_code": "99",
      "rules": [
        {
          "code": "LGC09",
          "severity": "rejection"
        }
      ]
    }
  }
}

8. Campos

Evento (cuerpo de POST)

Factura recibida (invoice)

Emisor de la factura (invoice.issuer)

Reclamo (claim)

Evento (lo que devuelve la API)

Un evento RADIAN 030–034 sobre una factura. Solo archivo xml. Un rechazo es final.

Aceptación tácita (GET …/tacit_acceptance)

¿Procede ya la aceptación tácita (034) sobre una factura propia? Solo lectura: consulta GetStatusEvent con el certificado de la empresa y no envía nada. Límite propio: 30 por minuto por llave.