Conciliação multi-moeda

O Matcher permite conciliar transações em diferentes moedas, convertendo os valores para uma moeda base comum antes da comparação. Isso possibilita a conciliação de transações internacionais, operações de tesouraria e conciliações multi-entidade.

Visão geral

A conciliação multi-moeda converte ambos os valores das transações para uma moeda base usando a taxa de câmbio apropriada e, em seguida, aplica as regras de conciliação padrão. Se os valores convertidos estiverem dentro da tolerância, o Matcher cria uma correspondência. Caso contrário, cria uma exceção para revisão.

Como funciona

O suporte multi-moeda é integrado aos tipos de contexto existentes (1:1, 1:N, N:M) e às regras de match — não existe um tipo de contexto “multi-moeda” separado. Quando as transações possuem moedas diferentes, o Matcher usa os campos amountBase e currencyBase de cada transação para comparar valores convertidos. Há duas formas de preencher esses campos base:

No momento da ingestão — o valor base e a moeda base são fornecidos a montante quando a transação é ingerida. Os valores do momento da ingestão sempre têm prioridade.
No momento do match — quando uma transação não tem um valor base do momento da ingestão, o Matcher deriva um a partir de dicas de câmbio por transação contidas na metadata da própria transação (consulte Câmbio a partir da metadata da transação abaixo).

Não existe nenhum provedor de câmbio externo nem serviço de consulta de taxas: a taxa sempre vem da própria linha da transação.

Componentes principais

Componente	Onde reside	Finalidade
`amountBase` / `currencyBase`	Campos da transação	Valores pré-convertidos para comparação
`matchBaseAmount` / `matchBaseCurrency`	Configuração da regra	Instrui a regra a comparar valores base em vez dos originais
`fx_rate`, `fx_base_currency`, `fx_notional_expr`	Metadata da transação	Dicas de câmbio por transação usadas para derivar o valor base no momento do match

Configurando regras para multi-moeda

Habilite a comparação multi-moeda definindo matchBaseAmount e matchBaseCurrency como true na configuração da regra.

Regra exact com correspondência de valor base

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "EXACT",
   "priority": 1,
   "config": {
     "matchBaseAmount": true,
     "matchBaseCurrency": true,
     "matchDate": true,
     "matchReference": false,
     "matchScore": 100,
     "matchBaseScore": 90
   }
 }'

Quando matchBaseAmount é true, a regra compara os campos amountBase em vez de amount. Quando matchBaseCurrency é true, compara currencyBase em vez de currency.

Regra tolerance com correspondência de valor base

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "TOLERANCE",
   "priority": 2,
   "config": {
     "matchBaseAmount": true,
     "matchBaseCurrency": true,
     "percentTolerance": 0.02,
     "absTolerance": 10.0,
     "matchScore": 85,
     "matchBaseScore": 80
   }
 }'

Score de confiança

Os campos matchScore e matchBaseScore são aceitos e validados na configuração da regra, mas não influenciam o score de confiança calculado. O mecanismo de scoring sempre usa os pesos fixos internos dos componentes (DefaultConfidenceWeights: valor 40, moeda 30, data 20, referência 10) para produzir um score de 0–100. Valores como matchScore: 100 ou matchBaseScore: 90 não são aplicados diretamente como a saída da correspondência. Esses campos estão atualmente reservados para uso futuro (mantidos por paridade entre as configurações de regra e para métricas); defini-los não tem efeito sobre como uma correspondência é pontuada ou confirmada automaticamente hoje.

Não confie em matchScore / matchBaseScore para controlar a confiança. Independentemente de a regra corresponder valores originais ou base, o score de confiança é calculado a partir dos mesmos pesos de componentes 40/30/20/10. Para refletir a incerteza de câmbio, ajuste a regra de correspondência em si (por exemplo, use uma regra TOLERANCE ou ajuste os requisitos de data/referência) em vez desses campos de score.

Para o modelo completo de scoring, consulte Score de confiança.

Câmbio a partir da metadata da transação

Quando uma transação chega sem um valor base do momento da ingestão, o Matcher ainda pode convertê-la no momento do match usando dicas de câmbio contidas na metadata dessa transação. O Matcher não chama nenhum provedor de taxas externo — a taxa viaja com a linha. A conversão só é executada quando fx_base_currency está presente, e nunca sobrescreve um valor base do momento da ingestão (a ingestão sempre vence). O amount e a currency originais nunca são alterados — a conversão muda apenas a comparação.

Campos de metadata

