Erstellen Sie XRechnung- und ZUGFeRD-Dateien und lassen Sie E-Rechnungsdateien prüfen, aus Ihrer eigenen Software und mit einem persönlichen Zugriffstoken.
- POST /xrechnung erstellt eine Datei im Format XRechnung 3.0 (CII-Syntax, EN 16931), der Version, die die XRechnung-Konfiguration 3.0.2 abdeckt, und gibt sie als application/xml zurück.
- POST /zugferd erstellt ein PDF im Format ZUGFeRD 2.x (Profil EN 16931) mit eingebettetem XML, ohne InkVoice-Hinweis auf der Seite.
- POST /check liest ein ZUGFeRD- oder Factur-X-PDF oder eine XRechnung-, CII- oder UBL-XML-Datei; die Datei selbst ist der Inhalt der Anfrage (application/pdf, application/xml, text/xml, application/octet-stream; andere Typen erhalten 415).
- GET /usage meldet die angerechneten Aufrufe des jüngsten Abrechnungszeitraums (solange der Tarif aktiv ist, des laufenden), je Route. Die Abfrage ist kein Aufruf, der angerechnet wird.
- Eine Rechnung an ihren Empfänger senden oder sie für Sie archivieren.
- Eine Datei beim Erstellen prüfen.
- Gutschriften, Rechnungskorrekturen, Rechnungen mit mehreren Steuersätzen, Rechnungen über innergemeinschaftliche Lieferungen (K) oder Ausfuhren (G) oder Zu- und Abschläge auf Dokumentebene erstellen.
- Steuer- oder Rechtsberatung leisten.
Der Entwicklertarif
Der Entwicklertarif kostet 19 € im Monat und enthält je Abrechnungszeitraum 1.000 Aufrufe für den Arbeitsbereich. Der Anbieter ist Kleinunternehmer im Sinne des § 19 UStG und weist keine Umsatzsteuer aus; der Preis ist daher ein Endpreis.
- Angerechnet wird jeder Aufruf, der eine Datei oder ein Prüfergebnis (
acceptoderreject) geliefert hat, auch wenn Sie die Antwort nicht lesen. Zurückgewiesene oder fehlgeschlagene Aufrufe, Prüfungen mitnot_checkedund Abfragen des Verbrauchs werden nicht angerechnet. - Sind die enthaltenen Aufrufe verbraucht, weist der Dienst weitere mit
api_call_limit_reachedzurück, bis der nächste Abrechnungszeitraum beginnt. Gleichzeitig laufende Aufrufe können die Grenze überschreiten. Nicht genutzte Aufrufe verfallen mit dem Ende des Abrechnungszeitraums, und je Aufruf wird nichts berechnet. - Verlängert sich der Entwicklertarif, bleiben die nicht verbrauchten Aufrufe des vorigen Abrechnungszeitraums nutzbar, bis Stripe den neuen Abrechnungszeitraum an InkVoice übermittelt hat, längstens bis 3 Tage nach Beginn des neuen; ein Aufruf in dieser Zeit wird auf beide Abrechnungszeiträume angerechnet.
- Es gibt keinen Testzeitraum.
Der Inhaber des Arbeitsbereichs bucht den Entwicklertarif in den Einstellungen des Arbeitsbereichs und bezahlt über Stripe. Der Entwicklertarif ist vom Tarif des Arbeitsbereichs (kostenloser Tarif, Pro oder Master) getrennt: Buchung, Wechsel, Kündigung oder Ende des einen berühren den anderen nicht. Kostenpflichtige Tarife können nur Kunden buchen, die ihren Sitz, Wohnsitz oder ihre Niederlassung, für die der Tarif gebucht wird, in Deutschland haben.
Ihr erster Aufruf
- 1Den Entwicklertarif buchen
Der Inhaber des Arbeitsbereichs bucht den Entwicklertarif in den Einstellungen des Arbeitsbereichs und bezahlt über Stripe.
- 2Ein Zugriffstoken erstellen
Erstellen Sie unter „Zugriffstoken“ ein Zugriffstoken (API-Token) mit „Lesen und schreiben“. Das Token wird nur einmal angezeigt, beim Erstellen.
- 3Dem Token die Entwickler-API erlauben
Ein Token funktioniert mit der API erst, wenn der Inhaber des Arbeitsbereichs dafür unter „Zugriffstoken“ die Einstellung „Entwickler-API erlauben“ einschaltet. Bei keinem Token ist sie von vornherein eingeschaltet.
- 4Die Rechnung senden
Legen Sie die Rechnungsanfrage in
invoice.jsonund das Token in die UmgebungsvariableINKVOICE_TOKENund senden Sie die Anfrage an/xrechnung. Die Antwort ist die XRechnung-Datei. Bei einem Fehler endet curl mit einem Exit-Code ungleich 0, und die Datei enthält den Inhalt der Fehlerantwort, sofern sie einen hat (siehe „Fehler“);--fail-with-bodybraucht curl 7.76 oder neuer.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
Routen
Alle Routen liegen unter https://api.inkvoice.net/api/v1. Jeder Aufruf außer openapi.json braucht ein persönliches Zugriffstoken als Authorization: Bearer inkv_…. Eine Anmeldung über die Website wird nicht angenommen, und Browser können die API nicht aufrufen (kein CORS). Erstellen und Prüfen brauchen ein Token mit „Lesen und schreiben“; ein Token nur zum Lesen darf nur den Verbrauch abfragen.
| Route | Inhalt der Anfrage | Antwort |
|---|---|---|
POST /xrechnung | Die Rechnungsanfrage als JSON | Die XRechnung-Datei, application/xml |
POST /zugferd | Die Rechnungsanfrage als JSON | Das ZUGFeRD-PDF, application/pdf |
POST /check | Die Datei selbst, als application/pdf, application/xml, text/xml oder application/octet-stream | Was die Prüfregeln gemeldet haben, als JSON |
GET /usage | Keiner | Die angerechneten Aufrufe des jüngsten Abrechnungszeitraums, je Route, als JSON. Wird nicht angerechnet |
GET /openapi.json | Keiner | Die Schnittstellenbeschreibung, OpenAPI 3.1, ohne Token abrufbar |
Die Rechnungsanfrage
Die Anfrage ist JSON von höchstens 512 KiB, mit number, issueDate, dueDate, currency, taxRate, taxCategoryCode, seller, buyer und lines (dueDate nicht vor dem Ausstellungsdatum). Verkäufer und Käufer brauchen je einen name und eine email (die elektronische Adresse, die XRechnung verlangt), der Verkäufer zudem eine taxNumber (USt-IdNr. oder Steuernummer). taxRate ist bei S größer als 0 und bei Z, E und AE gleich 0. taxExemptionReason ist bei E und AE Pflicht und bei S und Z unzulässig. Bei AE braucht auch der Käufer eine USt-IdNr. in taxNumber (BT-48). /xrechnung verlangt außerdem buyerReference (BT-10) und iban (BR-DE-1), die bei /zugferd optional sind. Fehlt deliveryDate, wird das Ausstellungsdatum als Lieferdatum angegeben. Bei /check darf der Inhalt der Anfrage höchstens 8 MiB groß sein, sonst lautet die Antwort 413 request_too_large; eine XML-Datei oder das XML in einem PDF darf höchstens 512 KiB groß sein, sonst lautet sie 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
}
]
}Jedes Feld, ob Pflicht oder optional, ist in der Schnittstellenbeschreibung beschrieben.
Was die Prüfung meldet
Die Prüfung führt innerhalb von InkVoice die XRechnung-Konfiguration der KoSIT (KoSIT rules, XRechnung 3.0.2 (2026-08-31)) und die ZF_250-Regeln des FeRD (ZUGFeRD rules, ZF_250, 1.09.2 (2026-08-04)) aus. Lief zusätzlich das EN-16931-CII-Stylesheet des CEN, endet die Konfiguration auf , EN 16931 CII 1.3.16. Sie führt weder das KoSIT-Prüftool noch Mustang aus und testet nicht, ob ein PDF dem Standard PDF/A entspricht. Das Feld validator der Antwort nennt die Prüfregeln und ihre Fassung, nach denen die Datei beurteilt wurde.
Die Prüfregeln folgen den Fassungen, die InkVoice festlegt, und eine Änderung wird in openapi.json angekündigt. Diese Seite nennt die aktuellen Fassungen.
accept oder reject gibt wieder, was diese Prüfregeln für die Datei gemeldet haben, mit ihren Meldungen. Es sagt nicht, dass die Rechnung gesetzlichen Anforderungen genügt oder dass ein Empfänger sie annimmt. not_checked mit einem notCheckedReason bedeutet, dass keine Prüfregeln die Datei beurteilt haben.
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.xmlWomit die erstellten Dateien getestet werden
Beim Erstellen findet keine Prüfung statt. Senden Sie eine erstellte Datei an /check, um sie prüfen zu lassen; dieser Aufruf wird angerechnet. Die Dateien erstellt der Code des kostenlosen Generators von InkVoice: Das XML ist das des kostenlosen Generators für dieselbe Rechnung, und das PDF bettet dieses XML ohne Hinweiszeile auf InkVoice ein. In der Testsuite des kostenlosen Generators wird jedes Szenario der Testtabellen, paarweise je Profil, vom KoSIT-Prüftool 1.6.3 mit der XRechnung-Konfiguration 3.0.2 (2026-08-31) akzeptiert und von Mustang 2.26.0 als EN 16931 in PDF/A-3b. Beide laufen in den Tests als eigene Werkzeuge, nicht in der API.
Die API kann keine Gutschriften, keine Rechnungskorrekturen, keine Rechnungen mit mehreren Steuersätzen, keine Rechnungen über innergemeinschaftliche Lieferungen (K) oder Ausfuhren (G) und keine Zu- und Abschläge auf Dokumentebene erstellen. Eine Rechnung hat eine Steuerkategorie (S, Z, E oder AE) und einen Steuersatz für alle Positionen. Die Testsuite deckt keinen Text in Schriftsystemen ab, für die keine Schriftart mitgeliefert wird. Beträge werden in jeder Währung mit zwei Nachkommastellen geschrieben; für JPY und KWD zeigt die Testsuite, dass die Prüfregeln das akzeptieren, nicht, dass es die kleinste Einheit der Währung ist.
Fehler
Eine Zurückweisung mit Code hat den Inhalt { error, code, args }; error ist ein fester englischer Text, werten Sie daher code aus.
| Status | Code | Bedeutung | Angerechnet |
|---|---|---|---|
| 400 | – | Die Anfrage enthält Fehler. Der Inhalt ist { errors: [...] } und nennt Pfade wie seller.name. | Nein |
| 401 | – | Kein Zugriffstoken, oder eines, das nicht angenommen wird. Ohne Inhalt. | Nein |
| 403 | – | Dem Token ist die Entwickler-API nicht erlaubt („Entwickler-API erlauben“, Schritt 3), oder ein Token nur zum Lesen hat eine Route zum Erstellen oder Prüfen aufgerufen. Ohne Inhalt. | Nein |
| 404 | – | Die API ist abgeschaltet, oder die Route gibt es nicht. | Nein |
| 413 | request_too_large | Der Inhalt der Anfrage ist größer, als die Route annimmt. | Nein |
| 415 | – | Der Inhalt der Anfrage hat einen Typ, den die Route nicht liest. Ohne Inhalt. | Nein |
| 422 | developer_plan_required | Der Arbeitsbereich hat keinen aktiven Entwicklertarif. | Nein |
| 422 | api_call_limit_reached | Die enthaltenen Aufrufe sind verbraucht. args.included nennt die enthaltenen Aufrufe, args.date den letzten Tag des Abrechnungszeitraums in UTC. | Nein |
| 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 | Bei /check: Die Datei ist nicht als Rechnung lesbar. | Nein |
| 429 | rate_limited | Zu viele Aufrufe. Erneut versuchen nach Retry-After Sekunden. | Nein |
| 429 | e_invoice_check_busy | Bei /check: zu viele Prüfungen gleichzeitig. Erneut versuchen nach Retry-After Sekunden. | Nein |
Grenzen
Die API begrenzt, wie viele Aufrufe ein Token, ein Arbeitsbereich und eine Adresse je Minute und gleichzeitig ausführen dürfen. Über einer Grenze antwortet sie mit 429 und Retry-After in Sekunden, und der Aufruf wird nicht angerechnet. Verfügbarkeit, Antwortzeit und Durchsatz werden nicht zugesagt.
Beschreibung der Schnittstelle und Versionen
Die Schnittstellenbeschreibung ist OpenAPI 3.1 unter https://api.inkvoice.net/api/v1/openapi.json, ohne Token abrufbar. v1 ändert sich nur durch Ergänzungen (neue optionale Felder, Routen oder Codes); alles andere wird /api/v2.
Vertragsbedingungen
Es gelten die AGB (Ziffer 4a), die Anlage „Entwickler-API“ zum Vertrag zur Auftragsverarbeitung und die Datenschutzerklärung. Diese Seite ist die Leistungsbeschreibung der Entwickler-API nach Ziffer 4a der AGB. Diese Fassung gilt seit dem 15. November 2026.
Den Entwicklertarif buchen Sie in den Einstellungen Ihres Arbeitsbereichs.