Let's Build: escáner de tarjetas de visita con IA y Transloadit
Convierte una imagen o un PDF de una tarjeta de visita en un archivo JSON local con datos de contacto. Este ejemplo en TypeScript sube una tarjeta a Transloadit, solicita a un modelo de IA que extraiga los campos visibles y guarda el resultado para que lo compares con el original antes de añadir un contacto a tu CRM.
Qué vamos a crear
- Aceptar una imagen PNG/JPEG de una tarjeta o un PDF.
- Optimizar imágenes con 🤖 /image/optimize, mientras que los PDF pasan directamente al Step de extracción.
- Extraer campos de contacto con 🤖 /ai/chat y descargar el resultado JSON.
Este es un ejemplo local de línea de comandos, no una aplicación de cámara. Necesitas una Auth Key y un Auth Secret de un Workspace de Transloadit, elegir explícitamente una credencial de IA y tener permiso para enviar la tarjeta a Transloadit y Anthropic. El procesamiento se factura, incluida la opción de credenciales de prueba de IA. Empieza con una tarjeta sintética sin datos personales de nadie.
Primero, el esquema (zod)
El script de ejemplo exporta businessCardSchema para que
puedas reutilizar el mismo contrato en lugar de mantener una segunda lista de campos. Sus campos
opcionales son full_name, title,
company, email, phones,
address, website, socials
y notes.
Los números de teléfono se mantienen como cadenas para conservar un +
inicial. Los campos desconocidos deberían omitirse.
Después de completar la configuración que se indica a continuación, guarda esto como
schema.ts en el directorio de tu proyecto y ejecuta node schema.ts
para inspeccionar el esquema que se envía al modelo:
import { zodToJsonSchema } from 'zod-to-json-schema'
import { businessCardSchema } from './business-card-scanner/run.ts'
console.log(JSON.stringify(zodToJsonSchema(businessCardSchema), null, 2))
Un esquema comprueba los tipos de los campos; no puede determinar si un nombre o email se leyó correctamente. El programa rechaza el JSON mal formado, los resultados que no cumplen el esquema y un objeto sin campos reconocidos. Un resultado no vacío que cumple el esquema también debe revisarse comparándolo con la tarjeta.
Vista general del pipeline
| Entrada | Ruta de procesamiento |
|---|---|
| Tarjeta en PDF | /ai/chat |
| Tarjeta en PNG/JPEG | /image/optimize → /ai/chat |
Los filtros de archivos dirigen los PDF por una ruta distinta de la de las imágenes. A pesar de su
nombre pdf_verified, el filtro de PDF solo selecciona el tipo MIME declarado;
no demuestra que un documento esté intacto o sea legible.
Fragmento de Assembly
La receta exportada por la aplicación proporciona los filtros, el prompt, el esquema y el modelo
anthropic/claude-sonnet-4-6. Para inspeccionar sus
Assembly Instructions, guarda esto como
instructions.ts junto a schema.ts y ejecuta 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))
Esto solo muestra la receta. La CLI que aparece a continuación la envía, espera a que finalice el procesamiento, descarga el resultado, lo valida y guarda los campos de contacto localmente. El archivo local es lo que conservas; la URL del resultado del procesamiento es temporal.
Prueba la aplicación de ejemplo
Usa Node.js 26.12.1,
Corepack instalado por separado, cURL y un directorio nuevo y vacío
fuera de un proyecto existente. Sigue las instrucciones de configuración
para instalar Yarn 4.12.0, @transloadit/node 4.14.0, Zod 3.25.76 y
zod-to-json-schema 3.25.2, y descarga tanto business-card-scanner/run.ts como
shared/runtime.ts. Mantén esa estructura de directorios: la aplicación importa el entorno
de ejecución compartido. No necesitas una copia de trabajo de un repositorio privado.
Estas son las versiones probadas. El ejemplo conserva Zod 3 y su conversor;
zod-to-json-schema está deprecado, y Zod 4
ofrece soporte nativo para JSON Schema. Actualizar ese contrato es un cambio independiente en la
aplicación.
En la terminal donde ejecutarás el programa, sustituye estos valores de ejemplo por los de tu Workspace:
export TRANSLOADIT_AUTH_KEY='YOUR_AUTH_KEY'
export TRANSLOADIT_AUTH_SECRET='YOUR_AUTH_SECRET'
Mantén los secretos fuera del control de versiones y del código del navegador. El programa lee el entorno del proceso; no carga un archivo de entorno ni crea credenciales.
Coloca tu tarjeta en card.png dentro del directorio del proyecto, o sustituye la
ruta de entrada. Elige un archivo de salida que no exista y autoriza explícitamente el uso de
credenciales de prueba de IA cuyo procesamiento se factura:
node business-card-scanner/run.ts --input ./card.png --output ./result.json --test-credentials
Como alternativa, establece TRANSLOADIT_AI_CREDENTIALS con el nombre de una credencial de IA de
Anthropic existente y omite --test-credentials. Selecciona exactamente un modo. Consulta las
instrucciones de configuración para configurar tu propia credencial del proveedor antes de ejecutar
la aplicación.
Si la ejecución se completa correctamente, abre result.json y compara el nombre,
el email y los números de teléfono extraídos con los de la tarjeta. Se permite que falten campos
opcionales. La aplicación deja la entrada sin cambios y rechaza una salida existente antes de enviar
el trabajo, así que usa un destino nuevo para otra ejecución. Limita la entrada y la salida descargada
a 20 MiB, espera hasta cinco minutos para el procesamiento y establece un plazo independiente de
30 segundos para descargar el resultado. Estos son límites del ejemplo, no del producto.
Si una ejecución falla después de mostrar el ID de una Assembly, inspecciona esa Assembly en la Console antes de volver a intentarlo. Un tiempo de espera agotado o una interrupción no demuestra que el procesamiento remoto se haya detenido, y el trabajo aún puede facturarse. El script no vuelve a intentar una Assembly automáticamente.
Entradas de ejemplo
Usa una tarjeta sintética legible con un nombre, una empresa, un email y un número de teléfono que puedas verificar. Procesa una sola tarjeta por archivo; si usas un PDF, empieza con una página. Para probar la ruta de PDF, pasa su nombre de archivo al mismo comando y elige un segundo archivo JSON de salida. Una extracción de imagen correcta no demuestra que un PDF específico sea legible, y la optimización de imágenes no garantiza un mejor reconocimiento.
Próximos pasos
Revisa cada extracción antes de insertar contactos en tu CRM. El esquema no devuelve puntuaciones de confianza, por lo que no puede seleccionar por ti contactos «con baja confianza». Después de la revisión, normaliza los números de teléfono y las direcciones según la configuración regional y elimina los contactos duplicados siguiendo las reglas de tu CRM.