Sugerencias de reglas

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

Un kill-switch global del advisor y una adhesión por tenant controlan este canal (falla de forma cerrada: un tenant sin adhesión recibe 403). El payload de salida es solo agregados. Ninguna transacción en bruto, ningún monto ni PII sale de tu despliegue.

Producir sugerencias

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

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 (producirlas 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 vienen de un vocabulario cerrado: EXACT (igualdad estricta), TOLERANCE (dentro de una banda de monto) o DATE_LAG (que permite un desfase de la fecha de liquidación). La candidata es solo de 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, con filtro opcional 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 envía nada hacia afuera.

Aprobar una sugerencia

Aprobar una sugerencia PENDING_REVIEW crea la regla de coincidencia por el camino determinista de escritura de configuración. Este es el único camino de una sugerencia de IA a una regla de coincidencia activa, y se ejecuta solo 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 y no crea ninguna regla. El cuerpo de la solicitud es obligatorio, pero su campo reason es opcional (envía {} para rechazar sin un 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" }'

Matcher registra para la auditoría el principal que aprueba o que rechaza.

Ciclo de vida después de la aprobación

Una vez que una sugerencia queda en APPROVED, su createdRuleId apunta a una regla de coincidencia real que participa en las ejecuciones de coincidencia igual que una regla escrita a mano. Una revisión es una máquina de estados de un solo sentido: una sugerencia PENDING_REVIEW pasa a APPROVED o a REJECTED una vez y no se puede volver a decidir. Intentar volver a decidirla, o aprobar una revisión ya vinculada, 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 producidas, listadas, aprobadas o rechazadas
`400`	Filtro de estado o id de sugerencia inválido
`403`	El tenant no se adhirió a las sugerencias de reglas
`404`	Sugerencia de regla no encontrada
`409`	Transición de estado inválida / ya vinculada
`422`	La sugerencia aprobada no pasó la validación
`503`	Sugerencia de reglas o advisor no disponible (escribe las reglas de forma manual)

Resumen

Guías

Matcher UI

Servidor MCP

Operaciones

Sugerencias de reglas

Producir sugerencias

Listar sugerencias

Aprobar una sugerencia

Rechazar una sugerencia

Ciclo de vida después de la aprobación

Códigos de respuesta

​Producir sugerencias

​Listar sugerencias

​Aprobar una sugerencia

​Rechazar una sugerencia

​Ciclo de vida después de la aprobación

​Códigos de respuesta

Producir sugerencias

Listar sugerencias

Aprobar una sugerencia

Rechazar una sugerencia

Ciclo de vida después de la aprobación

Códigos de respuesta