Extrator de documentos
O Extrator lê PDFs (guias, recibos, boletos) e captura automaticamente os dados que interessam — competência, valor, vencimento e, principalmente, de qual cliente é o documento. Este guia mostra como configurar cada etapa e, em especial, como testar o que o Extrator está puxando antes de colocar no ar.
Você não precisa adivinhar: teste cada fluxo
Cada etapa do Extrator tem um botão Testar próprio. Rode os documentos de exemplo por elas e veja exatamente o que o Extrator está capturando — campo a campo, documento a documento — sem afetar nada em produção. Sempre teste todos os fluxos antes de salvar e ativar.
O Extrator fica em Nuvem → Extrator (rota /korok/nuvem/extrator). Abra um extrator existente ou crie um novo para chegar ao editor descrito abaixo.
Como o Extrator processa um documento
São quatro etapas em sequência — cada uma testável de forma independente
Um padrão de identificação decide se aquele PDF é do tipo que este extrator entende (ex.: uma guia de FGTS, um boleto de ISS).
Opcional. Quando um PDF traz vários documentos concatenados, o Extrator divide o arquivo em vários documentos separados antes de extrair.
Para cada campo (competência, valor, vencimento, cliente…) o Extrator executa uma sequência de regras até chegar ao valor final.
Com os dados extraídos, os fluxos decidem o que fazer: salvar a guia, criar tarefa, arquivar o PDF no drive, etc.
Como o Extrator descobre de qual cliente é o documento
A peça mais importante — e a causa mais comum de documentos que “não caem” no cliente certo
O Extrator não compara o CNPJ pela formatação. Ele primeiro normaliza o CNPJ para apenas números — removendo pontos, barras e traços — e usa esse número para encontrar o cliente cadastrado.
O que acontece, passo a passo:
O valor extraído do PDF, como 12.345.678/0001-90, vira só dígitos: 12345678000190.
O Extrator procura um cliente que tenha exatamente aquele CNPJ cadastrado. Esse match exato sempre tem prioridade (assim uma filial não é confundida com a matriz).
Se nenhum CNPJ completo bater, o Extrator usa a raiz (os 8 primeiros dígitos) para casar a empresa. Isso cobre guias que só trazem a raiz, como o FGTS Digital.
O Extrator também identifica por outros documentos do cliente:
| Identificador | Como é tratado |
|---|---|
| CNPJ (14 dígitos) | Normaliza para números; match exato primeiro, depois pela raiz de 8 dígitos |
| CPF (11 dígitos) | Normaliza para números; match exato com o CPF cadastrado |
| Inscrição Estadual (IE) | Normaliza para números; casa pela IE cadastrada, podendo restringir por estado |
Para o documento ser atribuído ao cliente, o CNPJ (ou CPF / IE) precisa estar cadastrado naquele cliente no Korok. Se o documento traz um CNPJ que não existe em nenhum cadastro, o Extrator não consegue classificá-lo — e é exatamente aí que o documento “some” ou cai no lugar errado. Antes de abrir um chamado, confira se a inscrição do cliente está cadastrada.
Fluxo 1 — Identificação
Em “Informações Básicas”, no campo do padrão de identificação
Defina o padrão de identificação (uma expressão regular) que aparece em todo documento desse tipo. Ele é o que diz ao Korok “este PDF é uma guia de FGTS”, por exemplo.
Como testar
Para cada documento de exemplo na coluna “Preview do documento”, o editor mostra um indicador verde (identificado) ou vermelho (não identificado). Ajuste o padrão até que todos os exemplos válidos fiquem verdes.
Fluxo 2 — Pré-processamento (divisão)
Na seção “Pré-processamento de PDF”
Use quando um único PDF contém vários documentos (ex.: um lote de guias). Habilite o pré-processamento, escolha dividir antes ou depois do padrão e informe o regex que marca a fronteira entre documentos.
Como testar
Clique em Testar na “Prévia da divisão”. O Extrator mostra quantos documentos seriam gerados, em quais páginas o padrão foi encontrado e uma linha do tempo com cada sub-documento (página inicial e final). Confirme que a quantidade e os limites batem com o esperado.
Fluxo 3 — Extração de campos (regras)
Na seção “Regras de Extração”
Cada campo tem uma sequência de regras (um pipeline). A saída de uma regra vira a entrada da próxima, até sobrar o valor final. É aqui, por exemplo, que se monta a identificação do cliente:
- Regra 1 (regex): localiza o CNPJ no texto →
12.345.678/0001-90 - Regra 2 (transformar para cliente): normaliza para números e busca o cliente cadastrado → o cliente é identificado
Como testar
Cada regra tem um botão Testar. Ao testar, o Extrator mostra o resultado passo a passo do pipeline: o que entrou, o que cada regra produziu e o valor final. Use isso para descobrir em qual regra a extração quebrou — em vez de só ver que o campo veio vazio.
Teste de ponta a ponta
Na seção “Testar Extração”
Depois de configurar as etapas, rode tudo junto. Clique em Testar em N documentos e o Extrator executa divisão + extração em todos os documentos de exemplo de uma vez.
O resultado mostra:
- Um resumo geral: quantos sucessos, parciais e falhas, com a confiança média.
- Por documento: cada campo, o valor extraído e quantos passos foram aplicados.
- Quando houve divisão, o resultado de cada sub-documento separadamente.
Use documentos de exemplo variados (matriz e filial, valores diferentes, meses diferentes). Quanto mais diverso o conjunto de testes, menos surpresas em produção.
Fluxo 4 — O que o Extrator faz com os dados
Na seção “Fluxos”
Os fluxos transformam a extração em ação. Cada fluxo aponta para os campos extraídos (qual campo é o cliente, qual é a competência, qual é o valor) — por isso a identificação correta do cliente é pré-requisito para quase todos eles:
Salvar guia / imposto
Registra a guia extraída no cliente, com competência, valor e vencimento
Criar tarefa
Abre uma tarefa no Korok vinculada ao cliente e à competência
Arquivar no drive
Salva o PDF na estrutura padrão do drive do cliente
Enviar e-mail / webhook
Notifica ou integra com sistemas externos a partir dos dados extraídos
Comece com os fluxos em modo manual para conferir o resultado de algumas execuções reais antes de deixar tudo automático.
Solução de problemas
Os relatos mais comuns — e o que verificar antes de abrir um chamado
- Confirme que o CNPJ / CPF / IE do documento está cadastrado naquele cliente. Sem o cadastro, não há como o Extrator casar o documento.
- Teste a regra de identificação do cliente passo a passo: veja se o CNPJ está sendo extraído corretamente do PDF antes da normalização.
- Se o documento traz só a raiz (8 dígitos) e você tem matriz e filiais cadastradas, o match por raiz pode pegar outra unidade. Prefira cadastrar o CNPJ completo quando o documento o fornece.
Configure, teste cada fluxo (identificação, divisão, regras) e rode o teste de ponta a ponta antes de ativar. E lembre: o Extrator só atribui o documento ao cliente quando o CNPJ normalizado bate com uma inscrição cadastrada. Em caso de dúvida, fale com a equipe pelo chat.