Formats et téléchargements

Votre produit doit conserver et présenter chaque facture dans sa forme réglementaire : un PDF lisible pour vos écrans, un Factur-X, un UBL ou un CII pour l'archivage et l'échange avec d'autres systèmes. Chaque facture Scribee, émise ou reçue, se télécharge dans ces quatre formats depuis un seul endpoint, GET /api/v1/invoices/{id}/download. L'appel ne transmet rien vers l'extérieur et se rejoue autant de fois que nécessaire sur votre compte de production, y compris sur un brouillon. Ce n'est pas une lecture pure pour autant : un format encore dépourvu d'exemplaire attaché est généré pendant la requête, et cette génération peut écrire sur la facture (voir plus bas).

Ce que Scribee fait pour vous

• Conversion de formats : les quatre représentations sont produites depuis les mêmes données de facture. Vous n'écrivez ni XML ni PDF ; vous choisissez un format à l'appel. Une exception, décrite plus bas : quand la facture a été déposée sous forme de Factur-X, le format facturx ne convertit rien - il restitue le fichier déposé.
• Conformité PDF/A-3 : le format facturx vise le PDF/A-3 avec le XML CII embarqué, mais la conformité est un état constaté, pas une garantie. Quand la facture porte un PDF fourni à la création (provided_pdf à true), sa conformité est vérifiée après génération et exposée dans le champ facturx_conformance (pending, compliant, non_compliant). Un résultat non_compliant n'interrompt pas la génération : le fichier reste téléchargeable tel quel. Il bloque en revanche le dépôt de la facture, en plus de sa transmission réglementaire - une facture à PDF fourni non conforme ne passe pas deposit. Lisez facturx_conformance avant de traiter un facturx comme un PDF/A-3. Sans PDF fourni, ce champ reste nul, le rendu Scribee étant conforme par construction. Seule exception, une facture de vente importée sous forme de Factur-X : son fichier est jugé à son dépôt, et le champ porte ce verdict (Importer des factures existantes).
• Génération anticipée : les fichiers sont générés en tâche de fond dès la création de la facture et régénérés à chaque modification. Si un fichier n'est pas encore prêt au moment de l'appel, il est généré à la volée dans la même requête : le téléchargement n'échoue pas parce que la génération est en cours.
• Une création incomplète n'attache pas votre PDF : si la charge utile omet invoice_number, issue_date, type_code ou currency_code, la facture est tout de même créée (réponse 201, valeurs de remplacement inscrites) mais le PDF que vous avez fourni n'est pas attaché et aucune génération n'est déclenchée. Vérifiez provided_pdf dans la réponse de création plutôt que de supposer que le fichier est arrivé.
• Votre PDF conservé jusqu'à la première modification : quand provided_pdf est true, le format pdf restitue le fichier fourni à la création de la facture, pas un rendu Scribee. Deux limites à connaître avant de vous appuyer dessus, détaillées plus bas : le fichier n'est conservé que si la création n'a produit aucune erreur bloquante, et un PATCH sur la facture le fait remplacer par un rendu Scribee dès que la régénération aboutit.

Les quatre formats

Le paramètre format accepte quatre valeurs ; sans paramètre, l'endpoint renvoie le pdf.

format	Contenu	Content-Type	Nom de fichier
pdf (défaut)	PDF, la rendition lisible de la facture, suivie de ses pièces jointes - ou le porteur déposé tel quel pour un Factur-X déposé	application/pdf	INV-2026-042.pdf
ubl	UBL XML (OASIS UBL 2.1, EN16931)	application/xml	INV-2026-042-ubl.xml
cii	CII XML (UN/CEFACT Cross Industry Invoice, EN16931)	application/xml	INV-2026-042-cii.xml
facturx	Factur-X : PDF/A-3 avec le XML CII embarqué (EN16931)	application/pdf	INV-2026-042-facturx.pdf

