Coincidencia multi-moneda

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.

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. Hay dos formas en que estos campos base se completan:

En el momento de la ingesta — el monto base y la moneda base se proporcionan aguas arriba cuando se ingiere la transacción. Los valores del momento de la ingesta siempre tienen prioridad.
En el momento de la coincidencia — cuando una transacción no tiene un monto base del momento de la ingesta, Matcher deriva uno a partir de pistas FX por transacción incluidas en la metadata de la propia transacción (consulta FX desde la metadata de la transacción más abajo).

No existe ningún proveedor FX externo ni servicio de consulta de tasas: la tasa siempre proviene de la propia fila de la transacción.

Componentes clave

Componente	Ubicación	Propósito
`amountBase` / `currencyBase`	Campos de transacción	Montos pre-convertidos para comparación
`matchBaseAmount` / `matchBaseCurrency`	Configuración de regla	Indica a la regla que compare montos base en lugar de originales
`fx_rate`, `fx_base_currency`, `fx_notional_expr`	Metadata de transacción	Pistas FX por transacción usadas para derivar el monto base en el momento de la coincidencia

Configurando reglas para multi-moneda

Habilita 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/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/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

Los campos matchScore y matchBaseScore se aceptan y validan en la configuración de la regla, pero no influyen en la puntuación de confianza calculada. El motor de puntuación siempre usa los pesos internos fijos de cada componente (DefaultConfidenceWeights: monto 40, moneda 30, fecha 20, referencia 10) para producir una puntuación de 0 a 100. Valores como matchScore: 100 o matchBaseScore: 90 no se aplican directamente como el resultado de la coincidencia. Estos campos están actualmente reservados para uso futuro (se conservan por paridad entre configuraciones de regla y para métricas); establecerlos no tiene efecto sobre cómo se puntúa o se confirma automáticamente una coincidencia hoy.

No dependas de matchScore / matchBaseScore para controlar la confianza. Ya sea que una regla coincida por montos originales o base, la puntuación de confianza se calcula a partir de los mismos pesos de componente 40/30/20/10. Para reflejar la incertidumbre FX, ajusta la regla de coincidencia en sí (por ejemplo, usa una regla TOLERANCE o ajusta los requisitos de fecha/referencia) en lugar de estos campos de puntuación.

Para el modelo de puntuación completo, consulta Puntuación de confianza.

FX desde la metadata de la transacción

Cuando una transacción llega sin un monto base del momento de la ingesta, Matcher aún puede convertirla en el momento de la coincidencia usando pistas FX incluidas en la metadata de esa transacción. Matcher no llama a ningún proveedor de tasas externo — la tasa viaja con la fila. La conversión solo se ejecuta cuando fx_base_currency está presente, y nunca sobrescribe un monto base del momento de la ingesta (la ingesta siempre gana). El amount y la currency originales nunca se modifican — la conversión cambia únicamente la comparación.

Campos de metadata

Campo de metadata	Requerido	Propósito
`fx_base_currency`	Sí (para activar)	La moneda base a la que se convierte el monto. Se convierte en `currencyBase`.
`fx_rate`	Sí, a menos que se defina `fx_notional_expr`	Tasa multiplicativa. `amountBase = amount * fx_rate`.
`fx_notional_expr`	No	Expresión evaluada contra la metadata de la transacción para derivar directamente el notional base. Cuando está presente, tiene prioridad sobre `fx_rate`.
`fx_rate_source`	No	Etiqueta opcional que identifica de dónde provino la tasa, conservada para validación y auditoría. Por defecto es `metadata`.

Ejemplo de transacción con metadata FX

{
  "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"
  }
}

Con la metadata anterior, Matcher deriva amountBase = 1000.00 * 1.085 = 1085.00 y currencyBase = USD, luego compara contra el otro lado usando las configuraciones matchBaseAmount / matchBaseCurrency de la regla.

Si una transacción ya lleva un monto base del momento de la ingesta, estas pistas de metadata se ignoran. Si las pistas faltan o están mal formadas (tasa no parseable, expresión fallida), la transacción simplemente no participa en la coincidencia por monto base — la ejecución no se aborta.

Campos de la transacción

Para la coincidencia multi-moneda, las transacciones deben incluir tanto los campos de moneda original como base:

Campo	Tipo	Descripción
`amount`	Decimal	Monto original de la transacción
`currency`	String	Código de moneda ISO 4217 original
`amountBase`	Decimal	Monto convertido a la moneda base
`currencyBase`	String	Código ISO 4217 de la moneda base

Ejemplo de transacción

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

Ejemplo: conciliación cross-currency

Origen (cuenta EUR):

ID	Monto	Monto base
txn_001	1,000.00 EUR	1,085.00 USD

Destino (cuenta USD):

ID	Monto	Monto base
txn_002	1,095.00 USD	1,095.00 USD

Con una regla TOLERANCE (matchBaseAmount: true, percentTolerance: 0.02):

Montos base: $1,085.00 vs$ 1,095.00
Variación: $10.00 (0.92%)
Tolerancia: 2%
Resultado: Coincidencia (0.92% < 2%)

Mejores prácticas

Pre-convierte montos en la ingesta

Completa 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.

Refleja la incertidumbre FX a través del diseño de la regla

matchBaseScore y matchScore son campos reservados y no cambian la puntuación de confianza calculada — el motor siempre usa los pesos fijos 40/30/20/10. Para marcar las coincidencias convertidas por FX para revisión, diseña la regla en sí (por ejemplo, tolerancias más ajustadas o comprobaciones de referencia/fecha requeridas) en lugar de depender de estos campos de puntuación.

Combina con reglas de tolerancia

Las conversiones FX introducen pequeñas variaciones. Usa reglas TOLERANCE con matchBaseAmount para permitir diferencias de redondeo y de timing de tasas.

Documenta la elección de tu moneda base

Usa una moneda base consistente en todos los contextos. USD es común para operaciones internacionales; usa tu moneda de reporte para operaciones domésticas + internacionales.

Coincidencia multi-moneda

Descripción general

Cómo funciona

Componentes clave

Configurando reglas para multi-moneda

Regla Exact con coincidencia de monto base

Regla Tolerance con coincidencia de monto base

Puntuación de confianza

FX desde la metadata de la transacción

Campos de metadata

Ejemplo de transacción con metadata FX

Campos de la transacción

Ejemplo de transacción

Ejemplo: conciliación cross-currency

Mejores prácticas

Próximos pasos

Confidence Scoring

Match Rules

​Descripción general

​Cómo funciona

​Componentes clave

​Configurando reglas para multi-moneda

​Regla Exact con coincidencia de monto base

​Regla Tolerance con coincidencia de monto base

​Puntuación de confianza

​FX desde la metadata de la transacción

​Campos de metadata

​Ejemplo de transacción con metadata FX

​Campos de la transacción

​Ejemplo de transacción

​Ejemplo: conciliación cross-currency

​Mejores prácticas

​Próximos pasos

Confidence Scoring

Match Rules

Descripción general

Cómo funciona

Componentes clave

Configurando reglas para multi-moneda

Regla Exact con coincidencia de monto base

Regla Tolerance con coincidencia de monto base

Puntuación de confianza

FX desde la metadata de la transacción

Campos de metadata

Ejemplo de transacción con metadata FX

Campos de la transacción

Ejemplo de transacción

Ejemplo: conciliación cross-currency

Mejores prácticas

Próximos pasos