Créez des fichiers XRechnung et ZUGFeRD et faites contrôler des fichiers de facture électronique depuis votre propre logiciel, avec un jeton d’accès personnel.
- POST /xrechnung produit un fichier XRechnung 3.0 (syntaxe CII, EN 16931), la version que couvre la configuration XRechnung 3.0.2, et le renvoie en application/xml.
- POST /zugferd produit un PDF ZUGFeRD 2.x (profil EN 16931) avec le XML intégré et sans mention d’InkVoice sur la page.
- POST /check lit un PDF ZUGFeRD ou Factur-X, ou un fichier XML XRechnung, CII ou UBL, envoyé tel quel comme corps de la requête (application/pdf, application/xml, text/xml, application/octet-stream ; les autres types reçoivent 415).
- GET /usage indique les appels comptés dans la période la plus récente (la période en cours tant que le plan est actif), par route. Le consulter n’est pas un appel d’API.
- Envoyer une facture à son destinataire, ou l’archiver pour vous.
- Contrôler un fichier au moment où elle le crée.
- Créer des avoirs ou des factures rectificatives, plusieurs taux de TVA sur une facture, des livraisons intracommunautaires (K), des exportations (G), ou des remises et frais au niveau du document.
- Donner des conseils fiscaux ou juridiques.
Le plan développeur
Le plan développeur coûte 19 € par mois et inclut 1 000 appels d’API par période pour l’espace de travail. InkVoice est un Kleinunternehmer (petite entreprise) au sens du § 19 UStG et ne facture pas de TVA : le prix est donc le prix final.
- Un appel qui a renvoyé un fichier ou un verdict (
acceptoureject) est compté, même si vous ne lisez pas la réponse. Les appels refusés ou ayant échoué, les contrôles avecnot_checkedet la consultation de l’utilisation ne sont pas comptés. - Une fois les appels inclus épuisés, les appels suivants sont refusés avec
api_call_limit_reachedjusqu’au début de la période suivante. Des appels simultanés peuvent dépasser la limite. Les appels non utilisés expirent à la fin de la période, et rien n’est facturé à l’appel. - Quand le plan se renouvelle, les appels non utilisés de la période précédente restent utilisables jusqu’à ce que Stripe ait transmis la nouvelle période à InkVoice, au plus tard 3 jours après le début de la nouvelle période ; un appel pendant ce temps compte pour les deux périodes.
- Il n’y a pas d’essai gratuit.
Le propriétaire de l’espace de travail souscrit le plan dans les paramètres de l’espace de travail et paie via Stripe. Le plan développeur est distinct du plan de l’espace de travail (gratuit, Pro ou Master) : souscrire, changer, résilier ou terminer l’un n’affecte pas l’autre. Les plans payants ne peuvent être souscrits que par des clients dont le siège, le domicile ou l’établissement pour lequel le plan est souscrit se trouve en Allemagne.
Votre premier appel
- 1Souscrire le plan développeur
Le propriétaire de l’espace de travail souscrit le plan dans les paramètres de l’espace de travail et paie via Stripe.
- 2Créer un jeton d’accès
Créez un jeton d’accès sous « Jetons d'accès » avec « Lecture et écriture ». Le jeton n’est affiché qu’une fois, à sa création.
- 3L’autoriser pour l’API
Un jeton ne fonctionne avec l’API qu’après que le propriétaire de l’espace de travail a activé « Autoriser l'API développeur » pour ce jeton sous « Jetons d'accès ». Cette option n’est activée d’office pour aucun jeton.
- 4Envoyer la facture
Mettez la requête de facture dans
invoice.jsonet le jeton dans la variable d’environnementINKVOICE_TOKEN, puis envoyez-la à/xrechnung. La réponse est le fichier XRechnung. En cas d’erreur, curl se termine avec un code de sortie non nul, et le fichier contient le corps de l’erreur, s’il y en a un (voir « Erreurs ») ;--fail-with-bodynécessite curl 7.76 ou plus récent.curl --fail-with-body -X POST https://api.inkvoice.net/api/v1/xrechnung \ -H "Authorization: Bearer $INKVOICE_TOKEN" \ -H "Content-Type: application/json" \ --data @invoice.json -o xrechnung.xml
Routes
Toutes les routes se trouvent sous https://api.inkvoice.net/api/v1. Chaque appel, sauf openapi.json, nécessite un jeton d’accès personnel sous la forme Authorization: Bearer inkv_…. Une connexion par le site web n’est pas acceptée, et les navigateurs ne peuvent pas appeler l’API (pas de CORS). Créer et contrôler nécessitent un jeton avec « Lecture et écriture » ; un jeton en lecture seule ne peut que consulter l’utilisation.
| Route | Corps | Réponse |
|---|---|---|
POST /xrechnung | La requête de facture en JSON | Le fichier XRechnung, application/xml |
POST /zugferd | La requête de facture en JSON | Le PDF ZUGFeRD, application/pdf |
POST /check | Le fichier lui-même, en application/pdf, application/xml, text/xml ou application/octet-stream | Ce que l’ensemble de règles a indiqué, en JSON |
GET /usage | Aucun | Les appels comptés dans la période la plus récente, par route, en JSON. Ce n’est pas un appel d’API |
GET /openapi.json | Aucun | La description de l’API, OpenAPI 3.1, lisible sans jeton |
La requête de facture
La requête est du JSON d’au plus 512 KiB, avec number, issueDate, dueDate, currency, taxRate, taxCategoryCode, seller, buyer et lines (dueDate pas avant la date d’émission). Le vendeur et l’acheteur ont chacun besoin d’un name et d’un email (l’adresse électronique qu’exige XRechnung), et le vendeur d’un taxNumber (numéro de TVA ou numéro fiscal). taxRate est supérieur à 0 pour S et égal à 0 pour Z, E et AE. taxExemptionReason est obligatoire pour E et AE et refusé pour S et Z. Pour AE, l’acheteur a aussi besoin d’un numéro de TVA dans taxNumber (BT-48). /xrechnung exige aussi buyerReference (BT-10) et iban (BR-DE-1), facultatifs sur /zugferd. Si deliveryDate est omis, la date d’émission est indiquée comme date de livraison. Sur /check, un corps de plus de 8 MiB reçoit 413 request_too_large, et un fichier XML, ou le XML contenu dans un PDF, de plus de 512 KiB reçoit 422 e_invoice_file_xml_too_large.
{
"number": "2026-0001",
"issueDate": "2026-11-16",
"dueDate": "2026-11-30",
"currency": "EUR",
"taxRate": 19,
"taxCategoryCode": "S",
"buyerReference": "04011000-1234512345-06",
"iban": "DE02120300000000202051",
"seller": {
"name": "Muster GmbH",
"email": "rechnung@example.com",
"addressLine": "Musterstraße 1",
"postalCode": "10115",
"city": "Berlin",
"country": "DE",
"taxNumber": "DE123456789"
},
"buyer": {
"name": "Beispiel AG",
"email": "eingang@example.com",
"addressLine": "Beispielweg 2",
"postalCode": "20095",
"city": "Hamburg",
"country": "DE"
},
"lines": [
{
"description": "Beratung",
"quantity": 8,
"unitPrice": 95
}
]
}Chaque membre, obligatoire ou facultatif, est décrit dans la description de l’API.
Ce que le contrôle indique
Le contrôle exécute, dans InkVoice, la configuration XRechnung de la KoSIT (KoSIT rules, XRechnung 3.0.2 (2026-08-31)) et les règles ZF_250 du FeRD (ZUGFeRD rules, ZF_250, 1.09.2 (2026-08-04)). Quand la feuille de style EN 16931 CII du CEN a aussi été exécutée, la configuration se termine par , EN 16931 CII 1.3.16. Il n’exécute ni le KoSIT Prüftool ni Mustang, et ne teste pas si un PDF respecte la norme PDF/A. Le champ validator de la réponse nomme l’ensemble de règles et la version qui ont jugé le fichier.
Les ensembles de règles suivent les versions qu’InkVoice fixe, et un changement est annoncé dans openapi.json. Cette page indique les versions actuelles.
accept ou reject indique ce que cet ensemble de règles a relevé pour le fichier, avec ses messages. Il ne dit pas que la facture répond aux exigences légales ni qu’un destinataire l’acceptera. not_checked, avec un notCheckedReason, signifie qu’aucun ensemble de règles n’a jugé le fichier.
curl --fail-with-body -X POST https://api.inkvoice.net/api/v1/check \
-H "Authorization: Bearer $INKVOICE_TOKEN" \
-H "Content-Type: application/xml" \
--data-binary @xrechnung.xmlAvec quoi les fichiers créés sont testés
Les fichiers créés ne sont pas contrôlés lors de leur création. Envoyez-en un à /check pour le faire contrôler ; c’est un appel d’API. Les fichiers sont produits par le code du générateur gratuit d’InkVoice : le XML est celui du générateur gratuit pour la même facture, et le PDF intègre ce XML sans ligne de mention. Dans la suite de tests du générateur gratuit, chaque scénario des tables de test (combinaisons par paires, pour chaque profil) est accepté par le KoSIT Prüftool 1.6.3 avec la configuration XRechnung 3.0.2 (2026-08-31), et par Mustang 2.26.0 comme EN 16931 en PDF/A-3b. Les deux tournent comme outils distincts dans les tests, pas dans l’API.
L’API ne peut pas créer d’avoirs ni de factures rectificatives, ni de factures à plusieurs taux de TVA, ni de livraisons intracommunautaires (K), ni d’exportations (G), ni de remises et frais au niveau du document. Une facture a une seule catégorie de TVA (S, Z, E ou AE) et un seul taux pour toutes les lignes. La suite de tests ne couvre pas le texte dans des écritures sans police fournie. Les montants sont écrits avec deux décimales dans toutes les devises ; pour JPY et KWD, la suite montre que les ensembles de règles l’acceptent, pas que c’est l’unité divisionnaire de la devise.
Erreurs
Un refus avec un code a pour corps { error, code, args } ; error est un texte anglais fixe, appuyez-vous donc sur code.
| Statut | Code | Signification | Compté |
|---|---|---|---|
| 400 | – | La requête contient des erreurs. Le corps est { errors: [...] }, qui nomme des chemins comme seller.name. | Non |
| 401 | – | Pas de jeton d’accès, ou un jeton qui n’est pas accepté. Sans corps. | Non |
| 403 | – | Le jeton n’est pas autorisé pour l’API (« Autoriser l'API développeur », étape 3), ou un jeton en lecture seule a appelé une route de création ou de contrôle. Sans corps. | Non |
| 404 | – | L’API est désactivée, ou la route n’existe pas. | Non |
| 413 | request_too_large | Le corps est plus grand que ce que la route accepte. | Non |
| 415 | – | Le corps a un type de contenu que la route ne lit pas. Sans corps. | Non |
| 422 | developer_plan_required | L’espace de travail n’a pas de plan développeur actif. | Non |
| 422 | api_call_limit_reached | Les appels inclus sont épuisés. args.included donne les appels inclus, args.date le dernier jour UTC de la période. | Non |
| 422 | e_invoice_file_empty, e_invoice_file_encrypted, e_invoice_file_no_invoice_xml, e_invoice_file_not_an_invoice, e_invoice_file_not_xml, e_invoice_file_number_out_of_range, e_invoice_file_older_zugferd, e_invoice_file_several_invoice_xml, e_invoice_file_too_complex, e_invoice_file_too_large, e_invoice_file_unreadable, e_invoice_file_xml_too_large | Sur /check : le fichier n’est pas lisible comme facture. | Non |
| 429 | rate_limited | Trop d’appels. Réessayez après Retry-After secondes. | Non |
| 429 | e_invoice_check_busy | Sur /check : trop de contrôles en même temps. Réessayez après Retry-After secondes. | Non |
Limites
L’API limite le nombre d’appels qu’un jeton, un espace de travail et une adresse peuvent faire par minute et en même temps. Au-delà d’une limite, elle répond 429 avec Retry-After en secondes, et l’appel n’est pas compté. Aucune promesse n’est faite sur la disponibilité, le temps de réponse ou le débit.
Description de l’API et versions
La description de l’API est en OpenAPI 3.1 à l’adresse https://api.inkvoice.net/api/v1/openapi.json, lisible sans jeton. La v1 ne change que par ajout (nouveaux membres facultatifs, routes ou codes) ; tout autre changement devient /api/v2.
Conditions
S’appliquent les AGB (conditions générales, Ziffer 4a), l’annexe « Entwickler-API » (API développeur) de l’AVV (contrat de sous-traitance) et la Datenschutzerklärung (politique de confidentialité). Cette page traduit la Leistungsbeschreibung (description des prestations) prévue à la Ziffer 4a (point 4a) des AGB ; la page allemande fait foi.
Le plan développeur se souscrit dans les paramètres de votre espace de travail.