Extração de NF-e e contratos

O negócio

Uma distribuidora de materiais de construção recebe alguns milhares de documentos de fornecedores por mês. São três tipos: DANFEs em PDF (a representação impressa da NF-e), notas de serviço de prefeituras, cada uma com seu layout, e contratos de fornecimento com cláusulas de reajuste.

Três pessoas do financeiro digitam esses dados no ERP. Na semana de fechamento, a fila atrasa e os pagamentos saem com juros. Quando alguém digita errado, o problema aparece semanas depois: um boleto pago em dobro, um imposto lançado com o valor errado, um fornecedor que não existe no cadastro.

O objetivo é ler cada documento e preencher o ERP sem digitação, com uma regra clara: na dúvida, o documento vai para revisão humana. Ele nunca entra com dado errado.

O que cada documento pede

Documento	Como chega	Campos críticos	O que complica
DANFE	PDF por email ou portal	CNPJ do emitente, chave de acesso, itens, impostos, total, vencimentos	Notas com dezenas de itens e várias parcelas
Nota de serviço	PDF ou link da prefeitura	CNPJ do prestador, valor do serviço, ISS retido, competência	Cada município tem um layout diferente
Contrato	PDF de 10 a 60 páginas	Partes, vigência, índice de reajuste, data-base, multa	A informação está espalhada em cláusulas

O que este cenário mede: acurácia por campo, documentos que vão para revisão e custo por documento.

Versão 1

A primeira versão foi feita em uma semana e acertou os dez documentos da demo.

flowchart LR
  P(["1. PDF"]):::io --> T["2. Texto extraído do PDF"]:::tool
  T --> M(["3. Prompt: liste os dados e calcule os totais"]):::llm
  M --> R["4. Regex no texto da resposta"]:::tool
  R --> E[("5. ERP")]:::store

1. O PDF chega por email ou portal.
2. Uma biblioteca extrai o texto do PDF.
3. Um prompt pede emitente, itens, impostos e totais, e pede para conferir se a soma bate.
4. Expressões regulares tiram os valores da resposta em texto.
5. Os dados entram no ERP.

O prompt central era este:

Você é um assistente financeiro. Leia a nota fiscal abaixo e liste:
emitente, CNPJ, data de emissão, itens com valores, impostos e total.
Some os itens e confira se o total está correto. Valide o CNPJ.

{texto_do_pdf}

Na demo, tudo funcionou. As dez notas eram de fornecedores grandes, com poucos itens e PDF gerado por sistema. O modelo respondia sempre no mesmo formato, e o regex achava os campos.

O problema é que a demo testava o caso fácil. Ninguém mediu notas escaneadas, notas com 40 itens, notas com desconto ou fornecedores pequenos com layout próprio.

O que quebrou

Semana 2. O modelo passou a escrever “Valor total da nota” em vez de “Total”. O regex não achou o campo, e 140 documentos entraram sem valor total. Ninguém percebeu por quatro dias.

Semana 4. Uma nota com 38 itens entrou com o total errado por R$ 0,12. O modelo tinha somado os itens de cabeça e arredondado diferente. O erro só apareceu na conciliação bancária.

Semana 5. Alguém pediu ao prompt para “manter duas casas decimais” e testou com três notas. A acurácia do campo de desconto caiu, mas só em notas com desconto, e nenhuma das três tinha desconto.

Semana 7. Um CNPJ com dígito verificador inválido foi aceito porque o modelo “validou” e respondeu que estava certo. O fornecedor não existia no cadastro.

Repare no que os quatro incidentes têm em comum: nenhum deles gerou erro. O sistema seguiu em frente com dado vazio ou errado, e quem descobriu foi outra área, dias depois. Em extração de documentos, falha silenciosa é o pior tipo de falha, porque o custo cresce a cada dia que ninguém nota.

Smells encontrados

Passagem em Texto Livre

