> ## 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 do Matcher

> Consulte os eventos de domínio que o Lerian Matcher emite — contextos de conciliação, rodadas de matching, exceções, disputas e governança — com payloads e semântica de entrega.

O Matcher emite eventos de domínio como mensagens **CloudEvents 1.0** em modo de conteúdo binário sobre Kafka, publicadas via `lib-streaming`. Todo evento trafega no [envelope compartilhado](/pt/reference/events/overview): `ce-type` nomeia o evento como `studio.lerian.<resource>.<event>`, `ce-subject` carrega o id do agregado, `ce-tenantid` o tenant proprietário e `ce-schemaversion` a versão do payload — `1.0.0` para todos os eventos abaixo.

O `ce-source` vem de `STREAMING_CLOUDEVENTS_SOURCE` e é obrigatório quando o streaming está habilitado; os deployments convencionalmente definem `matcher`, então os tópicos chegam em `matcher.<resource>.<event>` (consulte [Nomes de tópicos](/pt/reference/events/overview#nomes-de-tópicos)). Valores monetários — valores de tarifas, valores de ajuste — trafegam pelo fio como **strings** decimais, nunca como floats. O Matcher serve seu catálogo completo de eventos em `GET /system/matcher/streaming/manifest`.

Esta página cobre o plano de streaming Kafka. O disparo de **webhooks** de exceção do Matcher — callbacks HTTP para roteamento de exceções — é uma superfície separada, documentada em [Webhooks e callbacks](/pt/matcher/integrations/matcher-webhooks-callbacks).

## Políticas de entrega

O catálogo do Matcher usa duas políticas de entrega:

* Eventos **respaldados por outbox** são gravados no outbox na mesma transação de banco de dados que a mudança de estado; um relay publica as linhas confirmadas e tenta novamente durante quedas do broker. São os fatos de nível de auditoria (desfechos de matching, resoluções de exceção, disputas, governança). Essa política não pode ser enfraquecida por deployment.
* Eventos **diretos** publicam depois que a transação confirma, em melhor esforço, com fallback para o outbox apenas quando o circuito do broker está aberto. São os sinais de configuração e de ciclo de vida operacional.

Cada tabela abaixo indica a política dos seus eventos.

## Eventos de matching

Respaldados por outbox: `transaction.matched`, `transaction.pending_review`. Diretos: os demais.

| Evento (`ce-type`)                         | Tópico                               | Dispara quando                                                                                                                            | Payload principal                                                                                                                                                                                                      |
| ------------------------------------------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `studio.lerian.transaction.matched`        | `matcher.transaction.matched`        | Uma linha de transação atinge o estado terminal MATCHED no commit de uma rodada de matching — um evento por linha casada.                 | `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` | Um candidato a match precisa de revisão humana (regra não automática).                                                                    | Mesmo esquema, com `pending_review_at`?                                                                                                                                                                                |
| `studio.lerian.transaction.ignored`        | `matcher.transaction.ignored`        | Uma transação é excluída do 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`        | Uma rodada de matching termina. O Lender consome este evento para traduzir vereditos de conciliação em ações de servicing de empréstimos. | `match_run_id`, `context_id`, `mode`, `status`, `stats`, `started_at`, `completed_at`?                                                                                                                                 |
| `studio.lerian.match_run.failed`           | `matcher.match_run.failed`           | Uma rodada de matching falha.                                                                                                             | Como `completed`, mais `failure_reason`                                                                                                                                                                                |
| `studio.lerian.match_group.confirmed`      | `matcher.match_group.confirmed`      | Um grupo de match é confirmado.                                                                                                           | `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`      | Um grupo de match confirmado é desfeito.                                                                                                  | Como `confirmed`, mais `previous_status`, `reason`, `unmatched_at`                                                                                                                                                     |
| `studio.lerian.fee_variance.created`       | `matcher.fee_variance.created`       | Uma regra fee-aware detecta uma variação entre tarifas esperadas e reais.                                                                 | `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 exceção e disputa

Respaldados por outbox, exceto `exception.assigned` e os eventos de comentário, que são diretos.

| Evento (`ce-type`)                              | Tópico                                    | Dispara quando                                                     | Payload principal                                                                                       |
| ----------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| `studio.lerian.exception.assigned`              | `matcher.exception.assigned`              | Uma exceção é atribuída a um operador.                             | `exception_id`, `status`, `version`, `assigned_at`                                                      |
| `studio.lerian.exception.resolved`              | `matcher.exception.resolved`              | Uma exceção é resolvida.                                           | `exception_id`, `status`, `version`, `resolution_type`?, `transaction_id`?, `resolved_at`               |
| `studio.lerian.exception.force_match_resolved`  | `matcher.exception.force_match_resolved`  | Uma exceção é resolvida por force-match com um motivo de override. | Campos base mais `resolution_type` (`FORCE_MATCH`), `override_reason_code`, `resolved_at`               |
| `studio.lerian.exception.adjust_entry_resolved` | `matcher.exception.adjust_entry_resolved` | Uma exceção é resolvida por um lançamento de ajuste.               | Campos base mais `resolution_type` (`ADJUST_ENTRY`), `reason_code`, `amount`, `currency`, `resolved_at` |
| `studio.lerian.exception.dispatched`            | `matcher.exception.dispatched`            | Uma exceção é despachada para um sistema externo.                  | `exception_id`, `target_system`, `queue`, `external_reference`, `acknowledged`, `dispatched_at`         |
| `studio.lerian.exception.callback_processed`    | `matcher.exception.callback_processed`    | O callback de um sistema externo é aplicado a uma exceção.         | Campos base mais `external_system`, `external_issue_id`, `callback_type`, `processed_at`                |
| `studio.lerian.exception_comment.added`         | `matcher.exception_comment.added`         | Um comentário é adicionado a uma thread de exceção.                | `comment_id`, `exception_id`, `created_at`                                                              |
| `studio.lerian.exception_comment.deleted`       | `matcher.exception_comment.deleted`       | Um comentário é excluído.                                          | `comment_id`, `exception_id`, `actor`, `deleted_at`                                                     |
| `studio.lerian.dispute.opened`                  | `matcher.dispute.opened`                  | Uma disputa é aberta sobre uma exceção.                            | `dispute_id`, `exception_id`, `state`, `resolution`?, `category`, `opened_at`                           |
| `studio.lerian.dispute.won`                     | `matcher.dispute.won`                     | Uma disputa fecha como ganha.                                      | Como `opened`, mais `closed_at`                                                                         |
| `studio.lerian.dispute.lost`                    | `matcher.dispute.lost`                    | Uma disputa fecha como perdida.                                    | Como `opened`, mais `closed_at`                                                                         |
| `studio.lerian.evidence.submitted`              | `matcher.evidence.submitted`              | Uma evidência é anexada a uma disputa.                             | `evidence_id`, `dispute_id`, `exception_id`, `has_file`, `submitted_at`                                 |

## Eventos de configuração e ingestão de dados

Todos diretos.

| Evento (`ce-type`)                             | Tópico                                   | Dispara quando                                                                 | Payload principal                                                                                                                                     |
| ---------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `studio.lerian.reconciliation_context.created` | `matcher.reconciliation_context.created` | Um contexto de conciliação é criado.                                           | `context_id`, `name`, `context_type`, `interval`, `status`, `auto_match_on_upload`, `created_at`, `tenant_id`                                         |
| `studio.lerian.reconciliation_context.updated` | `matcher.reconciliation_context.updated` | Os metadados ou o status de ciclo de vida de um contexto mudam.                | Mesmo esquema, com `updated_at`                                                                                                                       |
| `studio.lerian.reconciliation_source.created`  | `matcher.reconciliation_source.created`  | Uma fonte (lado de entrada) é criada em um contexto.                           | `context_id`, `source_id`, `name`, `source_type`, `side`, `created_at`                                                                                |
| `studio.lerian.match_rule.created`             | `matcher.match_rule.created`             | Uma regra de match é criada.                                                   | `context_id`, `rule_id`, `rule_type`, `priority`, `config_hash`, `created_at`                                                                         |
| `studio.lerian.match_rule.reordered`           | `matcher.match_rule.reordered`           | As prioridades das regras são reordenadas.                                     | `context_id`, `ordered_rule_ids`, `priority_version`, `reordered_at`                                                                                  |
| `studio.lerian.fetcher_connection.synced`      | `matcher.fetcher_connection.synced`      | Uma conexão do Fetcher e seu snapshot de esquema descoberto são sincronizados. | `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` | Uma conexão do Fetcher fica inalcançável.                                      | Mesmo esquema, mais `previous_status`                                                                                                                 |
| `studio.lerian.extraction_request.created`     | `matcher.extraction_request.created`     | Uma requisição de extração é criada contra uma conexão.                        | `extraction_request_id`, `connection_id`, `status`, `table_count`, `has_filters`, `start_date`, `end_date`, `created_at`                              |
| `studio.lerian.ingestion.completed`            | `matcher.ingestion.completed`            | Um job de ingestão 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`               | Um job de ingestão falha.                                                      | `job_id`, `context_id`, `source_id`, `status`, `total_rows`, `failed_rows`, `error_code`, `failed_at`                                                 |

## Eventos de governança e relatórios

Respaldados por outbox, exceto a família de export-job, que é direta.

| Evento (`ce-type`)                       | Tópico                             | Dispara quando                                                   | Payload principal                                                                                                                                                                                                            |
| ---------------------------------------- | ---------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `studio.lerian.audit_log.created`        | `matcher.audit_log.created`        | Uma entrada de log de auditoria encadeada por hash é persistida. | `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` | O worker de arquivamento registra uma partição de arquivo.       | `archive_metadata_id`, `tenant_id`, `partition_name`, `date_range_start`, `date_range_end`, `status`, `created_at`, `updated_at`, mais `checksum`?, `row_count`?, `compressed_size_bytes`?, `storage_class`?, `archived_at`? |
| `studio.lerian.archive.uploaded`         | `matcher.archive.uploaded`         | Um arquivo é enviado ao armazenamento.                           | Mesmo esquema                                                                                                                                                                                                                |
| `studio.lerian.archive.completed`        | `matcher.archive.completed`        | Um ciclo de arquivamento termina.                                | Mesmo esquema                                                                                                                                                                                                                |
| `studio.lerian.actor.pseudonymized`      | `matcher.actor.pseudonymized`      | Os dados pessoais de um ator são pseudonimizados (GDPR/LGPD).    | `actor_id`, `pseudonymized`, `display_name_status`, `email_status`, `updated_at`, `tenant_id`                                                                                                                                |
| `studio.lerian.export_job.created`       | `matcher.export_job.created`       | Um job de exportação é criado.                                   | `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`     | Um job de exportação termina de gravar seu artefato.             | Mesmo esquema, mais `file_name`?, `sha256`?, `records_written`?, `bytes_written`?, `attempts`?, `finished_at`?                                                                                                               |
| `studio.lerian.export_job.failed`        | `matcher.export_job.failed`        | Um job de exportação falha.                                      | Mesmo esquema, mais `error_code`, `attempts`?, `finished_at`?                                                                                                                                                                |
| `studio.lerian.export_job.expired`       | `matcher.export_job.expired`       | Um artefato de exportação expira e é limpo.                      | Mesmo esquema, mais `expired_at`?                                                                                                                                                                                            |

## Declarados mas ainda não emitidos

O catálogo e o manifesto declaram sete eventos adicionais que **nenhum caminho de código emite hoje**: `reconciliation_context.deleted` e a família de ciclo de vida de `extraction_request` (`submitted`, `completed`, `failed`, `cancelled`, `bridged`, `bridge_failed`). Eles são reservas de contrato — não construa consumidores que dependam de recebê-los.

## Eventos consumidos

O Matcher **não consome eventos de streaming Kafka**. Seus insumos de integração chegam por HTTP: uploads de arquivo, extrações do Fetcher e — quando habilitadas — entregas de webhook do Streaming Hub em `POST /v1/discovery/hub/events` (assinadas com HMAC, deduplicadas por id de evento, desabilitadas por padrão).