API de facturation électronique : XRechnung, ZUGFeRD, Factur-X, Peppol BIS

KRONENWERK ne dispose pas d'un endpoint distinct de « génération de facture électronique ». Les factures électroniques structurées sont produites et validées au moment où une facture est émise dans le produit, dans le format exigé par le pays du vendeur : XRechnung ou ZUGFeRD en Allemagne, Factur-X en France, Peppol BIS Billing 3.0 UBL en Belgique, XML FA(3) en Pologne. Votre intégration crée le brouillon avec POST /invoices/drafts et reçoit invoice.issued lorsque le document validé existe. Séparément, un vérificateur gratuit et anonyme à l'adresse POST /api/v1/meta/pruefen valide n'importe quel fichier selon les règles d'un pays et ne conserve rien.

Comment les formats structurés sont produits à partir d'un brouillon

Un brouillon contient des faits : vendeur, acheteur, lignes, dates, devise. Lorsqu'une personne l'émet, le module pays de l'entité juridique du vendeur transforme ces faits en document attendu par ce pays et valide le résultat avant que le numéro de facture ne soit consommé. Les mêmes faits produisent un PDF pour le lecteur et un fichier structuré pour la machine ; la syntaxe structurée et le profil dépendent du pays et des paramètres de l'entreprise.

1. Le verdict fiscal est calculé à partir des faits (pays du vendeur et de l'acheteur, professionnel ou consommateur, nature de l'opération) et le numéro de TVA de l'acheteur est vérifié dans VIES. Un verdict « nécessite une saisie » bloque l'émission jusqu'à ce qu'une personne décide.
2. Le module pays génère le document structuré — UBL, CII, PDF/A-3 avec CII intégré, ou XML FA(3).
3. Le document est validé selon les règles publiées par ce pays. Un document allemand passe par les règles Schematron KoSIT et est contre-vérifié avec la bibliothèque Mustang ; les validateurs exécutés sont enregistrés avec le résultat.
4. Ce n'est que si la validation réussit que le numéro est consommé, que la ligne d'archive est gelée et que invoice.issued est mis en file d'attente pour votre endpoint webhook.

C'est pourquoi l'API s'arrête au brouillon. Un document qui échoue à la validation est un document qu'une personne doit corriger, et les champs qui déterminent le format sont des paramètres de l'entité juridique, pas des paramètres d'une requête. Le raisonnement est exposé sur la page de l'API factures.

Comportement par pays à l'émission

XRechnung, ZUGFeRD, Factur-X et Peppol BIS sont tous des implémentations du modèle sémantique européen EN 16931 ; ZUGFeRD et Factur-X sont techniquement le même standard hybride, publié conjointement par le FeRD et le FNFE-MPE. FA(3) est le schéma propre à la Pologne et n'est pas une syntaxe EN 16931. Les formats sont comparés sur formats de factures électroniques ; le choix allemand est expliqué sur XRechnung vs ZUGFeRD.

Ce que l'API expose au sujet des factures électroniques

Moins que vous ne pourriez le penser, et la liste est exacte.

• POST /invoices/drafts démarre le brouillon qui deviendra le document structuré. Il n'accepte que customerId.
• GET /invoices et GET /invoices/{number} renvoient les chiffres gelés de la facture émise : number, documentType, buyer, currency, issuedOn, dueOn, deliveredOn, net, tax, gross, outstanding, paymentState, overdue, cancelled, creditNote, paidOn, recordedAt.
• Le webhook invoice.issued signale qu'un document validé existe désormais, avec invoiceId, number, documentType, buyerName, issueDate, dueDate, currency, netMinor, taxMinor, grossMinor, amountDueMinor et paymentState.

Non exposés, et inaccessibles quel que soit le scope : le fichier XML ou PDF lui-même, le rapport de validation d'une facture émise, le raisonnement du verdict fiscal, l'état de transmission Peppol ou KSeF, et tout endpoint qui émet, envoie ou annule. Les fichiers se téléchargent dans le produit ; la transmission y est configurée et suivie. Rien ne promet ici qu'une future version de l'API ajoutera le téléchargement de fichiers.

Le vérificateur gratuit : POST /api/v1/meta/pruefen

Le vérificateur valide un fichier selon les règles d'un pays et répond par un verdict structuré. Il ne nécessite ni compte ni clé API, et il ne conserve rien — ni le fichier, ni une empreinte, ni une ligne. Il existe parce que toute entreprise allemande doit accepter les factures électroniques structurées depuis le 1er janvier 2025 et que la plupart n'ont aucun moyen de savoir si celle qui vient d'arriver est valide ; facturer cette vérification reviendrait à facturer la conformité elle-même. La version navigateur se trouve sur vérifier une facture électronique.

