Téléverser un fichier de facture

POST 
/api/v1/workspaces/:workspace_id/invoices/upload

Téléverse un fichier de facture (XML ou PDF) pour analyse et import automatiques.

Formats pris en charge :

• XML : UBL 2.1 Invoice/CreditNote, UN/CEFACT CII (conforme EN16931)
• PDF : Factur-X / ZUGFeRD (PDF/A-3 avec XML intégré)

Le fichier est traité de façon synchrone et le document de facture créé est retourné.

Passez lifecycle_state pour créer la facture et atteindre l'état de cycle de vie en un seul appel, au lieu d'enchaîner avec PATCH /api/v1/invoices/{id}/transition. La transition suit les mêmes règles que cet endpoint. C'est tout ou rien : une transition refusée retourne 422 et ne laisse aucune facture derrière elle. Un fichier qui nécessite une extraction assistée (un PDF sans XML intégré) ne peut pas porter lifecycle_state et est rejeté avec 422 - téléversez-le seul, puis effectuez la transition une fois le traitement terminé.

Request

Responses

201

La facture créée par l'analyse et l'import du contenu UBL, CII ou Factur-X du fichier téléversé.

202

Le fichier ne porte aucune facture structurée à analyser - un PDF sans XML intégré, ou une image - et a été accepté pour une extraction assistée par IA, en tâche de fond. Aucune facture n'existe encore : le corps est un accusé de prise en charge et ne partage aucun champ avec celui du 201, aiguillez sur le code de statut, pas sur le corps. La facture est créée plus tard, si l'extraction aboutit, et c'est le webhook invoice.created qui l'annonce - upload_file_id identifie le traitement mais aucun endpoint n'en rend compte. Seul un espace de travail dont l'offre souscrite autorise le dépôt non structuré atteint ce chemin ; sur les autres, le même fichier est refusé avec 422. lifecycle_state ne peut pas accompagner un tel fichier, puisqu'il n'y aurait rien à faire transitionner.

401

La requête ne comporte aucun jeton d'accès (bearer token) OAuth, ou celui-ci est invalide ou expiré.

403

L'application OAuth du jeton n'a aucune relation d'accès avec le tenant de l'espace de travail demandé, ou un tel espace de travail n'existe pas.

422

Le fichier téléversé n'a pas pu être analysé ou importé. Le corps d'erreur indique error: "unprocessable_entity" décrivant l'échec. Lorsque le téléversement demandait lifecycle_state: "deposited" et que le contrôle Schematron l'a refusé, code nomme laquelle des trois causes l'a fait : schematron_fatal (assertion fatale - details porte alors la carte indexée par champ à la place de sa clé file habituelle ; corrigez ces champs puis réessayez), schematron_engine_unavailable (le moteur devait un verdict et n'a pas pu le produire - transitoire, réessayez, la facture n'est pas en cause) ou schematron_profile_unsupported (la réforme n'admet aucun jeu de règles pour ce profil - déterministe, envoyez-en un autre). Un lifecycle_state: "deposited" demandé emprunte le même contrôle de dépôt que PATCH /invoices/{id}/transition, si bien que ses refus remontent ici aussi - parmi eux une partie qui ne déclare aucun pays, avec details sous la clé seller.address.country_code ou buyer.address.country_code. Seule l'obligation flux 1 porte cette règle de présence ; une vente dont l'acheteur doit une déclaration e-reporting (flux 10) n'est pas refusée pour cela. Le refus est tout-ou-rien : aucune facture n'est enregistrée.