Cargando la descripción de la API…
Eventos y webhooks
Firmar depende de personas: pueden pasar días entre que se despacha un flujo y se completa. En lugar de consultar todo el tiempo, registra un webhook y recibe un POST firmado cada vez que pasa algo.
No hay una lista aparte de «eventos de webhook». Lo que recibe tu sistema es exactamente lo que el registro de evidencia va a mostrar después, con el mismo código. Así, cuando tu sistema dice firmado y en un juicio se le pregunta al registro de evidencia, hay una sola versión de los hechos para discutir y no dos — y un evento que se agrega al registro nunca puede dejar de llegarte sin que nadie lo note.
El código de cada evento va adentro del hash que encadena el registro de evidencia, y un trigger de la base de datos impide que nadie le cambie el nombre a uno: por eso un código no cambia nunca, ni siquiera cuando cambia el idioma de la interfaz. Que algunas de sus palabras sean castellanas es porque el producto empezó así; léelas como identificadores, no como texto. Así que mapéalos una sola vez, como mapearías un OID o un eventType de PREMIS, y van a seguir significando lo mismo dentro de diez años. Lo que cambia con el idioma es la descripción legible: cada webhook la lleva en inglés como event_label, y GET /api/v1/event-types la sirve para cada código. Las claves del cuerpo también están en inglés (event, event_label, occurred_at, account, workflow, document, data); las castellanas de antes (evento, ocurrido_en, cuenta, circuito, instancia, datos) viajan al lado una versión más, con payload_version: 2, para que puedas pasarte sin que nada se rompa.
| Evento | Qué significa para tu sistema |
|---|---|
circuito.despachado |
Salió de borrador. Se invitó a las personas y empezó a correr el plazo. |
documento.abierto |
Alguien abrió el documento. Sirve para distinguir “no lo vio” de “lo vio y no firmó”. |
firma.aplicada |
Firmó una persona. Lleva quién, con qué tipo de firma, y el hash del documento antes y después. |
firma.rechazada |
Alguien rechazó firmar, con su motivo. El flujo se detiene. |
circuito.completo |
Todos firmaron. Este es el momento en que existe el informe de finalización, y lleva el id de instancia que le pides al paquete de entrega. |
documento.preservado |
El documento ahora lleva adentro lo necesario para validar sus firmas dentro de años: la cadena de certificación, las respuestas de revocación y, cuando una autoridad de sellado de tiempo responde, un sello de tiempo de documento. |
circuito.cancelado |
El remitente lo canceló. |
Los siete de arriba son los que una integración suele escuchar. El vocabulario completo y autoritativo —cada código que puede llevar el registro de evidencia, con su categoría y su descripción en tres idiomas— se sirve en GET /api/v1/event-types, para que tu sistema lo lea en vez de dejarlo fijo en el código.