Simulación

Simula una regla de coincidencia y previsualiza los cálculos de un esquema de comisiones en Matcher. Ambos endpoints son de solo lectura, así que puedes validar la configuración antes de comprometer nada.

Matcher expone dos endpoints de simulación de solo lectura para que puedas responder “¿qué pasaría?” antes de comprometer una configuración. Son la simulación de coincidencia (¿esta regla va a coincidir?) y la simulación de comisiones (¿qué comisiones cobraría este esquema?). Ninguno persiste nada.

​

Simulación de coincidencia

---

Previsualiza cómo una sola regla haría coincidir las transacciones no conciliadas de un contexto, sin comprometer nada. Elige una regla configurada existente (ruleId) o una regla candidata en línea (rule).

curl -X POST "https://api.matcher.example.com/v1/matching/simulate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contextId": "550e8400-e29b-41d4-a716-446655440000",
    "rule": {
      "type": "TOLERANCE",
      "config": { "percentTolerance": "0.01" }
    },
    "sampleLimit": 25
  }'

Proporciona exactamente uno de:

• ruleId: previsualiza una regla configurada existente del contexto.
• rule: previsualiza una definición candidata no persistida (type es uno de EXACT, TOLERANCE, DATE_LAG, FUZZY, más su config).

Proporcionar ambos, o ninguno, devuelve 400. sampleLimit (1–200, 25 de forma predeterminada) limita los pares candidatos que se devuelven.

La respuesta informa cuántos grupos 1:1 formaría la regla y los conteos de no conciliados por lado. También devuelve una muestra acotada de pares candidatos, cada uno con una puntuación de confianza. En why, los booleanos indican si los dos montos, monedas y fechas son iguales, no los componentes de la puntuación:

{
  "ruleType": "TOLERANCE",
  "matchedGroups": 12,
  "unmatchedLeft": 3,
  "unmatchedRight": 5,
  "sampleTruncated": false,
  "sample": [
    {
      "left":  { "id": "...", "amount": "100", "currency": "BRL", "date": "2025-06-01T00:00:00Z" },
      "right": { "id": "...", "amount": "100", "currency": "BRL", "date": "2025-06-01T00:00:00Z" },
      "score": 100,
      "why": { "amountMatch": true, "currencyMatch": true, "dateMatch": true, "referenceScore": 1 },
      "amountDelta": "0",
      "dateDeltaDays": 0
    }
  ]
}

Alcance: la simulación lee como máximo 5,000 transacciones no conciliadas del contexto, y los orígenes del contexto deben resolverse en dos lados. Puntúa con el motor de reglas determinista sobre los montos brutos de las transacciones. No aplica la normalización de comisiones en tiempo de ejecución, la conversión FX ni la banda de variación FX, y previsualiza solo el agrupamiento por pares 1:1 (sin asignación 1:N/N:M). La simulación no cuenta un par que solo coincide después de la normalización de comisiones, después de la conversión FX, dentro de la banda FX o por asignación.

​

Simulación de comisiones

---

Calcula las comisiones de un monto bruto dado con un esquema de comisiones específico. currency debe ser igual a la moneda del esquema. Úsalo para validar las reglas de un esquema antes de asociarlo a un contexto.

curl -X POST "https://api.matcher.example.com/v1/fee-schedules/{scheduleId}/simulate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "grossAmount": "100.00", "currency": "USD" }'

La respuesta devuelve el monto neto, la comisión total y un desglose por ítem:

{
  "grossAmount": "100",
  "netAmount": "97.7",
  "totalFee": "2.3",
  "currency": "USD",
  "items": [
    { "name": "interchange", "fee": "1.5", "baseUsed": "100" },
    { "name": "processing", "fee": "0.8", "baseUsed": "100" }
  ]
}

La simulación de comisiones no tiene metadatos de transacción, así que los ítems de comisión por expresión que requieren un identificador de transacción exponen su error de identificador faltante como un 4xx. Un esquema que no existe devuelve 404.

​

Cuándo usar cada una

---

Uso	Cuándo
Simulación de coincidencia (/matching/simulate)	Estás escribiendo o revisando una regla de coincidencia y quieres ver cuántas transacciones agruparía, y qué pares, antes de comprometerla.
Simulación de comisiones (/fee-schedules/{scheduleId}/simulate)	Estás configurando un esquema de comisiones y quieres verificar el desglose de neto y comisión que produciría para un monto bruto representativo.

Ambos endpoints se mantienen estrictamente de solo lectura. Nunca persisten una ejecución, un grupo, un ítem, una regla ni una transacción. El tenant siempre viene del JWT.

​

Códigos de respuesta

---

Estado	Significado
200	Simulación devuelta
400	Entrada inválida (regla ambigua o ausente, tipo de regla inválido, lados que no se resuelven, monto bruto inválido)
404	Contexto, regla o esquema de comisiones no encontrado
422	Campo con formato incorrecto, como un id inválido
503	Simulación de coincidencia no disponible