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

# Sugestões de regras

> Gere regras de match sugeridas por IA, revise-as em uma fila com intervenção humana e aprove ou rejeite cada candidata antes de criar qualquer regra.

O Matcher pode propor regras de match (apenas configuração) a partir do histórico de um contexto usando IA, mas **a saída da IA nunca é autoritativa**. Gerar uma sugestão não cria nenhuma regra; uma regra é criada apenas quando uma pessoa aprova uma sugestão. Este guia cobre a fila de sugestões de regras com intervenção humana (HITL).

<Note>O fluxo é controlado por um interruptor global do advisor **e** por uma adesão por tenant (fail-closed: um tenant sem adesão recebe `403`). A carga útil de saída contém **apenas agregados**: nenhuma transação, valor ou PII sem tratamento sai do seu ambiente.</Note>

## Gerar sugestões

***

Construa características de histórico agregadas e seguras para a privacidade de um contexto, peça regras candidatas ao advisor de IA e enfileire cada candidata que sobrevive na fila de revisão.

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

A resposta retorna as revisões `PENDING_REVIEW` recém-criadas; gerá-las não cria nenhuma regra:

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

Os tipos de candidata vêm do vocabulário fechado: `EXACT` (igualdade estrita), `TOLERANCE` (dentro de uma faixa de valor) ou `DATE_LAG` (que permite uma defasagem na data de liquidação). A candidata é **apenas configuração**: nunca carrega um valor monetário nem uma transação.

## Listar sugestões

***

Lista paginada por cursor das sugestões de regras de um contexto, opcionalmente filtrada por status.

```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) e `cursor`. Ler a fila não gera nenhuma saída.

## Aprovar uma sugestão

***

Aprovar uma sugestão `PENDING_REVIEW` cria a regra de match através do caminho de escrita de configuração determinístico. Este é o **único** caminho de uma sugestão de IA até uma regra de match ativa, e ele é executado somente mediante aprovação 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"
}
```

## Rejeitar uma sugestão

***

Rejeitar uma sugestão `PENDING_REVIEW` a descarta: nada é criado. O corpo é 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" }'
```

O principal que aprova ou rejeita é registrado para auditoria.

## Ciclo de vida após a aprovação

***

Uma vez que uma sugestão está `APPROVED`, seu `createdRuleId` vincula a uma regra de match real que participa das execuções de match exatamente como uma regra escrita à mão. Uma revisão é uma máquina de estados unidirecional: uma sugestão `PENDING_REVIEW` transiciona para `APPROVED` ou `REJECTED` uma única vez e não pode ser decidida novamente. Tentar decidir novamente, ou aprovar uma revisão já vinculada, retorna `409`. Uma candidata aprovada que não passa na validação retorna `422`.

<Tip>Visualize como uma regra candidata se comportaria antes de aprová-la com o endpoint de simulação somente leitura; consulte [Simulação](/pt/matcher/matching/matcher-simulate).</Tip>

## Códigos de resposta

***

| Status | Significado                                                         |
| ------ | ------------------------------------------------------------------- |
| `200`  | Sugestões geradas, listadas, aprovadas ou rejeitadas                |
| `400`  | Filtro de status ou id de sugestão inválido                         |
| `403`  | Tenant sem adesão às sugestões de regras                            |
| `404`  | Sugestão de regra não encontrada                                    |
| `409`  | Transição de estado inválida / já vinculada                         |
| `422`  | A sugestão aprovada não passou na validação                         |
| `503`  | Sugestão de regra ou advisor indisponível (crie regras manualmente) |