Pièces jointes aux factures

Ce guide explique comment ajouter, lire et interpréter les pièces jointes lorsque vous travaillez avec des factures via l’API ou XML.

Choisir un workflow

Créer avec JSON : créez la facture d’abord, puis ajoutez les pièces jointes avec add_attachment ou add_attachments.
Importer un XML avec pièces jointes intégrées : incluez les pièces jointes dans le XML et importez le fichier.
Importer un PDF avec XML intégré (factures reçues) : si le PDF contient un XML embarqué (Factur-X/ZUGFeRD), B2Brouter peut l’extraire et créer la facture reçue.

Principes importants

Le XML est la source légale et structurée. Votre PDF doit être cohérent avec les données XML. N’essayez pas de modifier la structure XML pour correspondre à une mise en page PDF personnalisée ; le XML doit suivre des schémas standardisés afin que n’importe quel destinataire puisse le traiter.
Les pièces jointes sont complémentaires. Un PDF (ou toute autre pièce jointe) n’est pas une facture électronique et ne permet pas à lui seul un traitement automatisé. Utilisez les pièces jointes comme documents de support, et non comme source principale de données.

Ajouter des pièces jointes à une facture existante

Ajouter une pièce jointe unique (recommandé pour l’aperçu PDF)

Vous devez d’abord créer ou importer une facture.

Après avoir créé la facture, une pièce jointe s’ajoute en effectuant une requête POST vers l’endpoint /invoices/{id}/add_attachment. La requête doit envoyer les octets bruts du fichier dans le corps et inclure le nom de fichier au moyen du paramètre de requête filename.

Si le PDF joint doit être utilisé comme représentation visuelle et légale de la facture, le paramètre use_as_pdf_view=true doit également être fourni.

curl --request POST \
  --url 'https://api-staging.b2brouter.net/invoices/12345/add_attachment?filename=invoice.pdf&use_as_pdf_view=true'

Remarques :

L’API attend Content-Type: application/octet-stream.
Les octets bruts sont recommandés ; les payloads base64 ou data-URI fonctionnent aussi.
use_as_pdf_view=true marque le PDF comme PDF visuel/légal (un seul par facture).
use_as_pdf_view=true ne s’applique qu’aux uploads PDF. N’essayez pas de marquer un XML (UBL/Facturae/CII/etc.) comme use_as_pdf_view=true : il ne deviendra pas la vue PDF.
La vue PDF est disponible pour les types de document basés sur PDF tels que pdf.invoice, pdf.invoice.signed et les types hybrides PDF/A comme pdf.a.invoice.with.xml.cii.cross_industry_invoice.facturx.en16931 et pdf.a.invoice.with.xml.cii.cross_industry_invoice.facturx.extended.
Si vous modifiez ensuite la facture, le même PDF reste utilisé sauf s’il est remplacé.

Ajouter plusieurs pièces jointes (ZIP)

Utilisez l’endpoint ZIP lorsque vous devez téléverser plusieurs fichiers en un seul appel.

zip attachments.zip file1.pdf file2.xml
curl --request POST \
  --url https://api-staging.b2brouter.net/invoices/12345/add_attachments

Si vous devez définir un PDF comme aperçu de la facture, téléversez d’abord ce PDF avec l’endpoint add_attachment en utilisant le paramètre de requête use_as_pdf_view=true, puis téléversez le reste avec l’endpoint add_attachments.

Ajouter des pièces jointes lors de l’import d’un XML de facture

Si vous générez déjà un XML (UBL, Facturae, CII, etc.), vous pouvez intégrer des pièces jointes dans le XML et importer le fichier. Les pièces jointes seront extraites et stockées automatiquement.

UBL (Peppol)

<cac:AdditionalDocumentReference>
  <cbc:ID>ATT-1</cbc:ID>
  <cac:Attachment>
    <cbc:EmbeddedDocumentBinaryObject
      mimeCode="application/pdf"
      filename="invoice.pdf">BASE64_DATA</cbc:EmbeddedDocumentBinaryObject>
  </cac:Attachment>
</cac:AdditionalDocumentReference>

Facturae

