Sugerencias de reglas

Genera reglas de coincidencia sugeridas por IA, revísalas en una cola con intervención humana y aprueba o rechaza cada candidata antes de crear cualquier regla.

Matcher puede proponer reglas de coincidencia (solo configuración) a partir del historial de un contexto usando IA, pero la salida de la IA nunca es autoritativa. Generar una sugerencia no crea ninguna regla; una regla se crea únicamente cuando una persona aprueba una sugerencia. Esta guía cubre la cola de sugerencias de reglas con intervención humana (HITL).

El flujo está controlado por un interruptor global del advisor y por una activación por tenant (fail-closed: un tenant sin activación recibe 403). La carga útil de salida contiene solo agregados: ninguna transacción, monto o PII sin procesar sale de tu despliegue.

​

Generar sugerencias

---

Construye características de historial agregadas y seguras para la privacidad de un contexto, pide reglas candidatas al advisor de IA y encola cada candidata que sobrevive en la cola de revisión.

curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/rule-suggestions" \
  -H "Authorization: Bearer $TOKEN"

La respuesta devuelve las revisiones PENDING_REVIEW recién creadas; generarlas no crea ninguna regla:

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "contextId": "550e8400-e29b-41d4-a716-446655440000",
      "candidate": {
        "type": "TOLERANCE",
        "priority": 10,
        "config": { "percentTolerance": "0.01" },
        "rationale": "near-miss amounts cluster under 1%",
        "expectedImprovement": "+8% auto-match",
        "confidence": 0.82
      },
      "status": "PENDING_REVIEW",
      "version": 1,
      "createdAt": "2026-06-16T10:30:00Z",
      "updatedAt": "2026-06-16T10:30:00Z"
    }
  ],
  "count": 1
}

Los tipos de candidata provienen del vocabulario cerrado: EXACT (igualdad estricta), TOLERANCE (dentro de una banda de monto) o DATE_LAG (que permite un desfase de fecha de liquidación). La candidata es solo configuración: nunca lleva un valor monetario ni una transacción.

​

Listar sugerencias

---

Lista paginada por cursor de las sugerencias de reglas de un contexto, filtrable opcionalmente por estado.

curl -X GET "https://api.matcher.example.com/v1/matching/contexts/{contextId}/rule-suggestions?status=PENDING_REVIEW&limit=20" \
  -H "Authorization: Bearer $TOKEN"

Parámetros de consulta: status (PENDING_REVIEW, APPROVED, REJECTED), limit (1–200) y cursor. Leer la cola no genera ninguna salida.

​

Aprobar una sugerencia

---

Aprobar una sugerencia PENDING_REVIEW crea la regla de coincidencia a través de la ruta de escritura de configuración determinista. Esta es la única ruta desde una sugerencia de IA hasta una regla de coincidencia activa, y solo se ejecuta con la aprobación humana explícita.

curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/rule-suggestions/{suggestionId}/approve" \
  -H "Authorization: Bearer $TOKEN"

{
  "reviewId": "550e8400-e29b-41d4-a716-446655440000",
  "createdRuleId": "550e8400-e29b-41d4-a716-446655440000"
}

​

Rechazar una sugerencia

---

Rechazar una sugerencia PENDING_REVIEW la descarta: no se crea nada. El cuerpo de la solicitud es obligatorio, pero su campo reason es opcional (envía {} para rechazar sin motivo).

curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/rule-suggestions/{suggestionId}/reject" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "too aggressive" }'

El principal que aprueba o rechaza se registra para auditoría.

​

Ciclo de vida después de la aprobación

---

Una vez que una sugerencia está APPROVED, su createdRuleId enlaza con una regla de coincidencia real que participa en las ejecuciones de coincidencia exactamente igual que una regla escrita a mano. Una revisión es una máquina de estados unidireccional: una sugerencia PENDING_REVIEW transiciona a APPROVED o REJECTED una sola vez y no puede volver a decidirse. Intentar volver a decidir, o aprobar una revisión ya enlazada, devuelve 409. Una candidata aprobada que no pasa la validación devuelve 422.

Previsualiza cómo se comportaría una regla candidata antes de aprobarla con el endpoint de simulación de solo lectura; consulta Simulación.

​

Códigos de respuesta

---

Estado	Significado
200	Sugerencias generadas, listadas, aprobadas o rechazadas
400	Filtro de estado o id de sugerencia inválido
403	Tenant sin activación para sugerencias de reglas
404	Sugerencia de regla no encontrada
409	Transición de estado inválida / ya enlazada
422	La sugerencia aprobada no pasó la validación
503	Sugerencia de regla o advisor no disponible (crea reglas manualmente)