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

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

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

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

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

```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 (producirlas 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": { "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.

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

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

```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" }'
```

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

<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/products/matcher/matching/matcher-simulate).</Tip>

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