Conciliação multi-moeda

O Matcher permite a conciliação de 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.

Habilitando multi-moeda

Configuração do contexto

Habilite a conciliação multi-moeda no nível do contexto ao criar ou atualizar um contexto:

{
  "name": "International Treasury Reconciliation",
  "type": "MULTI_CURRENCY",
  "settings": {
    "multi_currency": {
      "enabled": true,
      "base_currency": "USD",
      "fx_rate_source": "external_provider",
      "fx_tolerance_percent": 2.0,
      "fx_tolerance_absolute": 10.0
    }
  }
}

Referência da API: Criar contexto, Atualizar contexto

Configurações multi-moeda

Configuração	Tipo	Descrição
`enabled`	Boolean	Habilita a conciliação multi-moeda
`base_currency`	String	Código ISO 4217 da moeda de comparação
`fx_rate_source`	String	Fonte das taxas de câmbio
`fx_tolerance_percent`	Decimal	Tolerância percentual para variação de câmbio
`fx_tolerance_absolute`	Decimal	Tolerância absoluta na moeda base
`rate_date_strategy`	String	Como determinar qual data da taxa usar
`fallback_behavior`	String	Ação quando a taxa de câmbio não está disponível

Moeda base

A moeda base é usada como denominador comum para todas as comparações.

Escolhendo uma moeda base

Cenário	Base Recomendada	Justificativa
Empresa sediada nos EUA	USD	Corresponde à moeda de relatório
Empresa sediada na UE	EUR	Corresponde à moeda de relatório
Operações multi-região	USD	Mais líquida, taxas amplamente disponíveis
Brasil doméstico + internacional	BRL	Corresponde ao relatório local

Alterando a moeda base

Alterar a moeda base afeta todas as correspondências pendentes. Conclua ou arquive as correspondências existentes antes de alterar.

Fontes de taxa de câmbio

O Matcher permite múltiplas fontes para taxas de câmbio.

Provedor externo

Conecte-se a APIs de terceiros para taxas de câmbio configurando a fonte de taxa FX nas configurações do contexto:

{
  "type": "external_provider",
  "provider": "openexchangerates",
  "settings": {
    "api_key_id": "secret_fx_001",
    "base_url": "https://openexchangerates.org/api/",
    "cache_duration_minutes": 60,
    "fallback_to_previous_day": true
  }
}

Provedores Suportados:

Provedor	Recursos	Frequência de Atualização
Open Exchange Rates	170+ moedas	Por hora
Fixer.io	170+ moedas	Por hora
Currency Layer	168 moedas	Por hora
XE	185+ moedas	Tempo real
European Central Bank	Pares EUR	Diário

Motor de taxa de ativos do Midaz (opcional)

Se você estiver usando o Midaz Ledger, pode consultar as taxas de câmbio diretamente dele:

{
  "type": "midaz",
  "settings": {
    "ledger_id": "ldg_001",
    "rate_type": "spot",
    "fallback_to_closing": true
  }
}

Esta opção só está disponível se você tiver o Midaz integrado. Consulte Integração com Midaz para instruções de configuração.

Entrada manual

Carregue taxas manualmente para ambientes controlados incluindo-as na configuração do contexto ou usando o gerenciamento dedicado de taxas.

Estratégia de data da taxa

Determine qual data da taxa de câmbio usar para a conversão.

Opções de estratégia

Estratégia	Descrição	Caso de Uso
`earlier_date`	Usa a taxa da data da transação mais antiga	Padrão, conservador
`later_date`	Usa a taxa da data da transação mais recente	Quando a data de liquidação importa
`source_date`	Usa a taxa da data da fonte interna	Quando a interna é autoritativa
`target_date`	Usa a taxa da data da fonte externa	Quando a externa é autoritativa
`average`	Média das taxas de ambas as datas	Reduz volatilidade de um único dia

Configurar estratégia de data da taxa

{
  "settings": {
    "multi_currency": {
      "rate_date_strategy": "earlier_date",
      "rate_time": "closing",
      "timezone": "America/New_York"
    }
  }
}

Opções de horário da taxa

Opção	Descrição
`opening`	Taxa de abertura do dia
`closing`	Taxa de fechamento do dia (padrão)
`midday`	Taxa às 12:00
`spot`	Taxa em tempo real no momento da transação

Configuração de tolerância

A conciliação multi-moeda usa tolerância combinada para considerar flutuações de câmbio.

Fórmula de tolerância

converted_amount_a = amount_a * fx_rate_a_to_base
converted_amount_b = amount_b * fx_rate_b_to_base

diff = abs(converted_amount_a - converted_amount_b)
max_amount = max(abs(converted_amount_a), abs(converted_amount_b))

passes = diff <= max(tolerance_absolute, tolerance_percent * max_amount)

Exemplos de tolerância

Exemplo 1: Dentro da Tolerância

Transação	Original	Taxa de Câmbio	Base (USD)
A (EUR)	1.000,00	1,0850	1.085,00
B (USD)	1.095,00	1,0000	1.095,00