La requête est un multipart/form-data à deux parties : datei (le fichier) et land (le code pays ISO dont les règles s'appliquent : DE, FR, BE, PL, CA ou US). Le pays est obligatoire. Il valait autrefois l'Allemagne par défaut, et une facture belge vérifiée selon les règles allemandes obtient une réponse assurée qui est assurément fausse.

curl -X POST https://kronenwerk.org/api/v1/meta/pruefen \
  -F "datei=@rechnung.xml" \
  -F "land=DE"

{
  "istERechnung": true,
  "lesbar": true,
  "gueltig": false,
  "format": "XRechnung (UBL)",
  "profil": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0",
  "zusammenfassung": "…",
  "lieferant": "Beispiel GmbH",
  "nummer": "2026-0041",
  "rechnungsdatum": "2026-08-28",
  "waehrung": "EUR",
  "nettoMinor": 89000,
  "steuerMinor": 16910,
  "bruttoMinor": 105910,
  "fehler": [
    { "schwere": "…", "quelle": "…", "regel": "BR-DE-15", "ort": "…", "meldung": "…" }
  ],
  "hinweise": [],
  "leseprobleme": [],
  "validatoren": ["KoSIT validationtool …", "…"]
}

Les trois booléens répondent à trois questions différentes. istERechnung : s'agit-il d'une facture électronique structurée, par opposition à un simple PDF ou une image. lesbar : le document a-t-il pu être lu en tant que facture. gueltig : respecte-t-il les règles du pays. Un simple PDF donne istERechnung: false et n'est pas une erreur. fehler et hinweise sont des listes de constats, chacun avec une sévérité, le validateur qui l'a émis, l'identifiant de la règle, un emplacement et un message. leseprobleme énumère les problèmes d'extraction, validatoren les validateurs qui ont réellement été exécutés, de sorte qu'une vérification partielle apparaisse comme partielle. Les totaux ne sont présents que lorsque le document est cohérent ; un document qui ne l'est pas constitue déjà un constat, et n'afficher aucun total vaut mieux qu'afficher une estimation. Les valeurs de format, profil et zusammenfassung dépendent du fichier et sont données ci-dessus à titre d'illustration.

Limites du vérificateur

• Les fichiers de plus de 25 Mo sont refusés avec un 413 avant qu'un seul octet ne soit analysé. Une vraie facture électronique avec son XML intégré pèse quelques centaines de kilooctets.
• Les requêtes sont limitées par adresse client : un budget de 5 vérifications qui se recharge à raison d'une vérification toutes les 60 secondes. Au-delà, la réponse est un 429 avec un en-tête Retry-After et un corps JSON indiquant combien de temps attendre. Le vérificateur est un outil pour les personnes et les scripts occasionnels, pas un service de validation en masse.
• Rien n'est stocké, il n'y a donc ni historique ni lien pour y revenir. Conservez la réponse si vous en avez besoin.
• Le vérificateur valide ; il ne tranche pas les questions juridiques. Savoir si un document qui passe est aussi une facture correcte aux fins de la TVA dans votre situation nécessite une confirmation professionnelle.

Recevoir des factures structurées

Les mêmes lecteurs que ceux du vérificateur sont utilisés dans le produit : les documents XRechnung, ZUGFeRD/Factur-X et UBL entrants sont importés en factures fournisseurs avec leur fournisseur, numéro, date et totaux, et leur résultat de validation est conservé avec la facture. Ce chemin entrant n'est pas exposé sur l'API publique aujourd'hui ; les factures fournisseurs enregistrées dans le produit sont signalées vers l'extérieur par le webhook purchase.recorded avec purchaseId, kind, documentNumber, supplierName, supplierId, documentDate, dueDate, currency, netMinor, taxMinor et grossMinor. Les obligations de réception allemandes sont expliquées sur recevoir des factures électroniques en Allemagne.

Comment KRONENWERK gère cela

PRIS EN CHARGE AVEC RESTRICTIONS La génération et la validation de XRechnung, ZUGFeRD, Factur-X, Peppol BIS UBL et FA(3) à l'émission font partie du produit (facturation électronique). La part de l'API dans tout cela, c'est le brouillon, la relecture et le webhook, sur le plan Enterprise (tarifs). Le vérificateur est gratuit pour tous. C'est du côté du transport que se situent les restrictions : l'envoi et la réception Peppol passent par 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 ; la transmission française via une plateforme agréée est prévue via la capacité de plateforme agréée de Storecove et n'est pas encore prête pour la production ; le module polonais KSeF 2.0 n'a pas été utilisé contre le KSeF de production. Chacun fait l'objet de sa propre page : intégration Peppol, intégration KSeF, et le guide des formats pour développeurs sur EN 16931 pour les développeurs.