Let's Build: analizador de facturas con IA y Transloadit
Convierte una factura PDF en un archivo JSON local con su proveedor, número de factura, moneda e importes. Este ejemplo sube tu documento a Transloadit y a un proveedor de IA, valida los tipos de los campos devueltos y guarda el resultado para que lo cotejes con la factura original.
Qué vamos a crear
El script de ejemplo acepta un archivo PDF o DOCX no vacío de hasta 20 MiB. Los PDF pasan directamente al 🤖 /ai/chat; los archivos DOCX pasan primero por el 🤖 /document/convert para convertirse en PDF. Este ejemplo rechaza otras extensiones de entrada.
Este tutorial trata sobre la extracción con resultados locales. Una Assembly completada y un JSON válido según el esquema no demuestran que un importe se haya leído correctamente. Revisa el resultado antes de usarlo para contabilidad o pagos; el esquema no devuelve puntuaciones de confianza.
Primero, el esquema (zod)
El programa descargable exporta su esquema de Zod. Tras seguir la estructura de descarga que se indica más abajo, puedes importarlo en tu propio código TypeScript en lugar de mantener una segunda lista de campos:
import { zodToJsonSchema } from 'zod-to-json-schema'
import { invoiceSchema } from './invoice-parser/run.ts'
const invoiceJsonSchema = zodToJsonSchema(invoiceSchema)
Los campos incluyen los datos del proveedor, las fechas de emisión y vencimiento de la factura, la moneda, el subtotal, los impuestos, el total, las partidas, las condiciones de pago y una orden de compra. Son opcionales para que el modelo pueda omitir los valores desconocidos. El programa rechaza el JSON mal formado, los tipos de campo no válidos y los objetos sin campos reconocidos. Un total plausible pero incorrecto puede superar esas comprobaciones.
Descripción general del pipeline
PDF → /ai/chat → JSON download → local validation → result.json
DOCX → /document/convert (PDF) → /ai/chat → JSON download → local validation → result.json
El programa selecciona explícitamente anthropic/claude-sonnet-4-6, un modelo que admite PDF y es
compatible con /ai/chat. Descarga la respuesta desde la URL del resultado y
guarda los datos validados localmente, para que puedas examinar el archivo después de que caduque
esa URL temporal.
Fragmento de Assembly
La receta exportada proporciona las Assembly Instructions completas. Este fragmento genera las instrucciones sin enviar una solicitud:
import { example } from './invoice-parser/run.ts'
const instructions = {
steps: example.steps({ test_credentials: true }),
}
El Step de extracción usa format: 'json', un JSON Schema serializado y
result: true. La CLI gestiona la subida, la comprobación de finalización, la
descarga del resultado y la validación local. Seleccionar test_credentials: true usa
credenciales de IA proporcionadas por Transloadit cuyo uso se factura; no hace que el
procesamiento sea gratuito.
Prueba la aplicación de ejemplo
Usa un directorio vacío fuera de un proyecto Node existente. Instala Node.js y cURL, e instala
Corepack por separado. El entorno de ejecución probado es
Node.js 26.12.1; usa una versión de Node 26 que siga recibiendo
mantenimiento al adaptar el ejemplo. Las instrucciones de configuración
usan Yarn 4.12.0 para instalar @transloadit/node 4.14.0, Zod 3.25.76 y
zod-to-json-schema 3.25.2. Estas versiones fijadas reproducen la combinación del SDK y el
convertidor de esquemas del ejemplo descargable; no se presentan como las versiones más recientes
ni exigen que instales versiones anteriores en una aplicación existente.
Sigue primero las instrucciones de instalación y configuración de acceso de ese README, ejecutando
sus comandos de uno en uno. Descarga ambos archivos, invoice-parser/run.ts y
shared/runtime.ts, manteniendo su estructura relativa. Ejecuta la comprobación
--help documentada antes de subir cualquier archivo. Si la instalación o
una descarga fallan, detente y resuelve el problema antes de ejecutar el analizador.
Exporta tu Auth Key y tu Auth Secret del Workspace como TRANSLOADIT_AUTH_KEY y
TRANSLOADIT_AUTH_SECRET en la misma sesión de shell. El script lee esas variables de entorno;
no carga un archivo de entorno ni crea credenciales. Mantén los secretos fuera del control de
versiones y del código del navegador.
Con TRANSLOADIT_AI_CREDENTIALS sin definir, coloca una factura que tengas permiso para subir en
invoice.pdf. Elige un destino que no exista y ejecuta:
node invoice-parser/run.ts --input ./invoice.pdf --output ./result.json --test-credentials
Este comando autoriza explícitamente el uso facturado de credenciales de prueba de IA, además del
procesamiento de Transloadit. Para usar tu propia clave de Anthropic, configura una credencial de IA
en la Console, exporta su nombre existente como TRANSLOADIT_AI_CREDENTIALS y omite
--test-credentials. Selecciona exactamente un modo de credencial del proveedor. Consulta
los precios antes de procesar un conjunto de facturas.
El programa mantiene intacto el archivo de entrada y rechaza un destino de salida existente antes de enviar una Assembly. Usa un nombre de archivo nuevo para otra ejecución. Los límites de este tutorial son 20 MiB para la entrada y la salida descargada, cinco minutos para el procesamiento y 30 segundos para la descarga del resultado. Estos no son límites del producto. Si el programa falla tras mostrar un ID de la Assembly, examina esa Assembly en la Console antes de volver a intentarlo: un tiempo de espera agotado o una interrupción no demuestran que el procesamiento remoto se haya detenido, y una ejecución fallida puede facturarse de todos modos. El programa no vuelve a intentar una Assembly automáticamente.
Ejemplos de entrada
Empieza con una factura sintética cuyos campos puedas comprobar de forma independiente. Por ejemplo,
una factura de Sample Workshop Ltd con el número INV-2026-0042, con dos
reparaciones de bicicletas de USD 100 cada una y USD 20 de impuestos, debería generar al menos estos
valores:
{
"vendor_name": "Sample Workshop Ltd",
"invoice_number": "INV-2026-0042",
"currency": "USD",
"subtotal": 200,
"tax": 20,
"total": 220
}
Tras una ejecución correcta, abre result.json en un editor de texto. Compara su
proveedor, número de factura, moneda, partidas e importes con tu archivo de entrada real; las
facturas diferentes deberían producir datos diferentes. Un campo ausente requiere revisión aunque
el archivo se haya guardado correctamente. Mantén el resultado privado cuando contenga información
empresarial o personal.
Próximos pasos
Antes de guardar los resultados en tu base de datos, decide qué campos necesita tu aplicación y remite los valores ausentes o que no coincidan a una revisión humana. Mantén la conversión de moneda separada de la extracción: la moneda y los importes devueltos describen la factura original, no asientos contables normalizados.