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.

Quando a Lerian habilita a extração de documentos no seu ambiente, você pode enviar documentos. Quando o recurso não está disponível no seu ambiente, a operação responde 503. 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. O Matcher envia um trecho limitado da camada de texto do documento para o provedor de modelo de linguagem que a Lerian configura para o seu ambiente. Quando o PDF não tem camada de texto, o Matcher envia o próprio PDF. 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). Na trilha text_layer, os valores de campo são tokens do texto do documento. Na trilha vision, o modelo os lê da imagem. 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 fecha a revisão, e 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. Quando a Lerian habilita o advisor de mapeamento no seu ambiente, o Matcher envia um trecho limitado da amostra para o provedor de modelo de linguagem que a Lerian configura para o seu ambiente. 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 e envia cada um em fluxo para o pipeline de ingestão de conteúdo confiável. kind é sftp (o padrão), https, s3 ou imap. O corpo carrega as coordenadas de conexão e um credentialRef obrigatório. Uma busca SFTP precisa da chave de host do servidor em connectOptions.known_hosts e lê no máximo 256 objetos correspondentes.

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": "<credential-ref>",
    "format": "br/cnab240/febraban-base",
    "connectOptions": { "known_hosts": "sftp.bank.example ssh-ed25519 AAAA..." }
  }'

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 do documento vazio, paginação inválida)
`403`	O consentimento para a extração de documentos não foi concedido para o seu ambiente
`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, ou requisição inválida (filtro de status inválido, amostra de mapeamento ausente, corpo estruturalmente inválido)
`503`	Extração, revisão, proposta ou busca não disponível no seu ambiente, extrator de documentos indisponível ou falha de transporte

Visão geral

Guias

Console

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