Os cinco conceitos principais do Matcher: contextos, fontes, mapas de campos, regras e matches. Entenda estes conceitos e você entenderá como todo o sistema funciona.
Contexto
Um contexto define o que você está conciliando. É o container que contém suas fontes, regras e resultados.
Um contexto responde: o que estou conciliando contra o quê?
Tipos de contexto
| Tipo | Descrição | Exemplo |
|---|
| 1:1 | Conciliação um-para-um | Extrato bancário vs registros do ERP |
| 1:N | Conciliação um-para-muitos | Um pagamento cobrindo múltiplas faturas |
| N:M | Conciliação muitos-para-muitos | Cenários de netting ou agregação |
Exemplo
Um contexto chamado “Banco Chase vs Sistema ERP” iria:
- Definir o Banco Chase como uma fonte de conciliação
- Definir seu sistema ERP como outra fonte
- Especificar as regras usadas para conciliar transações entre eles
Fonte
Uma fonte é de onde as transações vêm. Todo contexto precisa de pelo menos duas fontes—é isso que você está conciliando.
Tipos de fonte
- Banco: Extratos ou feeds de bancos
- ERP: Exportações do SAP, Oracle, NetSuite
- Ledger: Sistemas de ledger internos (incluindo Midaz)
- Processador de pagamento: Liquidações do Stripe, Adyen, PayPal
- Bandeira de cartão: Arquivos da Visa, Mastercard, Elo
Configuração da fonte
Cada fonte possui:
- Nome: Identifique-a (ex: “Conta Corrente Chase”)
- Tipo: Categoria (banco, ERP, etc.)
- Mapa de campos: Como seus campos mapeiam para o schema do Matcher
Mapa de campos
Um mapa de campos traduz nomes de campos externos para o schema padrão do Matcher. Cada sistema nomeia as coisas de forma diferente—mapas de campos normalizam isso.
Campos padrão
| Campo | Tipo | Descrição |
|---|
transaction_id | String | Identificador da transação no sistema de origem |
amount | Decimal | Valor da transação (positivo ou negativo) |
currency | String | Código de moeda ISO 4217 |
date | DateTime | Data da transação |
reference | String | Referência externa ou descrição |
metadata | Object | Atributos específicos da fonte |
Exemplo de mapeamento
Um extrato bancário expondo TXN_ID, VALUE, CCY e POST_DATE seria mapeado como:
{
"transaction_id": "TXN_ID",
"amount": "VALUE",
"currency": "CCY",
"date": "POST_DATE"
}
Regra de match
Uma regra de match diz ao Matcher como comparar transações. As regras são executadas em ordem de prioridade—o primeiro match vence.
Tipos de regra
- EXACT: Os campos devem corresponder exatamente (valor, data, referência)
- TOLERANCE: Permite pequenas diferenças (0,5% de variância, R$10 absolutos)
- DATE_LAG: Match dentro de uma janela de datas (±3 dias)
Ordem de prioridade
Números menores são executados primeiro. O Matcher para na primeira regra que faz match.
| Prioridade | Regra | Descrição |
|---|
| 1 | Match exato | Valor, data e referência devem corresponder |
| 2 | Tolerância mesmo dia | Mesma data, valor dentro de 0,5% |
| 3 | Tolerância semanal | Dentro de 7 dias, valor dentro de 1% |
Parâmetros da regra
| Tipo de regra | Parâmetros |
|---|
| EXACT | fields: lista de campos para comparar |
| TOLERANCE | percent: variância percentual, absolute: valor de variância fixo |
| DATE_LAG | days_before, days_after: offset permitido a partir da data da transação |
Match
Um match é quando transações de fontes diferentes são conciliadas juntas. É o objetivo final.
Status do match
| Status | Descrição |
|---|
PROPOSED | Matcher encontrou, aguardando confirmação |
CONFIRMED | Aprovado automaticamente ou manualmente |
REJECTED | Rejeitado manualmente |
Padrões de match
Match 1:1
Uma transação de cada fonte é conciliada.
Banco: R$100,00 em 15 Jan → ERP: R$100,00 em 15 Jan
Match 1:N
Uma transação é conciliada contra múltiplas transações.
Banco: R$300,00 → ERP: R$100,00 + R$100,00 + R$100,00
Match N:1
Múltiplas transações são conciliadas contra uma única transação.
Banco: R$50,00 + R$50,00 + R$50,00 → ERP: R$150,00
Itens do match
Cada grupo de match contém itens de match, que registram a participação e alocação das transações.
Isso permite conciliação parcial em cenários de split e agregação.
Exceção
Uma exceção é uma transação que não fez match. Ela precisa de revisão manual.
Status da exceção
| Status | Descrição |
|---|
OPEN | Aguardando atribuição |
ASSIGNED | Alguém está investigando |
RESOLVED | Tratada |
Severidade
O Matcher auto-classifica exceções para que você saiba o que priorizar.
| Severidade | Critério padrão |
|---|
| Critical | Valor ≥ R$100K, idade ≥ 5 dias, ou sinalizado por regulação |
| High | Valor ≥ R$10K ou idade ≥ 3 dias |
| Medium | Valor ≥ R$1.000 ou idade ≥ 1 dia |
| Low | Todos os outros casos |
Tipos de resolução
- Force match: Conciliar transações manualmente
- Adjustment: Registrar um ajuste compensatório
- Write-off: Encerrar a exceção com justificativa
Score de confiança
Um score de confiança indica a confiabilidade de um match automatizado em uma escala de 0–100.
Scores mais altos representam maior alinhamento entre transações.
Cálculo do score
| Componente | Peso | Descrição |
|---|
| Match de valor | 40% | Grau de alinhamento do valor |
| Match de moeda | 30% | Consistência da moeda |
| Tolerância de data | 20% | Proximidade das datas das transações |
| Match de regra | 10% | Aplicação determinística da regra |
Faixas de confiança
| Faixa | Intervalo de score | Comportamento do sistema |
|---|
| Auto-aprovado | ≥ 90 | Confirmado automaticamente |
| Precisa revisão | 60–89 | Sinalizado para revisão manual |
| Sem match | < 60 | Tratado como exceção |
Os limites de confiança podem ser customizados por tenant para refletir diferentes tolerâncias a risco.
Log de auditoria
Um log de auditoria é um registro imutável de todas as ações do sistema.
Ele fornece rastreabilidade completa para revisão operacional, auditorias e compliance regulatório.
Eventos registrados
Entradas de auditoria são criadas para:
- Alterações em contextos, fontes e regras
- Ingestão e processamento de arquivos
- Confirmações e rejeições de matches
- Resolução de exceções e overrides
Conteúdo da entrada de auditoria
| Campo | Descrição |
|---|
timestamp | Timestamp da ação (UTC) |
user_id | Ator responsável pela ação |
action | Ação realizada |
resource_type | Tipo do recurso afetado |
resource_id | Identificador do recurso afetado |
before_state | Estado antes da ação |
after_state | Estado após a ação |
notes | Justificativa, quando aplicável |
Os logs de auditoria são apenas append. Entradas não podem ser modificadas ou removidas.
Próximos passos