Diferença: $10,00 (0,92%)
Tolerância: max( $10,00, 2% x$ 1.095) = max( $10,00,$ 21,90) = $21,90
Resultado: Correspondência ( $10,00 <=$ 21,90)

Exemplo 2: Fora da Tolerância

Transação	Original	Taxa de Câmbio	Base (USD)
A (EUR)	1.000,00	1,0850	1.085,00
B (USD)	1.150,00	1,0000	1.150,00

Diferença: $65,00 (5,99%)
Tolerância: max( $10,00, 2% x$ 1.150) = max( $10,00,$ 23,00) = $23,00
Resultado: Sem Correspondência ( $65,00 >$ 23,00)

Tolerância personalizada por par de moedas

Defina tolerâncias diferentes para pares de moedas voláteis:

{
  "settings": {
    "multi_currency": {
      "fx_tolerance_percent": 2.0,
      "fx_tolerance_absolute": 10.0,
      "currency_pair_overrides": [
        {
          "pair": "BRL/USD",
          "tolerance_percent": 5.0,
          "tolerance_absolute": 50.0
        },
        {
          "pair": "ARS/USD",
          "tolerance_percent": 10.0,
          "tolerance_absolute": 100.0
        }
      ]
    }
  }
}

Tratamento de taxas de câmbio ausentes

Quando uma taxa de câmbio não está disponível, o Matcher segue o comportamento de fallback configurado.

Opções de fallback

Comportamento	Descrição	Nível de Risco
`exception`	Cria exceção para tratamento manual	Mais baixo
`skip`	Pula tentativa de correspondência, continua processamento	Baixo
`previous_day`	Usa taxa disponível do dia anterior	Médio
`interpolate`	Estima a partir de datas adjacentes	Médio
`fail`	Falha todo o job	Mais alto

Configurar fallback

{
  "settings": {
    "multi_currency": {
      "fallback_behavior": "previous_day",
      "max_fallback_days": 3,
      "alert_on_fallback": true
    }
  }
}

Exceção de taxa ausente

Quando o fallback é exception, a transação se torna uma exceção com detalhes específicos:

{
  "exceptionId": "{exceptionId}",
  "type": "FX_RATE_UNAVAILABLE",
  "severity": "HIGH",
  "details": {
    "from_currency": "TRY",
    "to_currency": "USD",
    "required_date": "2024-01-20",
    "nearest_available": "2024-01-18",
    "gap_days": 2
  },
  "resolution_options": [
    "Provide manual rate",
    "Use fallback rate from 2024-01-18",
    "Mark as no match"
  ]
}

Impacto na pontuação de confiança

A conciliação multi-moeda afeta a pontuação de confiança através do componente de moeda.

Cálculo da pontuação de moeda

Cenário	Pontuação de Moeda
Mesma moeda	30/30 (100%)
Moeda diferente, correspondência exata de câmbio	28/30 (93%)
Moeda diferente, variação de câmbio até 1%	25/30 (83%)
Moeda diferente, variação de câmbio até 2%	22/30 (73%)
Moeda diferente, variação de câmbio >2%	15-20/30
Taxa de câmbio indisponível (fallback usado)	10/30 (33%)

Exemplo de pontuação

Correspondência multi-moeda com leve variação de câmbio:

{
  "confidence": 82,
  "confidence_breakdown": {
    "amount": {
      "score": 36,
      "weighted_score": 14.4,
      "details": {
        "source_amount": "EUR 1,000.00",
        "target_amount": "USD 1,095.00",
        "converted_source": "USD 1,085.00",
        "variance_percent": 0.91
      }
    },
    "currency": {
      "score": 22,
      "weighted_score": 6.6,
      "details": {
        "source_currency": "EUR",
        "target_currency": "USD",
        "fx_rate_used": 1.085,
        "fx_rate_date": "2024-01-15",
        "fx_variance_from_market": 0.8
      }
    },
    "date": {
      "score": 18,
      "weighted_score": 3.6
    },
    "rule": {
      "score": 10,
      "weighted_score": 1.0
    }
  }
}

Taxas variáveis por atributos de transação

Recurso Avançado: A conciliação com taxas variáveis permite que as taxas mudem com base em atributos da transação como MCC, tipo de cartão, método de transação e segmento do estabelecimento. Isso é comumente usado em conciliação de adquirência/redes de cartões.

Em alguns cenários de conciliação, particularmente em processamento de adquirência e redes de cartões, a taxa aplicável varia com base em múltiplos atributos da transação em vez de ser fixa.

Casos de uso comuns

Conciliação de Adquirência (Interchange Plus)

Taxa varia por MCC (Merchant Category Code)
Taxas diferentes para cartões de crédito vs. débito
Precificação baseada em segmento (varejo, restaurante, combustível)
Método de transação (físico vs. link/online)

Telecomunicações

Taxas diferentes por operadora
Taxa varia por tipo de plano e região
Precificação promocional vs. padrão

