> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Eventos de Matcher

> Consulta los eventos de dominio que emite Lerian Matcher — contextos de conciliación, corridas de matching, excepciones, disputas y gobernanza — con payloads y semántica de entrega.

Matcher emite eventos de dominio como mensajes **CloudEvents 1.0** en modo de contenido binario sobre Kafka, publicados vía `lib-streaming`. Cada evento viaja en el [sobre compartido](/es/reference/events/overview): `ce-type` nombra el evento como `studio.lerian.<resource>.<event>`, `ce-subject` lleva el id del agregado, `ce-tenantid` el tenant propietario y `ce-schemaversion` la versión del payload — `1.0.0` para todos los eventos de abajo.

El `ce-source` viene de `STREAMING_CLOUDEVENTS_SOURCE` y es obligatorio cuando el streaming está habilitado; los despliegues convencionalmente definen `matcher`, así que los tópicos llegan a `matcher.<resource>.<event>` (consulta [Nombres de tópicos](/es/reference/events/overview#nombres-de-tópicos)). Los importes de dinero — valores de comisiones, importes de ajuste — viajan por el hilo como **cadenas** decimales, nunca como floats. Matcher sirve su catálogo completo de eventos en `GET /system/matcher/streaming/manifest`.

Esta página cubre el plano de streaming Kafka. El despacho de **webhooks** de excepción de Matcher — callbacks HTTP para el enrutamiento de excepciones — es una superficie separada, documentada en [Webhooks y callbacks](/es/matcher/integrations/matcher-webhooks-callbacks).

## Políticas de entrega

El catálogo de Matcher usa dos políticas de entrega:

* Los eventos **respaldados por outbox** se escriben en el outbox dentro de la misma transacción de base de datos que el cambio de estado; un relay publica las filas confirmadas y reintenta durante las caídas del broker. Son los hechos de grado de auditoría (desenlaces de matching, resoluciones de excepción, disputas, gobernanza). Esta política no puede debilitarse por despliegue.
* Los eventos **directos** publican después de que la transacción confirma, con mejor esfuerzo, cayendo al outbox solo cuando el circuito del broker está abierto. Son las señales de configuración y de ciclo de vida operativo.

Cada tabla de abajo indica la política de sus eventos.

## Eventos de matching

Respaldados por outbox: `transaction.matched`, `transaction.pending_review`. Directos: el resto.

| Evento (`ce-type`)                         | Tópico                               | Se dispara cuando                                                                                                                               | Payload principal                                                                                                                                                                                                      |
| ------------------------------------------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `studio.lerian.transaction.matched`        | `matcher.transaction.matched`        | Una línea de transacción alcanza el estado terminal MATCHED en el commit de una corrida de matching — un evento por línea emparejada.           | `transaction_id`, `context_id`, `match_run_id`, `previous_status`, `status`, `match_group_id`?, `candidate_match_group_id`?, `source_id`?, `matched_at`?                                                               |
| `studio.lerian.transaction.pending_review` | `matcher.transaction.pending_review` | Un candidato a match necesita revisión humana (regla no automática).                                                                            | Mismo esquema, con `pending_review_at`?                                                                                                                                                                                |
| `studio.lerian.transaction.ignored`        | `matcher.transaction.ignored`        | Una transacción se excluye del matching.                                                                                                        | `transaction_id`, `ingestion_job_id`, `context_id`, `source_id`, `previous_status`, `status`, `extraction_status`, `updated_at`                                                                                        |
| `studio.lerian.match_run.completed`        | `matcher.match_run.completed`        | Una corrida de matching termina. Lender consume este evento para traducir los veredictos de conciliación en acciones de servicing de préstamos. | `match_run_id`, `context_id`, `mode`, `status`, `stats`, `started_at`, `completed_at`?                                                                                                                                 |
| `studio.lerian.match_run.failed`           | `matcher.match_run.failed`           | Una corrida de matching falla.                                                                                                                  | Como `completed`, más `failure_reason`                                                                                                                                                                                 |
| `studio.lerian.match_group.confirmed`      | `matcher.match_group.confirmed`      | Un grupo de match se confirma.                                                                                                                  | `match_group_id`, `match_run_id`, `context_id`, `rule_id`, `transaction_ids`, `confidence`, `status`, `confirmed_at`?                                                                                                  |
| `studio.lerian.match_group.unmatched`      | `matcher.match_group.unmatched`      | Un grupo de match confirmado se deshace.                                                                                                        | Como `confirmed`, más `previous_status`, `reason`, `unmatched_at`                                                                                                                                                      |
| `studio.lerian.fee_variance.created`       | `matcher.fee_variance.created`       | Una regla fee-aware detecta una variación entre comisiones esperadas y reales.                                                                  | `fee_variance_id`, `context_id`, `match_run_id`, `match_group_id`, `transaction_id`, `fee_schedule_id`, `fee_schedule_name_snapshot`, `currency`, `expected_fee`, `actual_fee`, `delta`, `variance_type`, `created_at` |

## Eventos de excepción y disputa

Respaldados por outbox, excepto `exception.assigned` y los eventos de comentario, que son directos.

| Evento (`ce-type`)                              | Tópico                                    | Se dispara cuando                                                     | Payload principal                                                                                      |
| ----------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `studio.lerian.exception.assigned`              | `matcher.exception.assigned`              | Una excepción se asigna a un operador.                                | `exception_id`, `status`, `version`, `assigned_at`                                                     |
| `studio.lerian.exception.resolved`              | `matcher.exception.resolved`              | Una excepción se resuelve.                                            | `exception_id`, `status`, `version`, `resolution_type`?, `transaction_id`?, `resolved_at`              |
| `studio.lerian.exception.force_match_resolved`  | `matcher.exception.force_match_resolved`  | Una excepción se resuelve por force-match con un motivo de anulación. | Campos base más `resolution_type` (`FORCE_MATCH`), `override_reason_code`, `resolved_at`               |
| `studio.lerian.exception.adjust_entry_resolved` | `matcher.exception.adjust_entry_resolved` | Una excepción se resuelve mediante un asiento de ajuste.              | Campos base más `resolution_type` (`ADJUST_ENTRY`), `reason_code`, `amount`, `currency`, `resolved_at` |
| `studio.lerian.exception.dispatched`            | `matcher.exception.dispatched`            | Una excepción se despacha a un sistema externo.                       | `exception_id`, `target_system`, `queue`, `external_reference`, `acknowledged`, `dispatched_at`        |
| `studio.lerian.exception.callback_processed`    | `matcher.exception.callback_processed`    | El callback de un sistema externo se aplica a una excepción.          | Campos base más `external_system`, `external_issue_id`, `callback_type`, `processed_at`                |
| `studio.lerian.exception_comment.added`         | `matcher.exception_comment.added`         | Se añade un comentario a un hilo de excepción.                        | `comment_id`, `exception_id`, `created_at`                                                             |
| `studio.lerian.exception_comment.deleted`       | `matcher.exception_comment.deleted`       | Se elimina un comentario.                                             | `comment_id`, `exception_id`, `actor`, `deleted_at`                                                    |
| `studio.lerian.dispute.opened`                  | `matcher.dispute.opened`                  | Se abre una disputa sobre una excepción.                              | `dispute_id`, `exception_id`, `state`, `resolution`?, `category`, `opened_at`                          |
| `studio.lerian.dispute.won`                     | `matcher.dispute.won`                     | Una disputa cierra como ganada.                                       | Como `opened`, más `closed_at`                                                                         |
| `studio.lerian.dispute.lost`                    | `matcher.dispute.lost`                    | Una disputa cierra como perdida.                                      | Como `opened`, más `closed_at`                                                                         |
| `studio.lerian.evidence.submitted`              | `matcher.evidence.submitted`              | Se adjunta evidencia a una disputa.                                   | `evidence_id`, `dispute_id`, `exception_id`, `has_file`, `submitted_at`                                |

## Eventos de configuración e ingesta de datos

Todos directos.

| Evento (`ce-type`)                             | Tópico                                   | Se dispara cuando                                                            | Payload principal                                                                                                                                     |
| ---------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `studio.lerian.reconciliation_context.created` | `matcher.reconciliation_context.created` | Se crea un contexto de conciliación.                                         | `context_id`, `name`, `context_type`, `interval`, `status`, `auto_match_on_upload`, `created_at`, `tenant_id`                                         |
| `studio.lerian.reconciliation_context.updated` | `matcher.reconciliation_context.updated` | Los metadatos o el estado de ciclo de vida de un contexto cambian.           | Mismo esquema, con `updated_at`                                                                                                                       |
| `studio.lerian.reconciliation_source.created`  | `matcher.reconciliation_source.created`  | Se crea una fuente (lado de entrada) en un contexto.                         | `context_id`, `source_id`, `name`, `source_type`, `side`, `created_at`                                                                                |
| `studio.lerian.match_rule.created`             | `matcher.match_rule.created`             | Se crea una regla de match.                                                  | `context_id`, `rule_id`, `rule_type`, `priority`, `config_hash`, `created_at`                                                                         |
| `studio.lerian.match_rule.reordered`           | `matcher.match_rule.reordered`           | Se reordenan las prioridades de las reglas.                                  | `context_id`, `ordered_rule_ids`, `priority_version`, `reordered_at`                                                                                  |
| `studio.lerian.fetcher_connection.synced`      | `matcher.fetcher_connection.synced`      | Una conexión de Fetcher y su snapshot de esquema descubierto se sincronizan. | `connection_id`, `fetcher_connection_id`, `config_name`, `database_type`, `status`, `schema_discovered`, `last_seen_at`, `updated_at`                 |
| `studio.lerian.fetcher_connection.unreachable` | `matcher.fetcher_connection.unreachable` | Una conexión de Fetcher queda inalcanzable.                                  | Mismo esquema, más `previous_status`                                                                                                                  |
| `studio.lerian.extraction_request.created`     | `matcher.extraction_request.created`     | Se crea una solicitud de extracción contra una conexión.                     | `extraction_request_id`, `connection_id`, `status`, `table_count`, `has_filters`, `start_date`, `end_date`, `created_at`                              |
| `studio.lerian.ingestion.completed`            | `matcher.ingestion.completed`            | Un job de ingesta termina.                                                   | `job_id`, `context_id`, `source_id`, `status`, `total_rows`, `failed_rows`, `transaction_count`, `date_range_start`, `date_range_end`, `completed_at` |
| `studio.lerian.ingestion.failed`               | `matcher.ingestion.failed`               | Un job de ingesta falla.                                                     | `job_id`, `context_id`, `source_id`, `status`, `total_rows`, `failed_rows`, `error_code`, `failed_at`                                                 |

## Eventos de gobernanza y reportes

Respaldados por outbox, excepto la familia de export-job, que es directa.

| Evento (`ce-type`)                       | Tópico                             | Se dispara cuando                                                | Payload principal                                                                                                                                                                                                           |
| ---------------------------------------- | ---------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `studio.lerian.audit_log.created`        | `matcher.audit_log.created`        | Se persiste una entrada de log de auditoría encadenada por hash. | `audit_log_id`, `tenant_id`, `entity_type`, `entity_id`, `action`, `tenant_seq`, `hash_version`, `record_hash`, `created_at`                                                                                                |
| `studio.lerian.archive_metadata.created` | `matcher.archive_metadata.created` | El worker de archivado registra una partición de archivo.        | `archive_metadata_id`, `tenant_id`, `partition_name`, `date_range_start`, `date_range_end`, `status`, `created_at`, `updated_at`, más `checksum`?, `row_count`?, `compressed_size_bytes`?, `storage_class`?, `archived_at`? |
| `studio.lerian.archive.uploaded`         | `matcher.archive.uploaded`         | Un archivo se sube al almacenamiento.                            | Mismo esquema                                                                                                                                                                                                               |
| `studio.lerian.archive.completed`        | `matcher.archive.completed`        | Un ciclo de archivado termina.                                   | Mismo esquema                                                                                                                                                                                                               |
| `studio.lerian.actor.pseudonymized`      | `matcher.actor.pseudonymized`      | Los datos personales de un actor se seudonimizan (GDPR/LGPD).    | `actor_id`, `pseudonymized`, `display_name_status`, `email_status`, `updated_at`, `tenant_id`                                                                                                                               |
| `studio.lerian.export_job.created`       | `matcher.export_job.created`       | Se crea un job de exportación.                                   | `export_job_id`, `tenant_id`, `context_id`, `report_type`, `format`, `status`, `schema_version`, `created_at`, `expires_at`, `updated_at`                                                                                   |
| `studio.lerian.export_job.succeeded`     | `matcher.export_job.succeeded`     | Un job de exportación termina de escribir su artefacto.          | Mismo esquema, más `file_name`?, `sha256`?, `records_written`?, `bytes_written`?, `attempts`?, `finished_at`?                                                                                                               |
| `studio.lerian.export_job.failed`        | `matcher.export_job.failed`        | Un job de exportación falla.                                     | Mismo esquema, más `error_code`, `attempts`?, `finished_at`?                                                                                                                                                                |
| `studio.lerian.export_job.expired`       | `matcher.export_job.expired`       | Un artefacto de exportación expira y se limpia.                  | Mismo esquema, más `expired_at`?                                                                                                                                                                                            |

## Declarados pero aún no emitidos

El catálogo y el manifiesto declaran siete eventos adicionales que **ningún camino de código emite hoy**: `reconciliation_context.deleted` y la familia de ciclo de vida de `extraction_request` (`submitted`, `completed`, `failed`, `cancelled`, `bridged`, `bridge_failed`). Son reservas de contrato — no construyas consumidores que dependan de recibirlos.

## Eventos consumidos

Matcher **no consume eventos de streaming Kafka**. Sus insumos de integración llegan por HTTP: subidas de archivos, extracciones de Fetcher y — cuando están habilitadas — entregas de webhook del Streaming Hub en `POST /v1/discovery/hub/events` (firmadas con HMAC, deduplicadas por id de evento, deshabilitadas por defecto).