A resposta do modelo era prosa, e o código tentava adivinhar onde estava cada valor:

resposta: "...O valor total da nota é de R$ 4.318,70, já incluídos..."
regex:    r"Total:\s*R\$\s*([\d.,]+)"     # não casa: não existe "Total:"
campo:    valor_total = None              # e o código segue sem reclamar

Qualquer mudança de redação, de versão do modelo ou de idioma quebra o contrato entre o modelo e o código. Causou os documentos sem valor da semana 2.

LLM Fazendo Conta

Somar 38 parcelas, arredondar centavos e calcular dígito verificador são tarefas determinísticas. O código acerta sempre, em microssegundos, e de graça. O modelo acerta quase sempre, e “quase sempre” em dinheiro é um defeito.

O trecho que mostra o smell estava no próprio prompt: “Some os itens e confira se o total está correto. Valide o CNPJ.” O modelo não executa um algoritmo de módulo 11. Ele produz o texto que parece a resposta de quem executou. Causou as semanas 4 e 7.

Prompt Sem Eval

A mudança da semana 5 foi testada assim: três notas coladas no playground, três respostas olhadas a olho, “parece bom”. Três exemplos não cobrem os tipos de documento, os emitentes nem os campos opcionais. A regressão estava justamente num campo que não aparecia nos exemplos. Causou a semana 5.

Checagem +20 XP de primeiraNa semana 2, 140 documentos entraram sem valor total e ninguém percebeu por quatro dias. Qual mudança ataca a causa do problema?

Melhorar o regex para aceitar variações como ‘Valor total’ e ‘Total da nota’

Pedir a saída num schema com o total como campo obrigatório e tipado

Reforçar no prompt que a resposta deve sempre usar a palavra ‘Total:’

Refatorações aplicadas

1. Criar Eval Antes de Mexer no Prompt

Antes de qualquer mudança, o time montou um conjunto de 180 documentos reais anonimizados. Cada um tem o valor certo de cada campo, digitado e conferido por duas pessoas do financeiro. O conjunto foi separado por tipo de documento e por emitente, para que fornecedores grandes não dominassem a média.

Anonimizar não é detalhe. Notas de serviço de autônomos trazem CPF, e contratos trazem nome e endereço de pessoas. Pela LGPD, esses dados precisam de base legal e de cuidado no uso. No dataset, eles foram trocados por valores fictícios que mantêm o formato e os dígitos verificadores válidos.

Um caso do eval tem esta cara:

{
  "id": "danfe-0412",
  "tipo": "danfe",
  "emitente_grupo": "pequeno-layout-proprio",
  "esperado": {
    "cnpj_emitente": "11222333000181",
    "valor_total_centavos": 431870,
    "desconto_centavos": 2500,
    "vencimentos": ["2026-03-10", "2026-04-10"]
  }
}

A versão 1 foi medida contra esse conjunto antes de qualquer mudança. Assim, cada refatoração seguinte tinha uma linha de base para comparar, campo por campo.

2. Trocar Texto Livre por Saída Estruturada

A extração passou a devolver um objeto num schema, com valores em centavos e datas tipadas. O regex foi apagado.

class Item(BaseModel):
    descricao: str
    quantidade: Decimal
    valor_total_centavos: int

class Danfe(BaseModel):
    chave_acesso: str = Field(pattern=r"^\d{44}$")
    cnpj_emitente: str
    data_emissao: date
    itens: list[Item]
    desconto_centavos: int = 0
    valor_total_centavos: int
    vencimentos: list[date]

Duas decisões pequenas fazem muita diferença. Valores em centavos, como inteiros, eliminam o erro de ponto flutuante (em Python, 0.1 + 0.2 dá 0.30000000000000004). E campos obrigatórios fazem a ausência virar erro: com saída estruturada nativa do provedor, o modelo não consegue omitir o total, e um total ilegível vira uma falha de validação visível.

3. Trocar Chamada de LLM por Código

