> ## 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.](https://mintcdn.com/lerian-49cb71fc/vdBt8wfgjsNRO1rf/images/pt/d2/matcher-multicurrency-matching.svg?fit=max\&auto=format\&n=vdBt8wfgjsNRO1rf\&q=85\&s=2003ee08d636d9e0af352308be2f1d56) 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. No momento da correspondência, o Matcher calcula um valor base e uma moeda base para cada transação a partir das dicas de câmbio nos metadados da própria transação (veja [Câmbio a partir dos metadados da transação](#fx-from-transaction-metadata) abaixo). As regras que definem `matchBaseAmount` ou `matchBaseCurrency` comparam esses valores base. Você não pode enviar um valor base diretamente. 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 | | - | - | - | | Valor base / moeda base | Calculados no momento da correspondência, não armazenados | Valores que as regras de valor base comparam, derivados dos metadados de câmbio | | `matchBaseAmount` / `matchBaseCurrency` | Config da regra | Fazem uma regra comparar valores base e moedas base | | `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. As verificações dos valores originais continuam ativas. Uma regra EXACT compara `amount` enquanto `matchAmount` está ligado, e as regras EXACT e TOLERANCE comparam `currency` enquanto `matchCurrency` está ligado. Os dois vêm ligados por padrão, então uma regra entre moedas os desliga. ### 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": { "matchAmount": false, "matchCurrency": false, "matchBaseAmount": true, "matchBaseCurrency": true, "matchDate": true, "matchReference": false } }' ``` `matchBaseAmount` compara os valores base, e `matchBaseCurrency` compara as moedas base. Uma transação sem valor base falha nas duas verificações. ### 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": { "matchCurrency": false, "matchBaseAmount": true, "matchBaseCurrency": true, "matchReference": false, "percentTolerance": 0.02, "absTolerance": 10.0 } }' ``` Com `matchBaseAmount`, uma regra TOLERANCE compara os valores base no lugar dos valores originais, e `absTolerance` fica em unidades da moeda base. ### Pontuação de confiança As regras de valor base usam os mesmos pesos fixos de componente que todas as outras regras. Para o modelo completo de pontuação, veja [Pontuação de confiança](https://docs.lerian.studio/pt/products/matcher/reference/matcher-confidence-scoring.md). ## 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 altera o `amount` e o `currency` originais, porque ela muda apenas a comparação. O Matcher arredonda o valor convertido na maior `roundingScale` entre as regras TOLERANCE do contexto, ou em 2 casas decimais quando o contexto não tem nenhuma. A simulação de correspondência não converte, então as regras de valor base não encontram correspondências em uma simulaçã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. A comparação diferencia maiúsculas de minúsculas, então use o mesmo código nos dois lados. | | `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`. | ### 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", "fx_base_currency": "USD", "fx_rate": "1.085" } ``` Para a transação acima, o Matcher deriva um valor base de 1.085,00 USD (1.000,00 × 1,085). Uma regra com `matchBaseAmount` e `matchBaseCurrency` então compara esse valor base e essa moeda com o outro lado. > [!NOTE] > > Quando as dicas estão ausentes ou inválidas (taxa não interpretável, expressão com falha), a transação não recebe valor base. Ela não pode corresponder sob uma regra de valor base e fica não conciliada. A execução continua. ## 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). * todas as outras verificações da regra (janela de data, referência, campos compostos) continuam passando. A regra precisa definir `matchCurrency` como `false`, porque a verificação de moeda rejeita pares cujas moedas originais diferem. 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": { "matchCurrency": false, "matchBaseAmount": true, "matchBaseCurrency": true, "matchReference": false, "percentTolerance": 0.01, "fxVarianceBand": "0.005" } }' ``` ## 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 | As duas transações trazem `fx_base_currency: "USD"`. A txn\_001 traz `fx_rate: "1.085"` e a txn\_002 traz `fx_rate: "1"`. Com uma regra TOLERANCE (`matchCurrency: false`, `matchBaseAmount: true`, `matchReference: false`, `percentTolerance: 0.02`): * Valores base: US$ 1.085,00 vs. US$ 1.095,00 * Diferença: US\$ 10,00 * Limiar: 2% do maior valor, US\$ 21,90 * Resultado: **Correspondência** (US$ 10,00 < US$ 21,90) ## Boas práticas *** > [accordion] Informe metadados de câmbio estáveis por transação > > 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. > [accordion] Combine com regras de tolerância > > 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. > [accordion] Documente a escolha da sua moeda base > > 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 *** > [card] [Pontuação de confiança](https://docs.lerian.studio/pt/products/matcher/reference/matcher-confidence-scoring.md) > > Como funcionam as pontuações de correspondência e quais limiares se aplicam. > [card] [Regras de correspondência](https://docs.lerian.studio/pt/products/matcher/configuration/matcher-match-rules.md) > > Referência completa dos tipos de regra e dos campos de config. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.