Envoyer une facture via l'API PSB

L'envoi d'une e-facture via l'API PSB est l'endpoint le plus utilisé. Vous envoyez un document XML à l'API dans le format que votre logiciel produit, et le PSB se charge de la validation, de la transformation automatique vers le format attendu par le destinataire, du routage et de la livraison via le réseau approprié.

Endpoint

POST /api/v1/{partyId}/salesInvoice/send

Le {partyId} dans l'URL est l'identifiant Peppol de l'organisation expéditrice (le fournisseur). La requête contient le document XML en tant que body (content-type application/xml). Le PSB détecte automatiquement le format du document et le valide. Vous pouvez livrer dans tout format supporté : UBL 2.1, NLCIUS, BIS Billing V3, PINT, CII, XRechnung, Factur-X, FatturaPA, ebInterface, Svefaktura, DICO, SETU et bien d'autres. Le PSB transforme automatiquement le document vers le format attendu par le destinataire.

Flux de base

Upload : envoyez le document XML à l'endpoint
Validation : la PSB valide le document par rapport au schéma XSD et aux règles métier
Routage : la PSB recherche via SML/SMP comment joindre le destinataire
Livraison : le document est livré via le canal approprié (Peppol, e-mail ou un autre réseau)
Mise à jour du statut : vous recevez une notification webhook avec le statut de livraison

Attention : la PSB détermine le destinataire sur la base de l'EndpointID dans votre document XML. Si cet élément est absent ou contient un identifiant incorrect, l'envoi échoue avec le statut InvoiceSentError. Assurez-vous que votre système source renseigne correctement l'EndpointID. Plus d'informations sur les identifiants et le routage dans l'article sur les identifiants Peppol.

Idempotency : prévenir les uploads en double

La PSB prend en charge l'idempotency via le header de requête X-EConnect-DocumentId. En incluant votre propre UUID à chaque requête d'upload, vous empêchez le traitement en double :

X-EConnect-DocumentId: 550e8400-e29b-41d4-a716-446655440000

Si vous renvoyez le même documentId, l'API retourne 409 Conflict, indiquant à l'expéditeur que le document a déjà été traité.

Attention : Utilisez toujours un UUID/GUID comme documentId. N'utilisez jamais le numéro de facture, car cela provoque des problèmes si vous souhaitez renvoyer une version corrigée de la même facture.

Vérifier le routage

Avant d'envoyer une facture, vous pouvez vérifier via queryRecipientParty si et comment le destinataire est joignable :

POST /api/v1/{partyId}/salesInvoice/queryRecipientParty

Dans le corps de la requête, vous transmettez une liste d'identifiants, par exemple ["0106:12345678"], ou un objet avec partyIds et metaAttributes. Les paramètres de requête optionnels sont ?preferredDocumentTypeId et ?includeOptions.

La réponse contient des informations sur :

Si le destinataire est inscrit sur Peppol
Quels types de documents le destinataire peut recevoir
Via quel Access Point le destinataire est joignable
Quel canal la PSB utilisera pour la livraison

Pour des lookups avancés incluant l'URL de l'Access Point et le certificat AP, une route distincte est disponible :

GET /api/v1/peppol/deliveryOption?partyIds={id}&documentFamily=Invoice&isCredit=false

Gestion des erreurs

En cas d'échec de livraison, la PSB applique automatiquement un mécanisme de réessai :

Jusqu'à 8 tentatives réparties sur environ 35 heures
Uniquement pour les erreurs serveur 5xx (erreurs temporaires côté destinataire)
Un événement InvoiceSentRetry est publié pour chaque tentative
En cas d'échec définitif, vous recevez un événement InvoiceSentError via votre webhook

Erreurs courantes lors de l'envoi :

Erreur

Cause

Solution

Erreur de validation (4xx)

Le document n'est pas conforme au standard

Validez le document avec la Validate API. Remarque : les erreurs 4xx ne sont pas réessayées ; le document reste dans InvoiceSentError comme statut final.

