TaxLayer

Entwickler · Beta

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.

Grundlagen

Basis-URL, Anmeldung, Antworten

Basis-URL

https://europe-west3-taxlayer-4d586.cloudfunctions.net/api/v1

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.

LimitWert
Anfragen pro Minute und Schlüssel60 (alle Schlüssel eines Kontos zusammen: 120)
Konvertierungen pro MonatIhr Tarif: 800 (Enterprise) bzw. 5.000 (Enterprise Plus), gemeinsam mit der Web-App und dem Team
Rechnungen pro CSV-Aufruf50 (Enterprise) bzw. 70 (Enterprise Plus)
Prüfungen pro Tag1.000 (Enterprise) bzw. 2.000 (Enterprise Plus), zählen nicht als Konvertierung
Positionen pro Rechnung1.000
Größe CSV / XML / Prüfung5 MB / 2 MB / 10 MB (Prüfung: XML und PDF)
Schlüssel pro Konto5

Antwort-Header

HeaderBedeutung
X-Request-IdKennung der Anfrage, gleich dem Feld requestId. Bitte bei Fragen angeben.
X-RateLimit-LimitAnfragen pro Minute für diesen Schlüssel.
X-RateLimit-RemainingDavon in der laufenden Minute noch frei.
Retry-AfterBei 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.

Beispiel (curl)

curl https://europe-west3-taxlayer-4d586.cloudfunctions.net/api/v1/status \
  -H "Authorization: Bearer tlk_IhrSchluessel"

Antwort (200)

{
  "requestId": "req_8Jt2fQ0aLm1x",
  "api": "v1",
  "beta": true,
  "plan": "enterprise",
  "key": { "name": "ERP Produktion" },
  "conversions": { "period": "2026-11", "used": 112, "limit": 800, "remaining": 688 },
  "validations": { "usedToday": 14, "limitPerDay": 1000 },
  "limits": { "requestsPerMinute": 60, "invoicesPerCsv": 50, "maxCsvBytes": 5242880, "maxXmlBytes": 2097152, "maxValidateBytes": 10485760 }
}
POST/v1/convert/csv

CSV in E-Rechnungen umwandeln

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

NameArtBedeutung
formatQuery, Pflichtzugferd (PDF mit eingebetteter XML), xrechnung (UBL-XML) oder peppol (PEPPOL BIS 3.0, UBL-XML)
includeXmlQuery, optionaltrue: 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.

Beispiel (curl)

curl -X POST "https://europe-west3-taxlayer-4d586.cloudfunctions.net/api/v1/convert/csv?format=xrechnung" \
  -H "Authorization: Bearer tlk_IhrSchluessel" \
  -H "Content-Type: text/csv" \
  --data-binary @rechnungen.csv

Antwort (200)

{
  "requestId": "req_Qm7dT1pXk2aA",
  "format": "xrechnung",
  "converted": 1,
  "failed": 1,
  "invoices": [
    {
      "invoiceNumber": "RE-2026-001",
      "format": "xrechnung",
      "valid": true,
      "totalAmount": 1428,
      "currency": "EUR",
      "filename": "RE-2026-001_xrechnung.xml",
      "contentType": "application/xml",
      "xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><ubl:Invoice …>"
    }
  ],
  "errors": [
    {
      "index": 1,
      "invoiceNumber": "RE-2026-002",
      "code": "missing_fields",
      "error": "Für die XRechnung fehlen noch folgende Angaben: Telefonnummer des Verkäufers.",
      "missingFields": ["BR-DE-6"]
    }
  ],
  "quota": { "used": 113, "limit": 800, "remaining": 687 }
}
POST/v1/convert/xml

XML-E-Rechnung umwandeln

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

NameArtBedeutung
formatQuery, Pflichtzugferd, xrechnung oder peppol
includeXmlQuery, optionaltrue: 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).

Beispiel (curl)

curl -X POST "https://europe-west3-taxlayer-4d586.cloudfunctions.net/api/v1/convert/xml?format=zugferd" \
  -H "Authorization: Bearer tlk_IhrSchluessel" \
  -H "Content-Type: application/xml" \
  --data-binary @xrechnung.xml \
  | jq -r '.invoices[0].pdfBase64' | base64 --decode > rechnung_zugferd.pdf

Antwort (200)

{
  "requestId": "req_c1Lw0Zb7RrQe",
  "format": "zugferd",
  "sourceSyntax": "UBL",
  "converted": 1,
  "failed": 0,
  "invoices": [
    {
      "invoiceNumber": "RE-2026-001",
      "format": "zugferd",
      "valid": true,
      "totalAmount": 1428,
      "currency": "EUR",
      "filename": "RE-2026-001_zugferd.pdf",
      "contentType": "application/pdf",
      "pdfBase64": "JVBERi0xLjcKJcfsj6IK…"
    }
  ],
  "errors": [],
  "quota": { "used": 114, "limit": 800, "remaining": 686 }
}
POST/v1/validate

