Aperçu
Adresse de base : https://api.normapi.de. Les requêtes et les réponses sont en UTF-8, et une erreur est un document JSON de problème (RFC 9457).
Contrôler et lire une facture ne demandent pas de clé, dans les limites d'un usage raisonnable. Pour créer des factures, vous créez vous-même une clé, qui porte le quota de votre forfait, et vous l'envoyez dans l'en-tête Authorization, sous la forme Bearer nk_live_….
Créer un compte (en anglais) est gratuit et ne demande pas de carte bancaire. Le contrôle et la lecture restent gratuits et ne sont jamais décomptés.
| Point d'accès | Rôle |
|---|---|
POST /v1/validate | Contrôler une facture, en XML (CII ou UBL) ou en PDF Factur-X, par les règles françaises du FNFE-MPE ou par celles de la KoSIT. |
POST /v1/parse | Lire une facture reçue en JSON, dans la forme exacte que prend POST /v1/invoices. |
POST /v1/invoices | Créer depuis du JSON un Factur-X, un CII ou un UBL contrôlé, dans notre mise en page ou dans votre propre PDF. |
POST /v1/validate : contrôler une facture
Le document est le corps brut de la requête, sans multipart ni base64. Son type est reconnu à son contenu, jamais à l'en-tête Content-Type. Dans un PDF Factur-X, c'est la facture jointe qui est contrôlée.
Avec rules=france, la facture est jugée par les règles françaises du FNFE-MPE (France_RFE). Un PDF Factur-X est alors contrôlé aussi comme fichier : le PDF/A-3, et le niveau Factur-X que déclarent ses métadonnées XMP.
Sans ce paramètre, ce sont les règles de la KoSIT et de la norme EN 16931. Une facture au profil EXTENDED-CTC-FR est jugée par les règles françaises dans les deux cas. Toute autre valeur de rules est un 400.
Quand une facture contrôlée sans les règles françaises semble française (un vendeur français, un SIREN, un cadre de facturation ou une mention obligatoire française), la réponse porte suggestedRules à france. Ce n'est qu'une indication : le verdict reste celui des règles appliquées.
Avec l'en-tête Accept-Language à fr, les explications sont en français, et Content-Language le confirme. Le texte des règles lui-même n'est pas traduit.
curl -X POST 'https://api.normapi.de/v1/validate?rules=france' \
-H 'Accept-Language: fr' \
-H 'Content-Type: application/pdf' \
--data-binary @f02-services-facturx.pdf{
"acceptable": true,
"wellFormed": true,
"schemaValid": true,
"schematronValid": true,
"businessRulesEvaluated": true,
"rulesetVersion": "FNFE France_RFE 1.4.0.04 (CEN 15 May 2026, Factur-X 1.09.2)",
"scenario": "France Factur-X EN16931",
"findings": [],
"rules": "france",
"notChecked": [
"siren-status",
"ppf-directory",
"invoice-number-uniqueness",
"rules-outside-schematron"
]
}Ce que disent les champs. Trois sont souvent mal lus :
| Champ | Sens |
|---|---|
acceptable | Le verdict. La seule réponse sur laquelle fonder une décision d'acceptation ou de refus. |
schematronValid | Pas un verdict, mais « les règles n'ont rien signalé du tout ». Les jeux de règles émettent des avis sur des factures valides, et un seul avis met ce champ à false alors qu'acceptable reste à true. |
businessRulesEvaluated | Vaut false quand une erreur de schéma a arrêté le contrôle. Une liste findings vide veut alors dire « pas contrôlé », jamais « rien à redire ». |
rules | france quand les règles françaises ont jugé le document, demandées par rules=france ou choisies par une facture EXTENDED-CTC-FR. Absent sous les règles de la KoSIT. |
suggestedRules | france quand une facture contrôlée sans les règles françaises semble française. Une indication seulement. Absent sinon. |
scenario | Le scénario de règles qui a jugé le document, ici « France Factur-X EN16931 ». null : aucun scénario ne l'a reconnu, rien n'a été contrôlé, et acceptable à false est alors un refus de juger, pas un jugement. |
rulesetVersion | La version des règles qui ont jugé, comme dans l'en-tête X-Normapi-Ruleset. |
findings[] | Chaque message avec le code de sa règle, sa gravité (ERROR, WARNING ou INFORMATION), le texte de la règle, sa position en XPath et le test qui a échoué. |
findings[].explanation | La règle en clair : ce qu'elle exige (meaning), pourquoi elle se déclenche le plus souvent (cause), comment corriger (fix), et le lien vers sa ligne du répertoire des erreurs (url). Chaque règle métier est expliquée, les règles françaises comprises. null sur ce qui n'est pas une règle métier, comme une erreur de schéma. |
findings[].advisory | Seulement sur un constat qui ne compte pas pour le verdict. en16931-core : une facture Factur-X au profil EXTENDED est jugée par les règles EXTENDED officielles. Ce que les règles de base de la norme EN 16931 y trouvent en plus figure à côté, avec la gravité INFORMATION. |
notChecked[] | Sous les règles françaises, ce qui n'a pas été contrôlé. Ce sont l'état du SIREN, l'annuaire du portail public de facturation, l'unicité du numéro de facture et les règles françaises qu'aucun schematron ne couvre : aucun validateur ne peut les contrôler sur la seule facture. Pour un acheteur public, s'y ajoutent les règles de Chorus Pro, qui n'ont pas encore de schematron officiel. Absent quand la liste est vide. |
POST /v1/parse : lire une facture reçue
Le chemin inverse de POST /v1/invoices : une facture électronique reçue, en CII ou en UBL, ou un PDF Factur-X, revient en JSON. Le point d'accès prend exactement ce que prend POST /v1/validate : le document en corps brut, reconnu à son contenu, jusqu'à 5 Mo.
Dans un PDF, c'est la facture jointe qui est lue. La lecture est gratuite, sans clé, et n'est jamais décomptée.
curl -X POST https://api.normapi.de/v1/parse \
-H 'Content-Type: application/pdf' \
--data-binary @f02-services-facturx.pdf{
"syntax": "cii",
"documentKind": "invoice",
"source": {"kind":"pdf","attachment":"factur-x.xml"},
"specificationId": "urn:cen.eu:en16931:2017",
"businessProcess": "S1",
"profile": "france",
"invoice": {
"invoiceNumber": "F2026-0002",
"issueDate": "2026-11-03",
"typeCode": "380",
"seller": { "name": "Atelier Exemple SAS", "registrationId": "100000009", ... },
"buyer": { "name": "Maison Exemple SARL", ... },
"lines": [{ "name": "Conseil en aménagement d'atelier", ... }, ...],
"france": {
"recipient": "business",
"operation": "services",
"stage": "standard",
"vatOnDebits": false,
"vatFranchise": false,
"discountTerms": "Escompte de 2 % pour tout paiement sous 8 jours.",
"latePenalty": "Pénalités de retard : taux de refinancement de la BCE majoré de 10 points",
"recoveryFee": "Indemnité forfaitaire pour frais de recouvrement en cas de retard de paiement : 40 €"
},
...
},
"stated": { "netTotal": "1850.00", "vatTotal": "370.00", "grossTotal": "2220.00", "amountDue": "2220.00", ... },
"notMapped": [],
"validation": null
}Une facture française est lue dans invoice.france. Une facture est française quand son vendeur semble français et qu'elle porte une marque de la France. Le vendeur semble français par le pays FR ou un département d'outre-mer, ou par un SIREN sous le schéma 0002. La marque est un cadre de facturation en BT-23, ou l'une des mentions PMT, PMD, AAB, BAR, ADN et TXD.
Le résultat nomme alors le profil france quand trois conditions sont réunies. BT-24 vaut urn:cen.eu:en16931:2017, la facture est française au sens ci-dessus, et l'objet france a été lu en entier : un cadre de facturation que france peut porter et un destinataire connu.
L'objet france peut être présent alors que profile vaut autre chose, ou null : la facture ne peut alors pas être recréée telle quelle sous profile=france. La description de profile, dans la spécification OpenAPI, dit quoi faire.
| Champ | Sens |
|---|---|
invoice | La facture dans la forme exacte que prend POST /v1/invoices : la lire, la modifier, la créer à nouveau, sans conversion entre les deux. Chaque champ est présent, et ce que le document ne contient pas vaut null. |
invoice.france | Ce que la France ajoute à la facture, dans la forme que prend la requête avec profile=france : le destinataire, la nature de l'opération, l'étape du cadre de facturation et les mentions de paiement. |
stated | Ce que NormAPI calcule lui-même quand il crée une facture, et ne prend donc pas dans la requête. Ce sont les totaux (BT-106 à BT-115), la ventilation de la TVA (BG-23) et le montant net de chaque ligne (BT-131). En chaînes, exactement comme le document les écrit. |
notMapped[] | Chaque valeur du document que la réponse ne porte pas, sous forme de chemin sans positions, avec son nombre d'occurrences. Pour une facture que NormAPI a créée, la liste est vide. Rien ne se perd sans que vous le voyiez. |
profile | La valeur de profile de POST /v1/invoices qui déclare exactement cette spécification (BT-24) : xrechnung, en16931 ou france, à passer pour créer la facture à nouveau sous les mêmes règles. null pour toute autre déclaration, comme EXTENDED-CTC-FR. |
syntax, source, documentKind | ubl ou cii ; xml ou pdf, et pour un PDF le nom du fichier joint ; invoice ou creditNote. En CII, le code de type (BT-3) décide, puisque les deux partagent un même élément racine. |
validation | Avec validate=true, le verdict exactement comme le rend POST /v1/validate. Sans ce paramètre, null : aucune règle ne tourne. |
POST /v1/invoices : créer une facture
À partir des données de la facture en JSON, l'API rend un document contrôlé : un UBL par défaut, un CII avec syntax=cii, ou un PDF Factur-X avec syntax=zugferd. Ce PDF est un PDF/A-3, avec la facture jointe et une page lisible.
Le serveur calcule chaque total en arithmétique décimale : le montant net des lignes, la ventilation de la TVA, les totaux du document. Les règles de calcul BR-CO sont donc respectées par construction.
Aucune facture ne sort sans contrôle. Un 200 porte un document qui a passé les règles. Si votre JSON décrit une facture que les règles refusent, la réponse est un 422 avec les constats, et chacun nomme les champs de votre JSON qu'il concerne.
Pour un vendeur établi en France : profile=france
Le profil écrit la facture EN 16931 avec ce que la loi française y ajoute. Ce sont le cadre de facturation en BT-23, les mentions PMT, PMD, AAB et BAR ou ADN, les mentions obligatoires françaises, et pour un PDF Factur-X une page en français.
Il la contrôle par les règles françaises du FNFE-MPE (BR-FR) avant de la rendre. La facture déclare la même spécification qu'avec profile=en16931 (BT-24), et un PDF Factur-X porte le profil EN 16931.
Il demande l'objet france de la requête, avec au moins recipient et operation. Le pays du vendeur doit être FR ou un département d'outre-mer (BR-FR-MAP-14).
La requête est contrôlée avant que rien ne soit écrit. Une erreur que les règles françaises refuseraient dans le document est un 400 qui nomme le champ, et la règle ou l'article quand il y en a un. Ce que seul le document écrit montre, comme une valeur hors d'une liste de codes, reste un 422.
Sans profile, l'API écrit une XRechnung, ce que demandent les administrations allemandes. Avec profile=en16931, c'est la norme EN 16931 seule, pour une entreprise. Toute autre valeur est un 400.
profile=extended-ctc-fr est un 400 : NormAPI n'écrit pas le profil EXTENDED-CTC-FR, qu'exige notamment la facture multi-vendeurs d'une place de marché. Si vous en avez besoin, écrivez à kontakt@normapi.de : nous comptons ces demandes pour décider de le construire.
pdfLanguage choisit la langue de la page d'un PDF Factur-X : ses mots, ses dates et ses nombres. Par défaut fr sous profile=france, et de sous les autres profils. Les mentions obligatoires françaises restent en français sur une page allemande.
Le paramètre est ignoré là où aucune page n'est imprimée (syntax=ubl, syntax=cii, votre propre PDF), et il est alors nommé dans X-Normapi-Ignored-Fields. Une valeur autre que de ou fr est un 400.
La requête f02 des exemples Factur-X, une prestation de services, qui devient un PDF Factur-X. Python et PHP lisent le même fichier JSON :
curl -X POST 'https://api.normapi.de/v1/invoices?syntax=zugferd&profile=france' \
-H "Authorization: Bearer $NORMAPI_KEY" \
-H 'Content-Type: application/json' \
-o facture.pdf \
--data-binary @- <<'JSON'
{
"invoiceNumber": "F2026-0002",
"issueDate": "2026-11-03",
"dueDate": "2026-12-03",
"deliveryDate": "2026-10-31",
"invoicePeriod": {
"startDate": "2026-10-01",
"endDate": "2026-10-31"
},
"currency": "EUR",
"seller": {
"name": "Atelier Exemple SAS",
"vatId": "FR88100000009",
"electronicAddress": "facturation@atelier-exemple.example",
"address": {
"street": "12 rue des Tanneurs",
"city": "Lyon",
"postcode": "69002",
"country": "FR"
},
"registrationId": "100000009",
"legalInformation": "SAS au capital de 40 000 EUR, RCS Lyon 100 000 009"
},
"buyer": {
"name": "Maison Exemple SARL",
"vatId": "FR37200000008",
"address": {
"street": "55 avenue de la République",
"city": "Nantes",
"postcode": "44000",
"country": "FR"
},
"registrationId": "200000008"
},
"payment": {
"meansCode": "58",
"iban": "FR2012542547256985425874698",
"reference": "F2026-0002",
"accountName": "Atelier Exemple SAS",
"bic": "EXMPFRPP"
},
"paymentTerms": "Paiement à 30 jours par virement.",
"lines": [
{
"name": "Conseil en aménagement d'atelier",
"description": "Octobre 2026",
"quantity": 18,
"unit": "HUR",
"unitPrice": 85,
"vatCategory": "S",
"vatRate": 20
},
{
"name": "Rapport de synthèse",
"quantity": 1,
"unit": "C62",
"unitPrice": 320,
"vatCategory": "S",
"vatRate": 20
}
],
"france": {
"recipient": "business",
"operation": "services",
"discountTerms": "Escompte de 2 % pour tout paiement sous 8 jours."
}
}
JSONimport os
import requests
# la requête f02 des exemples Factur-X
with open("f02-services-normapi.json", "rb") as f:
body = f.read()
r = requests.post(
"https://api.normapi.de/v1/invoices",
params={"syntax": "zugferd", "profile": "france"},
headers={
"Authorization": f"Bearer {os.environ['NORMAPI_KEY']}",
"Content-Type": "application/json",
},
data=body,
)
r.raise_for_status()
with open("facture.pdf", "wb") as f:
f.write(r.content)<?php
// la requête f02 des exemples Factur-X
$invoice = file_get_contents('f02-services-normapi.json');
$ch = curl_init('https://api.normapi.de/v1/invoices?syntax=zugferd&profile=france');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('NORMAPI_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $invoice,
CURLOPT_RETURNTRANSFER => true,
]);
$pdf = curl_exec($ch);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) !== 200) {
throw new RuntimeException($pdf);
}
file_put_contents('facture.pdf', $pdf);Le corps de la réponse est le document lui-même : le PDF ou le XML, à écrire dans un fichier. Les en-têtes disent d'où il vient :
| En-tête | Contenu |
|---|---|
X-Normapi-Ruleset | La version des règles qui ont jugé le document, sous profile=france celles du FNFE-MPE. |
X-Normapi-Scenario | Le scénario de règles que le document a passé. |
X-Normapi-Quota-Used | Les factures créées ce mois-ci, seulement avec une clé qui porte un quota. |
X-Normapi-Quota-Limit | Le quota du forfait. Une fois atteint, POST /v1/invoices répond 402. |
X-Normapi-Daily-Remaining | Sans clé : combien de factures restent pour aujourd'hui, celle-ci déjà décomptée. L'en-tête X-Normapi-Daily-Limit donne la limite du jour. |
X-Request-Id | L'identifiant de cet appel, sur chaque réponse. Citez-le quand vous nous écrivez. |
Idempotent-Replayed | true sur la répétition d'un appel déjà réussi sous la même Idempotency-Key : la même facture, sans nouveau décompte (voir Nouvelles tentatives). |
X-Normapi-Ignored-Fields | Les champs de vos données qu'aucune partie d'une facture ne connaît, et qui ne sont donc dans aucun document. Un champ mal orthographié explique souvent un champ manquant. |
X-Normapi-Customer | Le client pour lequel l'appel a compté, seulement quand vous en avez nommé un (voir Clients). Avec X-Normapi-Customer-Used et X-Normapi-Customer-Limit quand il a un plafond. |
X-Normapi-Letterhead | Sur un PDF Factur-X dans notre mise en page, quand votre compte a un papier à en-tête : son identifiant quand le PDF est imprimé dessus, none sinon. Avec X-Normapi-Letterhead-Skipped et la raison (voir Papier à en-tête). |
Avoirs, factures rectificatives et factures d'acompte se choisissent avec typeCode (BT-3), et la référence à la facture antérieure va dans precedingInvoices (BG-3). Un 381 est écrit comme un document UBL CreditNote, comme les règles le demandent. Les montants restent positifs : le type du document dit dans quel sens va l'argent.
Avec profile=france, les types sont ceux de la règle BR-FR-04 : 380, 389, 393, 501, 386, 500, 384, 471, 472, 473, 261, 262, 381, 396, 502 et 503. Le schéma France de la spécification dit lesquels demandent precedingInvoices, contractReference ou invoicePeriod. Sous profile=france, une facture définitive après acompte se déclare par france.stage à final (BT-23).
"typeCode": "381",
"precedingInvoices": [
{ "number": "F2026-0002", "issueDate": "2026-11-03" }
]Remises et frais existent au niveau du document (allowances, charges, chacun avec sa propre catégorie de TVA) et par ligne, sans catégorie de TVA : celle de la ligne s'applique. Donnez un montant ou un pourcentage. Le serveur calcule le montant depuis le pourcentage, arrondi au centime (la moitié vers le haut), et avec lui chaque total et la ventilation de la TVA.
"allowances": [
{ "amount": 9.80, "reason": "Remise de fidélité", "reasonCode": "95",
"vatCategory": "S", "vatRate": 20 }
],
"charges": [
{ "amount": 12.50, "reason": "Frais de port", "reasonCode": "FC",
"vatCategory": "S", "vatRate": 20 }
],
"lines": [
{ "name": "Licence logicielle, abonnement annuel", "quantity": 3, "unit": "C62",
"unitPrice": 199.00, "vatCategory": "S", "vatRate": 20,
"allowances": [
{ "percent": 10, "reason": "Remise sur quantité", "reasonCode": "95" }
] }
]Moyens de paiement : virement (58, 30) avec un compte, prélèvement SEPA (59) avec un mandat, paiement par carte (48, 54, 55) avec une carte, et tout autre code UNTDID 4461 sans rien de plus. Chaque moyen ne porte que son propre groupe, et ce sont les règles qui jugent quel groupe va avec quel code. Sous les règles XRechnung, un IBAN du bénéficiaire à côté d'un prélèvement est un 422 (BR-DE-25-b), pas un 400.
"payment": {
"meansCode": "59",
"reference": "F2026-0002",
"directDebit": {
"mandateReference": "MANDAT-2026-001",
"creditorId": "FR12ZZZ123456",
"debitedAccount": "FR7630006000011234567890189"
}
}Votre propre PDF
Si votre logiciel met déjà ses factures en page, gardez cette mise en page : envoyez votre PDF, et NormAPI y joint le XML contrôlé.
La requête est en multipart, avec les données de la facture dans la partie invoice (le même JSON que plus haut) et votre PDF dans la partie pdf, jusqu'à 5 Mo.
La syntaxe est zugferd, la seule qu'un PDF puisse porter, et peut donc être omise. Il faut une clé d'API, et l'appel compte pour une facture créée, comme les autres.
curl -X POST 'https://api.normapi.de/v1/invoices?profile=france' \
-H 'Authorization: Bearer nk_live_…' \
-F 'invoice=@f02-services-normapi.json;type=application/json' \
-F 'pdf=@votre-facture.pdf;type=application/pdf' \
-o facture.pdfContrôlé deux fois avant d'être rendu.
Le XML est contrôlé par les règles, comme chaque facture créée, et la conformité PDF/A-3 du fichier fini, avec veraPDF.
NormAPI corrige d'abord lui-même deux défauts fréquents, sans changer la page. Une police Helvetica ou Arial non incorporée est remplacée par Liberation Sans, de mêmes métriques, qui est incorporée. Les images perdent les clés que PDF/A interdit (Interpolate, Alternates, OPI).
Un fichier qui ne peut toujours pas devenir un PDF/A-3 revient en 422, dont les violations nomment les clauses de l'ISO 19005-3 qu'il enfreint.
Le plus souvent, une autre police n'est pas incorporée : exportez le PDF en PDF/A (1b, 2b ou 3b) depuis le logiciel qui le produit, puis refaites l'appel.
Un PDF qui porte déjà une facture électronique est refusé plutôt qu'écrasé. Chaque refus de votre PDF porte, à côté du texte, une reason que votre programme peut tester : not-pdfa, uncheckable, unreadable, already-invoice, not-rewritable, too-large ou not-pdf.
{
"type": "https://normapi.de/problems/pdf-not-pdfa",
"title": "PDF cannot become a PDF/A-3",
"status": 422,
"reason": "not-pdfa",
"violations": [
{ "clause": "6.2.11.4.1", "test": 1, "occurrences": 1,
"description": "The font programs for all fonts used for rendering within a conforming file shall be embedded ..." }
]
}Votre papier à en-tête
Un PDF Factur-X dans notre mise en page (syntax=zugferd, sans votre propre PDF) est imprimé par NormAPI sur le papier à en-tête de votre compte, quand il en a un. L'adresse du destinataire tombe alors dans la fenêtre de l'enveloppe.
Vous le déposez une fois, en PDF, dans le compte : Letterhead, dans le compte (en anglais). Le dépôt, le remplacement et la suppression n'existent que là, et l'API n'a pas de point d'accès pour eux. Le papier à en-tête est compris dans chaque forfait, le gratuit aussi, et les factures imprimées dessus comptent comme toute autre facture créée. Une facture XML (UBL ou CII) n'a pas de page et reste telle quelle.
Vous déposez un fichier PDF de 5 Mio au plus, d'une ou deux pages A4 en portrait. Ses images vont jusqu'à 10 mégapixels en couleur (30 en niveaux de gris), et ses dessins jusqu'à 512 Kio par page.
La première page sert d'en-tête à la première page d'une facture, la seconde aux pages suivantes ; un fichier d'une page sert à toutes.
Dans le compte, vous choisissez aussi si le papier à en-tête vaut pour chaque facture du compte ou pour un seul vendeur. Ce vendeur se reconnaît à son identifiant à la TVA, à son identifiant fiscal (BT-32) ou à son nom, et il suffit que l'un d'eux corresponde.
# Sur le papier à en-tête du compte, s'il en a un (par défaut)
curl -X POST 'https://api.normapi.de/v1/invoices?syntax=zugferd&profile=france' \
-H 'Authorization: Bearer nk_live_…' \
-H 'Content-Type: application/json' \
--data-binary @f02-services-normapi.json -o facture.pdf -D -
# Dans la mise en page standard de NormAPI
curl -X POST 'https://api.normapi.de/v1/invoices?syntax=zugferd&profile=france&letterhead=none' ...Le paramètre de requête letterhead décide à chaque appel :
| Valeur | Sens |
|---|---|
auto | Par défaut : le papier à en-tête de votre compte, sauf si l'une des raisons ci-dessous s'y oppose. |
none | La mise en page standard de NormAPI. |
Le paramètre vaut pour les appels avec une clé d'API : sans clé, il n'y a ni compte ni papier à en-tête. Toute autre valeur est un 400 qui nomme letterhead, pour UBL et CII aussi, où la valeur n'a sinon aucun effet.
Un appel avec votre propre PDF ne le lit pas : votre PDF est alors la mise en page.
Deux en-têtes de réponse disent ce qui s'est passé. Ils ne viennent qu'avec un PDF Factur-X dans notre mise en page, et seulement quand votre compte a un papier à en-tête. Sans papier à en-tête, et pour un XML, ils sont absents.
# Le PDF est imprimé sur le papier à en-tête
X-Normapi-Letterhead: lh_9f2c4e1a7b3d45f6a8c0e2b4d6f81357
# Mise en page standard, avec la raison
X-Normapi-Letterhead: none
X-Normapi-Letterhead-Skipped: requested| X-Normapi-Letterhead-Skipped | Raison |
|---|---|
requested | L'appel a envoyé letterhead=none. |
customer-call | L'appel est pour l'un de vos clients, par l'en-tête X-Normapi-Customer ou par une clé liée à un client (voir Clients). Votre papier à en-tête n'est jamais imprimé sur les factures de vos clients. |
seller-mismatch | Le papier à en-tête est pour un seul vendeur, et le vendeur de la facture en est un autre. |
needs-confirmation | Le contrôle du papier à en-tête a relevé des remarques encore à confirmer dans le compte, par le bouton « Use it anyway ». |
recheck-failed | Le contrôle qui suit une mise à jour de NormAPI a échoué, et le compte en montre la raison. |
render-failed | Le papier à en-tête n'a pas pu servir pour cette facture, à cause d'une erreur de notre côté. La facture a été créée dans la mise en page standard. |
Si plusieurs raisons s'appliquent, l'en-tête nomme la première dans cet ordre. Avec une Idempotency-Key, une répétition nomme le papier à en-tête sur lequel la facture du premier appel a été imprimée. S'il a changé depuis, la répétition est une autre requête (422 idempotency-key-reused).
Champs à remplacer. Si l'un de ces champs est du texte de votre papier à en-tête, NormAPI y met sa valeur sur chaque page, en Liberation Sans, à la taille et à la position du champ. Majuscules et minuscules sont indifférentes.
| Champ | Remplacé par |
|---|---|
[RECHNUNGSNUMMER] | Le numéro de la facture (BT-1). Aussi [INVOICE NUMBER]. |
[SEITE] | Le numéro de la page. Aussi [PAGE] et [X]. |
[SEITEN] | Le nombre de pages. Aussi [PAGES] et [Y]. |
Les champs s'écrivent en allemand ou en anglais ; ils n'ont pas de forme française.
Sans champs à remplacer, les pages suivantes d'une facture en français commencent par « Facture F2026-0002 · Page 2 sur 3 », ou par « Avoir … » pour un avoir. Si NormAPI ne reconnaît pas les champs du papier à en-tête, par exemple parce que la police n'a pas de correspondance Unicode, l'aperçu du compte le dit.
Le champ d'adresse selon la DIN 5008. NormAPI imprime le destinataire dans le champ d'adresse et les données de la facture dans le bloc d'informations, aux positions de la norme allemande DIN 5008:2020. Elles se mesurent en millimètres depuis le bord supérieur de la page, et le corps de la facture va de 25 à 190 mm du bord gauche.
| Zone | Forme B | Forme A |
|---|---|---|
| Champ d'adresse, 85 × 45 mm, à 20 mm du bord gauche | 45 à 90 mm | 27 à 72 mm |
| Zusatz- und Vermerkzone (zone de mentions) : le haut du champ d'adresse, où se trouve la ligne d'expéditeur de votre papier à en-tête | 45 à 62,7 mm | 27 à 44,7 mm |
| Anschriftzone (zone d'adresse), à 25 mm du bord gauche : là où NormAPI imprime l'adresse du destinataire | 62,7 à 90 mm | 44,7 à 72 mm |
| Bloc d'informations, de 125 à 190 mm du bord gauche : les données de la facture | dès 50 mm | dès 32 mm |
| Titre : l'intitulé imprimé, « FACTURE » sur une facture en français (sa ligne de base) | 98,46 mm | 80,46 mm |
| Repères de pliage | 105 et 210 mm | 87 et 192 mm |
NormAPI reconnaît la forme aux repères de pliage du papier à en-tête ou, sans repères, à la ligne d'expéditeur dans la Zusatz- und Vermerkzone. S'il ne trouve ni l'un ni l'autre, le papier à en-tête compte comme sans fenêtre : l'adresse et les données de la facture se placent alors directement dessous.
Dans le compte, vous pouvez changer la forme de l'enveloppe et les marges. L'aperçu y montre une facture d'exemple sur votre papier à en-tête, avec le champ d'adresse en pointillés.
Nouvelles tentatives : Idempotency-Key
Après un délai dépassé, vous ne pouvez pas distinguer « jamais arrivé » de « créé, mais la réponse s'est perdue ». Envoyez un en-tête Idempotency-Key, de 1 à 255 caractères ASCII imprimables (un UUID ou votre numéro de facture), et réessayez avec la même clé.
Si le premier appel a réussi, vous recevez de nouveau la facture, marquée par l'en-tête Idempotent-Replayed à true, et elle n'est pas décomptée une seconde fois.
Une clé d'idempotence reste valable 24 heures, et seule son empreinte SHA-256 est gardée : ni la clé elle-même ni la facture ne sont conservées. Elle ne sert qu'aux appels avec une clé d'API, ceux qui sont décomptés.
curl -X POST 'https://api.normapi.de/v1/invoices?syntax=zugferd&profile=france' \
-H 'Authorization: Bearer nk_live_…' \
-H 'Idempotency-Key: F2026-0002' \
-H 'Content-Type: application/json' \
--data-binary @f02-services-normapi.json -o facture.pdf| Situation | Réponse |
|---|---|
| Premier appel avec la clé | Il se déroule comme d'habitude. |
| Même clé, même requête, et le premier appel a réussi | 200 avec la même facture, Idempotent-Replayed à true, sans décompte, même si le quota est épuisé depuis. |
| Le premier appel a échoué (400, 422, 503…) | La clé est de nouveau libre : corrigez les données et réessayez avec la même clé. |
| Même clé pendant que le premier appel tourne encore | 409, avec l'en-tête Retry-After à 1. |
| Même clé pour une autre requête : d'autres données, une autre syntaxe ou un autre PDF | 422 idempotency-key-reused : une nouvelle facture demande une nouvelle clé. |
Une répétition est créée de nouveau plutôt que lue dans un stockage, puisque les factures ne sont pas conservées. La facture est la même ; les horodatages internes d'un PDF peuvent différer.
Les clients de votre logiciel
Quand votre logiciel crée des factures pour ses propres clients (comptabilité, boutique en ligne, portail), nommez le client de chaque appel dans l'en-tête X-Normapi-Customer, avec votre propre référence pour lui.
Cela reste un seul compte avec un seul quota, mais NormAPI compte chaque client à part. Dans le compte, sous Customers (en anglais), vous voyez ce que chacun a créé dans le mois, et vous pouvez fixer un plafond pour chacun.
curl -X POST 'https://api.normapi.de/v1/invoices?syntax=zugferd&profile=france' \
-H 'Authorization: Bearer nk_live_…' \
-H 'X-Normapi-Customer: client-42' \
-H 'Content-Type: application/json' \
--data-binary @f02-services-normapi.json -o facture.pdf| Question | Réponse |
|---|---|
| Que peut-il contenir ? | De 1 à 64 caractères : lettres, chiffres, point, tiret bas, deux-points et trait d'union, en commençant par une lettre ou un chiffre. La casse compte. Tout le reste est un 400 invalid-request, avec l'en-tête dans rejectedFields. |
| À quoi s'applique-t-il ? | À chaque appel sous /v1 fait avec une clé d'API : contrôle, lecture et création. La réponse le renvoie. Sans clé, il est ignoré, puisque rien n'est alors décompté. |
| Et le quota ? | Il n'y en a qu'un, celui du compte : les factures de tous vos clients s'imputent ensemble sur le forfait. |
| Avec une Idempotency-Key ? | Le client fait partie de la requête. La même Idempotency-Key pour un autre client est une autre requête : 422 idempotency-key-reused. |
Une clé par client. Une clé peut être liée à un client à sa création. Chaque appel fait avec elle compte pour ce client, avec ou sans en-tête ; un appel dont l'en-tête nomme un autre client reçoit un 400 customer-mismatch. Un client qui tient sa propre clé ne peut donc pas imputer ses appels à un autre. Une clé liée ne lit que son propre client sous /v1/customers et ne change aucun plafond (403 customer-bound-key).
Un plafond par client. Pour chaque client, vous pouvez fixer le nombre maximal de factures qu'il crée dans un mois civil (UTC). Ce qui compte, c'est ce qui a été créé : les refus ne comptent pas, et la répétition d'un appel réussi sous la même Idempotency-Key est livrée même au plafond.
Une fois le plafond atteint, /v1/invoices répond 429 customer-quota-exceeded pour ce client, avec un Retry-After jusqu'au début du mois suivant. Le contrôle et la lecture restent gratuits, et vos autres clients continuent.
En dessous du plafond, les réponses réussies portent X-Normapi-Customer-Used (les factures créées ce mois-ci) et X-Normapi-Customer-Limit.
{
"type": "https://normapi.de/problems/customer-quota-exceeded",
"title": "Monthly ceiling for this customer reached",
"status": 429,
"customer": "client-42",
"used": 500,
"limit": 500,
"resetsAt": "2026-11-01T00:00:00Z"
}Les chiffres pour votre facturation sont aussi dans l'API, avec la même clé et sans décompte :
| Appel | Effet |
|---|---|
GET /v1/customers?month=2026-10 | Chaque client du mois, le plus actif d'abord : les factures créées (generated), les créations refusées en 4xx (refused), les appels par point d'accès (calls) et le plafond (monthlyInvoices). Sans month, le mois en cours ; limit (de 1 à 1000, 100 par défaut) et cursor pour paginer. |
GET /v1/customers/{customer} | Un client dans le mois (month comme ci-dessus), avec des zéros pour un client qui n'a pas encore appelé. |
PUT /v1/customers/{customer}/allowance | Le corps, avec monthlyInvoices à 500 par exemple, fixe ou remplace le plafond (de 1 à 10 000 000), tout de suite et pour tout le mois. |
DELETE /v1/customers/{customer}/allowance | Retire le plafond. La réponse est un 204, qu'il y en ait eu un ou non. |
{
"month": "2026-10",
"customers": [
{ "customer": "client-42", "generated": 418, "refused": 3,
"calls": { "generate": 421, "validate": 96 }, "monthlyInvoices": 500 },
{ "customer": "client-7", "generated": 97, "refused": 0,
"calls": { "generate": 97 }, "monthlyInvoices": null }
],
"withoutCustomer": { "generated": 12, "refused": 1,
"calls": { "generate": 13, "validate": 40 } },
"nextCursor": null
}Une clé sans compte reçoit ici un 403 account-required, et un appel sans clé un 401. Quand nextCursor n'est pas null, le même appel avec cursor à cette valeur va chercher la page suivante.
Ce qui est contrôlé
Ce que veut dire acceptable à true dépend du document et des règles demandées. Tout ce qui suit tourne à chaque appel, sauf mention contraire, et « pas contrôlé » veut dire exactement cela.
Avec rules=france, ce sont les règles françaises : FNFE France_RFE 1.4.0.04 (CEN 15 mai 2026, Factur-X 1.09.2).
| Document (contrôle avec rules=france) | Règles appliquées | Verdict |
|---|---|---|
UBL ou CII au profil EN16931 (BT-24 urn:cen.eu:en16931:2017) | Le schéma, les règles de la norme EN 16931, puis les règles françaises BR-FR | Le verdict des règles. |
| UBL ou CII au profil EXTENDED-CTC-FR | Le schéma et les règles EXTENDED-CTC-FR, puis les règles françaises BR-FR | Le verdict des règles. Ce profil est jugé par les règles françaises même sans rules=france. |
| PDF Factur-X EN 16931 | Le XML joint, comme un CII au profil EN16931, et le fichier PDF lui-même (voir le PDF plus bas) | Le verdict des règles. |
| PDF Factur-X EXTENDED, le profil qui porte EXTENDED-CTC-FR dans un PDF | Les règles Factur-X EXTENDED, dans la version corrigée par le FNFE-MPE, puis les règles françaises BR-FR | Le verdict des règles. |
| PDF Factur-X BASIC WL | Le scénario BASIC WL du FNFE-MPE, puis les règles françaises BR-FR | Le verdict des règles, avec la note NORMAPI-FR-BASICWL (INFORMATION). Un profil transitoire : l'arrêté du 27 juillet 2026 ne le cite pas, et la note du FNFE-MPE le prévoit « juste la première année ». |
| Factur-X MINIMUM et BASIC, et tout autre identifiant de spécification (BT-24) | Aucune : les règles françaises ne contrôlent pas ces profils | acceptable à false, avec la note NORMAPI-FR-PROFILE (ERROR), qui cite les formats que l'arrêté permet. |
| Un message de cycle de vie (CDAR) ou un fichier d'e-reporting (flux 10) | Aucune : ce n'est pas une facture | acceptable à false, avec la note NORMAPI-FR-NOT-INVOICE (ERROR). |
Les notes NORMAPI-FR viennent de NormAPI, pas d'un jeu de règles, et leur texte le dit.
Les règles de Chorus Pro (BR-FR-CPRO) ne sont pas contrôlées : le FNFE-MPE n'en a pas encore publié de schematron officiel, et aucune date n'est annoncée. Pour un acheteur public, la liste notChecked le dit avec chorus-pro.
Sans rules=france, ce sont les règles de la KoSIT, dans sa configuration officielle v2026-08-31 (XRechnung 3.0.2).
| Document (contrôle sans rules=france) | Schéma XML | Règles EN 16931 | Règles XRechnung |
|---|---|---|---|
| XRechnung UBL, facture ou avoir, variantes Extension et CVD comprises | UBL 2.1 | contrôlées | contrôlées |
| XRechnung CII, et ZUGFeRD/Factur-X au profil XRECHNUNG | CII D16B | contrôlées | contrôlées |
| EN 16931 sans CIUS nationale : UBL, CII, et ZUGFeRD/Factur-X EN 16931 (autrefois COMFORT) | UBL 2.1 / CII D16B | contrôlées | sans objet |
| ZUGFeRD/Factur-X BASIC, un scénario que NormAPI ajoute, avec les règles EN 16931 officielles | CII D16B | contrôlées | sans objet |
| ZUGFeRD/Factur-X EXTENDED, un scénario que NormAPI ajoute, avec les règles EXTENDED officielles de Factur-X 1.09.2 | Factur-X EXTENDED | contrôlées comme EXTENDED les formule ; ce que les règles de base trouvent en plus figure en information, avec advisory en16931-core | sans objet |
| ZUGFeRD/Factur-X MINIMUM et BASIC WL, Peppol BIS Billing, tout le reste (scenario null) | pas contrôlé | pas contrôlées | pas contrôlées |
| Le PDF d'une facture hybride (contrôle) | Contrôlé ? |
|---|---|
| Le XML joint (factur-x.xml, xrechnung.xml ou zugferd-invoice.xml) | Contrôlé, comme dans les tableaux ci-dessus. |
| La conformité PDF/A-3 du fichier | Toujours contrôlée avec rules=france, les écarts en erreurs. Sous les règles de la KoSIT, avec le paramètre pdf=check (veraPDF), les écarts en avertissements ; le validateur de ce site le demande toujours. |
| Le profil déclaré dans les métadonnées XMP (ConformanceLevel), comparé au XML | Toujours contrôlé avec rules=france, un écart en erreur. Sous les règles de la KoSIT, avec pdf=check, un écart en avertissement. |
| Si la page montre ce que dit le XML | Pas contrôlé. |
| Création | XML | |
|---|---|---|
syntax=ubl, syntax=cii | Par défaut, XRechnung 3.0.2 avec ses trois couches de règles. Avec profile=en16931, le schéma et les règles EN 16931 ; avec profile=france, les règles françaises BR-FR en plus. À chaque appel. | Aucun. |
syntax=zugferd dans notre mise en page | Le profil XRECHNUNG avec ses trois couches de règles. Avec profile=en16931 ou profile=france, le profil EN 16931 avec le schéma et les règles EN 16931, et sous profile=france les règles françaises en plus. À chaque appel. | PDF/A-3 : le PDF de notre mise en page est vérifié avec veraPDF par la suite de tests, à chaque version, pas à chaque appel. |
syntax=zugferd sur votre PDF | Le profil XRECHNUNG, EN 16931 ou France, comme ci-dessus. À chaque appel. | PDF/A-3B avec veraPDF, à chaque appel. Les montants de votre page ne sont pas comparés à ceux du XML. |
Référence des champs : créer
Les champs obligatoires sont marqués d'un astérisque rouge. Pour le reste, ce sont les règles qui décident, et un refus nomme la règle, jamais un code d'erreur inventé par NormAPI.
Sous profile=france, la demande est d'abord vérifiée champ par champ, avant que rien ne soit écrit. La première erreur trouvée donne un 400 dont detail nomme le champ, et la règle ou l'article d'où vient la limite. Une facture que les règles refusent ensuite donne un 422 qui nomme chaque règle : voir les réponses d'erreur.
| Champ | Type | Signification |
|---|---|---|
| invoiceNumber * | texte | Numéro de la facture (BT-1). Sous profile=france, au plus 35 caractères parmi A-Z, a-z, 0-9 et + - _ /, et au plus 20 pour un acheteur public (BR-FR-01, BR-FR-02, BR-FR-CPRO-02) |
| issueDate * | AAAA-MM-JJ | Date d'émission (BT-2). Sous profile=france, entre 2000 et 2099 (BR-FR-03) |
| typeCode | UNTDID 1001 | Type de document (BT-3), 380 par défaut, la facture commerciale. Sous les règles allemandes : 326 facture partielle, 381 avoir, 384 facture rectificative, 389 facture auto-facturée, 875, 876 et 877 pour les factures de travaux. Un autre code y donne l'avertissement BR-DE-17. Sous profile=france, les types de BR-FR-04 : voir les avoirs |
| dueDate | AAAA-MM-JJ | Date d'échéance (BT-9). Sans dueDate ni paymentTerms, la facture n'indique aucun délai de paiement. Sous profile=france, elle ne précède pas issueDate, sauf pour une facture d'acompte ou son avoir (386, 500, 503) et pour une facture déjà payée (BR-FR-CO-07) |
| deliveryDate | AAAA-MM-JJ | Date de livraison (BT-72). Sans elle ni invoicePeriod, les règles donnent un avertissement. Sous profile=france en Factur-X, donnez-la, ou un deliverTo, ou un despatchAdviceReference : sinon les règles Factur-X du FNFE-MPE avertissent par PEPPOL-EN16931-R008. La facture est tout de même créée, car NormAPI n'invente pas de date |
| deliverTo | DeliverTo | Lieu de livraison (BG-13), quand ce n'est pas simplement l'acheteur : name (BT-70), locationId (BT-71, par exemple le GLN) avec locationIdScheme (BT-71-1, 0088 pour un GLN), address (BG-15, comme l'adresse plus bas). Nécessaire pour une livraison intracommunautaire (catégorie K) : sans pays de livraison, les règles la refusent (BR-IC-12) |
| invoicePeriod | Period | Période de facturation (BG-14) : startDate (BT-73) et endDate (BT-74), chacune au format AAAA-MM-JJ, et une seule borne suffit. À la place de deliveryDate ou à côté, par exemple pour une facture mensuelle |
| currency * | ISO 4217 | Devise de la facture (BT-5), par exemple EUR |
| buyerReference | texte | Référence de l'acheteur (BT-10), la Leitweg-ID pour un acheteur public allemand. Obligatoire en XRechnung (BR-DE-15), facultative avec profile=en16931 |
| orderReference | texte | Numéro du bon de commande de l'acheteur (BT-13). Pour un acheteur public français, c'est le numéro d'engagement que Chorus Pro peut exiger, 50 caractères au plus |
| contractReference | texte | Numéro de contrat (BT-12), 50 caractères au plus pour un acheteur public français. Sous profile=france, un avoir pour remise globale (262) le nomme, avec les deux bornes de invoicePeriod |
| projectReference | texte | Numéro de projet (BT-11) |
| despatchAdviceReference | texte | Numéro du bon de livraison (BT-16) |
| attachments | Attachment[] | Pièces jointes (BG-24), 20 au plus : id (BT-122, sinon le nom du fichier), description (BT-123), le fichier en content (base64, BT-125) avec filename et mimeCode, ou une url (BT-124). Formats permis : PDF, PNG, JPEG, CSV, XLSX et ODS (BR-CL-24), chaque nom de fichier une seule fois (BR-DE-22), 3 Mo en tout. En CII, deux fichiers ou descriptions donnent les avertissements CII-SR-475 et CII-SR-476, un défaut connu de ces règles du CEN. Sous profile=france, une description est l'un des codes de BR-FR-17, comme RIB, LISIBLE ou BON_COMMANDE, et LISIBLE ne vient qu'une fois (BR-FR-18) |
| precedingInvoices | PrecedingInvoice[] | Factures antérieures citées (BG-3) : number (BT-25, obligatoire), issueDate (BT-26). Attendues pour une facture rectificative 384 (BR-DE-26). Une seule en CII et en Factur-X, dont le schéma n'a de place que pour une. Sous profile=france, une facture rectificative (384, 471, 472, 473) en cite exactement une, et un avoir (261, 381, 396, 502, 503) au moins une, chacune avec sa date |
| note | texte | Note libre (BT-22). Sous profile=france, elle ne porte pas de code du sujet entre dièses, comme #PMT#, car NormAPI écrit lui-même ces notes (BR-FR-05, BR-FR-06, BR-FR-20, BR-FR-31). Un # qui n'est pas un code, comme dans « Facture #12 », est accepté |
| seller * | Party | Vendeur (BG-4), voir plus bas |
| buyer * | Party | Acheteur (BG-7), voir plus bas |
| payment * | Payment | Instructions de paiement (BG-16), voir plus bas |
| paymentTerms | texte | Conditions de paiement (BT-20). En XRechnung, un escompte s'écrit aussi pour la machine, sur une ligne #SKONTO#TAGE=14#PROZENT=2.00# (BR-DE-18). Sous profile=france, l'escompte va dans france.discountTerms |
| allowances | AllowanceCharge[] | Remises sur le document (BG-20), voir plus bas |
| charges | AllowanceCharge[] | Frais sur le document (BG-21), voir plus bas |
| prepaidAmount | nombre | Montant déjà payé (BT-113), comme des acomptes avant une facture définitive, et le montant à payer (BT-115) baisse d'autant. Sous profile=france, pour une facture déjà payée (france.stage à paid), il est égal au total, et rempli pour vous si vous l'omettez |
| lines * | Line[] | Au moins une ligne (BG-25), voir plus bas |
| taxCurrency | ISO 4217 | Devise de comptabilisation de la TVA (BT-6), quand ce n'est pas currency. Elle va avec vatTotalInTaxCurrency, et l'un sans l'autre, ou la devise de la facture elle-même, donne un 400 (BR-53). Sous profile=france, c'est EUR (BR-FR-CO-12), rempli pour vous quand la facture est dans une autre devise |
| vatTotalInTaxCurrency | nombre | Total de la TVA dans taxCurrency (BT-111), deux décimales. Vous le donnez, car un taux de change est un fait du jour, pas un calcul. Sous profile=france, une facture dans une autre devise que l'euro en a besoin (BR-FR-CO-12, BR-53), et la page imprime la TVA en euros |
| france | France | Ce que seule la France demande, obligatoire avec profile=france : voir son tableau, plus bas |
Party La même forme pour le vendeur et l'acheteur. Ce qu'il faut de chaque côté, ce sont les règles qui le disent : le vendeur a besoin d'une identité fiscale, et en XRechnung d'un contact, l'acheteur non.
| Champ | Type | Signification |
|---|---|---|
| name * | texte | Raison sociale (BT-27 / BT-44) |
| identifier | texte | Identifiant de la partie (BT-29 / BT-46). Utile au vendeur sans identifiant à la TVA : le numéro fiscal allemand satisfait BR-DE-16, mais seul un identifiant satisfait BR-CO-26, et y répéter le numéro fiscal convient. Sous profile=france, pour un acheteur public, c'est le SIRET de chacune des deux parties (BR-FR-CPRO-09, BR-FR-CPRO-10) |
| identifierScheme | ISO 6523 | Schéma de identifier (BT-29-1 / BT-46-1) : 0009 pour un SIRET, 0160 pour un GTIN. Écrit seulement quand il est donné, et seulement avec un identifier, car donné seul, il donne un 400. Sous profile=france, un identifiant a besoin du sien (BR-FR-CO-10), et 0009 est écrit pour les SIRET d'une facture à un acheteur public. Le 0231 du vendeur ne se donne pas ici : il vient de france.singleTaxablePerson |
| vatId | texte | Identifiant à la TVA (BT-31), par exemple FR88100000009 ou DE123456789 |
| taxNumber | texte | Numéro fiscal allemand, la Steuernummer (BT-32). Sous profile=france, un vendeur en franchise en base sans identifiant à la TVA ni numéro fiscal y répète son SIREN, rempli pour vous (BR-FR-CO-16) |
| electronicAddress | texte | Adresse électronique (BT-34 / BT-49), en Allemagne le plus souvent un courriel. La XRechnung l'exige des deux côtés (PEPPOL-EN16931-R020 et PEPPOL-EN16931-R010), l'EN 16931 non. Sous profile=france, elle est demandée des deux côtés, 125 caractères au plus (BR-FR-12, BR-FR-13). Pour un acheteur professionnel, et pour le vendeur d'une autofacturation entre professionnels, le SIREN sous le schéma 0225 en tient lieu, écrit pour vous si vous l'omettez (BR-FR-21, BR-FR-22) |
| electronicAddressScheme | code EAS | Schéma de l'adresse, EM (courriel) par défaut. Sous profile=france, 0225 est écrit pour l'adresse d'un acheteur professionnel donnée sans schéma, ou en autofacturation pour celle du vendeur. Sous 0225, l'adresse ne contient que des lettres non accentuées, des chiffres, le tiret, le tiret bas et le point (BR-FR-23) |
| address * | Address | street (facultatif), city, postcode, country (ISO 3166-1 alpha-2) : city et postcode sont obligatoires. Sous profile=france, le pays du vendeur doit être FR ou un département d'outre-mer (GP, MQ, RE, GF, YT). Celui de l'acheteur aussi pour business et public, et ni l'un ni l'autre pour abroad (BR-FR-MAP-14) |
| contact | objet | name, phone, email : obligatoires pour le vendeur en XRechnung (BR-DE-2 à BR-DE-7), avec des contrôles de vraisemblance (BR-DE-27, BR-DE-28). Facultatifs avec profile=en16931, même un par un |
| tradingName | texte | Nom commercial, à côté de la raison sociale (BT-28 / BT-45) |
| registrationId | texte | Immatriculation (BT-30 / BT-47), par exemple un SIREN ou HRB 123456. Elle identifie le vendeur comme le fait un identifiant à la TVA (BR-CO-26). Sous profile=france, c'est le SIREN, 9 chiffres, du vendeur toujours, et d'un acheteur professionnel ou public (BR-FR-10, BR-FR-11, BR-FR-09) |
| registrationIdScheme | ISO 6523 | Schéma de registrationId (BT-30-1 / BT-47-1) : 0002 pour un SIREN, aucun pour un registre allemand. Sous profile=france, 0002 est écrit quand vous n'en donnez pas, pour le vendeur et pour un acheteur professionnel ou public. L'immatriculation d'un acheteur à l'étranger ou d'un particulier reste sans schéma |
| legalInformation | texte | Vendeur seulement (BT-33), et sur l'acheteur c'est un 400. Ce que le droit des sociétés veut voir sur les documents commerciaux, au-delà du nom et de l'immatriculation. Pour une société allemande, ce sont le siège, le tribunal du registre et les dirigeants (§ 35a GmbHG, § 80 AktG, § 37a HGB). La page Factur-X l'imprime avec l'immatriculation |
Payment et Line Le paiement, puis chaque ligne de la facture.
| Champ | Type | Signification |
|---|---|---|
| payment.meansCode * | UNTDID 4461 | 58 virement SEPA, 30 virement, 59 prélèvement SEPA, 48, 54 et 55 carte. Les autres codes (10, 20, ZZZ…) vont sans groupe supplémentaire |
| payment.meansText | texte | Moyen de paiement en clair (BT-82), par exemple « Virement SEPA » |
| payment.iban | texte | Compte du bénéficiaire (BT-84), exigé par BR-DE-23-a pour les codes 58 et 30. Sur un avoir, le compte où le montant est versé. Pour un acheteur public français, 27 caractères exactement, comme le veut Chorus Pro |
| payment.accountName | texte | Titulaire du compte (BT-85) |
| payment.bic | BIC | BIC de la banque du bénéficiaire (BT-86), 8 ou 11 caractères |
| payment.reference | texte | Libellé du virement (BT-83) |
| payment.card | Card | Pour 48, 54 et 55 (BG-18) : number (BT-87), les 4 à 6 derniers chiffres seulement, sans astérisque ni espace, et plus de 10 chiffres donnent un 400. Puis holder (BT-88) et network (par exemple VISA, en UBL seulement) |
| payment.directDebit | DirectDebit | Pour 59 (BG-19), les trois : mandateReference (BT-89), creditorId (BT-90, votre identifiant de créancier), debitedAccount (BT-91, l'IBAN du client). Laissez alors votre propre IBAN de côté |
| line.id | texte | Numéro de la ligne (BT-126), de 1 à n quand il est absent |
| line.name * | texte | Nom de l'article (BT-153) |
| line.description | texte | Description de l'article (BT-154) |
| line.quantity * | nombre | Quantité (BT-129), jusqu'à 6 décimales. Sous profile=france, 4 décimales au plus une fois les zéros de fin retirés (BR-FR-DEC-02), et 4.000000 s'écrit 4 |
| line.unit * | UN/ECE Rec 20 | Unité (BT-130) : C62 pièce, HUR heure, DAY jour… |
| line.unitPrice * | nombre | Prix unitaire net (BT-146), jusqu'à 4 décimales. Avec baseQuantity, c'est le prix de ce nombre d'unités. Sous profile=france, il n'est jamais négatif, et un avoir porte des prix positifs (BR-FR-DEC-03) |
| line.vatCategory * | UNTDID 5305 | S taux normal · Z taux zéro · E exonération · AE autoliquidation · K livraison intracommunautaire · G exportation · O hors du champ de la TVA · L et M. O reste seul : aucune autre catégorie à côté, pas d'identifiant à la TVA chez le vendeur ni chez l'acheteur, et un motif d'exonération. Le vendeur se présente alors par taxNumber et identifier. Sous profile=france, L et M sont refusés (BR-FR-15), et K et G sont réservés à abroad |
| line.vatRate | pourcentage | Taux de TVA (BT-152), obligatoire pour S. Sous profile=france, l'une des valeurs 0, 0.9, 1.05, 1.75, 2.1, 5.5, 7, 8.5, 9.2, 9.6, 10, 13, 19.6, 20 et 20.6 (BR-FR-16) |
| line.vatExemptionReason | texte | Motif d'exonération (BT-120), que les règles demandent pour E, AE, K et G, par exemple « Kleinunternehmer gemäß § 19 UStG ». Sous profile=france, E hors franchise en base, K, G et O en ont besoin, en toutes lettres (CGI 242 nonies A I 12°). Pour une autoliquidation sans motif, « Autoliquidation » est écrit pour vous |
| line.allowances | LineAllowanceCharge[] | Remises sur la ligne (BG-27) : amount ou percent, baseAmount, reason, reasonCode, sans catégorie de TVA. Le net de la ligne (BT-131) vaut quantité × prix ÷ baseQuantity, moins les remises, plus les frais |
| line.charges | LineAllowanceCharge[] | Frais sur la ligne (BG-28), de même forme |
| line.period | Period | Période que couvre la ligne (BG-26), comme invoicePeriod |
| line.orderLineReference | texte | Ligne du bon de commande que cette ligne facture (BT-132) |
| line.note | texte | Note sur cette ligne (BT-127) |
| line.sellerItemId | texte | Référence de l'article chez le vendeur (BT-155) |
| line.buyerItemId | texte | Référence du même article chez l'acheteur (BT-156) |
| line.standardItemId | texte | Identifiant sous un schéma enregistré (BT-157), le plus souvent le GTIN (EAN) de l'emballage |
| line.standardItemIdScheme | ISO 6523 | Schéma de cet identifiant (BT-157-1), 0160, le GTIN, quand il est absent |
| line.listPrice | nombre | Prix catalogue avant rabais (BT-148), au moins unitPrice. NormAPI calcule le rabais (BT-147), listPrice moins unitPrice. Sous profile=france, il n'est jamais négatif (BR-FR-DEC-03) |
| line.baseQuantity | nombre | Quantité de base du prix (BT-149) : le nombre d'unités auquel s'appliquent unitPrice et listPrice, par exemple 100 pour des vis vendues par cent, et 1 quand elle est absente. Sous profile=france, 4 décimales au plus (BR-FR-DEC-02) |
AllowanceCharge Une remise ou des frais sur le document. Sur une ligne, les mêmes champs, sans les trois de la TVA.
| Champ | Type | Signification |
|---|---|---|
| amount | nombre | Montant (BT-92 / BT-99), deux décimales. Il faut exactement l'un des deux, amount ou percent |
| percent | pourcentage | Pourcentage (BT-94 / BT-101). Le serveur calcule le montant, arrondi au centime, la moitié vers le haut |
| baseAmount | nombre | Montant de base (BT-93 / BT-100), seulement avec percent, car une base sans pourcentage est une erreur (PEPPOL-EN16931-R042). Omis, c'est la somme des nets de ligne de même catégorie et de même taux de TVA, et sur une ligne, quantité × prix |
| reason | texte | Motif en clair (BT-97 / BT-104). reason ou reasonCode doit être présent |
| reasonCode | code | Pour une remise, UNTDID 5189, par exemple 95 rabais. Pour des frais, UNTDID 7161, par exemple FC fret |
| vatCategory * | UNTDID 5305 | Catégorie de TVA (BT-95 / BT-102) : elle décide quel groupe de TVA le montant baisse ou augmente. Avec france.vatFranchise, toujours E |
| vatRate | pourcentage | Taux de TVA (BT-96 / BT-103) |
| vatExemptionReason | texte | Motif d'exonération du groupe de TVA (BT-120), quand ce montant seul le crée |
L'objet france Ce que seule la France demande d'une facture va dans france, obligatoire avec profile=france. Ce que la France partage avec le reste de l'EN 16931 a son propre champ, plus haut : le SIREN est registrationId sous le schéma 0002, BT-13 est orderReference, BG-15 est deliverTo.
| Champ | Type | Signification |
|---|---|---|
| france.recipient * | texte | Le destinataire de la facture, qui décide de la note BAR ou ADN, des identifiants exigés de l'acheteur et des catégories de TVA possibles. business : une entreprise en France, note BAR à B2B, son SIREN exigé (BR-FR-11). abroad : une entreprise hors de France, BAR à B2BINT, avec sa propre adresse et son schéma, seul destinataire des catégories K et G. consumer : un particulier, BAR à B2C. public : un acheteur public français, dont les factures passent par Chorus Pro, note ADN à B2G, son SIREN et son SIRET exigés (BR-FR-CPRO-10, BR-FR-09). Le pays de l'acheteur en découle (BR-FR-MAP-14) |
| france.operation * | texte | Ce qui est facturé : la première lettre de BT-23, le cadre de facturation (BR-FR-08). goods donne B, services S, et mixed M, pour des biens et des services qui ne sont pas accessoires les uns des autres |
| france.stage | texte | L'étape de la facture : le chiffre de BT-23, donc B1, S1 ou M1 pour standard, la valeur par défaut. paid donne 2, une facture déjà payée, dont dueDate est la date du paiement et BT-113 le total entier (BR-FR-CO-09). final donne 4, la facture définitive après acompte, qui n'est elle-même ni une facture d'acompte ni un avoir de facture d'acompte : ni 386, ni 500, ni 503 (BR-FR-CO-08). Les autres codes du cadre de facturation ne sont pas proposés |
| france.vatOnDebits | booléen | Le choix de payer la TVA d'après les débits, BT-8, que la page imprime dans les mots prescrits, « Option pour le paiement de la taxe d'après les débits ». Pour les services seulement : avec operation à goods, c'est un 400 qui nomme france.vatOnDebits (BR-FR-MAP-03, CGI 269-2-c). false par défaut |
| france.vatFranchise | booléen | Le vendeur ne facture pas la TVA (franchise en base, CGI 293 B). Chaque ligne, remise et frais est en catégorie E, et une ligne d'une autre catégorie donne un 400 qui la nomme. BT-121 vaut VATEX-FR-FRANCHISE, et BT-120 porte les mots prescrits, « TVA non applicable, article 293 B du CGI », sauf si vous donnez un vatExemptionReason. false par défaut |
| france.discountTerms | texte | L'escompte pour paiement anticipé, ou son absence, en toutes lettres : la note AAB (BR-FR-05, BR-FR-06, L441-9). Omis, la note dit qu'il n'y a pas d'escompte. 500 caractères au plus |
| france.latePenalty | texte | Le taux des pénalités de retard, en toutes lettres : la note PMD (BR-FR-05, BR-FR-06, L441-10). Omis, la note donne le taux prévu à défaut par L441-10 : celui de refinancement de la BCE majoré de 10 points. 500 caractères au plus |
| france.recoveryFee | texte | Le montant de l'indemnité forfaitaire pour frais de recouvrement, en toutes lettres : la note PMT (BR-FR-05, BR-FR-06). Omis, 40 €, comme le fixe D441-5. 500 caractères au plus |
| france.serviceCode | texte | Le code service d'un acheteur public, BT-46 sous le schéma 0224 (BR-FR-CPRO-11), que Chorus Pro peut exiger pour un acheteur donné, comme il peut exiger un numéro d'engagement dans orderReference. Des lettres non accentuées, des chiffres, le tiret, le tiret bas et le point (BR-FR-24), 100 caractères au plus. Écrit en CII seulement, car en UBL et en Factur-X l'acheteur n'a qu'un identifiant, son SIRET (UBL-SR-16, FX-SCH-A-000164). Avec syntax=ubl ou syntax=zugferd, c'est un 400 qui nomme france.serviceCode : utilisez syntax=cii, ou donnez le numéro d'engagement dans orderReference |
| france.singleTaxablePerson | SingleTaxablePerson | L'assujetti unique dont le vendeur est membre (CGI 242 nonies A 5° bis) : BG-11, avec name (BT-62), address (BG-12) et vatId (BT-63), et memberId, l'identifiant du vendeur comme membre, 9 chiffres, tous obligatoires. NormAPI en écrit l'identifiant sous le schéma 0231 et la note TXD MEMBRE_ASSUJETTI_UNIQUE (BR-FR-CO-14, BR-FR-CO-15). La page imprime « Membre d'un assujetti unique » avec le nom, l'adresse et l'identifiant à la TVA. Donner vous-même seller.identifierScheme à 0231 est un 400 |
| france.billingAddress | Address | L'adresse de facturation de l'acheteur, quand ce n'est pas la sienne (L441-9). Imprimée sur la page seulement, car l'EN 16931 n'a pas de terme pour elle et le XML ne la porte pas |
Ce que vous omettez est rempli, pour que le XML et la page le portent. Ce sont le schéma 0002 d'un SIREN et 0009 d'un SIRET public, l'adresse électronique 0225 qui est le SIREN, et le SIREN d'un vendeur en franchise en base en BT-32.
S'y ajoutent le montant payé d'une facture déjà payée, taxCurrency à EUR pour une autre devise, et une quantité sans ses zéros de fin. Une date de livraison ou de prestation n'est jamais remplie.
Réponses d'erreur
Une erreur est un JSON de problème selon la RFC 9457, avec type, title, status et detail. Le statut a un sens :
| Statut | Signification | Que faire |
|---|---|---|
| 400 | La demande est inutilisable telle quelle, et detail nomme chaque champ en cause. Un champ manque ou est mal formé, comme un BIC ou un X-Normapi-Customer avec une espace. Ou il ne peut pas entrer dans un document : amount et percent ensemble, un pourcentage sans base, un numéro de carte de plus de 10 chiffres. Sous profile=france, aussi la première limite française enfreinte, avec sa règle. Aussi : une clé liée à un client, avec un en-tête qui en nomme un autre (customer-mismatch), ou un corps videType : invalid-request, customer-mismatch, invalid-document | Corriger la demande |
| 401 | La clé envoyée est inconnue ou révoquée. Sans clé, les limites anonymes s'appliquent, et une clé fausse est donc pire que pas de clé. Aussi : votre propre PDF envoyé sans clé (api-key-required)Type : invalid-api-key, api-key-required | Vérifier la clé |
| 402 | Le quota mensuel de factures créées est épuisé. Volontairement pas un 429 : cela ne veut pas dire « ralentissez », mais « le forfait est épuisé ». Contrôler et lire restent gratuitsType : quota-exceeded | Passer au forfait suivant, ou attendre le mois suivant |
| 403 | Sous /v1/customers : une clé sans compte (account-required), ou la clé d'un client qui lit les autres clients ou change un plafond (customer-bound-key)Type : account-required, customer-bound-key | Utiliser la clé du compte |
| 409 | Un appel avec la même Idempotency-Key est encore en cours. Sous /v1/customers : le compte tient déjà 100 000 plafonds (too-many-customer-allowances)Type : idempotency-key-in-use, too-many-customer-allowances | Réessayer avec la même clé après Retry-After, ou retirer les plafonds devenus inutiles |
| 413 | Un document de plus de 5 Mo, votre propre PDF compris, ou des données de facture de plus de 6 MoType : invalid-document | Ne pas réessayer |
| 415 | Le corps n'est ni du XML ni un PDF, ou la partie pdf n'est pas un PDFType : invalid-document | Ne pas réessayer |
| 422 | Lisible, mais pas permis. Un PDF sans facture intégrée, et à la lecture aussi un XML qui n'est pas une facture : mal formé, avec un DOCTYPE, ou avec un autre élément racine. À la création, des données que les règles refusent, où findings[] nomme chaque règle et fields les champs de votre JSON en cause. Ou votre propre PDF qui ne peut pas devenir un PDF/A-3 (violations[]), ou une Idempotency-Key reprise pour une autre demandeType : invalid-document, invoice-not-permitted, pdf-not-pdfa, idempotency-key-reused | Corriger les données, le PDF ou la clé |
| 429 | Votre budget de requêtes est épuisé, et Retry-After dit combien de secondes attendre. Sans clé, aussi : la limite de factures du jour est atteinte (daily-limit-reached), et Retry-After court jusqu'à minuit. Avec un client, aussi : il a atteint son plafond mensuel (customer-quota-exceeded), et Retry-After court jusqu'au début du mois suivantType : rate-limited, daily-limit-reached, customer-quota-exceeded | Attendre, puis réessayer, ou utiliser une clé, ou relever le plafond |
| 503 | Toutes les places de contrôle sont prises, ou pour un Factur-X toutes celles de rendu PDF : une charge de notre côté, pas une faute de votre partType : over-capacity | Réessayer après Retry-After |
Chaque type est une adresse sous https://normapi.de/problems/, suivie du nom que donne le tableau, par exemple https://normapi.de/problems/invoice-not-permitted. Ces adresses restent celles de normapi.de, ne changent pas, et sont faites pour être comparées telles quelles.
Comparez type, jamais title ni detail : ces deux textes sont faits pour être lus, et leur langue peut changer.
Les deux réponses ci-dessous sont celles que l'API a rendues le 21 novembre 2026 pour la facture f02 de la bibliothèque d'exemples, chacune avec une erreur introduite. L'en-tête Accept-Language valait fr : le message du champ refusé et l'explication du constat sont en français, les titres et le reste de detail en anglais.
{
"detail": "france.operation: ne doit pas être nul",
"instance": "/v1/invoices",
"status": 400,
"title": "Request body is invalid",
"type": "https://normapi.de/problems/invalid-request"
}{
"detail": "The data describes an invoice the rule set does not permit. Each finding names the violated rule and the request fields it concerns. Fields to correct: payment.meansCode (BR-CL-16).",
"instance": "/v1/invoices",
"status": 422,
"title": "Invoice not permitted by the rule set",
"type": "https://normapi.de/problems/invoice-not-permitted",
"rulesetVersion": "FNFE France_RFE 1.4.0.04 (CEN 15 May 2026, Factur-X 1.09.2)",
"findings": [
{
"code": "BR-CL-16",
"severity": "ERROR",
"text": "[BR-CL-16]-Payment means in an invoice MUST be coded using UNTDID 4461 code list",
"origin": "SCHEMATRON",
"line": null,
"column": null,
"explanation": {
"meaning": "Le type de moyen de paiement (BT-81) doit être l'un des codes de la liste UNTDID 4461. La valeur s'écrit exactement comme la liste l'écrit : sans espace à l'intérieur et avec les mêmes majuscules et minuscules.",
"cause": "Par exemple, le système d'origine enregistre la valeur sous forme d'abréviation interne ou de texte libre, comme « Virement » ou « SEPA », et la correspondance la reprend telle quelle. Convertir la valeur en un code de la liste demande une table que quelqu'un doit établir.",
"fix": "Convertissez la valeur en un code de la liste, au moyen d'une seule table de correspondance. Utilisez 58 pour un virement SEPA, 30 pour un virement ou 59 pour un prélèvement SEPA. En UBL, le code se place dans cac:PaymentMeans/cbc:PaymentMeansCode ; en CII, dans ram:SpecifiedTradeSettlementPaymentMeans/ram:TypeCode.",
"url": "https://normapi.com/fr/erreurs#BR-CL-16"
},
"fields": [
"payment.meansCode"
]
}
]
}Limites
- 30 requêtes par minute par appelant, qui servent aussi de budget de rafale. Au-delà, un 429 avec
Retry-After. - 10 factures créées par jour sans clé, par adresse IP (par /64 en IPv6), et le compteur repart à minuit, heure de Paris. Au-delà, un 429 de type
daily-limit-reached, avecRetry-Afterjusqu'à minuit. Les données refusées (400, 422) ne comptent pas, contrôler et lire n'ont pas de limite par jour, et une clé porte à la place le quota de son forfait. - 5 Mo par document, alors qu'une vraie facture électronique pèse quelques kilo-octets.
- Contrôles, lectures et rendus PDF simultanés en nombre limité. Sous charge, l'API répond vite par un 503 plutôt que lentement par des délais dépassés. Attendez un peu, puis réessayez.
- Quotas plus élevés pour une intégration : kontakt@normapi.de.
Bibliothèques clientes
@normapi/client : TypeScript, sans dépendance, pour Node 18 et plus, les navigateurs, Deno et Bun. Il couvre chaque point d'accès : validate(), parse() depuis la 0.7.0, et generateInvoice().
Les réponses en français, avec l'option language à fr, et les règles françaises, avec l'option rules à france, arrivent avec la 0.10.0, comme les champs rules, suggestedRules et notChecked. La 0.11.0 ajoute le profil france, l'objet france et l'option pdfLanguage.
Pour le papier à en-tête, generateInvoicePdf() prend l'option letterhead (auto ou none) depuis la 0.9.0, et rend letterhead et letterheadSkipped.
npm install @normapi/clientimport { validate } from '@normapi/client'
import { readFile } from 'node:fs/promises'
const result = await validate(await readFile('f02-services-facturx.pdf'), {
rules: 'france',
language: 'fr',
})
if (result.acceptable) {
console.log('conforme, contrôlée comme', result.scenario, 'par', result.rulesetVersion)
} else {
for (const f of result.findings) {
console.log(f.severity, f.code, ':', f.explanation?.fix ?? f.text)
}
}Pour tout autre langage, l'API est volontairement petite : un POST avec le document dans le corps. Les exemples curl plus haut se traduisent en quelques lignes dans n'importe quelle bibliothèque HTTP, ici en PHP.
<?php
$pdf = file_get_contents('f02-services-facturx.pdf');
$ch = curl_init('https://api.normapi.de/v1/validate?rules=france');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $pdf,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/pdf',
'Accept-Language: fr',
],
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
if ($result['acceptable']) {
echo "conforme, contrôlée comme {$result['scenario']}
";
} else {
foreach ($result['findings'] as $f) {
echo "{$f['severity']} {$f['code']} : {$f['text']}
";
if ($f['explanation'] !== null) {
echo " Correction : {$f['explanation']['fix']}
";
}
}
}Vous produisez vos factures avec une bibliothèque libre, comme Mustang ou factur-x ? Contrôlez-les par les règles françaises avec POST /v1/validate et rules=france, sans Java ni Docker de votre côté.
Spécification et Postman
La spécification OpenAPI 3.1 complète décrit chaque point d'accès, chaque statut et la structure des champs. Elle sert aux générateurs de code, aux serveurs fictifs et à l'import dans tout outil d'API, et elle est écrite en anglais.
Règles et versions
Chaque réponse nomme dans rulesetVersion le jeu de règles qui a rendu son verdict. Avec rules=france, et pour une facture créée sous profile=france, ce sont les règles françaises du FNFE-MPE, aujourd'hui FNFE France_RFE 1.4.0.04 (CEN 15 mai 2026, Factur-X 1.09.2). Une facture EXTENDED-CTC-FR est elle aussi jugée par les règles françaises. Sinon, ce sont celles de la KoSIT, aujourd'hui v2026-08-31.
Le FNFE-MPE publie ses règles sur GitHub sous le nom France_RFE, et la KoSIT met à jour celles de la XRechnung environ deux fois par an. Une facture valable aujourd'hui peut recevoir des avertissements ou des erreurs d'une version plus récente.
Ce que chaque version change : les règles en vigueur. Pour être prévenu : le flux Atom des règles, ou la lettre d'information, qui suit les règles de la KoSIT et paraît en allemand et en anglais.
Ce que veut dire chaque règle, et comment corriger la facture : la liste des codes d'erreur. Pour essayer sans écrire de code : le validateur, et avec un compte le bac à sable (en anglais) : de vrais appels pour créer, contrôler et lire, sans clé, avec l'appel en curl, TypeScript ou Python à côté.