> ## 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. # Conciliação multi-moeda > Concilie transações em moedas diferentes convertendo os valores para uma moeda base comum antes de aplicar as regras de matching do Matcher. 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. ## 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](#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 ```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`, compara `currencyBase` em vez de `currency`. ### Regra tolerance 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 } }' ``` ### 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](/pt/matcher/reference/matcher-confidence-scoring). ## 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 ```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 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 ```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 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 *** 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. `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 *** Como as pontuações de correspondência funcionam e quais limites se aplicam. Referência completa para tipos de regra e campos de configuração.