> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # 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](#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 ```bash cURL theme={null} 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 ```bash cURL theme={null} 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](/es/matcher/reference/matcher-confidence-scoring). ## 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 ```json theme={null} { "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. ```bash cURL theme={null} 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: ```json theme={null} { "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 *** 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. `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. Las conversiones FX introducen pequeñas variaciones. Usa reglas TOLERANCE con matchBaseAmount para permitir diferencias de redondeo y de timing de tasas. 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 *** Cómo funcionan las puntuaciones de coincidencia y qué umbrales aplican. Referencia completa de tipos de reglas y campos de configuración.