Pular para o conteúdo principal
O Matcher pode extrair candidatos de transações de documentos e propor mapeamentos de campos usando IA — mas a saída da IA nunca é autoritativa. Nada é conciliado até que um humano aprove. Este guia cobre a fila de revisão de extração com supervisão humana (HITL), as propostas de mapeamento de IA e as ações de job relacionadas.
A esteira de extração de documentos é protegida por um kill-switch global e uma adesão explícita por tenant. Um tenant que não aderiu recebe 403 antes que qualquer byte do documento seja armazenado ou transmitido.

​
Enfileirar um documento para extração

Faça upload de um documento de origem (PDF) para executar a extração determinística + IA. Os candidatos de transações resultantes são enfileirados em uma revisão — nada é conciliado 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 ao enfileirar: 
{
  "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, opcionalmente filtrada por 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 consulta: 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 seu ciclo de vida, os candidatos propostos, a proveniência e o estado de vinculação: 
{
  "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 esteira que o produziu: text_layer (texto do PDF, maior confiança) ou vision (modelo de OCR/visão, menor confiança). Os valores dos campos são tokens literais — o dinheiro permanece como string, nunca como um valor parseado.

​
Aprovar ou rejeitar

​
Aprovar

Aprovar uma revisão em estado PENDING_REVIEW executa o único repasse determinístico para o pipeline normal de ingestão (deduplicação + outbox + gatilho de matching) e vincula o job resultante à revisão. Este é o único caminho de um candidato de IA a uma transação conciliada, e ele só é executado mediante 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 — nada é ingerido. 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 é registrado para auditoria.

​
Propostas de mapeamento

Antes de declarar um mapa de campos manualmente, peça ao advisor para inspecionar uma amostra representativa e propor um mapeamento somente de configuração. Ele é consultivo e sem efeitos colaterais: gerar uma proposta não persiste nada. Você confirma o resultado pelo caminho existente de declaração do mapa de campos. 
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 campos proposto, o dialeto de origem 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 parseados, montantes ou transações.

​
Buscar de um transporte externo

Dispare um fetch-and-ingest manual que lista todos os objetos que correspondem às coordenadas de transporte fornecidas (SFTP hoje) e transmite cada um para o pipeline de ingestão de conteúdo confiável. O corpo carrega as coordenadas de conexão mais uma referência de credencial opaca — 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 de busca. Falhas de intake por arquivo são reportadas sem fazer o lote falhar: 
{
  "files": [
    { "name": "statement-2025-06.ret", "ingestionJobId": "550e8400-...", "transactionCount": 42 }
  ]
}
Uma falha em nível de transporte (endpoint inacessível ou credencial rejeitada) retorna 503.

​
Inspecionar erros de um job

Após uma importação, liste os erros de parse/normalização por linha armazenados para um job (limitados a 100 por job) para explicar importações que falharam total ou parcialmente. 
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 é o total de falhas sem limite; truncated é true quando ele excede o conjunto armazenado (limitado).

​
Códigos de resposta

StatusSignificado
200Revisão, lista, proposta de mapeamento ou erros de job retornados
202Documento enfileirado / fetch aceito
400Entrada inválida (corpo vazio, filtro de status incorreto, paginação inválida)
403Tenant não aderiu à extração de documentos
404Revisão ou job não encontrado
409Transição de estado de revisão inválida
422Nenhum candidato pôde ser extraído / amostra de mapeamento rejeitada a jusante
503Extração, revisão, proposta ou fetch não habilitados neste deployment