Le nom de fichier est construit depuis le invoice_number de la facture et porté par l'en-tête Content-Disposition. Côté Factur-X, les niveaux de conformité reconnus sont Factur-X Minimum, Factur-X Basic WL, Factur-X Basic, EN16931 et Factur-X Extended ; le niveau inscrit dans le fichier produit est dérivé du profil du XML embarqué.

Le format pdf d'une facture rendue par Scribee ne contient pas que la facture : les pièces justificatives marquées comme jointes à la facture (formats PDF uniquement) y sont concaténées après les pages de la facture, suivies des conditions générales de vente de l'entreprise quand elle en a. Le nombre de pages n'est donc pas déductible des seules données de la facture. Cette composition ne s'applique pas à une facture portant provided_pdf à true, ni à une facture déposée en Factur-X : le téléchargement sert alors le fichier tel quel, sans rien y ajouter.

Un Factur-X déposé vous est restitué tel quel

Quand la facture est entrée chez Scribee sous forme de Factur-X - un PDF/A-3 porteur d'un CII, ce que source_format signale par la valeur facturx (Importer des factures existantes) -, les formats facturx et pdf vous rendent les octets déposés, à l'identique. Scribee ne recompose pas le fichier : il relit le porteur archivé à l'import et le sert inchangé, et le XML CII publié pour ce document est celui réellement embarqué dans ces octets.

Ce que vous pouvez en attendre concrètement : l'empreinte sha256 du fichier téléchargé est celle du fichier déposé. La norme AFNOR XP Z12-013 distingue en §5.4.1 le docType Original, la facture telle que reçue, du docType Converted, une version convertie, et recommande en §5.2.3 que la plateforme calcule l'empreinte sha256 du fichier déposé et réponde en 4XX quand la comparaison diffère. Une régénération, si fidèle soit-elle aux données, produit un autre fichier et donc une autre empreinte : elle ne peut pas satisfaire cette comparaison. La restitution vous permet de la mener de bout en bout, et conserve la couche visuelle et le sceau apposés par l'émetteur.

La portée est étroite, et elle tient au porteur :

• facturx d'une facture déposée en Factur-X : les octets déposés, restitués.
• facturx de toute autre facture : génération, comme auparavant. Un CII ou un UBL déposé en XML nu n'a pas de porteur PDF à rendre ; source_format vaut alors cii ou ubl, et le Factur-X est produit depuis les données.
• ubl et cii : toujours générés depuis les données de la facture, y compris pour un Factur-X déposé.
• pdf d'une facture déposée en Factur-X : les octets déposés, restitués eux aussi. Un Factur-X est un PDF/A-3 : sa couche visuelle est une vue lisible, celle de l'émetteur. Scribee n'en fabrique pas une seconde par-dessus.
• pdf de toute autre facture : une rendition lisible produite par Scribee, comme auparavant.

La restitution s'applique encore après une modification de la facture. Ce que vous avez déposé ne change pas parce que les données extraites ont été corrigées : ce sont les formats ubl et cii qui portent les données à jour.

Une condition la suspend : le fichier d'origine doit avoir été conservé à l'import, ce qui n'est pas le cas au-delà de 50 Mo (Importer des factures existantes). Sans porteur archivé, le format facturx est produit depuis les données, comme pour n'importe quelle autre facture.

Si le porteur a bien été conservé mais se révèle illisible dans le stockage au moment de l'export, le téléchargement échoue en 422 (voir plus bas) au lieu de vous rendre un PDF régénéré à sa place. Scribee ne substitue jamais silencieusement une régénération au fichier que vous avez déposé : vous ne pourriez pas faire la différence, et rien ne vous inviterait à regarder.

:::warning Changement de comportement Jusqu'ici, le format facturx d'une facture déposée en Factur-X renvoyait un PDF régénéré par Scribee depuis les données extraites, et jamais le fichier d'origine. Son empreinte ne correspondait donc pas à celle du fichier déposé, et sa couche visuelle était le rendu Scribee et non celui de l'émetteur. Si votre intégration archive ce téléchargement, ou compare son empreinte à celle du fichier que vous avez transmis, elle reçoit désormais vos propres octets. :::

