Let's Build: scanner de cartões de visita com IA e Transloadit
Transforme uma imagem ou um PDF de um cartão de visita em um arquivo JSON local com dados de contato. Este exemplo em TypeScript faz upload de um cartão para a Transloadit, pede a um modelo de IA que extraia os campos visíveis e salva o resultado para você comparar com o original antes de adicionar um contato ao seu CRM.
O que vamos criar
- Aceitar uma imagem PNG/JPEG de um cartão ou um PDF.
- Otimizar imagens com 🤖 /image/optimize, enquanto os PDFs seguem diretamente para o Step de extração.
- Extrair campos de contato com 🤖 /ai/chat e baixar o resultado JSON.
Este é um exemplo local de linha de comando, não um aplicativo de câmera. Você precisa de uma Auth Key e de um Auth Secret de um Workspace da Transloadit, escolher explicitamente uma credencial de IA e ter permissão para enviar o cartão à Transloadit e à Anthropic. O processamento é cobrado, inclusive na opção de credenciais de teste de IA. Comece com um cartão sintético sem dados pessoais de ninguém.
Primeiro, o esquema (zod)
O script de exemplo exporta businessCardSchema para
você reutilizar o mesmo contrato em vez de manter uma segunda lista de campos. Os campos opcionais são
full_name, title, company,
email, phones, address,
website, socials e notes.
Os números de telefone continuam sendo strings para preservar um +
inicial. Campos desconhecidos devem ser omitidos.
Após a configuração abaixo, salve este conteúdo como schema.ts no diretório do
projeto e execute node schema.ts para inspecionar o esquema enviado ao modelo:
import { zodToJsonSchema } from 'zod-to-json-schema'
import { businessCardSchema } from './business-card-scanner/run.ts'
console.log(JSON.stringify(zodToJsonSchema(businessCardSchema), null, 2))
Um esquema verifica os tipos dos campos; ele não pode determinar se um nome ou e-mail foi lido corretamente. O executor rejeita JSON malformado, saídas inválidas segundo o esquema e objetos sem campos reconhecidos. Um resultado não vazio e válido segundo o esquema ainda precisa ser comparado com o cartão.
Visão geral do fluxo de processamento
| Entrada | Caminho de processamento |
|---|---|
| Cartão em PDF | /ai/chat |
| Cartão em PNG/JPEG | /image/optimize → /ai/chat |
Os filtros de arquivo encaminham PDFs separadamente das imagens. Apesar do nome
pdf_verified, o filtro de PDF apenas seleciona o tipo MIME informado; ele não
comprova que um documento está íntegro ou legível.
Trecho da Assembly
A receita exportada pelo aplicativo fornece os filtros, o prompt, o esquema e o modelo
anthropic/claude-sonnet-4-6. Para inspecionar suas
Assembly Instructions, salve este conteúdo como
instructions.ts ao lado de schema.ts e execute
node instructions.ts:
import { example } from './business-card-scanner/run.ts'
const steps = example.steps({ test_credentials: true })
console.log(JSON.stringify({ steps }, null, 2))
Isso apenas exibe a receita. A CLI abaixo a envia, aguarda a conclusão, baixa o resultado, valida-o e salva os campos de contato localmente. O arquivo local é o que você mantém; a URL do resultado do processamento é temporária.
Experimente o aplicativo de exemplo
Use Node.js 26.12.1, o
Corepack instalado separadamente, cURL e um novo diretório vazio fora
de um projeto existente. Siga as instruções de configuração para
instalar Yarn 4.12.0, @transloadit/node 4.14.0, Zod 3.25.76 e
zod-to-json-schema 3.25.2, e baixar tanto business-card-scanner/run.ts quanto
shared/runtime.ts. Mantenha essa estrutura de diretórios: o aplicativo importa o código
de execução compartilhado. Não é necessário fazer checkout de um repositório privado.
Essas versões foram testadas. O exemplo mantém o Zod 3 e seu conversor;
zod-to-json-schema está descontinuado, e o Zod 4
tem suporte nativo a JSON Schema. Atualizar esse contrato é uma alteração separada no aplicativo.
No shell em que você executará o programa, substitua estes valores de exemplo pelos do seu Workspace:
export TRANSLOADIT_AUTH_KEY='YOUR_AUTH_KEY'
export TRANSLOADIT_AUTH_SECRET='YOUR_AUTH_SECRET'
Mantenha os segredos fora do controle de versão e do código do navegador. O programa lê o ambiente do processo; ele não carrega um arquivo de ambiente nem cria credenciais.
Coloque seu cartão em card.png no diretório do projeto ou substitua o caminho
de entrada. Escolha um destino de saída que não exista e, em seguida, autorize explicitamente o uso
de credenciais de teste de IA com cobrança:
node business-card-scanner/run.ts --input ./card.png --output ./result.json --test-credentials
Como alternativa, defina TRANSLOADIT_AI_CREDENTIALS com o nome de uma credencial de IA da
Anthropic existente e omita --test-credentials. Selecione exatamente um modo. Consulte as
instruções de configuração para configurar sua própria credencial do provedor antes de executar o
aplicativo.
Se a execução for bem-sucedida, abra result.json e compare o nome, o e-mail e os
números de telefone extraídos com o cartão. Campos opcionais podem estar ausentes. O aplicativo
mantém a entrada inalterada e recusa um destino de saída existente antes de enviar o trabalho,
portanto, use um novo destino para outra execução. Ele limita a entrada e a saída baixada a 20 MiB,
aguarda até cinco minutos pelo processamento e dá ao download do resultado um prazo separado de
30 segundos. Esses são limites do exemplo, não do produto.
Se uma execução falhar após exibir 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 o trabalho ainda pode ser cobrado. O script não tenta executar uma Assembly novamente de forma automática.
Exemplos de entrada
Use um cartão sintético legível com nome, empresa, e-mail e número de telefone que você possa conferir. Processe um único cartão por arquivo; para um PDF, comece com uma página. Para testar o caminho de processamento de PDF, passe o nome do arquivo ao mesmo comando e escolha um segundo arquivo JSON de saída. Uma extração bem-sucedida de uma imagem não comprova que um PDF específico seja legível, e a otimização de imagens não garante um reconhecimento melhor.
Próximos passos
Revise cada extração antes de inserir contatos no seu CRM. O esquema não retorna pontuações de confiança, portanto, não pode selecionar contatos com “baixa confiança” para você. Após a revisão, normalize números de telefone e endereços de acordo com a localidade e remova contatos duplicados usando as regras do seu CRM.