Intégrer Peppol dans votre application : envoyer des e-factures via KRONENWERK

Vous intégrez l'envoi Peppol dans votre application via KRONENWERK en créant le brouillon de facture avec POST /invoices/drafts, en faisant émettre et transmettre la facture dans le produit, et en recevant invoice.issued sur votre endpoint webhook. KRONENWERK n'est pas un point d'accès Peppol. Il envoie et reçoit via Peppol par l'intermédiaire d'un prestataire de point d'accès accrédité (Storecove) une fois l'entreprise connectée dans Paramètres → Envoi, et l'envoi en production dépend de ce compte et de sa configuration. La fonctionnalité est PRISE EN CHARGE AVEC RESTRICTIONS.

Ce qu'est Peppol, pour un intégrateur

Peppol est un réseau de livraison à quatre coins : votre entreprise (coin 1) remet un document à son point d'accès (coin 2), qui recherche le point d'accès du destinataire (coin 3) via l'annuaire SML/SMP et livre à l'entreprise destinataire (coin 4). Les documents sont des UBL structurés conformes à Peppol BIS Billing 3.0, une implémentation de l'EN 16931. Les participants sont adressés par des identifiants tels qu'un numéro de TVA sous un schéma issu des listes de codes OpenPeppol, obligatoires dans le réseau et mises à jour régulièrement (v9.7 au 2 juillet 2026). Le mécanisme est expliqué sur Peppol, les identifiants sur Identifiants Peppol et l'aspect pratique sur envoyer et recevoir via Peppol.

Pour un développeur, la conséquence est simple : vous ne parlez jamais directement au réseau. C'est le point d'accès de quelqu'un qui le fait, et la question est de savoir lequel. Construire son propre point d'accès signifie adhérer à OpenPeppol, obtenir l'accréditation, exploiter une passerelle AS4 et publier dans un SMP. Passer par KRONENWERK signifie que le point d'accès est celui de Storecove, que la connexion appartient à l'entreprise et que votre code ne parle qu'à l'API KRONENWERK.

Le flux : brouillon, émission, transmission, webhook

1. Votre application crée le client avec POST /customers. Donnez au client un pays et un numéro de TVA : l'identifiant de participant Peppol d'un destinataire belge est dérivé de son numéro d'entreprise ou de TVA, et un client qui n'en a pas ne peut pas être adressé sur le réseau.
2. Votre application démarre le brouillon avec POST /invoices/drafts et une Idempotency-Key. La réponse est un brouillon à l'état DRAFT avec la proposition de numérotation du vendeur et les conditions de paiement du client.
3. Une personne émet le brouillon dans le produit. KRONENWERK calcule le verdict fiscal, vérifie le numéro de TVA dans VIES, génère l'UBL Peppol BIS Billing 3.0 pour un vendeur belge, le valide et consomme le numéro. invoice.issued est mis en file d'attente pour votre endpoint à ce moment-là.
4. La facture est transmise depuis le produit. La transmission est une action distincte et auditée sur la facture émise, pas un effet secondaire de l'émission : le module pays désigne le canal (Peppol pour la Belgique), le prestataire de point d'accès connecté transporte le document, et le résultat est consigné sur la facture. Si le résultat est inconnu — un timeout après le départ de la requête — le produit refuse de renvoyer tant qu'un appel de réconciliation n'a pas demandé à l'autre partie si elle détient le document. Réessayer un résultat inconnu, c'est ainsi qu'une facture devient deux.
5. Votre application reçoit invoice.issued, vérifie KRONENWERK-Signature, déduplique sur KRONENWERK-Event-Id et stocke invoiceId et number. Plus tard suivent invoice.paid ou invoice.cancelled.

Ce qu'un développeur doit configurer