:::info customization_id est déduit quand vous ne l'envoyez pas Les formats ubl, cii et facturx reprennent le customization_id que vous envoyez à la création. Si vous ne l'envoyez pas, l'identifiant de spécification (BT-24) du fichier produit est celui du profil EXTENDED-CTC-FR, écrit dans la syntaxe du format demandé, et le XMP du facturx annonce le même profil dans fx:ConformanceLevel. Les deux couches du fichier concordent.

Envoyez explicitement le customization_id dès que vous visez un autre profil - le socle EN 16931 ou un profil Peppol : la valeur que vous transmettez l'emporte toujours sur celle déduite.

Cette déduction ne vaut que pour les factures émises depuis Scribee. Un document que vous importez conserve le customization_id que son émetteur a déclaré, et n'en reçoit aucun s'il n'en déclarait pas : Scribee n'invente pas la déclaration de spécification d'un tiers.

Ce que cela change si vous n'envoyiez rien. Le BT-24 produit était auparavant vide, et le XMP du facturx inscrivait malgré tout EN 16931 - les deux couches se contredisaient, et un destinataire pouvait refuser le fichier. Vos appels ne changent pas ; le fichier produit, si.

Une facture qui porte une partie payer exige un customization_id de profil EXTENDED-CTC-FR : c'est le seul profil où cette partie est légale, la chaîne EN 16931 standard l'interdisant. La combinaison est refusée à l'écriture : POST /api/v1/workspaces/{workspace_id}/invoices et PATCH /api/v1/invoices/{id} répondent 422 dès que la charge utile porte une partie payer sans customization_id EXTENDED-CTC-FR, et la facture n'est ni créée ni modifiée (Émettre une facture de vente). Le refus au téléchargement ne concerne plus que les factures dont la partie payer est arrivée par un autre chemin que ces deux appels - l'import d'un fichier UBL ou CII par POST /api/v1/workspaces/{workspace_id}/invoices/upload en particulier : ubl et cii échouent alors à la génération. :::

L'adresse électronique des parties dans ubl et cii

Les fichiers ubl et cii portent l'adresse électronique de chaque partie de la facture - BT-34 pour le vendeur, BT-49 pour l'acheteur. Pour ces deux rôles, Scribee la résout dans cet ordre : directory_routing_identifier, l'identifiant d'adressage de l'annuaire, sous le schéma 0225 ; à défaut legal_registration_id, sous ce même schéma 0225 ; à défaut endpoint_id, sous son propre endpoint_scheme_id. Les autres rôles (payee, payer, delivery, tax_representative) lisent directement endpoint_id.

Le dernier niveau est nouveau pour le vendeur et l'acheteur : une partie sans directory_routing_identifier ni legal_registration_id produisait jusqu'ici un fichier sans aucune adresse électronique, même lorsque endpoint_id était renseigné. Le champ que vous posez sur la fiche client ou fournisseur (Clients et fournisseurs) est désormais repris.

endpoint_id est repris sous le schéma que vous lui avez donné, jamais réétiqueté en 0225 : un identifiant déclaré sous 0208 reste sous 0208 dans le fichier produit.

Étape 1 : télécharger le PDF

Récupérez la rendition lisible avec l'identifiant de la facture (le champ id retourné à sa création ou par la liste des factures). Le scope read suffit.

curl https://app.scribee.tech/api/v1/invoices/YOUR_INVOICE_ID/download \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -D - -o facture.pdf

La réponse est le fichier binaire lui-même, en pièce jointe. Les en-têtes qui portent le format et le nom du fichier :

HTTP/2 200
content-type: application/pdf
content-disposition: attachment; filename="INV-2026-042.pdf"; filename*=UTF-8''INV-2026-042.pdf
content-transfer-encoding: binary

