Lorsqu'une facture destinée à votre organisation arrive via Peppol ou un autre réseau, le PSB stocke le document et envoie une notification à votre webhook. Dans cet article, vous apprenez comment recevoir cette notification, télécharger le document et mettre en place la gestion des statuts.

La réception d'une facture se déroule en quatre étapes :

1. Notification : le PSB envoie un événement webhook InvoiceReceived à votre endpoint
2. Téléchargement : vous récupérez le document via l'endpoint PurchaseInvoice
3. Traitement : vous traitez la facture dans votre propre système
4. Nettoyage (optionnel) : vous supprimez le document du PSB

Pour recevoir des factures, vous avez besoin d'un webhook qui écoute le topic InvoiceReceived. Enregistrez-le via la Hook API :

POST /api/v1/hook

{
  "action": "https://mijn-systeem.nl/webhook/invoices#mijnSecretKey",
  "topics": ["InvoiceReceived"]
}

Dès qu'une facture arrive, votre endpoint reçoit une requête POST avec un payload JSON. Ce payload contient entre autres le documentId et le partyId avec lesquels vous pouvez récupérer le document.

Conseil : configurez également un webhook sur le topic InvoiceReceivedError pour recevoir des notifications en cas de problème lors de la réception.

Utilisez le documentId du payload webhook pour récupérer la facture :

GET /api/v1/{partyId}/purchaseInvoice/{documentId}/download HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}

La réponse contient le document XML (par défaut dans le format original). Vous souhaitez recevoir le document dans un autre format ? Utilisez le paramètre targetDocumentTypeId :

GET /api/v1/{partyId}/purchaseInvoice/{documentId}/download?targetDocumentTypeId={URN}

Le PSB transforme automatiquement le document dans le format spécifié avant de le retourner.

Le PSB conserve les documents reçus selon le schéma suivant :

Il est recommandé de récupérer les documents dès leur réception et de les stocker dans votre propre système. Ne comptez pas sur le PSB comme stockage à long terme.

Après traitement, vous pouvez supprimer manuellement le document :

DELETE /api/v1/{partyId}/purchaseInvoice/{documentId} HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}

Cela supprime définitivement le document du PSB. La piste d'audit reste disponible.

Après réception, vous pouvez mettre à jour le statut de traitement d'une facture d'achat. Cela est particulièrement pertinent si vous souhaitez envoyer des Invoice Responses (messages de statut) à l'expéditeur. Pour cela, consultez l'article Envoyer un Invoice Response.

Le PSB envoie automatiquement un message MLS (Message Level Status) à l'expéditeur après réception d'un document. Cela confirme que le document a été reçu et livré. En tant qu'intégrateur, vous n'avez rien à configurer : le PSB gère cela entièrement. Si vous envoyez vous-même des documents, vous recevez des retours MLS via le topic webhook MessageLevelStatusReceived. Voir Configurer les webhooks pour la configuration.

Si vous ne pouvez pas configurer de webhooks (par exemple dans un environnement on-premise sans trafic internet entrant), vous pouvez également récupérer les factures par polling :

GET /api/v1/{partyId}/purchaseInvoice HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}

Cet endpoint retourne une liste des factures d'achat disponibles. Les webhooks restent cependant la méthode préférée en raison du traitement en temps réel et de la charge réduite sur l'API.

Attention : pour les intégrations on-premise, envisagez également le reverse webhook (HTTPS inbound hook), avec lequel le PSB pousse les documents sans que votre système doive être directement accessible depuis Internet.

• Traitez de manière idempotente : le PSB peut, dans des cas exceptionnels, livrer un événement plusieurs fois. Vérifiez de votre côté si vous avez déjà traité un document avant de l'importer à nouveau.
• Téléchargez immédiatement : récupérez les documents le plus rapidement possible après la notification webhook. La rétention de 90 jours est un filet de sécurité, pas une stratégie de stockage.
• Journalisez le documentId : conservez le documentId PSB dans votre propre système pour le traçage et le dépannage éventuel.
• Convertir le format : si vous avez besoin d'un format XML spécifique, utilisez targetDocumentTypeId lors du téléchargement au lieu de convertir vous-même.
• Réessais webhook : si votre endpoint est temporairement inaccessible, la PSB réessaie la notification pendant 5 jours maximum. En cas d'indisponibilité prolongée, utilisez les batch hooks comme solution de repli pour récupérer les documents manqués.

Consultez les endpoints PurchaseInvoice complets et les modèles de réponse sur psb.econnect.eu.