> ## 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. # Correspondência multimoeda > Concilie transações entre moedas no Matcher convertendo os valores para uma base com dicas de câmbio por transação, e depois aplique suas regras de correspondência atuais. 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. ## 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](#fx-from-transaction-metadata) 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 | Componente | Onde fica | Finalidade | | ------------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------- | | `amountBase` / `currencyBase` | Campos da transação | Valores em moeda base usados na comparação, derivados no momento da correspondência a partir dos metadados de câmbio | | `matchBaseAmount` / `matchBaseCurrency` | Config da regra | Dizem a uma regra para comparar valores base em vez dos originais | | `fx_rate`, `fx_base_currency`, `fx_notional_expr` | Metadados da transação | Dicas de câmbio por transação usadas para derivar o valor base no momento da correspondência | ## 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 ```bash cURL theme={null} 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`, ela compara `currencyBase` em vez de `currency`. ### Regra de tolerância com correspondência de valor base ```bash cURL theme={null} 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 } }' ``` ### 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](/pt/products/matcher/reference/matcher-confidence-scoring).

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 | Campo de metadado | Obrigatório | Finalidade | | ------------------ | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `fx_base_currency` | Sim (para acionar) | A moeda base **para a qual** o valor é convertido. Vira `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 sobre os metadados da transação para derivar o nocional base diretamente. Quando presente, ela tem precedência sobre `fx_rate`. | | `fx_rate_source` | Não | Rótulo opcional que identifica de onde veio a taxa, guardado para validação e auditoria. O padrão é `metadata`. | ### Exemplo de transação com metadados de câmbio ```json theme={null} { "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 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. ```bash cURL theme={null} curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \ -H "Authorization: Bearer ***" \ -H "Content-Type: application/json" \ -d '{ "type": "TOLERANCE", "priority": 3, "config": { "matchBaseAmount": true, "matchBaseCurrency": true, "percentTolerance": 0.01, "fxVarianceBand": "0.005" } }' ``` ## 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: | Campo | Tipo | Descrição | | -------------- | ------- | --------------------------------------------------------------------- | | `amount` | Decimal | Valor original da transação (informado no upload) | | `currency` | String | Código de moeda ISO 4217 original (informado no upload) | | `amountBase` | Decimal | Valor convertido para a moeda base (derivado dos metadados de câmbio) | | `currencyBase` | String | Código ISO 4217 da moeda base (derivado de `fx_base_currency`) | ### Exemplo de transação Depois da conversão de câmbio, uma transação fica assim internamente: ```json theme={null} { "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 entre moedas *** **Fonte (conta em EUR):** | ID | Valor | Valor base | | -------- | ------------ | ------------ | | txn\_001 | 1.000,00 EUR | 1.085,00 USD | **Destino (conta em 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: 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 *** Como funcionam as pontuações de correspondência e quais limiares se aplicam. Referência completa dos tipos de regra e dos campos de config.