Sugestões de regras

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

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.

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.

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

{
  "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.

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.

curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/rule-suggestions/{suggestionId}/approve" \
  -H "Authorization: Bearer $TOKEN"

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

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.

Veja como uma regra candidata se comportaria antes de aprová-la, com o endpoint de simulação somente leitura. Veja Simulação.

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)

Visão geral

Guias

Matcher UI

Servidor MCP

Operações

Sugestões de regras

Produzir sugestões

Listar sugestões

Aprovar uma sugestão

Rejeitar uma sugestão

Ciclo de vida depois da aprovação

Códigos de resposta

​Produzir sugestões

​Listar sugestões

​Aprovar uma sugestão

​Rejeitar uma sugestão

​Ciclo de vida depois da aprovação

​Códigos de resposta

Produzir sugestões

Listar sugestões

Aprovar uma sugestão

Rejeitar uma sugestão

Ciclo de vida depois da aprovação

Códigos de resposta