Skip to main content
Midaz emite sus hechos públicos de negocio JSON como CloudEvents 1.0 en modo de contenido binario sobre Kafka mediante lib-streaming.

Catálogo público JSON del ledger

El manifiesto público del ledger contiene las definiciones verificadas a continuación. Cada definición catalogada tiene una ruta de emisión de producción no relacionada con pruebas.

Sobre CloudEvents

Cada hecho JSON público usa el sobre compartido de abajo. Los encabezados llevan información de enrutamiento y esquema; el valor de Kafka lleva el objeto JSON data.

Tópicos, manifest y enrutamiento

El tópico de aplicación identifica la aplicación productora, no un evento individual. Enruta un registro por ce-resourcetype y ce-eventtype, y valida ce-schemaversion antes de decodificar su valor data.
  • Hechos: lerian.streaming.ledger
  • DLQ de ruta: lerian.streaming.ledger.dlq
  • Manifest: GET /v1/streaming/manifest expone el catálogo JSON público y el mapeo de tópicos, incluso cuando la publicación está deshabilitada.

Semántica de entrega y fallo

La publicación permanece deshabilitada hasta que STREAMING_ENABLED=true y la configuración de brokers tiene éxito. Cuando está habilitada, Midaz emite después del cambio de estado de negocio. No conecta un writer de outbox, un repositorio de outbox, un outbox transaccional ni un relay de outbox de lib-streaming.
  • Política: cada definición JSON pública es un fact con entrega directa, gestión de DLQ on_routable_failure y fallback_on_circuit_open configurado por lib-streaming v3.
  • Límite real de Midaz: como no hay ningún writer de outbox conectado, el fallback de circuito abierto no puede persistir un evento. Las rutas de emisión registran y descartan los errores de publicación en lugar de devolverlos al comando de negocio.
  • Requisito del consumidor: la entrega del broker es al menos una vez para los registros publicados. Mantén handlers idempotentes y deduplica con (ce-source, ce-id).

Plano heredado separado de RabbitMQ

Midaz también tiene exchanges de compatibilidad para notificaciones seleccionadas de transacciones, overdraft y auditoría. Son un plano heredado separado de RabbitMQ, no un contrato de lib-streaming ni una representación completa de este catálogo público de 49 eventos JSON. Para integraciones nuevas, usa el contrato Kafka de esta página.

Contratos completos de data

Estas declaraciones de estilo TypeScript reflejan la forma wire del productor. Cada nombre de campo es su nombre JSON. ? significa que el campo tiene omitempty; | null significa que el campo acepta nulo sin omitirse. Un comentario de tipo de origen conserva exactamente el tipo del inventario. Los valores decimales son cadenas JSON, nunca números binarios de punto flotante.

Mapeos compartidos de tipos de origen

