Pièces jointes

Un bon de commande, un bon de livraison ou un contrat accompagne souvent la facture qu'il justifie : c'est ce qui permet au destinataire de rapprocher le document et de l'approuver sans aller-retour. L'API Scribee attache ces fichiers à deux endroits : sur une facture, où ils peuvent être embarqués dans la facture électronique transmise, et sur une fiche client ou fournisseur, où ils servent de documents de référence. La norme EN 16931 prévoit ce transport (bloc BG-24) ; Scribee en applique les contraintes de format pour vous.

Ce que Scribee fait pour vous

Embarque les documents marqués attachable_to_invoice dans chaque format de la facture généré après le marquage : fichiers incorporés au Factur-X, bloc BG-24 encodé en base64 dans les XML UBL et CII, pages ajoutées à la fin du rendu PDF pour les pièces au format PDF. Le Factur-X vise le PDF/A-3, mais la conformité est un état constaté - lisez facturx_conformance avant de traiter le fichier comme tel (Formats et téléchargements).
Vérifie à l'activation que le fichier respecte la liste fermée de formats EN 16931 : une facture ne part jamais avec une pièce embarquée non conforme.
Nomme chaque document embarqué, selon des règles qui diffèrent d'un format à l'autre. En UBL et en CII, l'identifiant du document est votre label - à défaut, le nom du fichier - et son type est porté à part sous la forme d'un code de la liste fermée BR-FR-17 (BON_COMMANDE, DOCUMENT_ANNEXE, ...), dérivé du kind (voir le tableau des types). En Factur-X, le fichier embarqué porte toujours le nom du fichier que vous avez envoyé, jamais le label ; celui-ci sert alors de description, et remplace le type en clair au lieu de s'y ajouter. Si vous vous appuyez sur ces libellés, envoyez des noms de fichiers explicites en plus du label.

Documents de facture, documents de tiers

POST /api/v1/invoices/{invoice_id}/supporting_documents : justificatifs propres à une facture, de vente comme d'achat. Seuls ces documents sont éligibles à l'embarquement dans la facture transmise.
POST /api/v1/parties/{party_id}/supporting_documents : documents de référence sur une fiche client ou fournisseur (coordonnées bancaires, contrat, extrait Kbis). attachable_to_invoice vaut toujours false sur cette portée : ces documents ne sont jamais embarqués dans une facture. La création des fiches est décrite dans Clients et fournisseurs.

Les types de document

`kind`	Libellé	Code BT-123 (UBL, CII)
`banking_coordinates`	Coordonnées bancaires	`RIB`
`purchase_order`	Bon de commande	`BON_COMMANDE`
`delivery_note`	Bon de livraison	`BON_LIVRAISON`
`contract`	Contrat	`DOCUMENT_ANNEXE`
`kbis`	Extrait Kbis	`DOCUMENT_ANNEXE`
`identity_document`	Pièce d'identité	`DOCUMENT_ANNEXE`
`general_terms`	Conditions générales de vente	`DOCUMENT_ANNEXE`
`stylesheet`	Feuille de style	`FEUILLE_DE_STYLE`
`tracking_slip`	Bordereau de suivi	`BORDEREAU_SUIVI`
`tracking_validation_slip`	Bordereau de suivi et validation	`BORDEREAU_SUIVI_VALIDATION`
`prepayment_statement`	État d'acompte	`ETAT_ACOMPTE`
`direct_payment_invoice`	Facture de paiement direct (sous-traitant)	`FACTURE_PAIEMENT_DIRECT`
`co_contracting_summary`	Récapitulatif de cotraitance	`RECAPITULATIF_COTRAITANCE`
`other`	Autre	`PJA`

La dernière colonne donne le code que Scribee écrit dans le BT-123 de chaque pièce embarquée : cbc:DocumentDescription en UBL, ram:Name en CII. La norme XP Z12-012 (règle BR-FR-17) restreint ce champ à une liste fermée de codes, et Scribee le dérive du seul kind : contract, kbis, identity_document et general_terms partagent le code générique DOCUMENT_ANNEXE, et other produit PJA. Choisissez le kind le plus précis pour que le destinataire reçoive le code correspondant.

Cet enum est distinct de celui des documents KYC des mandats (kbis_extract, identity_paper, signing_capacity_proof, additional) : kbis n'est pas kbis_extract, identity_document n'est pas identity_paper. Les documents KYC se déposent sur un mandat - voir Mandats de facturation électronique - jamais via les endpoints de cette page.

