EMISSION_REQUIRED tiene false como valor predeterminado. Define EMISSION_REQUIRED=true en un despliegue cuyos sistemas downstream dependan de estos eventos. Entonces el bootstrap falla cerrado a menos que la emisión de eventos esté conectada por completo.
Los webhooks registrados reciben eventos durables del plano de control. Las familias settlement.* y spb.ldl.* van solo al backbone de streaming. Los sistemas downstream leen el estado de liquidación de los eventos de streaming settlement.* y no hacen sondeo.
Familias de eventos
Integración con el ledger
Tu consumidor de ledger debe recibir tanto la familia
str.operation.* como la settlement.* en el backbone de streaming. El evento str.operation.accepted señala la aceptación del despacho, no la liquidación en BACEN, así que úsalo para registrar un asiento pendiente.
Registra la posición final a partir de los hechos settlement.* del backbone de streaming. La transición de negocio detrás de settlement.settled ocurre cuando la pata R entrante mueve la operación a CONFIRMED. La entrega del broker es al menos una vez y puede reenviar el hecho. El ce-id es determinista, así que deduplica por el par (ce-source, ce-id).
El evento settlement.failed se dispara cuando BACEN rechaza la operación o cuando una cancelación revierte un original que nunca liquidó. El evento settlement.returned se dispara cuando un retorno confirmado revierte un original liquidado. Un retorno sigue el mismo patrón: str.operation.returnRequested señala la aceptación del despacho del retorno, y el asiento padre se revierte con settlement.returned. Lerian SPB no mantiene ninguna posición contable. El riel transporta el mensaje y su estado de liquidación, y tu ledger registra el dinero.
Webhooks
Los consumidores de webhooks se autorregistran en las constantes canónicas de eventos. Negocian las formas de payload desde un catálogo de eventos compartido. La entrega es durable. Puedes reintentar manualmente una entrega fallida. Un camino dead-letter atiende las entregas que agotan sus reintentos.
Convenciones de la API
- La autenticación es un Bearer token.
- Las escrituras son idempotentes mediante una clave de idempotencia. Un envío reintentado no despacha dos veces.
- Las lecturas del log de mensajes no exponen el frame firmado que viajó por la red. Lees un solo mensaje por su NUOp para obtener datos estructurados. Cuando el riel retuvo un frame, lee su XML reconstruido por la ruta de frame dedicada y autorizada por separado. No retiene por separado los bytes literales enviados.
- Los ids desconocidos devuelven un not-found uniforme. La respuesta nunca revela si existe una operación que tu institución no posee.