Let’s Build : analyseur de factures IA avec Transloadit
Transformez une facture PDF en fichier JSON local contenant le fournisseur, le numéro de facture, la devise et les montants. Cet exemple téléverse votre document vers Transloadit et un fournisseur d’IA, valide les types des champs renvoyés et enregistre le résultat pour que vous puissiez le comparer à la facture d’origine.
Ce que nous allons créer
Le script d’exemple accepte un fichier PDF ou DOCX non vide de 20 MiB maximum. Les PDF passent directement au 🤖 /ai/chat ; les fichiers DOCX passent d’abord par le 🤖 /document/convert pour être convertis en PDF. Cet exemple rejette les autres extensions de fichiers d’entrée.
Ce tutoriel porte sur une extraction avec enregistrement local. Une Assembly terminée et un JSON conforme au schéma ne prouvent pas qu’un montant a été lu correctement. Vérifiez le résultat avant de l’utiliser pour la comptabilité ou les paiements ; le schéma ne renvoie pas de scores de confiance.
Le schéma d’abord (zod)
Le programme téléchargeable exporte son schéma Zod. Après avoir respecté l’organisation des fichiers à télécharger ci-dessous, vous pouvez l’importer dans votre propre code TypeScript au lieu de maintenir une seconde liste de champs :
import { zodToJsonSchema } from 'zod-to-json-schema'
import { invoiceSchema } from './invoice-parser/run.ts'
const invoiceJsonSchema = zodToJsonSchema(invoiceSchema)
Les champs comprennent les coordonnées du fournisseur, les dates de facturation et d’échéance, la devise, le sous-total, les taxes, le total, les lignes de facture, les conditions de paiement et un bon de commande. Ils sont facultatifs pour permettre au modèle d’omettre les valeurs inconnues. Le programme rejette le JSON mal formé, les types de champs invalides et les objets sans aucun champ reconnu. Un total plausible mais incorrect peut tout de même passer ces vérifications.
Vue d’ensemble du pipeline
PDF → /ai/chat → JSON download → local validation → result.json
DOCX → /document/convert (PDF) → /ai/chat → JSON download → local validation → result.json
Le programme sélectionne explicitement anthropic/claude-sonnet-4-6, un modèle capable de traiter
les PDF et pris en charge par /ai/chat. Il télécharge la réponse depuis l’URL du
résultat et enregistre les données validées localement, afin que vous puissiez examiner le fichier
après l’expiration de cette URL temporaire.
Extrait de configuration d’Assembly
La recette exportée fournit l’intégralité des Assembly Instructions. Cet extrait construit les instructions sans envoyer de requête :
import { example } from './invoice-parser/run.ts'
const instructions = {
steps: example.steps({ test_credentials: true }),
}
Le Step d’extraction utilise format: 'json', un JSON Schema sérialisé et
result: true. La CLI gère le téléversement, la vérification de fin de traitement,
le téléchargement du résultat et la validation locale. La sélection de
test_credentials: true utilise les informations d’accès à l’IA fournies par Transloadit,
dont l’utilisation est facturée ; elle ne rend pas le traitement gratuit.
Essayer l’application d’exemple
Utilisez un répertoire vide en dehors d’un projet Node existant. Installez Node.js et cURL, et
installez Corepack séparément. L’environnement d’exécution testé est
Node.js 26.12.1 ; utilisez une version maintenue de Node 26
lorsque vous adaptez l’exemple. Les instructions d’installation
utilisent Yarn 4.12.0 pour installer @transloadit/node 4.14.0, Zod 3.25.76 et
zod-to-json-schema 3.25.2. Ces versions fixes reproduisent la combinaison du SDK et du
convertisseur de schéma de l’exemple téléchargeable ; elles ne sont pas présentées comme les plus
récentes et n’imposent pas de rétrograder une application existante.
Suivez d’abord les instructions d’installation et de configuration des accès de ce README, en
exécutant ses commandes une à une. Téléchargez les deux fichiers
invoice-parser/run.ts et shared/runtime.ts, en conservant leur organisation
relative. Exécutez la vérification --help documentée avant tout téléversement.
Si l’installation ou un téléchargement échoue, arrêtez-vous et résolvez le problème avant d’exécuter
l’analyseur.
Exportez l’Auth Key et l’Auth Secret de votre Workspace sous les noms
TRANSLOADIT_AUTH_KEY et TRANSLOADIT_AUTH_SECRET dans le même shell. Le script lit
ces variables d’environnement ; il ne charge pas de fichier d’environnement et ne crée pas
d’informations d’accès. Gardez les secrets hors du contrôle de version et du code côté navigateur.
Sans définir TRANSLOADIT_AI_CREDENTIALS, placez une facture que vous êtes autorisé à téléverser
à l’emplacement invoice.pdf. Choisissez une destination qui n’existe pas, puis
exécutez :
node invoice-parser/run.ts --input ./invoice.pdf --output ./result.json --test-credentials
Cette commande autorise explicitement l’utilisation facturée d’informations d’accès de test à l’IA,
ainsi que le traitement par Transloadit. Pour utiliser votre propre clé Anthropic à la place,
configurez un jeu d’informations d’identification pour l’IA dans la Console, exportez son nom existant
sous TRANSLOADIT_AI_CREDENTIALS et omettez --test-credentials. Sélectionnez exactement un
mode d’accès au fournisseur. Consultez les tarifs avant de traiter
un ensemble de factures.
Le programme laisse le fichier d’entrée inchangé et refuse une destination de sortie existante avant de soumettre une Assembly. Utilisez un nouveau nom de fichier pour une autre exécution. Ses limites pour ce tutoriel sont de 20 MiB pour le fichier d’entrée et le résultat téléchargé, de cinq minutes pour le traitement et de 30 secondes pour le téléchargement du résultat. Ce ne sont pas des limites du produit. Si le programme échoue après avoir affiché un identifiant d’Assembly, examinez cette Assembly dans la Console avant de réessayer : un dépassement de délai ou une interruption ne prouve pas que le traitement distant s’est arrêté, et une exécution ayant échoué peut tout de même être facturée. Le programme ne relance pas automatiquement une Assembly.
Exemples de fichiers d’entrée
Commencez par une facture fictive créée pour les tests dont vous pouvez vérifier les champs
indépendamment.
Par exemple, une facture de Sample Workshop Ltd portant le numéro INV-2026-0042,
avec deux réparations de vélo à USD 100 chacune et USD 20 de taxes, devrait produire au moins
ces valeurs :
{
"vendor_name": "Sample Workshop Ltd",
"invoice_number": "INV-2026-0042",
"currency": "USD",
"subtotal": 200,
"tax": 20,
"total": 220
}
Après une exécution réussie, ouvrez result.json dans un éditeur de texte.
Comparez le fournisseur, le numéro de facture, la devise, les lignes de facture et les montants avec
votre fichier d’entrée réel ; des factures différentes devraient produire des données différentes.
Un champ manquant doit être vérifié même si le fichier a été enregistré avec succès. Gardez le résultat
confidentiel lorsqu’il contient des informations professionnelles ou personnelles.
Étapes suivantes
Avant d’enregistrer les résultats dans votre base de données, déterminez les champs requis par votre application et soumettez les valeurs manquantes ou incohérentes à une vérification humaine. Gardez la conversion des devises distincte de l’extraction : la devise et les montants renvoyés décrivent la facture d’origine, et non des écritures comptables normalisées.