Skip to main content
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.
Fluxo de conciliação multi-moeda.

Fluxo de conciliação multi-moeda.

​
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. Hoje, esses campos base são preenchidos no momento do match: o Matcher os deriva 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). Você não pode fornecer um valor base diretamente no upload de arquivo — o vocabulário do field map não possui colunas de valor base. Se uma transação já carrega um valor base, o Matcher o respeita e nunca o sobrescreve, mas a forma suportada de obter valores base nas suas transações é o caminho da metadata de câmbio. 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

​
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
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

​
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 ainda não tem um valor base, o Matcher a converte 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 que já esteja definido na transação. O amount e a currency originais nunca são alterados — a conversão muda apenas a comparação.

​
Campos de metadata

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

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, essas dicas de metadata são ignoradas — o Matcher nunca sobrescreve um valor base existente. 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.

​
Quando os campos base estão ausentes

Quando uma regra exige correspondência por valor base (matchBaseAmount / matchBaseCurrency) e as transações não possuem um valor base ou uma moeda base, o Matcher registra a condição sob a razão de exceção FX_RATE_UNAVAILABLE. Você pode filtrar a lista de exceções por reason=FX_RATE_UNAVAILABLE (junto com as razões relacionadas MISSING_BASE_AMOUNT e MISSING_BASE_CURRENCY) para encontrar transações que não puderam participar da comparação por valor base.

​
Banda de variação de taxa de câmbio

Valores entre moedas distintas costumam divergir ligeiramente porque cada lado foi convertido com uma taxa diferente ou em um dia diferente. A chave fxVarianceBand nas regras TOLERANCE trata disso: ela define um segundo limite empilhado acima da tolerância de match, expresso como fração decimal (0.0001 = 1 ponto-base). Após a passagem de tolerância estrita, o Matcher reexamina os pares 1:1 cross-currency não correspondidos. Um par cujo residual de valor base excede a tolerância de match mas permanece dentro da banda ainda corresponde — o par vira um grupo proposto com confiança fixa de 75, abaixo do limite de confirmação automática, portanto sempre exige revisão humana. Ambas as transações são sinalizadas com a razão de exceção FX_RATE_VARIANCE, de modo que o residual fica registrado como uma exceção tipada em vez de colapsar para UNMATCHED. A banda só se aplica quando:
  • ambos os lados carregam um valor base e a mesma moeda base;
  • as moedas originais diferem (um desvio na mesma moeda é uma divergência simples, não um caso de câmbio);
  • todas as demais condições da regra (janela de data, referência, moeda, campos compostos) continuam sendo atendidas.
Um fxVarianceBand zerado ou ausente desativa a banda.
cURL

​
Campos da transação

Para conciliação multi-moeda, cada transação carrega tanto os campos de moeda original quanto os de moeda base. Você fornece amount e currency no upload; o Matcher deriva amountBase e currencyBase no momento do match a partir da metadata de câmbio:

​
Exemplo de transação

Após a conversão de câmbio, uma transação fica assim internamente:

​
Exemplo: conciliação cross-currency

Origem (conta EUR): Destino (conta USD): Com uma regra TOLERANCE (matchBaseAmount: true, percentTolerance: 0.02):
  • Valores base: 1.085,00vs1.085,00 vs 1.095,00
  • Variância: $10,00 (0,92%)
  • Tolerância: 2%
  • Resultado: Corresponde (0,92% < 2%)

​
Melhores práticas

Anexe fx_base_currency e fx_rate (ou fx_notional_expr) à metadata de cada transação na origem, usando a taxa vigente quando a transação foi liquidada. Como a taxa viaja com a linha, os resultados são reproduzíveis entre execuções — sem consultas de taxas em tempo de execução.
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.
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.
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.

​
Próximos passos

Pontuação de Confiança

Como as pontuações de correspondência funcionam e quais limites se aplicam.

Regras de Correspondência

Referência completa para tipos de regra e campos de configuração.