> ## 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]
>
> Quando a Lerian habilita as sugestões de regras no seu ambiente, o Matcher envia cada requisição de sugestão para o provedor de modelo de linguagem que a Lerian configura para o seu ambiente. Quando o recurso não está disponível no seu ambiente, a operação responde `503`. O payload traz apenas agregados. Nenhuma transação bruta, nenhum valor monetário e nenhum PII sai do Matcher.

## 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 uma transação, mas a config dela pode definir limiares monetários como `absTolerance`.

## 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](https://docs.lerian.studio/pt/products/matcher/matching/matcher-simulate.md).

## Códigos de resposta

***

| Status | Significado |
| - | - |
| `200` | Sugestões produzidas, listadas, aprovadas ou rejeitadas |
| `403` | Permissão ausente, contexto inativo ou (apenas ao produzir sugestões) consentimento para as sugestões de regras não concedido para o seu ambiente |
| `404` | Sugestão de regra não encontrada |
| `409` | Transição de estado inválida / já vinculada |
| `422` | Filtro de status ou id inválido, ou sugestão aprovada falhou na validação |
| `503` | Sugestão de regra ou advisor indisponível (escreva as regras manualmente) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.