> ## 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 multimoneda
> Concilia transacciones en distintas monedas en Matcher convirtiendo a un monto base con las indicaciones de FX de cada transacción y aplica luego tus reglas de coincidencia existentes.
Matcher permite conciliar transacciones en monedas diferentes al convertir los montos a una moneda base común antes de compararlos. Esto habilita la coincidencia entre transacciones internacionales, operaciones de tesorería y conciliaciones de múltiples entidades.
## Resumen
***
La coincidencia multimoneda convierte los montos de ambas transacciones a una moneda base con el tipo de cambio correspondiente y luego aplica las reglas de coincidencia estándar. Si los montos convertidos quedan dentro de la tolerancia, Matcher crea una coincidencia. De lo contrario, crea una excepción para revisión.
## Cómo funciona
***
El soporte multimoneda reside 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-currency" separado.
Cuando las transacciones tienen monedas diferentes, Matcher usa los campos `amountBase` y `currencyBase` de cada transacción para comparar los montos convertidos. Hoy, Matcher completa estos campos base **en el momento de la coincidencia**. Matcher los deriva de las indicaciones de FX por transacción que viajan en los metadatos de la propia transacción (consulta [FX desde los metadatos de la transacción](#fx-from-transaction-metadata) más abajo).
No puedes suministrar un monto base directamente al cargar el archivo, porque el vocabulario del mapeo de campos no tiene columnas de monto base. Si una transacción ya trae un monto base, Matcher lo respeta y nunca lo sobrescribe, pero la vía admitida para llevar montos base a tus transacciones es la de los metadatos de FX.
No hay un proveedor de FX externo ni un servicio de consulta de tipos de cambio: el tipo de cambio siempre proviene de la propia fila de la transacción.
### Componentes clave
| Componente | Dónde reside | Propósito |
| ------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `amountBase` / `currencyBase` | Campos de la transacción | Montos en moneda base usados para la comparación, derivados en el momento de la coincidencia a partir de los metadatos de FX |
| `matchBaseAmount` / `matchBaseCurrency` | Configuración de la regla | Indican a una regla que compare montos base en lugar de los originales |
| `fx_rate`, `fx_base_currency`, `fx_notional_expr` | Metadatos de la transacción | Indicaciones de FX por transacción usadas para derivar el monto base en el momento de la coincidencia |
## Cómo configurar reglas para multimoneda
***
Habilita la comparación multimoneda al configurar `matchBaseAmount` y `matchBaseCurrency` en `true` en la configuración de la regla.
### Regla exacta 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 de tolerancia 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 los componentes (`DefaultConfidenceWeights`: monto 40, moneda 30, fecha 20, referencia 10) para producir una puntuación de 0–100. Valores como `matchScore: 100` o `matchBaseScore: 90` **no** se aplican directamente como salida de la coincidencia.
Estos campos están actualmente **reservados para uso futuro**. Matcher los mantiene por paridad entre las configuraciones de reglas y para métricas. Configurarlos hoy no tiene efecto sobre la puntuación de coincidencia ni sobre la confirmación automática.
No dependas de `matchScore` / `matchBaseScore` para controlar la confianza. Ya sea que una regla coincida con montos originales o base, el motor de puntuación calcula la puntuación de confianza a partir de los mismos pesos de componentes 40/30/20/10. Para reflejar la incertidumbre de FX, ajusta la **regla** de coincidencia en sí (por ejemplo, usa una regla TOLERANCE o cambia 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/products/matcher/reference/matcher-confidence-scoring).
***
Cuando una transacción todavía no tiene un monto base, Matcher la convierte en el momento de la coincidencia con las indicaciones de FX que viajan en el `metadata` de esa transacción. Matcher **no** llama a ningún proveedor de tipos de cambio externo. El tipo de cambio viaja con la fila.
La conversión solo se ejecuta cuando `fx_base_currency` está presente. La conversión nunca sobrescribe un monto base que la transacción ya trae. La conversión nunca modifica el `amount` ni el `currency` originales, porque solo cambia la comparación.
### Campos de metadatos
| Campo de metadatos | Obligatorio | Propósito |
| ------------------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fx_base_currency` | Sí (para disparar) | La moneda base **a la que** se convierte el monto. Pasa a ser `currencyBase`. |
| `fx_rate` | Sí, a menos que se configure `fx_notional_expr` | Tipo de cambio multiplicativo. `amountBase = amount * fx_rate`. |
| `fx_notional_expr` | No | Expresión que se evalúa contra los metadatos de la transacción para derivar el nocional base directamente. Cuando está presente, tiene precedencia sobre `fx_rate`. |
| `fx_rate_source` | No | Etiqueta opcional que identifica de dónde vino el tipo de cambio; se guarda para validación y auditoría. El valor predeterminado es `metadata`. |
### Ejemplo de transacción con metadatos de 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 los metadatos anteriores, Matcher deriva `amountBase = 1000.00 * 1.085 = 1085.00` y `currencyBase = USD`, y luego compara contra el otro lado según la configuración `matchBaseAmount` / `matchBaseCurrency` de la regla.
Si una transacción ya trae un monto base, Matcher ignora estas indicaciones de metadatos, porque nunca sobrescribe un monto base existente. La transacción no participa en la coincidencia por monto base cuando las indicaciones faltan o no son válidas (tipo de cambio no interpretable, expresión fallida). La ejecución continúa.
### Cuando faltan los campos base
Cuando una regla requiere coincidencia por monto base (`matchBaseAmount` / `matchBaseCurrency`) y las transacciones carecen de monto base o de moneda base, Matcher registra la condición bajo el motivo de excepción `FX_RATE_UNAVAILABLE`. Puedes filtrar la lista de excepciones por `reason=FX_RATE_UNAVAILABLE` (junto con los motivos relacionados `MISSING_BASE_AMOUNT` y `MISSING_BASE_CURRENCY`) para encontrar las transacciones que no pudieron sumarse a la comparación por monto base.
## Banda de variación del tipo de cambio
***
Los montos entre monedas suelen diferir levemente, porque cada lado convierte con un tipo de cambio distinto o en un día distinto. La clave `fxVarianceBand` en las reglas TOLERANCE atiende esto: define un **segundo umbral apilado por encima de 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 escanear los pares `1:1` entre monedas que quedaron no conciliados. Un par cuyo residuo de monto base supera la tolerancia de coincidencia pero se mantiene dentro de la banda igual **coincide**. El par pasa a ser un grupo propuesto con una confianza fija de 75, por debajo del umbral de confirmación automática, así que siempre requiere revisión humana. Matcher marca ambas transacciones con el motivo de excepción `FX_RATE_VARIANCE`. El residuo pasa entonces a ser una excepción tipificada en lugar de reducirse a `UNMATCHED`.
La banda solo aplica cuando:
* ambos lados traen un monto base y la misma moneda base.
* las monedas originales difieren (la desviación dentro de la misma moneda es un simple desajuste, no un caso de FX).
* todos los demás controles de la regla (ventana de fechas, referencia, moneda, campos compuestos) siguen pasando.
Un `fxVarianceBand` en cero o ausente deshabilita 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 multimoneda, cada transacción trae los campos de moneda original y de moneda base. Suministras `amount` y `currency` en la carga. Matcher deriva `amountBase` y `currencyBase` en el momento de la coincidencia a partir de los metadatos de FX:
| Campo | Tipo | Descripción |
| -------------- | ------- | ------------------------------------------------------------------- |
| `amount` | Decimal | Monto original de la transacción (suministrado en la carga) |
| `currency` | String | Código de moneda ISO 4217 original (suministrado en la carga) |
| `amountBase` | Decimal | Monto convertido a la moneda base (derivado de los metadatos de 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 de 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 entre monedas
***
**Origen (cuenta en EUR):**
| ID | Monto | Monto base |
| -------- | ------------ | ------------ |
| txn\_001 | 1,000.00 EUR | 1,085.00 USD |
**Destino (cuenta en 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 los metadatos de cada transacción en la fuente, con el tipo de cambio que aplicaba cuando la transacción se liquidó. Como el tipo de cambio viaja con la fila, los resultados son reproducibles entre ejecuciones, sin consultas de tipo de cambio en tiempo de ejecución.
`matchBaseScore` y `matchScore` siguen siendo campos reservados y no cambian la puntuación de confianza calculada. El motor siempre usa los pesos fijos 40/30/20/10. Para marcar para revisión las coincidencias convertidas con FX, diseña la regla en sí (por ejemplo, tolerancias más estrictas o verificaciones obligatorias de referencia/fecha) en lugar de depender de estos campos de puntuación.
Las conversiones de FX introducen pequeñas variaciones. Usa reglas TOLERANCE con matchBaseAmount para admitir diferencias de redondeo y de momento del tipo de cambio.
Usa una moneda base consistente en todos los contextos. USD es común para operaciones internacionales. Usa tu moneda de reporte para nacional + internacional.
## Próximos pasos
***
Cómo funcionan las puntuaciones de coincidencia y qué umbrales aplican.
Referencia completa de los tipos de regla y los campos de configuración.