Pular para o conteúdo principal
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. A conversão de câmbio ocorre no momento da ingestão ou através de uma fonte FX externa.

​
Componentes principais

ComponenteOnde resideFinalidade
amountBase / currencyBaseCampos da transaçãoValores pré-convertidos para comparação
matchBaseAmount / matchBaseCurrencyConfiguração da regraInstrui a regra a comparar valores base em vez dos originais
rateIdContextoReferência à taxa de câmbio usada para conversão
Interface FXSourcePorta de integraçãoInterface plugável para buscar taxas de câmbio

​
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
curl -X POST "https://api.matcher.example.com/v1/config/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

cURL
curl -X POST "https://api.matcher.example.com/v1/config/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

Quando uma regra faz match pelos valores base, a pontuação de confiança usa matchBaseScore em vez de matchScore. Isso permite atribuir menor confiança a correspondências com conversão de câmbio para refletir a incerteza adicional.
Tipo de matchPontuação padrão
Match pelo valor originalmatchScore (ex: 100 para EXACT)
Match pelo valor basematchBaseScore (ex: 90 para EXACT)

​
Integração FXSource

O Matcher define uma interface de porta FXSource para buscar taxas de câmbio em tempo de execução. Você pode implementar essa interface para conectar qualquer provedor de taxas de câmbio ao Matcher. 
// FXSource port interface (internal/matching/ports/fx_source.go)
type FXSource interface {
    GetRate(ctx context.Context, from, to string, date time.Time) (Rate, error)
}

​
Usando a fonte FX

  1. Implemente a interface FXSource com seu provedor de taxas preferido.
  2. Registre a implementação na inicialização da aplicação.
  3. Defina rateId no contexto para referenciar a configuração de taxa.
A integração de fonte FX é opcional. Se não configurada, a conciliação multi-moeda depende dos campos amountBase e currencyBase pré-convertidos fornecidos no momento da ingestão.

​
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:
CampoTipoDescrição
amountDecimalValor original da transação
currencyStringCódigo ISO 4217 da moeda original
amountBaseDecimalValor convertido para a moeda base
currencyBaseStringCódigo ISO 4217 da moeda base

​
Exemplo de transação

{
  "transaction_id": "txn_001",
  "amount": 1000.00,
  "currency": "EUR",
  "amountBase": 1085.00,
  "currencyBase": "USD",
  "date": "2024-01-15",
  "reference": "PAY-2024-001"
}

​
Exemplo: conciliação cross-currency

Origem (conta EUR):
IDValorMoedaValor BaseMoeda Base
txn_0011.000,00EUR1.085,00USD
Destino (conta USD):
IDValorMoedaValor BaseMoeda Base
txn_0021.095,00USD1.095,00USD
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: Match (0,92% < 2%)

​
Melhores práticas

Popule amountBase e currencyBase durante o upload de arquivo ou ingestão. Isso evita consultas FX em tempo de execução e garante resultados reproduzíveis.
Defina matchBaseScore menor que matchScore para que correspondências com conversão de câmbio recebam menor confiança, sinalizando-as para revisão quando apropriado.
Conversões de câmbio introduzem pequenas variâncias. Use regras TOLERANCE com matchBaseAmount para permitir diferenças de arredondamento e 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.