Precificação Multi-Nível

Níveis de taxa baseados em volume
Precificação por segmento de cliente
Variações de taxa baseadas em tempo

Configuração de consulta de taxas

Configure a consulta de taxas com base nos metadados da transação nas configurações do contexto:

{
  "name": "Interchange Plus Rate Lookup",
  "rate_type": "variable",
  "lookup_strategy": "multi_attribute",
  "attributes": [
    {
      "field": "metadata.mcc",
      "type": "string",
      "required": true
    },
    {
      "field": "metadata.card_type",
      "type": "string",
      "required": true,
      "values": ["credit", "debit"]
    },
    {
      "field": "metadata.transaction_method",
      "type": "string",
      "required": true,
      "values": ["physical", "online", "link"]
    }
  ],
  "rate_source": {
    "type": "api",
    "endpoint": "https://rates-api.example.com/interchange/v1/rate",
    "method": "POST",
    "auth_type": "bearer",
    "cache_ttl_seconds": 3600
  },
  "fallback": {
    "strategy": "default_rate",
    "default_rate": 2.5,
    "alert_on_fallback": true
  }
}

Melhores práticas para taxas variáveis

Cache nas consultas de taxas

Habilite cache para chamadas de API de taxas para reduzir latência. A maioria das taxas não muda dentro de um dia.

Versione suas tabelas de taxas

Use tabelas de taxas versionadas (ex: “2024Q1”) e rastreie qual versão foi usada para cada correspondência.

Defina tolerância apropriada

Taxas de rede podem variar ligeiramente. Defina tolerância de 1-2% para evitar exceções falsas.

Monitore falhas de consulta de taxas

Alerte quando consultas de taxas falharem frequentemente - pode indicar códigos MCC ausentes ou problemas de API.

Melhores práticas

Use fontes confiáveis de taxas de câmbio

Conecte-se a provedores de câmbio estabelecidos com dados históricos. Evite fontes com lacunas ou atualizações atrasadas.

Defina tolerâncias apropriadas por moeda

Moedas voláteis (mercados emergentes) precisam de tolerâncias maiores. Pares estáveis (EUR/USD) podem usar tolerâncias mais restritas.

Monitore tendências de variação de câmbio

Revise regularmente os relatórios de variação de câmbio. Variância crescente pode indicar problemas de timing ou de fonte de taxas.

Documente decisões de fonte de taxas

Registre por que fontes de taxas e estratégias específicas foram escolhidas. Isso ajuda durante auditorias e resolução de problemas.

Planeje para indisponibilidade de taxas

Configure comportamento de fallback sensato e alertas. Tenha um processo para fornecer taxas manuais quando necessário.

Considere o timing de liquidação

Taxas de câmbio podem mudar entre as datas de transação e liquidação. Escolha a estratégia de data da taxa com base nos seus requisitos contábeis.

Introduction

Primeiros passos

Configurações

Reconciliação diária

Integrações

Referência

​Visão geral

​Habilitando multi-moeda

​Configuração do contexto

​Configurações multi-moeda

​Moeda base

​Escolhendo uma moeda base

​Alterando a moeda base

​Fontes de taxa de câmbio

​Provedor externo

​Motor de taxa de ativos do Midaz (opcional)

​Entrada manual

​Estratégia de data da taxa

​Opções de estratégia

​Configurar estratégia de data da taxa

​Opções de horário da taxa

​Configuração de tolerância

​Fórmula de tolerância

​Exemplos de tolerância

​Tolerância personalizada por par de moedas

​Tratamento de taxas de câmbio ausentes

​Opções de fallback

​Configurar fallback

​Exceção de taxa ausente

​Impacto na pontuação de confiança

​Cálculo da pontuação de moeda

​Exemplo de pontuação

​Taxas variáveis por atributos de transação

​Casos de uso comuns

​Configuração de consulta de taxas

​Melhores práticas para taxas variáveis

​Melhores práticas

​Próximos passos

Pontuação de Confiança

Divisão e Agregação

Visão geral

Habilitando multi-moeda

Configuração do contexto

Configurações multi-moeda

Moeda base

Escolhendo uma moeda base

Alterando a moeda base

Fontes de taxa de câmbio

Provedor externo

Motor de taxa de ativos do Midaz (opcional)

Entrada manual

Estratégia de data da taxa

Opções de estratégia

Configurar estratégia de data da taxa

Opções de horário da taxa

Configuração de tolerância

Fórmula de tolerância

Exemplos de tolerância

Tolerância personalizada por par de moedas

Tratamento de taxas de câmbio ausentes

Opções de fallback

Configurar fallback

Exceção de taxa ausente

Impacto na pontuação de confiança

Cálculo da pontuação de moeda

Exemplo de pontuação

Taxas variáveis por atributos de transação

Casos de uso comuns

Configuração de consulta de taxas

Melhores práticas para taxas variáveis

Melhores práticas

Próximos passos