> ## 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>Cuando Lerian habilita las sugerencias de reglas en tu entorno y en tu tenant, Matcher envía cada solicitud de sugerencia al proveedor de modelos de lenguaje que Lerian configura para tu entorno. Un tenant sin sugerencias de reglas recibe `403`. El payload es **solo agregados**. Ninguna transacción en bruto, ningún monto ni PII sale de Matcher.</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 una transacción, pero su configuración puede fijar umbrales monetarios como `absTolerance`.

## 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 |
| `403` | Las sugerencias de reglas no están habilitadas para tu tenant (solo al producir sugerencias) |
| `404` | Sugerencia de regla no encontrada |
| `409` | Transición de estado inválida / ya vinculada |
| `422` | Filtro de estado o id inválido, o la sugerencia aprobada no pasó la validación |
| `503` | Sugerencia de reglas o advisor no disponible (escribe las reglas de forma manual) |