O modelo passou a só ler os valores impressos. Somas, impostos e validação de CNPJ viraram funções com testes:

def cnpj_valido(cnpj: str) -> bool:
    c = re.sub(r"[.\-/\s]", "", cnpj.upper())
    if not re.fullmatch(r"[0-9A-Z]{12}[0-9]{2}", c) or len(set(c)) == 1:
        return False
    def dv(base: str) -> str:
        pesos = [6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2][-len(base):]
        resto = sum((ord(ch) - 48) * p for ch, p in zip(base, pesos)) % 11
        return "0" if resto < 2 else str(11 - resto)
    return c[12] == dv(c[:12]) and c[13] == dv(c[:13])

O validador já aceita o CNPJ alfanumérico definido pela Receita Federal na IN RFB 2.229/2024, previsto para novas inscrições a partir de julho de 2026. Para dígitos, ord(ch) - 48 dá o próprio valor, então a mesma função serve para os dois formatos. É o tipo de mudança de regra que, num prompt, ninguém lembraria de atualizar.

A virada mais importante foi outra: o modelo lê o total impresso, o código calcula o total a partir dos itens, e os dois são comparados. Se divergem, alguém leu errado. Essa divergência virou o principal alarme do sistema.

Checagem +20 XP de primeiraUm colega propõe manter a conferência da soma no prompt: o modelo leria os itens e responderia ‘ok’ ou ‘divergente’. Por que a arquitetura final não faz isso?

Porque soma é trabalho determinístico: o código acerta sempre, de graça, e o modelo só precisa ler os valores

Porque o modelo não consegue ler tabelas de itens com precisão

Porque a conferência no prompt gastaria tokens demais

Arquitetura final

flowchart LR
  P(["1. Documento"]):::io --> XQ{"2. Tem XML?"}
  XQ -->|sim| XP["2a. Ler XML em código"]:::tool
  XQ -->|não| C(["3. Classificar tipo"]):::llm
  C --> X(["4. Extrair por tipo, em schema"]):::llm
  X --> V["5. Validar em código"]:::tool
  XP --> V
  V --> D{"6. Tudo confere?"}
  D -->|sim| E[("7. ERP")]:::store
  D -->|"não, primeira vez"| RP(["8. Reparo com o erro"]):::llm
  RP --> V
  D -->|"não, após reparo"| H((("9. Revisão humana"))):::human
  H --> G[("10. Dataset de ouro")]:::store

1. O documento chega por email ou portal.
2. Antes de chamar o modelo, o sistema procura o XML da NF-e. Ele pode vir anexado ao email ou ser baixado pelo serviço de distribuição do Ambiente Nacional da NF-e, que entrega ao destinatário as notas emitidas contra o seu CNPJ. O acesso exige o certificado digital da empresa, e o XML completo costuma depender da manifestação do destinatário. Com o XML, a leitura é feita em código (2a): dado estruturado e assinado, sem modelo.
3. Sem XML, um passo curto, com modelo pequeno, classifica o tipo: DANFE, nota de serviço ou contrato.
4. Cada tipo tem seu prompt e seu schema. O documento inteiro vai para o modelo, que lê texto e imagem. Contratos longos são lidos por partes e os resultados juntados.
5. O código soma itens, confere impostos, valida CNPJ, chave de acesso e datas.
6. Se tudo confere, o documento segue.
7. Os dados entram no ERP com a referência do documento e da versão do prompt.
8. Se algo não confere, o erro volta ao modelo uma vez, com a mensagem exata da validação.
9. Se o reparo falha, o documento vai para uma pessoa, com o campo problemático destacado ao lado da imagem da página.
10. Cada correção humana vira um caso novo no dataset de ouro.

O passo 2 parece óbvio depois que alguém fala, mas a versão 1 não tinha. Para a maioria das DANFEs, o melhor extrator é não extrair nada. O modelo fica para o que não tem XML: notas de serviço de prefeituras com layout próprio, PDFs de fornecedores que não mandam o XML e contratos.

