Saltar al contenido principal
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": { "tolerance": 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 es opcional. 
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

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