Le nom de fichier est répété sous ses deux formes, ASCII translittéré (filename) et UTF-8 percent-encodé (filename*) : si vous analysez cet en-tête, attendez-vous aux deux paramètres.

Étape 2 : choisir un autre format

Le même appel avec le paramètre format renvoie l'artefact structuré. Pour l'archivage réglementaire, facturx est le format qui réunit la couche lisible et les données structurées dans un seul fichier.

curl "https://app.scribee.tech/api/v1/invoices/YOUR_INVOICE_ID/download?format=facturx" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o facture-facturx.pdf

ubl et cii renvoient de la même façon un document XML (Content-Type: application/xml).

Quand les fichiers sont générés

• À la création : dès qu'une facture est créée par l'API, les quatre fichiers sont générés en tâche de fond, sans appel supplémentaire de votre part.
• À chaque modification : la mise à jour d'un brouillon relance la génération des fichiers depuis les nouvelles données, en tâche de fond. Rien n'est supprimé d'abord : les exemplaires précédents restent téléchargeables jusqu'à ce que la régénération les remplace, et un fichier téléchargé avant la modification ne correspond plus à la facture. Si la facture portait un PDF que vous aviez fourni, il cesse d'être servi : provided_pdf repasse à false et facturx_conformance est remis à nul dès le PATCH, puis la régénération remplace le fichier et le format pdf restitue désormais un rendu Scribee. Conservez une copie de votre PDF de votre côté si vous en avez besoin après une modification. Cela ne vise pas le Factur-X déposé à l'import, que le format facturx continue de restituer après la modification (voir plus haut) : les deux fichiers ont des origines distinctes.
• Au dépôt : le passage du brouillon dans le cycle de vie déclenche une dernière régénération, en tâche de fond et après le changement de statut. Les anciens fichiers ne sont pas purgés d'abord, et le téléchargement sert l'exemplaire existant quand il y en a un : un appel lancé juste après le dépôt peut donc renvoyer l'artefact du brouillon, sous le nom de fichier définitif. Laissez passer la régénération avant d'archiver, ou comparez le contenu au numéro de facture définitif.
• À la demande : si l'appel arrive avant la fin d'une génération en tâche de fond, le fichier est produit à la volée dans la requête, depuis les données de la facture au moment de l'appel. Cette génération n'a lieu qu'à défaut d'exemplaire attaché : le téléchargement sert l'exemplaire existant quand il y en a un, donc un appel lancé entre une modification et la fin de sa régénération peut encore renvoyer le fichier précédent.

Ce qui se passe ensuite

Le téléchargement ne change pas le statut de cycle de vie et ne transmet rien au PPF (Portail Public de Facturation), au réseau Peppol ou au destinataire. Ce n'est pas pour autant une lecture pure : quand le format demandé n'a pas encore d'exemplaire attaché, il est généré à la volée pendant la requête, et un facturx ainsi produit enregistre au passage son résultat de conformité (facturx_conformance) et les erreurs d'import éventuelles. Cette génération à la volée n'attache pas le fichier qu'elle renvoie : tant que la tâche de fond n'a pas déposé d'exemplaire, chaque appel refait la génération et réécrit ces champs. Ce n'est donc pas « le premier appel seulement » - c'est tout appel qui retombe sur la génération à la volée. Un téléchargement servi depuis un exemplaire déjà attaché, lui, n'écrit rien.

Vous n'avez pas besoin d'interroger l'API pour savoir quoi télécharger : chaque notification Webhooks (création de facture, événement de cycle de vie) porte un objet download avec l'URL de téléchargement des quatre formats (pdf, facturx, ubl, cii). Ces URLs pointent vers cet endpoint et s'appellent avec votre access token, comme n'importe quelle requête.

Le cas des devis

Les devis se téléchargent en PDF uniquement, via leur propre endpoint GET /api/v1/quotes/{id}/download (Devis).

Erreurs et cas limites

400 Bad Request : format inconnu

Une valeur de format hors des quatre codes renvoie :

