> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# 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).

<Note>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.</Note>

## 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.

```bash theme={null}
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:

```json theme={null}
{
  "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.

```bash theme={null}
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.

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

```json theme={null}
{
  "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.

```bash theme={null}
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`.

<Tip>Previsualiza cómo se comportaría una regla candidata antes de aprobarla con el endpoint de simulación de solo lectura; consulta [Simulación](/es/matcher/matching/matcher-simulate).</Tip>

## 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) |