O passo 4 também mudou em relação à versão 1. Extrair texto de PDF perde a estrutura de tabela, e PDF escaneado nem tem camada de texto. Mandar a página como imagem deixa o modelo ver colunas e linhas como uma pessoa veria.

Exemplo trabalhado: uma DANFE do começo ao fim

Suponha um PDF de um fornecedor pequeno, sem XML no email. O classificador responde {"tipo": "danfe"}. A extração devolve:

{
  "chave_acesso": "35260111222333000181550010000123451000123451",
  "cnpj_emitente": "11222333000181",
  "data_emissao": "2026-01-14",
  "itens": [
    { "descricao": "Cimento CP-II 50kg", "quantidade": "40", "valor_total_centavos": 159600 },
    { "descricao": "Argamassa AC-II 20kg", "quantidade": "25", "valor_total_centavos": 77500 }
  ],
  "desconto_centavos": 0,
  "valor_total_centavos": 237100,
  "vencimentos": ["2026-02-13"]
}

O validador roda quatro checagens, todas em código:

Checagem	Conta	Resultado
Dígito verificador da chave de acesso	módulo 11 sobre os 43 primeiros dígitos	passa
CNPJ do emitente bate com a chave	posições 7 a 20 da chave contêm 11222333000181	passa
Soma dos itens menos desconto	159.600 + 77.500 = 237.100	passa
Vencimento depois da emissão	13/02 vem depois de 14/01	passa

A segunda checagem é a mais esperta. A chave de acesso carrega o CNPJ do emitente dentro dela. Se o modelo ler um dígito errado em um dos dois lugares, eles deixam de bater, e o erro aparece sem que ninguém precise conhecer o fornecedor.

Agora imagine que o modelo leu o segundo item como 75.500 centavos. A soma dá 235.100, e o total impresso diz 237.100. O reparo recebe uma mensagem específica:

A validação falhou:
- soma dos itens (235100) diferente de valor_total_centavos (237100), diferença de 2000.
Releia os valores dos itens e o total na página. Não ajuste números para fechar a conta:
se o documento estiver de fato inconsistente, devolva os valores como impressos.

A última frase do reparo importa. Sem ela, o modelo tende a “consertar” a conta mudando um número qualquer até fechar. Isso troca um erro visível por um invisível. Se a segunda leitura ainda não fecha, o documento vai para revisão, e a pessoa vê o item suspeito destacado.

Contratos longos

Contrato não tem total para conferir, então a validação muda de forma. O contrato é lido por partes (Map-Reduce de Documentos): cada bloco de páginas devolve as cláusulas que encontrou, e um passo final junta tudo num schema com partes, vigência, índice de reajuste (IPCA, IGP-M), data-base e multa.

Cada campo vem com o trecho literal que o sustenta e o número da página. O código confere se o trecho existe mesmo naquela página. Se o modelo citar um texto que não está no documento, o campo vai para revisão.

Armadilhas comuns

• Pedir ao modelo uma nota de confiança. “Confiança de 0 a 1” parece uma boa porta para a revisão humana. Na prática, a confiança que o modelo declara costuma ser mal calibrada: ele diz 0,95 para leituras erradas. Checagens verificáveis (soma, dígito, trecho citado) são melhores portas.
• Reparo sem limite. Repetir o reparo até a validação passar ensina o modelo a inventar números que fecham a conta. Uma tentativa, depois uma pessoa.
• Tolerância de centavos. Aceitar diferença de “até R$ 1” parece pragmático. Em 3 mil documentos por mês, é assim que o erro da semana 4 volta a entrar sem ninguém ver.
• Um prompt para todos os tipos. Contrato e DANFE pedem campos e validações diferentes. Um schema genérico com tudo opcional faz a validação perder os dentes.

