Saltar al contenido principal
Matcher permite conciliar transacciones en diferentes monedas convirtiendo los montos a una moneda base común antes de la comparación. Esto habilita la coincidencia entre transacciones internacionales, operaciones de tesorería y conciliaciones multi-entidad.

​
Descripción general

La coincidencia multi-moneda convierte ambos montos de transacción a una moneda base usando la tasa FX apropiada, luego aplica las reglas de coincidencia estándar. Si los montos convertidos están dentro de la tolerancia, Matcher crea una coincidencia. De lo contrario, crea una excepción para revisión.
Flujo de coincidencia multi-moneda

​
Cómo funciona

El soporte multi-moneda está integrado en los tipos de contexto existentes (1:1, 1:N, N:M) y en las reglas de coincidencia — no existe un tipo de contexto “multi-moneda” separado. Cuando las transacciones tienen monedas diferentes, Matcher usa los campos amountBase y currencyBase en cada transacción para comparar montos convertidos. La conversión FX ocurre en el momento de la ingesta o a través de una fuente FX externa.

​
Componentes clave

ComponenteUbicaciónPropósito
amountBase / currencyBaseCampos de transacciónMontos pre-convertidos para comparación
matchBaseAmount / matchBaseCurrencyConfiguración de reglaIndica a la regla que compare montos base en lugar de originales
rateIdContextoReferencia a la tasa FX usada para la conversión
Interfaz FXSourcePuerto de integraciónInterfaz conectable para obtener tasas de cambio

​
Configurando reglas para multi-moneda

Habilite la comparación multi-moneda configurando matchBaseAmount y matchBaseCurrency como true en la configuración de la regla.

​
Regla Exact con coincidencia de monto 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
   }
 }'
Cuando matchBaseAmount es true, la regla compara los campos amountBase en lugar de amount. Cuando matchBaseCurrency es true, compara currencyBase en lugar de currency.

​
Regla Tolerance con coincidencia de monto 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
   }
 }'

​
Puntuación de confianza

Cuando una regla coincide por montos base, la puntuación de confianza usa matchBaseScore en lugar de matchScore. Esto permite asignar menor confianza a coincidencias convertidas por FX para reflejar la incertidumbre adicional.
Tipo de coincidenciaPuntuación por defecto
Coincidencia por monto originalmatchScore (ej. 100 para EXACT)
Coincidencia por monto basematchBaseScore (ej. 90 para EXACT)

​
Integración FXSource

Matcher define una interfaz de puerto FXSource para obtener tasas de cambio en tiempo de ejecución. Puede implementar esta interfaz para conectar cualquier proveedor de tasas FX a Matcher. 
// Interfaz del puerto FXSource (internal/matching/ports/fx_source.go)
type FXSource interface {
    GetRate(ctx context.Context, from, to string, date time.Time) (Rate, error)
}

​
Usando la fuente FX

  1. Implemente la interfaz FXSource con su proveedor de tasas preferido.
  2. Registre la implementación al iniciar la aplicación.
  3. Configure rateId en el contexto para referenciar la configuración de tasas.
La integración de fuente FX es opcional. Si no está configurada, la coincidencia multi-moneda depende de los campos amountBase y currencyBase pre-convertidos proporcionados en el momento de la ingesta.

​
Campos de la transacción

Para la coincidencia multi-moneda, las transacciones deben incluir tanto los campos de moneda original como base:
CampoTipoDescripción
amountDecimalMonto original de la transacción
currencyStringCódigo de moneda ISO 4217 original
amountBaseDecimalMonto convertido a la moneda base
currencyBaseStringCódigo ISO 4217 de la moneda base

​
Ejemplo de transacción

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

​
Ejemplo: conciliación cross-currency

Origen (cuenta EUR):
IDMontoMonedaMonto baseMoneda base
txn_0011,000.00EUR1,085.00USD
Destino (cuenta USD):
IDMontoMonedaMonto baseMoneda base
txn_0021,095.00USD1,095.00USD
Con una regla TOLERANCE (matchBaseAmount: true, percentTolerance: 0.02):
  • Montos base: 1,085.00vs1,085.00 vs 1,095.00
  • Variación: $10.00 (0.92%)
  • Tolerancia: 2%
  • Resultado: Coincidencia (0.92% < 2%)

​
Mejores prácticas

Complete los campos amountBase y currencyBase durante la carga de archivos o la ingesta. Esto evita consultas FX en tiempo de ejecución y asegura resultados reproducibles.
Configure matchBaseScore más bajo que matchScore para que las coincidencias convertidas por FX reciban menor confianza, marcándolas para revisión cuando sea apropiado.
Las conversiones FX introducen pequeñas variaciones. Use reglas TOLERANCE con matchBaseAmount para permitir diferencias de redondeo y timing de tasas.
Use una moneda base consistente en todos los contextos. USD es común para operaciones internacionales; use su moneda de reporte para operaciones domésticas + internacionales.

​
Próximos pasos

Puntuación de confianza

Cómo funcionan las puntuaciones de coincidencia y qué umbrales aplican.

Reglas de coincidencia

Referencia completa de tipos de reglas y campos de configuración.