E-Rechnung-API

API-Schlüssel erstellen

Melden Sie sich an und öffnen Sie im Konto den Bereich „API“. Dort erstellen Sie einen Schlüssel, am besten mit einer Bezeichnung wie dem Namen des Systems, das ihn nutzt. Den Schlüssel zeigen wir nur einmal an. Speichern Sie ihn sicher, zum Beispiel in der Konfiguration Ihres Systems. Brauchen Sie ihn nicht mehr, widerrufen Sie ihn im Konto; er funktioniert dann sofort nicht mehr.

Jede Anfrage trägt den Schlüssel im Header:

Authorization: Bearer <Ihr API-Schlüssel>

Die Umwandlungen werden dem Guthaben des Kontos belastet, in dem der Schlüssel erstellt wurde. Gehört das Konto zu einem Team, ist es das gemeinsame Guthaben des Teams.

Rechnung umwandeln

POST https://www.e-rechnung.tools/api/v1/conversions

Senden Sie die Rechnung als multipart/form-data mit diesen Feldern:

Beispiel mit curl:

curl https://www.e-rechnung.tools/api/v1/conversions \
  -H "Authorization: Bearer $ERT_API_KEY" \
  -F file=@rechnung.pdf \
  -F format=zugferd

Eine Umwandlung dauert meist unter einer Minute, umfangreiche Rechnungen bis zu fünf Minuten. Stellen Sie den Timeout Ihres Clients auf mindestens zehn Minuten.

Antwort

Die Antwort ist JSON:

{
  "id": "6f0c2b1e-8d4a-4c2b-9f1e-2a7b5c3d9e10",
  "status": "completed",
  "format": "zugferd",
  "file": {
    "name": "ZUGFeRD RE-2026-0815.pdf",
    "contentType": "application/pdf",
    "layout": "original",
    "base64": "JVBERi0xLjcK…"
  },
  "issues": [],
  "notices": [],
  "totalsCheck": { "status": "confirmed", "statedTotal": 1961.12, "statedLabel": "Gesamtbetrag" },
  "validation": { "checked": true, "valid": true, "reason": null, "errors": [], "warnings": [], "reportHtml": "<!DOCTYPE html>…" },
  "invoice": { "invoiceNumber": "RE-2026-0815" },
  "charge": { "type": "credits", "credits": 1 },
  "credits": { "balance": 41, "freeTrialRemaining": 0 }
}

Prüfung vor der Ausgabe

Standardmäßig liefert die API eine Datei nur, wenn der Konverter die Summe mit dem Endbetrag auf der Rechnung bestätigen konnte und der KoSIT-Validator keine Fehler findet. Sonst lautet der Status needs_review: Sie erhalten die erkannten Daten und die Befunde, aber keine Datei.

Mit strict=false erhalten Sie die Datei trotzdem; die Befunde stehen dann in issues. Fehlen Pflichtangaben, entsteht keine Datei, auch nicht mit strict=false.

Ist validation.checked gleich false, hat der Validator die Datei nicht geprüft. Den Grund nennt validation.reason: large_document bei mehr als 500 KB XML (prüfen Sie die Datei dann unter E-Rechnung validieren), validator_unavailable, wenn der Validator kurz nicht erreichbar war, oder not_checkable. Die Datei wird in diesen Fällen trotzdem ausgeliefert.

Abrechnung

Jede Umwandlung kostet wie ein Upload auf der Website eine Konvertierung, umfangreiche Rechnungen eine je angefangene 20 Seiten, Scans eine je angefangene 5 Seiten und große Tabellen (Excel oder CSV mit mehr als 50.000 Zeichen) eine je angefangene 500 Zeilen. Abgebucht wird nach dem Auslesen der Rechnung, auch wenn der Status needs_review lautet. Ihre kostenlosen Konvertierungen gelten auch für die API.

Kostet eine Rechnung mehr als maxCredits, lehnt die API sie vor dem Auslesen ab (HTTP 402, credits_limit_exceeded), ohne etwas abzubuchen. Für umfangreiche Rechnungen, Scans mit mehr als 5 Seiten und Tabellen mit mehr als 500 Zeilen senden Sie ein passendes maxCredits mit, zum Beispiel -F maxCredits=5.

Ihr Guthaben fragen Sie so ab:

GET https://www.e-rechnung.tools/api/v1/account

{ "credits": { "balance": 41, "freeTrialRemaining": 0 } }

Die API speichert keine Ergebnisse. Bricht die Verbindung vor der Antwort ab, lässt sich die Datei nicht erneut abrufen; eine neue Anfrage wird neu abgerechnet.

Fehler

Fehler kommen mit einem HTTP-Status und diesem JSON: { "error": { "code": "…", "message": "…" } }. Die Meldung ist deutsch und für Menschen gedacht; Ihr System wertet am besten code aus.

Grenzen

• Dateien bis 4 MB
• Bis zu 10 Umwandlungen und 30 Anfragen insgesamt je Minute und Schlüssel
• Bis zu 10 Schlüssel je Anmeldung

Datenschutz

Über die API übermittelte Rechnungen verarbeiten wir wie Uploads auf der Website. Die E-Rechnung und das Prüfprotokoll übermitteln wir nur in der Antwort und speichern sie nicht. Den Schlüssel selbst speichern wir nicht, sondern einen Prüfwert. Einzelheiten stehen in der Datenschutzerklärung und im Auftragsverarbeitungsvertrag.

Fragen zur Anbindung beantworten wir unter support@e-rechnung.tools.