Simulación

Ejecuta en modo dry-run una regla de coincidencia y previsualiza el cálculo de un programa de comisiones — solo lectura, para validar la configuración.

Matcher expone dos endpoints de simulación de solo lectura para que puedas responder “¿qué pasaría?” antes de confirmar la configuración: simulación de coincidencia (¿esta regla realmente coincidirá?) y simulación de comisiones (¿qué comisiones cobraría este programa de comisiones?). Ninguna persiste nada.

​

Simulación de coincidencia

---

Previsualiza cómo una única regla — una regla existente ya configurada (ruleId) o una regla candidata en línea (rule) — coincidiría con las transacciones no conciliadas de un contexto, sin confirmar nada.

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 existente ya configurada 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, por defecto 25) limita los pares de posible coincidencia devueltos.

La respuesta indica cuántos grupos 1:1 formaría la regla, una muestra acotada de pares de posible coincidencia (cada uno con una puntuación de confianza y una justificación por componente) y los recuentos de no conciliados por lado:

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

Alcance: la simulación puntúa mediante el motor de reglas determinista sobre los montos originales de la transacción. No aplica la normalización de comisiones en tiempo de ejecución ni la banda de variación de FX, y solo previsualiza el agrupamiento por pares 1:1 (sin asignación 1:N/N:M). Un par que solo coincide tras la normalización de comisiones, dentro de la banda de FX o mediante asignación no se cuenta aquí.

​

Simulación de comisiones

---

Calcula las comisiones para un monto bruto dado usando un programa de comisiones específico. Úsala para validar las reglas de un programa de comisiones 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.00",
  "netAmount": "97.70",
  "totalFee": "2.30",
  "currency": "USD",
  "items": [
    { "name": "interchange", "fee": "1.50", "baseUsed": "100.00" }
  ]
}

La simulación de comisiones no tiene metadatos de transacción, por lo que los ítems de comisión basados en expresiones que requieren un identificador de transacción devuelven su error de identificador faltante como un 4xx. Un programa de comisiones inexistente devuelve 404.

​

Cuándo usar cada una

---

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

Ambas son estrictamente de solo lectura: nunca persisten una ejecución, grupo, ítem, regla ni transacción, y el tenant siempre se toma del JWT.

​

Códigos de respuesta

---

Estado	Significado
200	Simulación devuelta
400	Entrada no válida (regla ambigua/faltante, ids no válidos, monto bruto no válido)
404	Contexto, regla o programa de comisiones no encontrado
503	Simulación de coincidencia no disponible