{
  "error": "invalid_format",
  "message": "Format non supporté : xml. Formats supportés : ubl, cii, facturx, pdf"
}

Utilisez pdf, ubl, cii ou facturx, en minuscules.

401 Unauthorized

Token absent, expiré ou invalide. Le corps de la réponse est vide ; redemandez un token sur /oauth/token (Authentification) et rejouez la requête.

404 Not Found

{
  "error": "not_found",
  "message": "La ressource demandée est introuvable"
}

Quatre situations donnent cette réponse, sans les distinguer - l'existence d'une ressource hors de votre périmètre n'est jamais révélée :

• Aucune facture ne porte cet identifiant.
• Elle appartient à un workspace non lié à votre application.
• Elle appartient à un workspace lié, mais dont la liste d'IP autorisées exclut l'adresse d'où part l'appel. Cette route ne porte pas de workspace_id, donc le refus de périmètre s'y présente en 404 et non en 403 : une intégration qui fonctionne depuis une adresse renvoie 404 depuis une autre.
• C'est une facture de vente d'une entreprise dont l'offre Scribee ne couvre pas la vente. Les factures d'achat ne sont jamais masquées de cette façon.

Vérifiez l'identifiant contre la liste des factures du workspace.

422 Unprocessable Entity : génération impossible

{
  "error": "export_failed",
  "code": "operation_failed",
  "message": "Le bloc tiers payeur (EXT-FR-FE-BG-02) n'est autorisé qu'en profil EXTENDED-CTC-FR ; export refusé pour éviter un document non conforme."
}

Le fichier demandé n'a pas pu être produit. Le message porte la raison exacte donnée par le générateur - ici, un bloc tiers payeur qui n'est légal qu'en profil EXTENDED-CTC-FR, sur un export ubl ou cii ; cette cause ne peut plus venir d'une facture créée ou modifiée par l'API, qui refuse la combinaison à l'écriture. D'autres refus se présentent de la même façon :

• des sous-lignes de rubrique BR-FREXT hors profil EXTENDED, sur ubl ou cii ; le message nomme alors les identifiants des lignes en cause ;
• plusieurs identifiants d'objet facturé (BT-128) sur une même ligne hors profil EXTENDED-CTC-FR, sur ubl ou cii ; le message nomme là aussi les identifiants des lignes en cause (Émettre une facture de vente) ;
• sur ubl seulement et sous le profil EXTENDED-CTC-FR, une ligne qui porte purchase_order_reference sans order_line_reference, ou despatch_advice_reference sans despatch_advice_line_reference : l'UBL ne sait pas transmettre l'un sans l'autre. Le message nomme les lignes et propose l'export cii ou facturx, qui les transmettent (Émettre une facture de vente) ;
• sur facturx, un PDF fourni qui n'a pas pu être traité, ou dont la conformité a été évaluée non conforme - voir Fournir votre propre PDF ;
• sur facturx comme sur pdf, un Factur-X déposé dont le fichier archivé est illisible dans le stockage. Le message indique alors que Scribee refuse de rendre un PDF régénéré à la place du fichier déposé. Ce refus est un incident de stockage à signaler à votre contact Scribee, pas un défaut de la facture : rejouer l'appel ne le corrigera pas.

Quand le générateur n'expose aucune raison, le message retombe sur le texte générique Impossible de générer le fichier d'export.

La clé error vaut export_failed sur cette route, et non unprocessable_entity comme sur les autres 422 de l'API ; code vaut operation_failed, comme ailleurs. La réponse ne porte jamais de clé details.

Un refus qui tient au contenu de la facture ou au PDF fourni se reproduira à l'identique : corrigez la facture plutôt que de rejouer l'appel. Si l'erreur persiste sans cause identifiable, signalez l'identifiant de la facture à votre contact Scribee.

Pages liées

• Émettre une facture - créer la facture dont vous téléchargez les artefacts
• Devis - le téléchargement PDF des devis
• Référence API : télécharger une facture