TaxLayer API E-Rechnungen aus Ihrem System, geprüft.
Wandeln Sie CSV- und XML-Rechnungen per REST-API in ZUGFeRD, XRechnung und PEPPOL um und prüfen Sie E-Rechnungen mit dem offiziellen KoSIT-Regelwerk. Enthalten in Enterprise und Enterprise Plus.
Jede Datei vor der Ausgabe geprüftKeine Rechnungsdateien gespeichertServer in Deutschland
Schnellstart
In drei Schritten zur ersten E-Rechnung
01
Schlüssel erstellen
Im Konto unter „API (Beta)“ einen Schlüssel anlegen und sicher in Ihrem Server speichern. Er wird nur einmal angezeigt.
02
Verbindung testen
GET /v1/status mit dem Schlüssel aufrufen. Die Antwort zeigt Tarif, Kontingent und Limits.
03
Rechnungen senden
CSV oder XML an /v1/convert senden, geprüfte E-Rechnungen zurückbekommen, oder fremde Rechnungen mit /v1/validate prüfen.
Beta Die API ist neu. Pfade unter /v1 bleiben stabil; neue Felder können hinzukommen, also ignorieren Sie unbekannte Felder. Änderungen kündigen wir per E-Mail an. Rückmeldungen gern an info@taxlayer.de.
Jede Anfrage trägt Ihren Schlüssel im Header Authorization: Bearer tlk_…. Antworten sind JSON und enthalten immer eine requestId; nennen Sie sie uns bei Fragen. Fehler haben ein Feld code (stabil, für Ihr Programm) und ein Feld error (Text für Menschen). Bei 429 und 503 senden Sie die Anfrage nach der Zeit in Retry-After bzw. nach einer Minute erneut; berechnet wurde dann nichts.
Limit
Wert
Anfragen pro Minute und Schlüssel
60 (alle Schlüssel eines Kontos zusammen: 120)
Konvertierungen pro Monat
Ihr Tarif: 800 (Enterprise) bzw. 5.000 (Enterprise Plus), gemeinsam mit der Web-App und dem Team
Rechnungen pro CSV-Aufruf
50 (Enterprise) bzw. 70 (Enterprise Plus)
Prüfungen pro Tag
1.000 (Enterprise) bzw. 2.000 (Enterprise Plus), zählen nicht als Konvertierung
Positionen pro Rechnung
1.000
Größe CSV / XML / Prüfung
5 MB / 2 MB / 10 MB (Prüfung: XML und PDF)
Schlüssel pro Konto
5
Antwort-Header
Header
Bedeutung
X-Request-Id
Kennung der Anfrage, gleich dem Feld requestId. Bitte bei Fragen angeben.
X-RateLimit-Limit
Anfragen pro Minute für diesen Schlüssel.
X-RateLimit-Remaining
Davon in der laufenden Minute noch frei.
Retry-After
Bei 429: Sekunden bis zur nächsten erlaubten Anfrage.
Endpunkte
Vier Endpunkte, alle mit Beispiel
GET /v1/status: Tarif, Kontingent und Limits des Kontos, zu dem der Schlüssel gehört. POST /v1/convert/csv: Eine CSV-Datei im TaxLayer-Format, eine oder viele Rechnungen, wird zu ZUGFeRD, XRechnung oder PEPPOL. POST /v1/convert/xml: Eine E-Rechnung im Standardformat (UBL oder CII) wird in ein anderes Format umgewandelt. POST /v1/validate: Prüft XML oder ein ZUGFeRD-PDF mit dem offiziellen Regelwerk und liefert die Fehler mit Regelcode.
GET/v1/status
Kontostatus abrufen
Zeigt, welcher Tarif aktiv ist, wie viele Konvertierungen in diesem Monat verbraucht und noch frei sind, wie viele Prüfungen heute gelaufen sind und welche Limits gelten.
Gut geeignet als Verbindungstest nach dem Einrichten und vor großen Stapeln. Der Aufruf zählt nicht gegen Ihr Kontingent (nur gegen die 60 Anfragen pro Minute). POST funktioniert ebenfalls.
Für Systeme, die Rechnungen als Tabelle exportieren können (ERP, Warenwirtschaft, eigene Software). Sie senden die CSV-Datei im TaxLayer-Format, wir erzeugen daraus fertige E-Rechnungen.
Eine Datei darf mehrere Rechnungen enthalten: Zeilen mit derselben Rechnungsnummer (Spalte invoiceNumber) bilden eine Rechnung, jede Zeile ist eine Position. Die Kopfdaten (Verkäufer, Käufer, Zahlung) stehen in jeder Zeile und werden aus der ersten Zeile der Rechnung gelesen.
Jede erzeugte Datei wird vor der Ausgabe mit dem offiziellen Prüfwerkzeug (KoSIT-Regeln über den Mustang-Validator) geprüft. Sie erhalten nur Dateien, die diese Prüfung bestanden haben. Ist eine Rechnung fehlerhaft, steht sie mit Grund in errors, die übrigen werden trotzdem erzeugt.
Vor der Arbeit wird das Kontingent für alle Rechnungen der Datei reserviert. Reicht es nicht, wird nichts erzeugt (429 quota_exceeded). Nur erfolgreich erzeugte Rechnungen zählen als Konvertierung.
Für XRechnung braucht die Rechnung eine Leitweg-ID bzw. Käuferreferenz (buyerReference), der Verkäufer Telefon (sellerPhone), E-Mail (sellerEmail), PLZ und Ort, der Käufer PLZ, Ort und USt-IdNr. oder E-Mail (buyerVatId oder buyerEmail). Für PEPPOL brauchen beide eine USt-IdNr. oder E-Mail.
Zahlen: Ein Trennzeichen gilt als Dezimaltrennzeichen (1234.56 oder 1234,56); Tausenderpunkte im deutschen Format (1.234,56) und Tausenderkommas im englischen Format (1,234.56) werden erkannt. Ist ein Wert keine Zahl, wird die Rechnung mit csv_invalid und dem Spaltennamen abgelehnt, statt mit 0 zu rechnen.
Parameter
Name
Art
Bedeutung
format
Query, Pflicht
zugferd (PDF mit eingebetteter XML), xrechnung (UBL-XML) oder peppol (PEPPOL BIS 3.0, UBL-XML)
includeXml
Query, optional
true: bei zugferd zusätzlich die eingebettete XML im Feld xml zurückgeben (sonst nur pdfBase64, hält die Antwort klein)
Request-Body
Die CSV-Datei als Text in UTF-8 oder windows-1252 (Excel-Standard, wird erkannt), Trennzeichen Semikolon oder Komma (wird erkannt), erste Zeile mit den Spaltennamen. Content-Type: text/csv. Höchstens 5 MB und 50 bzw. 70 Rechnungen pro Aufruf.
Liest eine vorhandene E-Rechnung im Standardformat und erzeugt daraus das gewünschte Zielformat. Angenommen werden UBL 2.1 (XRechnung, PEPPOL BIS, Invoice und CreditNote) und UN/CEFACT CII (ZUGFeRD, Factur-X, XRechnung in CII).
Typische Fälle: aus einer XRechnung ein ZUGFeRD-PDF für Empfänger ohne XML-Viewer machen, aus ZUGFeRD-XML eine PEPPOL-Rechnung für das PEPPOL-Netz, oder eine Factur-X-Rechnung in eine XRechnung für öffentliche Auftraggeber. Die Quelldatei muss dafür alle Angaben des Zielformats enthalten; die API ergänzt nichts. Für eine XRechnung an Behörden sind das insbesondere Leitweg-ID, Telefon und E-Mail des Verkäufers.
Das Auslesen ist regelbasiert, ohne KI: Beträge, Positionen, Parteien und Zahlungsangaben werden exakt übernommen. Weichen die Summen der Quelldatei von ihren Positionen ab, wird keine Datei erzeugt (totals_mismatch), statt still neu zu rechnen. Wie bei CSV wird die erzeugte Datei vor der Ausgabe mit dem offiziellen Validator geprüft.
Eine Rechnung pro Aufruf, sie zählt als eine Konvertierung (nur bei Erfolg). Ein PDF nimmt dieser Endpunkt nicht an; zum Prüfen eines ZUGFeRD-PDFs nutzen Sie /validate.
Parameter
Name
Art
Bedeutung
format
Query, Pflicht
zugferd, xrechnung oder peppol
includeXml
Query, optional
true: bei zugferd zusätzlich die eingebettete XML im Feld xml zurückgeben (sonst nur pdfBase64, hält die Antwort klein)
Request-Body
Die XML-Datei in UTF-8 oder der im XML-Kopf angegebenen Kodierung ISO-8859-1 bzw. windows-1252, Content-Type: application/xml. Höchstens 2 MB und 1.000 Positionen. Dateien mit DOCTYPE- oder ENTITY-Deklaration werden aus Sicherheitsgründen abgelehnt (E-Rechnungen brauchen keine).
Prüft eine E-Rechnung gegen EN 16931, die XRechnung-Regeln (CIUS, BR-DE) und PEPPOL BIS über den Mustang-Validator mit den KoSIT-Prüfregeln, also dasselbe Regelwerk, das öffentliche Rechnungsempfänger nutzen.
Sie senden XML (UBL oder CII) oder ein ZUGFeRD- bzw. Factur-X-PDF; aus dem PDF wird die eingebettete XML geprüft. Geeignet für eingehende Rechnungen von Lieferanten genauso wie für Rechnungen aus Ihrer eigenen Software.
Solange die Datei lesbar ist, antwortet der Endpunkt mit 200 und valid: true oder false. Jeder Fehler kommt mit Regelcode (zum Beispiel BR-CO-15 oder BR-DE-6) und Meldung. Mit ?report=full erhalten Sie zusätzlich den vollständigen Prüfbericht als XML-Text.
Prüfungen zählen nicht als Konvertierung, sondern gegen ein eigenes Tageslimit (1.000 bzw. 2.000 pro Konto und Tag). Die Datei wird nur geprüft, nicht gespeichert.
Parameter
Name
Art
Bedeutung
report
Query, optional
full: zusätzlich den vollständigen Prüfbericht (Feld report) zurückgeben
Request-Body
XML (Content-Type: application/xml) oder PDF (Content-Type: application/pdf), höchstens 10 MB. Aus PDFs mit sehr großen oder ungewöhnlich komprimierten Inhalten wird nichts entpackt (pdf_too_complex).
{
"requestId": "req_4kPq9sV2nHcY",
"valid": false,
"syntax": "CII",
"source": "pdf",
"errors": [
{ "rule": "BR-CO-15", "message": "Invoice total amount with VAT (BT-112) = Invoice total amount without VAT (BT-109) + Invoice total VAT amount (BT-110)." }
],
"validator": "KoSIT / Mustang (EN 16931, XRechnung, PEPPOL)"
}
Codebeispiele
Node.js und Python
Speichern Sie den Schlüssel als Umgebungsvariable (TAXLAYER_API_KEY), nie im Quelltext oder im Browser.
// Node.js 18+ (fetch ist eingebaut)
import { readFile, writeFile } from "node:fs/promises";
const res = await fetch("https://europe-west3-taxlayer-4d586.cloudfunctions.net/api/v1/convert/xml?format=zugferd", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TAXLAYER_API_KEY}`,
"Content-Type": "application/xml",
},
body: await readFile("xrechnung.xml"),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.code}: ${data.error} (${data.requestId})`);
for (const inv of data.invoices) {
await writeFile(inv.filename, Buffer.from(inv.pdfBase64, "base64"));
}
Fehlercodes
Was schiefgehen kann
Fehler, die die ganze Anfrage betreffen, kommen mit dem HTTP-Status unten. Fehler einzelner Rechnungen stehen bei Erfolg der übrigen im Feld errors (Status 200).
code
Status
Bedeutung
missing_key
401
Kein Schlüssel im Header Authorization.
invalid_key
401
Schlüssel unbekannt oder widerrufen, oder das Konto existiert nicht mehr.
account_not_activated
403
Das Konto ist noch nicht aktiviert (E-Mail bestätigen und AGB in der App annehmen).
plan_required
403
Das Konto hat keinen Enterprise-Tarif (mehr). Der Schlüssel funktioniert wieder, sobald der Tarif aktiv ist.
not_found
404
Diesen Pfad gibt es nicht.
method_not_allowed
405
Falsche HTTP-Methode für diesen Pfad.
format_required
400
Query-Parameter format fehlt oder ist ungültig.
empty_body
400
Leerer Request-Body.
empty
400
Die XML-Datei ist leer.
malformed
400
Die XML-Datei ist nicht wohlgeformt.
doctype_not_allowed
400
XML mit DOCTYPE oder ENTITY (Schutz vor XXE-Angriffen).
bad_csv
400
Die CSV-Datei ist nicht lesbar (zum Beispiel eine Excel- oder ZIP-Datei).
bad_pdf
400
Die PDF-Datei ist nicht lesbar.
bad_encoding
400
Die Zeichenkodierung stimmt nicht (XML: UTF-8 oder die im Kopf angegebene ISO-8859-1 bzw. windows-1252).
payload_too_large
413
Die Datei ist größer als erlaubt (siehe maxBytes).
too_many_invoices
413
Mehr Rechnungen in der CSV, als Ihr Tarif pro Aufruf erlaubt (siehe max). Teilen Sie die Datei.
not_an_einvoice
422
Die XML ist weder UBL noch CII.
no_invoices
422
Die CSV enthält keine Rechnung.
no_einvoice_in_pdf
422
Das PDF enthält keine eingebettete E-Rechnung.
pdf_too_complex
422
Das PDF enthält zu große oder ungewöhnlich komprimierte Daten und wird nicht entpackt.
conversion_failed
422
Keine Rechnung konnte erzeugt werden; die Gründe stehen in errors.
rate_limited
429
Mehr als 60 Anfragen pro Minute und Schlüssel (120 pro Konto) oder zu viele ungültige Schlüssel. Header Retry-After beachten.
quota_exceeded
429
Das monatliche Kontingent reicht für diese Anfrage nicht (needed, remaining).
validation_limit
429
Tageslimit für Prüfungen erreicht. Header Retry-After beachten.
validator_unavailable
503
Der Prüfdienst ist kurz nicht erreichbar. Nichts wurde berechnet, auch keine Prüfung vom Tageslimit; bitte erneut senden.
service_unavailable
503
Kurzzeitige Störung. Nichts wurde berechnet; bitte erneut senden.
internal
500
Unerwarteter Fehler. Bitte schicken Sie uns die requestId.
Fehler einzelner Rechnungen (errors[].code)
code
Bedeutung
missing_fields
Für das Zielformat fehlen Pflichtangaben; missingFields nennt die Regeln (zum Beispiel BR-DE-6).
validation_failed
Die erzeugte Datei hat die offizielle Prüfung nicht bestanden; validationErrors nennt Regel und Meldung. Es wird keine Datei ausgegeben.
tax_invalid
Die Steuerangaben passen nicht zusammen (zum Beispiel Steuerkategorie und Steuersatz).
csv_invalid
Die Rechnung in der CSV ist unvollständig oder ein Wert ist keine Zahl; die Meldung nennt die Spalte.
too_many_lines
Die Rechnung hat mehr als 1.000 Positionen.
totals_mismatch
Die Summen der Quell-XML passen nicht zu ihren Positionen (Feld totals zeigt beide Werte). Es wird keine Datei erzeugt.
not_processed
Das Zeitlimit der Anfrage war erreicht, bevor diese Rechnung an der Reihe war. Nicht berechnet; bitte erneut senden.
build_failed
Die Datei konnte aus den Daten nicht erzeugt werden.
validator_unavailable
Der Prüfdienst war für diese Rechnung nicht erreichbar; erneut senden.
Sicherheit und Datenschutz
Für den Betrieb auf Ihrem Server gebaut
Alle Prüfungen laufen ausschließlich automatisiert. TaxLayer prüft oder validiert Rechnungen nicht manuell. Ein gültiges Ergebnis bestätigt die formale Konformität mit den Regelwerken, nicht die inhaltliche Richtigkeit Ihrer Rechnung. Es gelten die AGB, § 4a.
Schlüssel speichern wir nur als Hash (SHA-256). Sie sehen ihn einmal beim Erstellen; verloren heißt: widerrufen und neu erstellen.
Ein widerrufener Schlüssel ist sofort ungültig. Tarif, Kontostatus und Teamzugehörigkeit prüfen wir bei jeder Anfrage neu.
Die API sendet keine CORS-Header: Aufrufe aus dem Browser sind nicht möglich, damit Schlüssel nicht in Webseiten landen.
Wir speichern keine Rechnungsdateien. Wie in der Web-App bleiben für Ihren Verlauf nur Rechnungsnummer, Betrag und Datum (90 Tage); das Zugriffsprotokoll enthält nur technische Daten.
XML mit DOCTYPE- oder ENTITY-Deklaration lehnen wir ab (Schutz vor XXE). Größen und Anfragen sind begrenzt.
Verarbeitung in Frankfurt (Google Cloud europe-west3). Den Auftragsverarbeitungsvertrag (AVV) schließen wir mit Enterprise-Kunden einzeln ab.
PDF
Warum keine PDF-API?
Aus einem beliebigen PDF liest unsere KI die Rechnungsdaten sehr gut, aber nicht fehlerfrei. In der Web-App prüfen Sie deshalb jede Rechnung vor der Ausgabe. Eine API ohne diesen Prüfschritt würde ungeprüfte Daten in rechtsverbindliche Rechnungen schreiben. Für PDFs nutzen Sie die Stapelverarbeitung in der App (bis zu 50 bzw. 70 PDFs auf einmal). Wenn Ihr System die Daten strukturiert ausgeben kann, ist CSV oder XML über die API der sichere, automatische Weg.
Bereit für die API?
Schlüssel im Konto erstellen und loslegen. Sie haben noch keinen Enterprise-Tarif? Die API ist in Enterprise und Enterprise Plus enthalten.