Invalid payload — '{valeur}' n'est pas un xs:decimal valide sur un champ de montant

Le système source sérialise un montant (par exemple cbc:TaxInclusiveAmount, cbc:PriceAmount, cbc:LineExtensionAmount) en notation scientifique, comme -1.336061E6 au lieu de -1336061.00. Les champs de montant UBL sont de type xs:decimal et le type XML Schema n'autorise pas la notation exponentielle ; seule la notation décimale fixe avec 2 décimales au maximum est valide. Se produit typiquement pour des montants importants ou négatifs sérialisés en interne comme double.

Adaptez le système source pour que les montants soient écrits comme des nombres décimaux ordinaires (pas de notation E, pas de séparateurs de milliers). Signalez le problème au fournisseur du logiciel d'envoi ; eConnect ne peut pas corriger ceci car la valeur est dans le XML fourni.

The string '' is not a valid Decimal value sur un champ PriceAmount

Un champ de montant (par exemple cbc:PriceAmount) contient une chaîne vide ("") au lieu d'un nombre décimal sur une ou plusieurs lignes de facture. xs:decimal n'autorise pas une chaîne vide comme valeur lexicale. Cause différente de la notation scientifique, même classe de motif d'erreur.

Non corrigible automatiquement par eConnect. Adaptez le système source afin qu'aucun champ de montant ne reste vide ; renvoyez la facture avec un montant décimal valide sur toutes les lignes.

Destinataire non trouvé

Identifiant non inscrit dans Peppol

Vérifiez via queryRecipientParty

409 Conflict

Un document avec ce documentId a déjà été traité

Aucune action nécessaire, le document a déjà été envoyé

HTTP 500 pour payload volumineuse

La requête dépasse la limite de 24 MB du serveur web (overhead inclus)

Réduisez les pièces jointes PDF intégrées ; tenez compte de ~33% d'overhead base64

Remarque : SI-UBL 1.2 (Simpler Invoicing 1.2) n'est plus autorisé sur le réseau Peppol depuis le 1er janvier 2024. Les factures dans ce format entraînent un InvoiceSentError. Utilisez NLCIUS (SI-UBL 2.0) ou Peppol BIS Billing V3. Vérifiez le CustomizationID dans votre document XML si vous rencontrez cette erreur.

Réponse

Un upload réussi retourne 200 OK avec l'identifiant du document dans la PSB. Utilisez cet identifiant pour suivre le statut du document via l'API ou via les webhooks.

Pas de DELETE sur salesInvoice : statut final après une erreur 4xx

Contrairement à purchaseInvoice, l'endpoint salesInvoice ne dispose pas de DELETE. Il s'agit d'un choix délibéré, car une facture de vente envoyée ou rejetée est un événement de vie pertinent pour l'audit : le document reste traçable dans la piste d'audit, même après l'échec de l'envoi.

Les clients demandent parfois si une facture de vente rejetée peut être stoppée ou supprimée, par exemple après avoir déjà crédité la facture en interne. La réponse est :

Erreur de validation (4xx, par exemple Invalid payload) : la PSB place le document dans le statut final InvoiceSentError. Aucun réessai n'est exécuté (seules les erreurs 5xx sont réessayées). Le document n'est pas livré au destinataire malgré tout. Aucune action n'est requise sur la PSB ; le document est dans son statut final et est conservé 90 jours à des fins d'audit.
Pas de besoin d'endpoint DELETE : comme le document n'est plus actif et n'est pas réessayé, il n'est pas nécessaire de le supprimer explicitement pour arrêter l'envoi.
Envoyer une correction via un nouveau document : si la facture originale était incorrecte et avait déjà été (partiellement) livrée, utilisez une note de crédit ou une facture de correction selon le flux comptable standard. Le documentId original reste comme référence dans la piste d'audit.

Cette différence de cycle de vie entre salesInvoice (sans DELETE) et purchaseInvoice (avec DELETE) découle du rôle : une facture sortante est une action commerciale enregistrée par l'émetteur qui doit être juridiquement traçable ; une facture entrante peut être supprimée du système du destinataire après un téléchargement réussi.

