Revisões de extração

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

Status	Significado
`200`	Revisão, lista, proposta de mapeamento ou erros de job retornados
`202`	Documento enfileirado / fetch aceito
`400`	Entrada inválida (corpo vazio, filtro de status incorreto, paginação inválida, amostra de mapeamento ausente)
`403`	Tenant não aderiu à 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 fetch não habilitados neste deployment

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 erros de um 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 erros de um 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 erros de um job

Códigos de resposta