Evento: studio.lerian.ledger.account.createdTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Se abre una cuenta en un ledger.Subject: ID de cuenta (p.ID)
Evento: studio.lerian.ledger.account.deletedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Se elimina una cuenta.Subject: ID de cuenta (p.ID)
Evento: studio.lerian.ledger.account.updatedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Cambian los campos mutables de una cuenta.Subject: ID de cuenta (p.ID)
Evento: studio.lerian.ledger.asset.createdTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Se registra un activo en un ledger.Subject: ID de activo (p.ID)
Evento: studio.lerian.ledger.asset.deletedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Se elimina un activo.Subject: ID de activo (p.ID)
Evento: studio.lerian.ledger.asset.updatedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Cambian los campos mutables de un activo.Subject: ID de activo (p.ID)
Evento: studio.lerian.ledger.balance.changedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Una transacción confirmada mueve un saldo — un evento por cada operación que afecta al saldo; los valores reflejan el estado posterior a la operación.Subject: ID de transacción e ID de operación (p.TransactionID + ":" + p.OperationID)
Evento: studio.lerian.ledger.balance.config_changedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Cambian los ajustes de un saldo, o se habilita el sobregiro (se materializa el saldo acompañante). changeType distingue settings_updated de overdraft_enabled.Subject: ID de saldo (p.ID)
Evento: studio.lerian.ledger.balance.createdTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Se crea un saldo durante la configuración de la cuenta.Subject: ID de saldo (p.ID)
Evento: studio.lerian.ledger.balance.deletedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Se elimina un saldo.Subject: ID de saldo (p.ID)
Evento: studio.lerian.ledger.balance.overdraft_clearedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: El sobregiro se salda por completo — señal terminal (action = cleared).Subject: ID de transacción e ID de operación (p.TransactionID + ":" + p.OperationID)
Evento: studio.lerian.ledger.balance.overdraft_drawnTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Un débito consume sobregiro más allá de los fondos disponibles (action = drawn).Subject: ID de transacción e ID de operación (p.TransactionID + ":" + p.OperationID)
Evento: studio.lerian.ledger.balance.overdraft_repaidTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: El uso del sobregiro disminuye pero no se salda por completo (action = repaid).Subject: ID de transacción e ID de operación (p.TransactionID + ":" + p.OperationID)
Evento: studio.lerian.ledger.fee_billing_packages.createdTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Se crea un paquete de facturación.Subject: ID de paquete de facturación (p.ID)
Evento: studio.lerian.ledger.fee_billing_packages.deletedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Se elimina un paquete de facturación.Subject: ID de paquete de facturación (p.ID)
Evento: studio.lerian.ledger.fee_billing_packages.updatedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Cambian los campos mutables de un paquete de facturación.Subject: ID de paquete de facturación (p.ID)
Evento: studio.lerian.ledger.fee_charge.appliedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Se aplica un paquete de tarifas a una transacción confirmada.Subject: ID de transacción (p.TransactionID)
Evento: studio.lerian.ledger.fee_packages.createdTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Se crea un paquete de tarifas.Subject: ID de paquete de tarifas (p.ID)
Evento: studio.lerian.ledger.fee_packages.deletedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Se elimina un paquete de tarifas.Subject: ID de paquete de tarifas (p.ID)
Evento: studio.lerian.ledger.fee_packages.updatedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Cambian los campos mutables de un paquete de tarifas.Subject: ID de paquete de tarifas (p.ID)
Evento: studio.lerian.ledger.holder.createdTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Se crea un titular.Subject: ID de titular (p.ID)
Evento: studio.lerian.ledger.holder.deletedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Se elimina un titular.Subject: ID de titular (p.ID)
Evento: studio.lerian.ledger.holder.updatedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Cambian los campos mutables de un titular.Subject: ID de titular (p.ID)
Evento: studio.lerian.ledger.instrument.createdTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Se crea un instrumento para un titular y una cuenta.Subject: ID de instrumento (p.ID)
Evento: studio.lerian.ledger.instrument.deletedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Se elimina un instrumento.Subject: ID de instrumento (p.ID)
Evento: studio.lerian.ledger.instrument.updatedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Cambian los campos mutables de un instrumento.Subject: ID de instrumento (p.ID)
Evento: studio.lerian.ledger.ledger.createdTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Se crea un ledger dentro de una organización.Subject: ID de ledger (p.ID)
Evento: studio.lerian.ledger.ledger.deletedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Se elimina un ledger.Subject: ID de ledger (p.ID)
Evento: studio.lerian.ledger.ledger.updatedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Cambia el nombre o el estado de un ledger.Subject: ID de ledger (p.ID)
Evento: studio.lerian.ledger.operation_route.createdTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Se crea una ruta de operación.Subject: ID de ruta de operación (p.ID)
Evento: studio.lerian.ledger.operation_route.deletedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Se elimina una ruta de operación.Subject: ID de ruta de operación (p.ID)
Evento: studio.lerian.ledger.operation_route.updatedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Cambian los campos mutables de una ruta de operación.Subject: ID de ruta de operación (p.ID)
Evento: studio.lerian.ledger.organization.createdTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Se crea una organización.Subject: ID de organización (p.ID)
Evento: studio.lerian.ledger.organization.deletedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Se elimina una organización.Subject: ID de organización (p.ID)
Evento: studio.lerian.ledger.organization.updatedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Cambian los campos mutables de una organización.Subject: ID de organización (p.ID)
Evento: studio.lerian.ledger.portfolio.createdTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Se crea un portafolio.Subject: ID de portafolio (p.ID)
Evento: studio.lerian.ledger.portfolio.deletedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Se elimina un portafolio.Subject: ID de portafolio (p.ID)
Evento: studio.lerian.ledger.portfolio.updatedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Cambian los campos mutables de un portafolio.Subject: ID de portafolio (p.ID)
Evento: studio.lerian.ledger.segment.createdTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Se crea un segmento.Subject: ID de segmento (p.ID)
Evento: studio.lerian.ledger.segment.deletedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Se elimina un segmento.Subject: ID de segmento (p.ID)
Evento: studio.lerian.ledger.segment.updatedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Cambian los campos mutables de un segmento.Subject: ID de segmento (p.ID)
Evento: studio.lerian.ledger.transaction.canceledTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Una transacción pendiente pasa de PENDING a CANCELED.Subject: ID de transacción (p.ID)
Evento: studio.lerian.ledger.transaction.committedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Una transacción pendiente pasa de PENDING a APPROVED.Subject: ID de transacción (p.ID)
Evento: studio.lerian.ledger.transaction.postedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Una transacción recién creada se confirma en el almacenamiento con todas sus operaciones persistidas (sin padre).Subject: ID de transacción (p.ID)
Evento: studio.lerian.ledger.transaction.revertedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Un flujo de reversión crea una transacción hija; parentTransactionId la correlaciona con la original.Subject: ID de transacción (p.ID)
Evento: studio.lerian.ledger.transaction_route.createdTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Se crea una ruta de transacción.Subject: ID de ruta de transacción (p.ID)
Evento: studio.lerian.ledger.transaction_route.deletedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Se elimina una ruta de transacción.Subject: ID de ruta de transacción (p.ID)
Evento: studio.lerian.ledger.transaction_route.updatedTópico: lerian.streaming.ledgerDLQ de ruta: lerian.streaming.ledger.dlqEsquema: 1.0.0Se emite cuando: Cambian los campos mutables de una ruta de transacción.Subject: ID de ruta de transacción (p.ID)

