Revisões de extração

O Matcher pode extrair candidatos a transação de documentos e propor mapeamentos de campo usando IA, mas a saída da IA nunca é a palavra final. Nada chega à conciliação até uma pessoa aprovar. Este guia cobre a fila de revisão de extração com humano no circuito (HITL), as propostas de mapeamento por IA e as ações de job relacionadas.

Um kill-switch global e uma adesão por tenant controlam a trilha de extração de documentos. Um tenant que não aderiu recebe 403. Essa resposta vem antes de qualquer armazenamento ou saída dos bytes do documento.

Enfileirar um documento para extração

Envie um documento de origem (PDF) para rodar a extração determinística + IA. Os candidatos a transação resultantes vão para uma fila de revisão. Nada chega à conciliação ainda.

curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{sourceId}/extract-document" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/pdf" \
  --data-binary @statement.pdf

A resposta (202 Accepted) retorna o id da revisão enfileirada, a contagem de candidatos e um status que é sempre PENDING_REVIEW no enfileiramento:

{
  "reviewId": "550e8400-e29b-41d4-a716-446655440000",
  "candidateCount": 12,
  "status": "PENDING_REVIEW"
}

A fila de revisão

Listar revisões

Lista paginada por cursor das revisões de extração de um contexto, filtrada opcionalmente pelo status do ciclo de vida.

curl -X GET "https://api.matcher.example.com/v1/imports/contexts/{contextId}/extraction-reviews?status=PENDING_REVIEW&limit=50" \
  -H "Authorization: Bearer $TOKEN"

Parâmetros de query: status (PENDING_REVIEW, APPROVED, REJECTED), limit (1–200) e cursor.

Obter uma revisão

curl -X GET "https://api.matcher.example.com/v1/imports/contexts/{contextId}/extraction-reviews/{reviewId}" \
  -H "Authorization: Bearer $TOKEN"

Uma revisão carrega o ciclo de vida dela, os candidatos propostos, a procedência e o estado de vínculo:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contextId": "550e8400-e29b-41d4-a716-446655440000",
  "sourceId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PENDING_REVIEW",
  "candidates": [
    {
      "source": "text_layer",
      "fields": [
        { "canonicalKey": "amount", "value": "100.50", "confidence": 0.95, "page": 1 },
        { "canonicalKey": "date", "value": "2025-06-01", "confidence": 0.9, "page": 1 }
      ]
    }
  ],
  "version": 1,
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

Cada candidato declara a trilha que o produziu: text_layer (texto do PDF, confiança maior) ou vision (modelo de OCR/visão, confiança menor). Os valores de campo são tokens literais. Dinheiro continua como string, nunca um valor interpretado.

Aprovar ou rejeitar

Aprovar

Aprovar uma revisão em PENDING_REVIEW executa o único repasse determinístico para o pipeline normal de ingestão (dedup + outbox + match-trigger) e vincula o job resultante à revisão. Este é o único caminho de um candidato da IA até uma transação conciliada, e ele roda apenas com aprovação humana explícita.

curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/extraction-reviews/{reviewId}/approve" \
  -H "Authorization: Bearer $TOKEN"

{
  "reviewId": "550e8400-e29b-41d4-a716-446655440000",
  "ingestionJobId": "550e8400-e29b-41d4-a716-446655440000",
  "candidateCount": 12
}

Rejeitar

Rejeitar descarta os candidatos, então nada entra na ingestão. O corpo é opcional. Um corpo vazio é uma “rejeição sem motivo” válida.

curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/extraction-reviews/{reviewId}/reject" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "poor scan quality, re-upload" }'

O principal que aprova ou rejeita fica registrado para auditoria.

Propostas de mapeamento

Antes de declarar um mapa de campo à mão, peça ao advisor para inspecionar uma amostra representativa e propor um mapeamento apenas de configuração. Ele é consultivo e sem efeitos colaterais: produzir uma proposta não persiste nada. Você confirma o resultado pelo caminho já existente de declaração de mapa de campo.

curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{sourceId}/mapping-proposal" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sample": "id;value;ccy;posted_at\nA1;10,50;BRL;2025-06-01\n",
    "format": "csv",
    "hints": { "locale": "pt-BR", "has_header": "true" }
  }'

A resposta carrega o mapa de campo proposto, o dialeto da fonte e um detalhamento por campo com confiança e justificativa:

{
  "mapping": { "amount": "value", "external_id": "id" },
  "dialect": {
    "encoding": "utf-8",
    "delimiter": "semicolon",
    "decimalStyle": "comma",
    "dateStyle": "iso"
  },
  "fields": [
    { "canonicalKey": "amount", "sourceColumn": "value", "confidence": 0.92, "rationale": "numeric column with comma decimal" }
  ]
}

A resposta nunca carrega valores interpretados, montantes nem transações.

Buscar de um transporte externo

Dispare uma busca e ingestão manual que lista cada objeto correspondente às coordenadas de transporte informadas (hoje, SFTP) e envia cada um em fluxo para o pipeline de ingestão de conteúdo confiável. O corpo carrega as coordenadas de conexão mais uma referência opaca de credencial, nunca um segredo.

curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{sourceId}/fetch" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "sftp",
    "host": "sftp.bank.example",
    "port": 22,
    "path": "outbound/returns",
    "glob": "*.ret",
    "credentialRef": "cred-handle-123",
    "format": "br/cnab240/febraban-base"
  }'

A resposta (202 Accepted) retorna um resultado por arquivo, na ordem da busca. Uma falha de entrada em um arquivo não para o lote. A resposta informa cada uma:

{
  "files": [
    { "name": "statement-2025-06.ret", "ingestionJobId": "550e8400-...", "transactionCount": 42 }
  ]
}

Uma falha no nível do transporte (endpoint inacessível ou credencial recusada) retorna 503.

Inspecionar os erros do job

Depois de uma importação, liste os erros de parse/normalização armazenados por linha de um job (limitados a 100 por job) para explicar importações que falharam ou falharam em parte.

curl -X GET "https://api.matcher.example.com/v1/imports/contexts/{contextId}/jobs/{jobId}/errors" \
  -H "Authorization: Bearer $TOKEN"

{
  "items": [ ... ],
  "totalErrors": 137,
  "storedErrors": 100,
  "errorCap": 100,
  "truncated": true
}

totalErrors guarda o total de falhas sem limite. truncated é true quando o total passa do conjunto armazenado (limitado).

Códigos de resposta

Status	Significado
`200`	Revisão, lista, proposta de mapeamento ou erros de job retornados
`202`	Documento enfileirado / busca aceita
`400`	Entrada inválida (corpo vazio, filtro de status inválido, paginação inválida, amostra de mapeamento ausente)
`403`	Tenant sem adesão à extração de documentos
`404`	Revisão ou job não encontrado
`409`	Transição de estado de revisão inválida
`422`	Nenhum candidato pôde ser extraído / corpo de requisição estruturalmente inválido
`503`	Extração, revisão, proposta ou busca não habilitada neste deploy

Visão geral

Guias

Matcher UI

Servidor MCP

Operações

Revisões de extração

Enfileirar um documento para extração

A fila de revisão

Listar revisões

Obter uma revisão

Aprovar ou rejeitar

Aprovar

Rejeitar

Propostas de mapeamento

Buscar de um transporte externo

Inspecionar os erros do job

Códigos de resposta

​Enfileirar um documento para extração

​A fila de revisão

​Listar revisões

​Obter uma revisão

​Aprovar ou rejeitar

​Aprovar

​Rejeitar

​Propostas de mapeamento

​Buscar de um transporte externo

​Inspecionar os erros do job

​Códigos de resposta

Enfileirar um documento para extração

A fila de revisão

Listar revisões

Obter uma revisão

Aprovar ou rejeitar

Aprovar

Rejeitar

Propostas de mapeamento

Buscar de um transporte externo

Inspecionar os erros do job

Códigos de resposta