Le type general_terms n'accepte que des fichiers PDF, et le fichier doit être un PDF lisible : un PDF corrompu est refusé au dépôt.

Étape 1 : joindre un document à une facture

Cet appel stocke le fichier dans votre workspace et le rattache à la facture. Il ne transmet rien vers l'extérieur et se défait avec le DELETE de l'étape 5.

curl -X POST https://app.scribee.tech/api/v1/invoices/YOUR_INVOICE_ID/supporting_documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "supporting_document[kind]=purchase_order" \
  -F "supporting_document[label]=Bon de commande BC-2025-0042" \
  -F "supporting_document[file]=@bon_de_commande.pdf"

Réponse 201, abrégée aux champs utiles ici :

{
  "data": {
    "id": 87,
    "kind": "purchase_order",
    "label": "Bon de commande BC-2025-0042",
    "attachable_to_invoice": false,
    "filename": "bon_de_commande.pdf",
    "content_type": "application/pdf",
    "byte_size": 15234,
    "download_url": "https://app.scribee.tech/storage/signed_blobs/bon_de_commande.pdf?token=..."
  }
}

La requête est en multipart/form-data ; kind et file sont obligatoires, label est optionnel. Formats acceptés au dépôt : PDF, PNG, JPEG, GIF, CSV, DOCX, XLSX, ODT, ODS ; une taille strictement inférieure à 10 Mio (10 485 760 octets) par fichier. attachable_to_invoice vaut false à la création, sauf dans un cas : sur une facture de vente, un attachable_to_invoice=true explicite accompagné d'un fichier au format EN 16931 (PDF, PNG, JPEG, CSV, XLSX, ODS) est accepté tel quel. Le drapeau est alors posé, mais rien n'est embarqué à cet instant : la création enregistre le document, elle ne régénère pas les fichiers de la facture. L'embarquement a lieu à la prochaine génération (voir plus bas). Partout ailleurs - facture d'achat, format hors EN 16931, drapeau omis - la valeur retombe à false sans erreur, et l'étape 2 est nécessaire.

Étape 2 : embarquer le document dans la facture

PATCH .../toggle_attachable inverse l'état de attachable_to_invoice. Cet appel ne transmet rien : il bascule un drapeau, et l'embarquement effectif se fait quand Scribee génère les fichiers de la facture. Réversible : rappelez le même endpoint pour désactiver.

curl -X PATCH https://app.scribee.tech/api/v1/invoices/YOUR_INVOICE_ID/supporting_documents/87/toggle_attachable \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

{
  "data": {
    "id": 87,
    "kind": "purchase_order",
    "attachable_to_invoice": true
  }
}

L'activation est acceptée à deux conditions : le document appartient à une facture de vente, et son fichier est dans la liste EN 16931 (PDF, PNG, JPEG, CSV, XLSX, ODS). GIF, DOCX et ODT se déposent donc à l'étape 1 mais ne s'embarquent pas. La désactivation est toujours acceptée.

Étape 3 : lister les pièces jointes d'une facture

Lors de l'import d'une facture, les fichiers qu'elle transporte sont ajoutés à cette liste lorsqu'ils respectent les formats acceptés. Ils portent tous attachable_to_invoice=false, et le fichier importé reste inchangé. Ils peuvent dépasser la limite du dépôt manuel. Un fichier refusé ou une limite atteinte produit un avertissement d'import.

UBL et CII, y compris le XML CII d'un Factur-X : chaque pièce BG-24 qui contient un objet encodé en base64 (BT-125) devient un document. Son kind est lu dans le code BT-123, sans tenir compte de la casse, selon le tableau des types : RIB donne banking_coordinates, BON_LIVRAISON donne delivery_note, et ainsi de suite. DOCUMENT_ANNEXE, PJA, un code absent ou hors liste donnent other. Son label reprend l'identifiant BT-122 quand celui-ci diffère du nom du fichier, et reste vide sinon. L'extraction accepte au plus 100 pièces et au plus 50 Mio (52 428 800 octets) de données décodées au total ; au-delà, aucune de ces pièces n'est importée.
Représentation lisible : la pièce BG-24 qui porte la représentation lisible de la facture - un PDF (BT-125-1 application/pdf) dont le BT-123 vaut LISIBLE, ou à défaut un PDF nommé exactement lisible.pdf, quelle que soit la casse - n'est jamais ajoutée à cette liste : c'est elle que Scribee retient comme PDF de la facture, dans les conditions décrites dans Importer des factures existantes. Une seconde pièce LISIBLE, ou une pièce LISIBLE qui n'est pas un PDF, est conservée comme document other.
Factur-X : les fichiers intégrés au PDF sont ajoutés avec kind=other. Le XML de la facture est exclu. L'extraction accepte au plus 100 fichiers et moins de 50 Mio (52 428 800 octets) de données décompressées au total, XML compris.