Evento interno de billing (fuera del catálogo público)

billing_recorded se emite por separado de los 49 hechos JSON públicos. Usa Protobuf con framing Confluent, no el manifest JSON público, y su tópico fijo es lerian.streaming.billing.recorded. No lo cuentes como un evento del manifest ni lo decodifiques como los contratos JSON data de arriba. Conserva los encabezados CloudEvents 1.0 con ce-source=ledger, ce-resourcetype=billing, ce-eventtype=recorded y ce-time definido como la fecha de creación de la transacción. Tipo CloudEvents: studio.lerian.ledger.billing.recorded Tópico: lerian.streaming.billing.recorded Tipo de contenido: application/vnd.confluent.protobuf Esquema: 1.0.0 DLQ de ruta: lerian.streaming.ledger.dlq Tenant: ce-tenantid sigue la misma regla de tenant resuelto o literal default que los hechos públicos. Subject: ID de cuenta Se emite cuando: Una escritura de ciclo de vida no noop deja la transacción en estado APPROVED; Midaz emite un registro por cada cuenta no externa única referenciada por sus operaciones.
Midaz rellena metric como active_account; properties.account_id y properties.transaction_id como cadenas; y subscription_id como el ID de tenant en modo multi-tenant o como el ID de organización de la transacción en los demás casos.