Notez ce qui n'est pas dans la liste : pas de SMP, pas de certificat AS4, pas d'adhésion à OpenPeppol de votre côté. Notez aussi ce que l'API ne peut pas faire : elle ne peut pas connecter l'entreprise au réseau, ne peut pas transmettre et ne peut pas lire le journal de transmission. Ce sont des paramètres et des actes qu'une personne effectue dans le produit.

Exemples de requêtes

curl -X POST https://kronenwerk.org/api/extern/v1/customers \
  -H "Authorization: Bearer greif_live_…" \
  -H "Idempotency-Key: crm-account-88213" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Voorbeeld BV",
    "street": "Rue de l'"'"'Exemple 12",
    "postalCode": "1000",
    "city": "Bruxelles",
    "country": "BE",
    "vatId": "BE0123456789",
    "email": "invoices@example.be"
  }'

curl -X POST https://kronenwerk.org/api/extern/v1/invoices/drafts \
  -H "Authorization: Bearer greif_live_…" \
  -H "Idempotency-Key: crm-account-88213-2026-09" \
  -H "Content-Type: application/json" \
  -d '{ "customerId": "3f2b…" }'

La réponse client porte le numéro de partenaire tiré de la séquence propre à l'entreprise (par exemple K-0042) et les champs tels qu'enregistrés : id, number, name, contact, email, phone, street, postalCode, city, country, vatId, currency, customer, supplier, archived, createdAt. Le nom, la rue, le code postal et la ville sont obligatoires parce que l'EN 16931 porte une adresse décomposée en parties, et qu'un client sans rue est un client auquel aucun document ne peut être adressé. L'API factures est décrite en détail sur la page de l'API factures.

Recevoir via Peppol

En Belgique, l'obligation de recevoir des factures structurées via Peppol s'applique aux entreprises identifiées à la TVA sans seuil, de sorte qu'une connexion qui ne fait qu'envoyer ne couvrirait que la moitié de l'obligation. Une fois l'entreprise connectée, les documents Peppol entrants arrivent chez le prestataire de point d'accès, sont remis à KRONENWERK, importés en factures fournisseurs et validés. Votre intégration en prend connaissance via le webhook purchase.recorded, qui porte purchaseId, kind, documentNumber, supplierName, supplierId, documentDate, dueDate, currency, netMinor, taxMinor et grossMinor. Le document entrant lui-même n'est pas exposé sur l'API. Le contexte belge se trouve sur le hub Belgique et la page pays Belgique.

Les alternatives, comparées honnêtement

Si votre besoin est un envoi entièrement automatisé sans qu'une personne n'émette, l'API de KRONENWERK ne le permet pas aujourd'hui, et un contrat direct avec un prestataire est la recommandation honnête. Le guide Peppol pour développeurs couvre ce que vous devriez construire dans ce cas ; Peppol vs réseaux nationaux explique où Peppol est le canal et où c'est un système national (KSeF, plateformes agréées françaises).

Comment KRONENWERK gère cela

PRIS EN CHARGE AVEC RESTRICTIONS KRONENWERK génère l'UBL Peppol BIS Billing 3.0 pour les vendeurs belges à l'émission et envoie et reçoit via Peppol par l'intermédiaire d'un prestataire de point d'accès accrédité (Storecove) une fois l'entreprise connectée dans Paramètres → Envoi. KRONENWERK n'est pas lui-même un point d'accès Peppol accrédité ou certifié. L'envoi en production dépend du compte Storecove de l'entreprise et de sa configuration, et la transmission est une action qu'une personne effectue dans le produit après l'émission. La part de l'API est le client, le brouillon, la relecture et les webhooks, sur le plan Enterprise. Le canal Peppol est câblé pour les vendeurs belges ; pour les vendeurs allemands, le produit génère XRechnung ou ZUGFeRD pour e-mail ou téléchargement et ne désigne aucun canal de transmission, car le droit allemand n'en désigne aucun. La transmission française est un mécanisme différent et est PAS ENCORE PRÊTE — voir plateformes françaises. Détails du produit : facturation électronique.