Commencer gratuitement

L’API de facture électronique d’InkVoice

Créez des fichiers XRechnung et ZUGFeRD à partir de JSON et faites contrôler des fichiers de facture électronique depuis votre propre code. Plan développeur, 19 € par mois, 1 000 appels d’API inclus.

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.

Ce que fait l’API, et ce qu’elle ne fait pas
  • 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 (accept ou reject) est compté, même si vous ne lisez pas la réponse. Les appels refusés ou ayant échoué, les contrôles avec not_checked et 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_reached jusqu’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

  1. 1
    Souscrire 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.

  2. 2
    Cré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.

  3. 3
    L’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.

  4. 4
    Envoyer la facture

    Mettez la requête de facture dans invoice.json et le jeton dans la variable d’environnement INKVOICE_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-body né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.

RouteCorpsRéponse
POST /xrechnungLa requête de facture en JSONLe fichier XRechnung, application/xml
POST /zugferdLa requête de facture en JSONLe PDF ZUGFeRD, application/pdf
POST /checkLe fichier lui-même, en application/pdf, application/xml, text/xml ou application/octet-streamCe que l’ensemble de règles a indiqué, en JSON
GET /usageAucunLes 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.jsonAucunLa 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.xml

Avec 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.

StatutCodeSignificationCompté
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
413request_too_largeLe 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
422developer_plan_requiredL’espace de travail n’a pas de plan développeur actif.Non
422api_call_limit_reachedLes appels inclus sont épuisés. args.included donne les appels inclus, args.date le dernier jour UTC de la période.Non
422e_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_largeSur /check : le fichier n’est pas lisible comme facture.Non
429rate_limitedTrop d’appels. Réessayez après Retry-After secondes.Non
429e_invoice_check_busySur /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.

Commencez avec un compte gratuit

Le plan développeur se souscrit dans les paramètres de votre espace de travail.

Dernière mise à jour le 15 novembre 2026. Cet article est une orientation générale et ne constitue pas un conseil fiscal ou juridique.