<AdditionalData>
  <RelatedDocuments>
    <Attachment>
      <AttachmentCompressionAlgorithm>NONE</AttachmentCompressionAlgorithm>
      <AttachmentFormat>PDF</AttachmentFormat>
      <AttachmentEncoding>BASE64</AttachmentEncoding>
      <AttachmentDescription>invoice.pdf</AttachmentDescription>
      <AttachmentData>BASE64_DATA</AttachmentData>
    </Attachment>
  </RelatedDocuments>
</AdditionalData>

CII / ZUGFeRD

<ram:AdditionalReferencedDocument>
  <ram:AttachmentBinaryObject
    mimeCode="application/pdf"
    filename="invoice.pdf">BASE64_DATA</ram:AttachmentBinaryObject>
</ram:AdditionalReferencedDocument>

Détails d’encodage :

Base64 est l’encodage par défaut.
Si le XML inclut un code d’encodage explicite, les valeurs prises en charge sont BASE64, BER et DER.
Dans Facturae, AttachmentCompressionAlgorithm peut être ZIP ou GZIP.
Si la compression n’est pas définie, le contenu est décodé comme du base64 simple.

Utiliser votre propre PDF dans ZUGFeRD / Factur-X

Pour envoyer un PDF hybride (PDF + XML intégré) avec votre propre mise en page :

Choisissez un type de document hybride dans le contact (par exemple : pdf.a.invoice.with.xml.cii.cross_industry_invoice.facturx.en16931).
Créez la facture comme d’habitude.
Téléversez votre PDF avec use_as_pdf_view=true.
Envoyez la facture.

Exemple de contact :

{
  "contact": {
    "name": "Example GmbH",
    "tin_scheme": "9930",
    "tin_value": "DE8******3",
    "transport_type_code": "email",
    "document_type_code": "pdf.a.invoice.with.xml.cii.cross_industry_invoice.facturx.en16931"
  }
}

Pour lister les types de document disponibles, utilisez l’endpoint document types GET /document_types.

Comment les pièces jointes apparaissent dans les réponses API

Le tableau attachments de l’endpoint get invoice GET /invoices/{id} inclut les fichiers normaux que vous avez téléversés dans la facture (il n’inclut pas le PDF marqué comme pdf_view).
En règle générale, un PDF téléversé avec use_as_pdf_view=true est stocké comme PDF visuel/légal (pdf_view) et n’apparaît pas dans le tableau attachments.
Exception : pour les factures reçues, si le document original est un PDF et que son type de document n’est pas un attached_document_type, ce PDF original est également exposé dans le tableau attachments.
Après l’envoi d’une facture émise, download_legal_url pointe vers le PDF légal (généré par B2Brouter ou votre pdf_view s’il est fourni).

Lire les pièces jointes des factures reçues

Lorsque vous récupérez une facture reçue, la réponse inclut un tableau attachments avec des liens de téléchargement :

{
  "attachments": [
    {
      "link": "/attachments/download/253526/2025-02-10_1_original.pdf",
      "content_type": "application/pdf"
    }
  ]
}

Pour télécharger le fichier, utilisez l’endpoint GET /attachments/download/{id}/{filename}

Incluez votre en-tête de clé API lors du téléchargement. L’id provient du lien.

Supprimer des pièces jointes

La suppression est possible depuis l’application web, mais il n’existe pas d’endpoint API public. Si une pièce jointe a été importée incorrectement et que vous avez besoin d’un flux automatisé, l’approche recommandée consiste à supprimer la facture puis à la soumettre de nouveau sans la pièce jointe erronée.

Limites et contraintes des transports

B2Brouter autorise jusqu’à 50 Mo par fichier. Si vous envoyez par e-mail, la taille totale des pièces jointes est limitée à 40 Mo. Certains réseaux peuvent imposer des limites plus basses (10–20 Mo), selon le canal.
Formats attendus : PDF et XML, ainsi que les formats bureautiques courants (par exemple CSV). Les formats exécutables ou scripts sont bloqués (par exemple .exe, .js, .bat, .sh, .jar, .ps1, .html, .gif).
Certains transports sont configurés comme “without embedded attachments” (détachés), de sorte que les pièces jointes ne sont pas incluses dans le XML envoyé au destinataire.
Certains systèmes destinataires ignorent les pièces jointes intégrées même lorsqu’elles sont présentes.
Si la facture n’est pas envoyée avec succès, le destinataire ne verra pas le PDF, quelles que soient les pièces jointes.
L’endpoint add_attachment requiert Content-Type: application/octet-stream et un paramètre de requête filename.