ViDA et reporting CTC

Lors de l'envoi d'une facture, le PSB gère également la déclaration fiscale. Dans le cadre de la directive ViDA (VAT in the Digital Age), le PSB génère automatiquement un DRR (Digital Reporting Requirement) à partir des données de la facture et le transmet à l'administration fiscale compétente. En tant qu'intégrateur, vous n'avez rien de plus à faire : le DRR est dérivé de la même facture que vous envoyez via l'endpoint habituel. Les messages de statut et les messages de reporting CTC sont inclus dans le prix du document.

Options avancées

Forcer un canal

Par défaut, la PSB sélectionne automatiquement le meilleur canal. Avec le paramètre de requête ?channel={hookId}, vous pouvez forcer un canal de livraison spécifique (par ex. un réseau spécifique ou un fallback e-mail).

Inclure des pièces jointes

Les pièces jointes (PDF, images) peuvent être intégrées en base64 dans le document UBL en tant qu'AdditionalDocumentReference. La PSB traite correctement les pièces jointes intégrées et les livre avec la facture.

Remarque : L'endpoint d'envoi accepte un maximum de 24 MB par requête (overhead HTTP inclus). Avec des pièces jointes encodées en base64, la payload augmente d'environ 33%, un PDF de 18 MB produit donc une requête d'environ 24 MB. Les payloads dépassant la limite sont rejetées par le serveur web avec HTTP 500 (pas 413), avant que la validation applicative n'intervienne. Réduisez les pièces jointes volumineuses ou envoyez-les via un canal séparé.

Conseil : Le standard Peppol BIS Billing 3.0 actuel prend en charge un maximum d'une OrderReference par facture. Si une facture concerne plusieurs commandes, plusieurs factures doivent être envoyées.

Conseil : Certains destinataires signalent des erreurs pour des factures avec un préfixe d'espace de noms XML (par ex. <urn:Invoice> au lieu de <Invoice>). Les deux formes sont du XML techniquement valide selon la spécification W3C. Si un destinataire invoque cela comme raison de rejet, ce n'est pas un refus valide au sein du réseau Peppol. Le destinataire doit utiliser un parseur XML qui gère correctement les espaces de noms préfixés et par défaut.

Questions fréquentes

Comment envoyer une facture et dans quel format ?

Vous pouvez livrer dans tout format supporté par le PSB : UBL 2.1, NLCIUS, BIS Billing V3, PINT, CII, XRechnung, Factur-X, FatturaPA, ebInterface, Svefaktura, DICO, SETU et bien d'autres. Postez le document XML comme body vers POST /api/v1/{partyId}/salesInvoice/send avec Content-Type: application/xml. Le PSB détecte le format automatiquement, valide le document et le transforme vers le format attendu par le destinataire. Le destinataire est déterminé via le EndpointID dans votre XML.

Comment éviter les envois en double et que signifie 409 Conflict ?

Incluez le header X-EConnect-DocumentId avec un UUID unique à chaque upload. Si vous réutilisez le même documentId, l'API répond avec 409 Conflict, confirmant que le document a déjà été traité. N'utilisez jamais le numéro de facture comme documentId, car lors d'un renvoi corrigé, vous aurez besoin d'un nouvel identifiant.

Comment suivre le statut de livraison et que se passe-t-il en cas d'erreurs temporaires ?

Après un upload réussi, l'API retourne un identifiant de document dans la PSB que vous pouvez utiliser pour suivre le statut via l'API ou les webhooks. En cas d'erreurs temporaires 5xx côté destinataire, la PSB publie un événement InvoiceSentRetry par tentative et réessaie jusqu'à 8 fois sur environ 35 heures ; en cas d'échec définitif, vous recevez un événement InvoiceSentError.

Vous souhaitez d'abord tester si votre document est valide ? Utilisez la Validate API.

Essayer dans l'API