GET /api/v1/invoices/{invoice_id}/supporting_documents retourne tous les documents de la facture, du plus récent au plus ancien, sans pagination : la réponse contient data sans objet meta.

curl https://app.scribee.tech/api/v1/invoices/YOUR_INVOICE_ID/supporting_documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

{
  "data": [
    {
      "id": 87,
      "kind": "purchase_order",
      "attachable_to_invoice": true,
      "filename": "bon_de_commande.pdf"
    }
  ]
}

GET /api/v1/invoices/{invoice_id}/supporting_documents/{id} retourne un document seul ; son download_url sert le contenu du fichier. Ce lien est temporaire : il reste valable une heure après la réponse qui le porte, puis répond 404. Il suffit seul à télécharger le fichier, sans token Bearer : quiconque le détient peut s'en servir jusqu'à son expiration. Supprimer le document (étape 5) y met fin aussitôt : le lien répond alors 404. C'est le seul moyen de le révoquer avant la fin de son heure. Ne le stockez pas et ne le partagez pas. Le fichier est toujours servi en pièce jointe (Content-Disposition: attachment). Pour obtenir un lien neuf, relisez le document ou la liste : chaque réponse en porte un nouveau.

Étape 4 : documents d'un client ou d'un fournisseur

Même mécanique de dépôt, sur la fiche du tiers. Cet appel stocke le fichier dans votre workspace, ne transmet rien vers l'extérieur, et se défait par un DELETE sur le même chemin.

curl -X POST https://app.scribee.tech/api/v1/parties/YOUR_PARTY_ID/supporting_documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "supporting_document[kind]=banking_coordinates" \
  -F "supporting_document[label]=RIB 2025" \
  -F "supporting_document[file]=@rib.pdf"

{
  "data": {
    "id": 91,
    "documentable_type": "Party",
    "documentable_id": 12,
    "kind": "banking_coordinates",
    "attachable_to_invoice": false
  }
}

documentable_type vaut Party, jamais Customer ni Supplier : les deux sont des sous-classes d'un même modèle et la colonne polymorphe stocke la classe de base. Filtrez sur documentable_id, pas sur le type.

La lecture suit les mêmes chemins que côté facture : GET /api/v1/parties/{party_id}/supporting_documents (liste, non paginée) et GET /api/v1/parties/{party_id}/supporting_documents/{id} (document seul). Il n'existe pas de toggle_attachable sur cette portée.

Étape 5 : supprimer un document

Cet appel supprime l'enregistrement et le fichier stocké - la suppression du fichier est définitive, seul un nouveau dépôt le restaure. Les factures déjà transmises ne sont pas modifiées.

curl -X DELETE https://app.scribee.tech/api/v1/invoices/YOUR_INVOICE_ID/supporting_documents/87 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Réponse 204 sans corps. Même chemin côté tiers : DELETE /api/v1/parties/{party_id}/supporting_documents/{id}. Le scope write est requis.

Ce qui se passe ensuite