Campo de metadata	Obrigatório	Finalidade
`fx_base_currency`	Sim (para acionar)	A moeda base para a qual o valor é convertido. Torna-se `currencyBase`.
`fx_rate`	Sim, a menos que `fx_notional_expr` esteja definido	Taxa multiplicativa. `amountBase = amount * fx_rate`.
`fx_notional_expr`	Não	Expressão avaliada contra a metadata da transação para derivar diretamente o notional base. Quando presente, tem prioridade sobre `fx_rate`.
`fx_rate_source`	Não	Rótulo opcional que identifica de onde a taxa veio, mantido para validação e auditoria. O padrão é `metadata`.

Exemplo de transação com metadata de câmbio

{
  "external_id": "txn_001",
  "amount": 1000.00,
  "currency": "EUR",
  "date": "2024-01-15",
  "metadata": {
    "fx_base_currency": "USD",
    "fx_rate": "1.085",
    "fx_rate_source": "ecb"
  }
}

Com a metadata acima, o Matcher deriva amountBase = 1000.00 * 1.085 = 1085.00 e currencyBase = USD, depois compara com o outro lado usando as configurações matchBaseAmount / matchBaseCurrency da regra.

Se uma transação já carrega um valor base do momento da ingestão, essas dicas de metadata são ignoradas. Se as dicas estiverem ausentes ou malformadas (taxa não parseável, expressão falha), a transação simplesmente não participa da correspondência por valor base — a execução não é abortada.

Campos da transação

Para conciliação multi-moeda, as transações devem incluir tanto os campos de moeda original quanto os de moeda base:

Campo	Tipo	Descrição
`amount`	Decimal	Valor original da transação
`currency`	String	Código ISO 4217 da moeda original
`amountBase`	Decimal	Valor convertido para a moeda base
`currencyBase`	String	Código ISO 4217 da moeda base

Exemplo de transação

{
  "external_id": "txn_001",
  "amount": 1000.00,
  "currency": "EUR",
  "amountBase": 1085.00,
  "currencyBase": "USD",
  "date": "2024-01-15",
  "description": "PAY-2024-001"
}

Exemplo: conciliação cross-currency

Origem (conta EUR):

ID	Valor	Valor base
txn_001	1.000,00 EUR	1.085,00 USD

Destino (conta USD):

ID	Valor	Valor base
txn_002	1.095,00 USD	1.095,00 USD

Com uma regra TOLERANCE (matchBaseAmount: true, percentTolerance: 0.02):

Valores base: $1.085,00 vs$ 1.095,00
Variância: $10,00 (0,92%)
Tolerância: 2%
Resultado: Corresponde (0,92% < 2%)

Melhores práticas

Pré-converta valores na ingestão

Popule amountBase e currencyBase durante o upload de arquivo ou ingestão. Isso evita consultas de câmbio em tempo de execução e garante resultados reproduzíveis.

Reflita a incerteza de câmbio pelo desenho da regra

matchBaseScore e matchScore são campos reservados e não alteram o score de confiança calculado — o mecanismo sempre usa os pesos fixos 40/30/20/10. Para sinalizar correspondências com conversão de câmbio para revisão, desenhe a própria regra (por exemplo, tolerâncias mais rígidas ou verificações obrigatórias de referência/data) em vez de depender desses campos de score.

Combine com regras de tolerância

Conversões de câmbio introduzem pequenas variâncias. Use regras TOLERANCE com matchBaseAmount para permitir diferenças de arredondamento e de timing de taxas.

Documente sua escolha de moeda base

Use uma moeda base consistente em todos os contextos. USD é comum para operações internacionais; use sua moeda de relatório para cenários doméstico + internacional.

Conciliação multi-moeda

Visão geral

Como funciona

Componentes principais

Configurando regras para multi-moeda

Regra exact com correspondência de valor base

Regra tolerance com correspondência de valor base

Score de confiança

Câmbio a partir da metadata da transação

Campos de metadata

Exemplo de transação com metadata de câmbio

Campos da transação

Exemplo de transação

Exemplo: conciliação cross-currency

Melhores práticas

Próximos passos

Pontuação de Confiança

Regras de Correspondência

​Visão geral

​Como funciona

​Componentes principais

​Configurando regras para multi-moeda

​Regra exact com correspondência de valor base

​Regra tolerance com correspondência de valor base

​Score de confiança

​Câmbio a partir da metadata da transação

​Campos de metadata

​Exemplo de transação com metadata de câmbio

​Campos da transação

​Exemplo de transação

​Exemplo: conciliação cross-currency

​Melhores práticas

​Próximos passos

Pontuação de Confiança

Regras de Correspondência

Visão geral

Como funciona

Componentes principais

Configurando regras para multi-moeda

Regra exact com correspondência de valor base

Regra tolerance com correspondência de valor base

Score de confiança

Câmbio a partir da metadata da transação

Campos de metadata

Exemplo de transação com metadata de câmbio

Campos da transação

Exemplo de transação

Exemplo: conciliação cross-currency

Melhores práticas

Próximos passos