Coincidencia multi-moneda

Concilia transacciones en diferentes monedas convirtiendo los montos a una base común antes de aplicar las reglas de coincidencia de Matcher.

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. Hoy, estos campos base se completan en el momento de la coincidencia: Matcher los deriva 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 puedes proporcionar un monto base directamente en la carga de archivos — el vocabulario del field map no tiene columnas de monto base. Si una transacción ya lleva un monto base, Matcher lo respeta y nunca lo sobrescribe, pero la forma soportada de obtener montos base en tus transacciones es la vía de la metadata FX.

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 en moneda base usados para comparación, derivados en el momento de la coincidencia a partir de la metadata FX
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 aún no tiene un monto base, Matcher la convierte 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 que ya esté definido en la transacción. 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, estas pistas de metadata se ignoran — Matcher nunca sobrescribe un monto base existente. 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.

​

Cuando faltan los campos base

Cuando una regla requiere coincidencia por monto base (matchBaseAmount / matchBaseCurrency) y las transacciones carecen de un monto base o una moneda base, Matcher registra la condición bajo la razón de excepción FX_RATE_UNAVAILABLE. Puedes filtrar la lista de excepciones por reason=FX_RATE_UNAVAILABLE (junto con las razones relacionadas MISSING_BASE_AMOUNT y MISSING_BASE_CURRENCY) para encontrar transacciones que no pudieron participar en la comparación por monto base.

​

Banda de variación de tasa FX

---

Los montos entre monedas distintas a menudo difieren ligeramente porque cada lado se convirtió con una tasa diferente o en un día diferente. La clave fxVarianceBand en las reglas TOLERANCE maneja esto: define un segundo umbral apilado sobre la tolerancia de coincidencia, expresado como fracción decimal (0.0001 = 1 punto básico).

Después de la pasada de tolerancia estricta, Matcher vuelve a examinar los pares 1:1 cross-currency sin coincidencia. Un par cuyo residual de monto base excede la tolerancia de coincidencia pero permanece dentro de la banda aún coincide — el par se convierte en un grupo propuesto con una confianza fija de 75, por debajo del umbral de confirmación automática, por lo que siempre requiere revisión humana. Ambas transacciones se marcan con la razón de excepción FX_RATE_VARIANCE para que el residual quede registrado como una excepción tipada en lugar de colapsar a UNMATCHED.

La banda solo aplica cuando:

• ambos lados llevan un monto base y la misma moneda base;
• las monedas originales difieren (una desviación en la misma moneda es una discrepancia simple, no un caso FX);
• todas las demás condiciones de la regla (ventana de fecha, referencia, moneda, campos compuestos) siguen cumpliéndose.

Un fxVarianceBand en cero o ausente desactiva la banda.

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer ***" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "TOLERANCE",
   "priority": 3,
   "config": {
     "matchBaseAmount": true,
     "matchBaseCurrency": true,
     "percentTolerance": 0.01,
     "fxVarianceBand": "0.005"
   }
 }'

​

Campos de la transacción

---

Para la coincidencia multi-moneda, cada transacción lleva tanto los campos de moneda original como base. Tú proporcionas amount y currency en la carga; Matcher deriva amountBase y currencyBase en el momento de la coincidencia a partir de la metadata FX:

Campo	Tipo	Descripción
amount	Decimal	Monto original de la transacción (proporcionado en la carga)
currency	String	Código de moneda ISO 4217 original (proporcionado en la carga)
amountBase	Decimal	Monto convertido a la moneda base (derivado de la metadata FX)
currencyBase	String	Código ISO 4217 de la moneda base (derivado de fx_base_currency)

​

Ejemplo de transacción

Después de la conversión FX, una transacción se ve así internamente:

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

---

Proporciona metadata FX estable por transacción

Adjunta fx_base_currency y fx_rate (o fx_notional_expr) a la metadata de cada transacción en el origen, usando la tasa que aplicaba cuando la transacción se liquidó. Como la tasa viaja con la fila, los resultados son reproducibles entre ejecuciones — sin consultas de tasas en tiempo de ejecución.

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.

​

Próximos pasos

---

Confidence Scoring

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

Match Rules

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