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

> Produza regras de correspondência sugeridas por IA, revise cada uma em uma fila com humano no circuito e aprove ou rejeite cada candidata antes de qualquer regra ser criada.

O Matcher pode propor regras de correspondência apenas de configuração a partir do histórico de um contexto usando IA, mas **a saída da IA nunca é autoritativa**. Produzir uma sugestão não cria nenhuma regra. O Matcher cria uma regra apenas quando uma pessoa aprova uma sugestão. Este guia cobre a fila de sugestões de regras com humano no circuito (HITL).

<Note>Um kill-switch global do advisor **e** um opt-in por tenant controlam essa via (fail-closed: um tenant sem opt-in recebe `403`). O payload de saída traz **apenas agregados**. Nenhuma transação bruta, nenhum valor monetário e nenhum PII sai do seu deploy.</Note>

## Produzir sugestões

***

Monte atributos de histórico agregados e seguros para a privacidade de um contexto, peça regras candidatas ao advisor de IA e coloque cada candidata que sobreviver 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 (produzi-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": { "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
}
```

Os tipos de candidata vêm de um vocabulário fechado: `EXACT` (igualdade estrita), `TOLERANCE` (dentro de uma faixa de valor) ou `DATE_LAG` (permitindo um deslocamento da data de liquidação). A candidata é **apenas de configuração**. Ela 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 query: `status` (`PENDING_REVIEW`, `APPROVED`, `REJECTED`), `limit` (1–200) e `cursor`. Ler a fila não envia nada para fora.

## Aprovar uma sugestão

***

Aprovar uma sugestão `PENDING_REVIEW` cria a regra de correspondência pelo caminho determinístico de escrita de configuração. Esse é o **único** caminho de uma sugestão de IA até uma regra de correspondência ativa, e ele roda apenas com 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 e não cria nenhuma regra. O corpo da requisição é obrigatório, mas o campo `reason` dele é opcional (envie `{}` para rejeitar sem 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" }'
```

O Matcher registra para auditoria o principal que aprovou ou rejeitou.

## Ciclo de vida depois da aprovação

***

Assim que uma sugestão fica `APPROVED`, o `createdRuleId` dela aponta para uma regra de correspondência real que participa das execuções de correspondência exatamente como uma regra escrita à mão. Uma revisão é uma máquina de estados de mão única: uma sugestão `PENDING_REVIEW` passa para `APPROVED` ou `REJECTED` uma vez e não pode ser decidida de novo. Tentar decidir de novo, ou aprovar uma revisão já vinculada, retorna `409`. Uma candidata aprovada que falha na validação retorna `422`.

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

## Códigos de resposta

***

| Status | Significado                                                               |
| ------ | ------------------------------------------------------------------------- |
| `200`  | Sugestões produzidas, listadas, aprovadas ou rejeitadas                   |
| `400`  | Filtro de status ou id de sugestão inválido                               |
| `403`  | Tenant sem opt-in para sugestões de regras                                |
| `404`  | Sugestão de regra não encontrada                                          |
| `409`  | Transição de estado inválida / já vinculada                               |
| `422`  | Sugestão aprovada falhou na validação                                     |
| `503`  | Sugestão de regra ou advisor indisponível (escreva as regras manualmente) |