Checagem +20 XP de primeiraO validador aponta que a soma dos itens difere do total impresso. O reparo relê a página e devolve os mesmos valores. O que o sistema deve fazer?

Aceitar o documento, porque o modelo confirmou a leitura duas vezes

Rodar o reparo de novo até a soma fechar

Mandar para revisão humana com o campo destacado e guardar a correção no dataset

Números

As métricas deste cenário são acurácia por campo, documentos que vão para revisão e custo por documento, comparando a versão 1 com a arquitetura final nos mesmos 180 documentos.

As três medem coisas diferentes, e duas delas puxam em sentidos opostos. Mandar tudo para revisão zera o dado errado no ERP e mata o projeto. Mandar nada para revisão faz o oposto. A leitura certa é: quantos documentos entram sem revisão, e quantos desses entram com algum campo crítico errado. O segundo número precisa ficar em zero; o primeiro é o que você otimiza.

A acurácia é medida por campo, não por documento, e separada por tipo e grupo de emitente. Uma média geral alta pode esconder um campo de desconto ruim, como mostrou a semana 5.

Os números ainda não foram publicados. Eles virão do código de referência executável, rodando as duas versões contra o mesmo conjunto, e esta seção será atualizada com o resultado e o script que gera os números. Até lá, nenhum número aparece aqui.

Padrões usados

Padrão	Papel no sistema
Encadeamento de Prompts	Classificar, extrair por tipo, validar
Saída Estruturada	Schema por tipo de documento
Map-Reduce de Documentos	Contratos longos lidos por partes
Validação e Reparo de Saída	Erro de validação devolvido ao modelo uma vez
Dataset de Ouro	180 documentos que crescem a cada correção humana

A lista completa de padrões ligados a este cenário está em Relações, abaixo.

Código de referência

O sistema completo, com as duas versões, o dataset anonimizado e o script que gera os números desta página, fica no repositório de código de referência do ai-guru, em scenarios/nfe-contract-extraction/. O repositório está sendo preparado, e o link entra aqui quando for publicado.

Lições

1. A melhor extração é a que você não precisa fazer. Quando existe um dado estruturado na origem, como o XML da NF-e, leia em código. O modelo fica para o que só existe como imagem ou texto livre.
2. Extração e conta são trabalhos diferentes. O modelo lê; o código soma. A divergência entre os dois virou o melhor detector de erro do sistema.
3. Erro silencioso é pior que erro barulhento. Trocar regex por schema transformou campos vazios em falhas visíveis.
4. O eval veio primeiro e pagou a conta. Sem os 180 documentos, nenhuma das mudanças seguintes teria sido segura.
5. Revisão humana é parte da arquitetura. O objetivo nunca foi zero revisão; foi zero dado errado no ERP. Cada correção humana vira um caso de teste, e o dataset cresce com o uso.

Teste seu entendimento

Checagem +20 XP de primeiraUm fornecedor de modelos oferece uma versão nova, mais barata. Antes de trocar, o que você roda?

Dez documentos recentes no playground, comparando as respostas a olho

Uma comparação de custo por documento entre os dois modelos

Os 180 documentos do eval, com acurácia por campo e por tipo, nas duas versões

Checagem +20 XP de primeiraA distribuidora descobre que consegue o XML de quase todas as NF-e emitidas contra o seu CNPJ. Qual é o melhor uso disso?

Ler o XML em código e reservar o modelo para documentos sem XML

Mandar o XML ao modelo junto com o PDF, para ele extrair com mais contexto

Converter o XML em PDF, para manter um único fluxo para todos os documentos

Checagem +20 XP de primeiraA diretoria pergunta se o sistema cumpre a regra ‘na dúvida, revisão humana’. Qual número responde isso?

A acurácia média de todos os campos em todos os documentos

Quantos documentos entraram sem revisão com algum campo crítico errado

A porcentagem de documentos que passaram sem revisão humana