L'embarquement s'applique au moment où Scribee génère les fichiers de la facture. Dans les XML UBL et CII, chaque document activé devient un bloc BG-24 avec son contenu encodé en base64, son nom issu de label (ou du nom de fichier) et le code BT-123 de son kind (voir le tableau des types). Dans le Factur-X, il est incorporé en fichier joint au PDF, et le XML CII embarqué dans ce PDF porte le même bloc BG-24 avec le même code. La conformité PDF/A-3 du Factur-X reste un état constaté et non une garantie (facturx_conformance). Dans le rendu PDF, les pages des pièces au format PDF sont ajoutées après la facture ; les pièces d'un autre format (PNG, CSV, ...) voyagent uniquement dans les XML et le Factur-X. Un PDF joint n'est pas contrôlé à la lecture au moment du dépôt : un fichier corrompu est accepté et marqué joignable, puis simplement ignoré lors de la concaténation, sans erreur ni signal dans l'API. Vérifiez vos pièces avant de les envoyer.
Activez le drapeau avant d'émettre la facture (Émettre une facture) : les fichiers d'export sont reconstruits à chaque modification du brouillon, mais un document ajouté ou activé après qu'un exemplaire a quitté la plateforme n'atteint pas cet exemplaire, et une suppression ne rappelle rien.
Les conditions générales de vente déposées au niveau de l'entreprise depuis l'interface Scribee sont ajoutées aux seuls PDF de vente rendus par Scribee, et seulement quand la langue déposée correspond à celle de l'acheteur (ou n'en précise aucune). Elles ne sont ajoutées ni à un PDF que vous fournissez, ni aux pièces jointes des formats UBL, CII et Factur-X. Elles ne passent pas par les endpoints de cette page.

Erreurs et cas limites

422 : champ manquant

kind et file sont obligatoires au dépôt :

{
  "error": "unprocessable_entity",
  "code": "validation_failed",
  "message": "La validation a échoué",
  "details": {
    "base": ["Un fichier est requis."]
  }
}

Un kind manquant produit "Un type de document est requis." au même format. Complétez la requête et rejouez-la.

422 : fichier refusé au dépôt

Un fichier hors de la liste acceptée (PDF, PNG, JPEG, GIF, CSV, DOCX, XLSX, ODT, ODS), un fichier de 10 Mo ou plus, ou un general_terms qui n'est pas un PDF lisible, retournent 422 avec la cause dans details. Convertissez ou réduisez le fichier avant de rejouer l'appel.

422 : activation refusée

toggle_attachable refuse l'activation dans deux cas, chacun avec son message :

{
  "error": "unprocessable_entity",
  "code": "validation_failed",
  "message": "La validation a échoué",
  "details": {
    "base": ["Le format du fichier n'est pas conforme à EN 16931."]
  }
}

"Ce document ne peut pas être joint au flux de facturation." : le document appartient à une facture d'achat ; seules les factures de vente embarquent des documents.
"Le format du fichier n'est pas conforme à EN 16931." : le fichier est un GIF, DOCX ou ODT. Redéposez la pièce dans un format de la liste EN 16931 (PDF, PNG, JPEG, CSV, XLSX, ODS), puis activez-la.

404 Not Found

Quatre causes. La facture, le tiers ou le document n'existe pas ; il appartient à un workspace hors du périmètre de votre application ; il appartient à un workspace dont l'allowlist IPv4 refuse l'adresse de votre requête - sur ces endpoints, une adresse refusée produit ce 404, et non le 403 décrit dans les Conventions de l'API ; ou l'offre de l'entreprise ne couvre pas la facturation de vente, ce qui masque à la fois ses factures de vente et ses fiches clients (les fournisseurs, eux, restent visibles). Cette dernière cause renvoie 404 sur une ressource qui existe et qui est bien dans votre périmètre.

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

Vérifiez l'identifiant et le rattachement du workspace (Votre premier appel).

403 Forbidden : scope insuffisant

Le dépôt et le toggle_attachable exigent le scope write ; la suppression exige write :

{
  "error": "forbidden",
  "message": "Vous n'êtes pas autorisé à effectuer cette action"
}

Redemandez un token avec les scopes voulus (Authentification).

Pages liées

Émettre une facture - le parcours de la facture dans lequel les pièces sont embarquées
Référence API : lister les pièces jointes d'une facture
Référence API : joindre un document à une facture
Référence API : embarquer ou retirer une pièce jointe
Référence API : lister les documents d'un tiers

Ce que Scribee fait pour vous​

Documents de facture, documents de tiers​

Les types de document​

Étape 1 : joindre un document à une facture​

Étape 2 : embarquer le document dans la facture​

Étape 3 : lister les pièces jointes d'une facture​

Étape 4 : documents d'un client ou d'un fournisseur​

Étape 5 : supprimer un document​

Ce qui se passe ensuite​

Erreurs et cas limites​

422 : champ manquant​

422 : fichier refusé au dépôt​

422 : activation refusée​

404 Not Found​

403 Forbidden : scope insuffisant​

Pages liées​