Pular para o conteúdo principal
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).
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.

​
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. 
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: 
{
  "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. 
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. 
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: nada é criado. O corpo é opcional. 
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.
Visualize como uma regra candidata se comportaria antes de aprová-la com o endpoint de simulação somente leitura; consulte Simulação.

​
Códigos de resposta

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