E-Rechnung prüfen

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

NameArtBedeutung
reportQuery, optionalfull: 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).

Beispiel (curl)

curl -X POST "https://europe-west3-taxlayer-4d586.cloudfunctions.net/api/v1/validate" \
  -H "Authorization: Bearer tlk_IhrSchluessel" \
  -H "Content-Type: application/pdf" \
  --data-binary @rechnung.pdf

Antwort (200)

{
  "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).

codeStatusBedeutung
missing_key401Kein Schlüssel im Header Authorization.
invalid_key401Schlüssel unbekannt oder widerrufen, oder das Konto existiert nicht mehr.
account_not_activated403Das Konto ist noch nicht aktiviert (E-Mail bestätigen und AGB in der App annehmen).
plan_required403Das Konto hat keinen Enterprise-Tarif (mehr). Der Schlüssel funktioniert wieder, sobald der Tarif aktiv ist.
not_found404Diesen Pfad gibt es nicht.
method_not_allowed405Falsche HTTP-Methode für diesen Pfad.
format_required400Query-Parameter format fehlt oder ist ungültig.
empty_body400Leerer Request-Body.
empty400Die XML-Datei ist leer.
malformed400Die XML-Datei ist nicht wohlgeformt.
doctype_not_allowed400XML mit DOCTYPE oder ENTITY (Schutz vor XXE-Angriffen).
bad_csv400Die CSV-Datei ist nicht lesbar (zum Beispiel eine Excel- oder ZIP-Datei).
bad_pdf400Die PDF-Datei ist nicht lesbar.
bad_encoding400Die Zeichenkodierung stimmt nicht (XML: UTF-8 oder die im Kopf angegebene ISO-8859-1 bzw. windows-1252).
payload_too_large413Die Datei ist größer als erlaubt (siehe maxBytes).
too_many_invoices413Mehr Rechnungen in der CSV, als Ihr Tarif pro Aufruf erlaubt (siehe max). Teilen Sie die Datei.
not_an_einvoice422Die XML ist weder UBL noch CII.
no_invoices422Die CSV enthält keine Rechnung.
no_einvoice_in_pdf422Das PDF enthält keine eingebettete E-Rechnung.
pdf_too_complex422Das PDF enthält zu große oder ungewöhnlich komprimierte Daten und wird nicht entpackt.
conversion_failed422Keine Rechnung konnte erzeugt werden; die Gründe stehen in errors.
rate_limited429Mehr als 60 Anfragen pro Minute und Schlüssel (120 pro Konto) oder zu viele ungültige Schlüssel. Header Retry-After beachten.
quota_exceeded429Das monatliche Kontingent reicht für diese Anfrage nicht (needed, remaining).
validation_limit429Tageslimit für Prüfungen erreicht. Header Retry-After beachten.
validator_unavailable503Der Prüfdienst ist kurz nicht erreichbar. Nichts wurde berechnet, auch keine Prüfung vom Tageslimit; bitte erneut senden.
service_unavailable503Kurzzeitige Störung. Nichts wurde berechnet; bitte erneut senden.
internal500Unerwarteter Fehler. Bitte schicken Sie uns die requestId.

Fehler einzelner Rechnungen (errors[].code)

codeBedeutung
missing_fieldsFür das Zielformat fehlen Pflichtangaben; missingFields nennt die Regeln (zum Beispiel BR-DE-6).
validation_failedDie erzeugte Datei hat die offizielle Prüfung nicht bestanden; validationErrors nennt Regel und Meldung. Es wird keine Datei ausgegeben.
tax_invalidDie Steuerangaben passen nicht zusammen (zum Beispiel Steuerkategorie und Steuersatz).
csv_invalidDie Rechnung in der CSV ist unvollständig oder ein Wert ist keine Zahl; die Meldung nennt die Spalte.
too_many_linesDie Rechnung hat mehr als 1.000 Positionen.
totals_mismatchDie Summen der Quell-XML passen nicht zu ihren Positionen (Feld totals zeigt beide Werte). Es wird keine Datei erzeugt.
not_processedDas Zeitlimit der Anfrage war erreicht, bevor diese Rechnung an der Reihe war. Nicht berechnet; bitte erneut senden.
build_failedDie Datei konnte aus den Daten nicht erzeugt werden.
validator_unavailableDer 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.