Let's Build: analisador de faturas com IA e Transloadit
Transforme uma fatura em PDF em um arquivo JSON local com fornecedor, número da fatura, moeda e valores. Este exemplo faz upload do seu documento para a Transloadit e um provedor de IA, valida os tipos dos campos retornados e salva o resultado para você comparar com a fatura original.
O que vamos criar
O script de exemplo aceita um arquivo PDF ou DOCX não vazio de até 20 MiB. Os PDFs vão diretamente para 🤖 /ai/chat; os arquivos DOCX primeiro passam pelo 🤖 /document/convert para serem convertidos em PDFs. Este exemplo rejeita outras extensões de entrada.
Este é um tutorial de extração com execução local. Uma Assembly concluída e um JSON válido conforme o esquema não comprovam que um valor foi lido corretamente. Revise a saída antes de usá-la na contabilidade ou em pagamentos; o esquema não retorna pontuações de confiança.
Primeiro, o esquema (zod)
O programa disponível para download exporta seu esquema Zod. Depois de seguir a organização de arquivos para download abaixo, você pode importá-lo no seu código TypeScript em vez de manter uma segunda lista de campos:
import { zodToJsonSchema } from 'zod-to-json-schema'
import { invoiceSchema } from './invoice-parser/run.ts'
const invoiceJsonSchema = zodToJsonSchema(invoiceSchema)
Os campos incluem dados do fornecedor, datas de emissão e vencimento da fatura, moeda, subtotal, imposto, total, itens da fatura, condições de pagamento e um pedido de compra. Eles são opcionais para que o modelo possa omitir valores desconhecidos. O executor rejeita JSON malformado, tipos de campo inválidos e objetos sem campos reconhecidos. Um total plausível, mas incorreto, ainda pode passar por essas verificações.
Visão geral do fluxo de processamento
PDF → /ai/chat → JSON download → local validation → result.json
DOCX → /document/convert (PDF) → /ai/chat → JSON download → local validation → result.json
O programa seleciona explicitamente anthropic/claude-sonnet-4-6, um modelo que aceita PDFs e é
compatível com /ai/chat. Ele baixa a resposta da URL do resultado e salva os
dados validados localmente, para que você possa inspecionar o arquivo depois que essa URL temporária
expirar.
Trecho da Assembly
A receita exportada fornece as Assembly Instructions completas. Este trecho cria as instruções sem enviar uma solicitação:
import { example } from './invoice-parser/run.ts'
const instructions = {
steps: example.steps({ test_credentials: true }),
}
O Step de extração usa format: 'json', um JSON Schema serializado e
result: true. A CLI cuida do upload, da verificação de conclusão, do download do
resultado e da validação local. Selecionar test_credentials: true usa credenciais de IA
fornecidas pela Transloadit com cobrança; isso não torna o processamento gratuito.
Teste o aplicativo de exemplo
Use um diretório vazio fora de um projeto Node existente. Instale o Node.js e o cURL e instale o
Corepack separadamente. O ambiente de execução testado é o
Node.js 26.12.1; use uma versão do Node 26 que ainda receba manutenção
ao adaptar o exemplo. As instruções de configuração usam o
Yarn 4.12.0 para instalar @transloadit/node 4.14.0, Zod 3.25.76 e
zod-to-json-schema 3.25.2. Essas versões fixas reproduzem a combinação de SDK e conversor
de esquemas do exemplo disponível para download; não indicam as versões mais recentes nem exigem
que você use versões anteriores em um aplicativo existente.
Primeiro, siga as instruções de instalação e configuração de acesso desse README, executando seus
comandos um de cada vez. Baixe ambos os arquivos, invoice-parser/run.ts e
shared/runtime.ts, mantendo sua organização relativa. Execute a verificação
--help documentada antes de fazer qualquer upload. Se a instalação ou um
download falhar, pare e resolva o problema antes de executar o analisador.
Exporte a Auth Key e o Auth Secret do seu Workspace como TRANSLOADIT_AUTH_KEY e
TRANSLOADIT_AUTH_SECRET no mesmo shell. O script lê essas variáveis de ambiente; ele não
carrega um arquivo de ambiente nem cria credenciais. Mantenha os segredos fora do controle de versão
e do código do navegador.
Com TRANSLOADIT_AI_CREDENTIALS não definida, escolha uma fatura que você tenha permissão para
enviar ao serviço por upload e salve o arquivo local como invoice.pdf.
Escolha um destino que não exista e execute:
node invoice-parser/run.ts --input ./invoice.pdf --output ./result.json --test-credentials
Este comando autoriza explicitamente o uso de credenciais de teste de IA com cobrança, além do
processamento da Transloadit. Para usar sua própria chave da Anthropic, configure uma credencial de
IA no Console, exporte o nome já existente dela como TRANSLOADIT_AI_CREDENTIALS e omita
--test-credentials. Selecione exatamente um modo de credenciais do provedor. Confira os
preços antes de processar uma coleção de faturas.
O executor mantém a entrada inalterada e rejeita um destino de saída já existente antes de enviar uma Assembly. Use um novo nome de arquivo para outra execução. Os limites deste tutorial são 20 MiB para a entrada e a saída baixada, cinco minutos para o processamento e 30 segundos para o download do resultado. Esses não são limites do produto. Se houver uma falha após a exibição de um Assembly ID, inspecione essa Assembly no Console antes de tentar novamente: um tempo limite excedido ou uma interrupção não comprova que o processamento remoto parou, e uma execução que falhou ainda pode ser cobrada. O executor não tenta executar novamente uma Assembly de forma automática.
Exemplos de entrada
Comece com uma fatura sintética cujos campos você possa verificar de forma independente. Por
exemplo, uma fatura da Sample Workshop Ltd com o número INV-2026-0042, contendo
dois consertos de bicicleta a USD 100 cada e USD 20 de imposto, deve gerar pelo menos estes valores:
{
"vendor_name": "Sample Workshop Ltd",
"invoice_number": "INV-2026-0042",
"currency": "USD",
"subtotal": 200,
"tax": 20,
"total": 220
}
Após uma execução bem-sucedida, abra result.json em um editor de texto. Compare
fornecedor, número da fatura, moeda, itens da fatura e valores com a entrada que você usou; faturas
diferentes devem produzir dados diferentes. Um campo ausente precisa de revisão mesmo quando o
arquivo foi salvo com sucesso. Mantenha o resultado privado quando ele contiver informações
comerciais ou pessoais.
Próximos passos
Antes de armazenar os resultados no seu banco de dados, decida quais campos seu aplicativo exige e encaminhe valores ausentes ou divergentes para revisão humana. Mantenha a conversão de moedas separada da extração: a moeda e os valores retornados descrevem a fatura original, não lançamentos contábeis normalizados.