Skip to main content
O Matcher permite conciliar transações em moedas diferentes convertendo os valores para uma moeda base comum antes da comparação. Isso permite a correspondência entre transações internacionais, operações de tesouraria e conciliações com várias entidades.

​
Visão geral

A correspondência multimoeda converte os valores das duas transações para uma moeda base usando a taxa de câmbio adequada e depois aplica as regras de correspondência padrão. Se os valores convertidos ficarem dentro da tolerância, o Matcher cria uma correspondência. Caso contrário, ele cria uma exceção para revisão.
Fluxo da correspondência multimoeda.

Fluxo da correspondência multimoeda.

​
Como funciona

O suporte a multimoeda fica nos tipos de contexto existentes (1:1, 1:N, N:M) e nas regras de correspondência. Não existe um tipo de contexto “multimoeda” separado. Quando as transações têm moedas diferentes, o Matcher usa os campos amountBase e currencyBase de cada transação para comparar os valores convertidos. Hoje, o Matcher preenche esses campos base no momento da correspondência. O Matcher os deriva de dicas de câmbio por transação levadas nos metadados da própria transação (veja Câmbio a partir dos metadados da transação abaixo). Você não pode informar um valor base diretamente no upload do arquivo, porque o vocabulário do mapa de campos não tem colunas de valor base. Se uma transação já traz um valor base, o Matcher o respeita e nunca o sobrescreve, mas a forma aceita de levar valores base às suas transações é o caminho dos metadados de câmbio. Não há provedor externo de câmbio nem serviço de consulta de taxas: a taxa sempre vem da própria linha da transação.

​
Componentes principais

​
Configurar regras para multimoeda

Habilite a comparação multimoeda definindo matchBaseAmount e matchBaseCurrency como true na config da regra.

​
Regra exata com correspondência de valor base

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

​
Regra de tolerância com correspondência de valor base

cURL

​
Pontuação de confiança

Os campos matchScore e matchBaseScore são aceitos e validados na config da regra, mas não influenciam a pontuação de confiança calculada. O motor de pontuação sempre usa os pesos internos fixos dos componentes (DefaultConfidenceWeights: valor 40, moeda 30, data 20, referência 10) para produzir uma pontuação de 0 a 100. Valores como matchScore: 100 ou matchBaseScore: 90 não são aplicados diretamente como saída da correspondência. Esses campos estão atualmente reservados para uso futuro. O Matcher os mantém por paridade entre as configs de regra e para métricas. Defini-los hoje não tem efeito sobre a pontuação da correspondência nem sobre a confirmação automática.
Não conte com matchScore / matchBaseScore para controlar a confiança. Quer a regra compare valores originais ou valores base, o motor de pontuação calcula a pontuação de confiança com os mesmos pesos de componente 40/30/20/10. Para refletir a incerteza do câmbio, ajuste a própria regra de correspondência (por exemplo, use uma regra TOLERANCE ou mude as exigências de data/referência) em vez desses campos de pontuação.
Para o modelo completo de pontuação, veja Pontuação de confiança.

​
Câmbio a partir dos metadados da transação

Quando uma transação ainda não tem valor base, o Matcher a converte no momento da correspondência usando as dicas de câmbio levadas no metadata daquela transação. O Matcher não chama nenhum provedor externo de taxas. A taxa viaja junto com a linha. A conversão apenas roda quando fx_base_currency está presente. A conversão nunca sobrescreve um valor base que a transação já traz. A conversão nunca altera o amount e o currency originais, porque ela muda apenas a comparação.

​
Campos de metadados

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

Com os metadados acima, o Matcher deriva amountBase = 1000.00 * 1.085 = 1085.00 e currencyBase = USD, e então compara com o outro lado usando as configurações matchBaseAmount / matchBaseCurrency da regra.
Se uma transação já traz um valor base, o Matcher ignora essas dicas de metadados, porque ele nunca sobrescreve um valor base existente. A transação não participa da correspondência por valor base quando as dicas estão ausentes ou inválidas (taxa não interpretável, expressão com falha). A execução continua.

​
Quando os campos base estão ausentes

Quando uma regra exige correspondência por valor base (matchBaseAmount / matchBaseCurrency) e as transações não têm valor base ou moeda base, o Matcher registra a condição sob o motivo de exceção FX_RATE_UNAVAILABLE. Você pode filtrar a lista de exceções por reason=FX_RATE_UNAVAILABLE (junto com os motivos relacionados MISSING_BASE_AMOUNT e MISSING_BASE_CURRENCY) para achar as transações que não puderam entrar na comparação por valor base.

​
Faixa de variação da taxa de câmbio

Valores entre moedas costumam divergir um pouco, porque cada lado converte com uma taxa diferente ou em um dia diferente. A chave fxVarianceBand nas regras TOLERANCE trata disso: ela define um segundo limiar empilhado acima da tolerância de correspondência, expresso como fração decimal (0.0001 = 1 ponto-base). Depois da passagem de tolerância estrita, o Matcher revarre os pares 1:1 entre moedas que ficaram não conciliados. Um par cujo residual de valor base passa da tolerância de correspondência mas fica dentro da faixa ainda corresponde. O par vira um grupo proposto com confiança fixa de 75, abaixo do limiar de confirmação automática, então ele sempre exige revisão humana. O Matcher sinaliza as duas transações com o motivo de exceção FX_RATE_VARIANCE. O residual então vira uma exceção tipada em vez de colapsar para UNMATCHED. A faixa se aplica apenas quando:
  • os dois lados trazem um valor base e a mesma moeda base.
  • as moedas originais diferem (uma divergência dentro da mesma moeda é um descasamento comum, não um caso de câmbio).
  • todos os outros filtros da regra (janela de data, referência, moeda, campos compostos) continuam passando.
Um fxVarianceBand zero ou ausente desabilita a faixa.
cURL

​
Campos da transação

Para a correspondência multimoeda, cada transação traz tanto os campos de moeda original quanto os de moeda base. Você informa amount e currency no upload. O Matcher deriva amountBase e currencyBase no momento da correspondência a partir dos metadados de câmbio:

​
Exemplo de transação

Depois da conversão de câmbio, uma transação fica assim internamente:

​
Exemplo: conciliação entre moedas

Fonte (conta em EUR): Destino (conta em USD): Com uma regra TOLERANCE (matchBaseAmount: true, percentTolerance: 0.02):
  • Valores base: US1.085,00vs.US 1.085,00 vs. US 1.095,00
  • Variação: US$ 10,00 (0,92%)
  • Tolerância: 2%
  • Resultado: Correspondência (0,92% < 2%)

​
Boas práticas

Anexe fx_base_currency e fx_rate (ou fx_notional_expr) aos metadados de cada transação na origem, usando a taxa que valia quando a transação liquidou. Como a taxa viaja junto com a linha, os resultados são reprodutíveis entre execuções, sem consultas de taxa em tempo de execução.
matchBaseScore e matchScore continuam sendo campos reservados e não mudam a pontuação de confiança calculada. O motor sempre usa os pesos fixos 40/30/20/10. Para marcar correspondências convertidas por câmbio para revisão, desenhe a própria regra (por exemplo, tolerâncias mais apertadas ou verificações obrigatórias de referência/data) em vez de contar com esses campos de pontuação.
As conversões de câmbio introduzem pequenas variações. Use regras TOLERANCE com matchBaseAmount para acomodar arredondamentos e diferenças no momento da taxa.
Use uma moeda base consistente em todos os contextos. USD é comum para operações internacionais. Use a moeda dos seus relatórios para operações domésticas + internacionais.

​
Próximos passos

Pontuação de confiança

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

Regras de correspondência

Referência completa dos tipos de regra e dos campos de config.