Entwickler

REST-API für E-Rechnungen

Erzeugen Sie XRechnung und ZUGFeRD aus Ihrem Shop, ERP oder CRM – mit einem einzigen JSON-Aufruf. Jede Rechnung wird automatisch mit dem KoSIT-Validator geprüft und archiviert.

Ab Business-TarifVersion v1JSON · HTTPS

Einstieg

Die API folgt REST-Konventionen, nimmt JSON entgegen und antwortet mit JSON (bzw. PDF/XML bei Downloads). Alle Anfragen laufen über HTTPS. Die Basis-URL lautet:

https://erechnungspilot.de/api/v1

Beträge werden als Dezimal-Strings übergeben (z. B. "120.00"), um Rundungsfehler durch Gleitkommazahlen zu vermeiden. Summen und Steuerbeträge berechnet die API selbst nach den Rechenregeln der EN 16931.

Authentifizierung

Erstellen Sie in der App im Bereich API-Schlüssel einen Schlüssel und senden Sie ihn bei jeder Anfrage im Authorization-Header mit. Behandeln Sie den Schlüssel wie ein Passwort: Speichern Sie ihn nur serverseitig und nie im Browser oder in öffentlichen Repositories.

Header

Authorization: Bearer <API-Schlüssel>

Limits & Tarife

Die API ist in den Tarifen Business und Pro sowie während der 14-tägigen Testphase verfügbar.
Rate-Limit: 60 Anfragen pro Minute je API-Schlüssel. Bei Überschreitung antwortet die API mit Status 429.
Kontingent: Jede finalisierte Rechnung zählt einmal gegen Ihr Monatskontingent (500 im Business-, 2.000 im Pro-Tarif). Abrufe, Downloads und Validierungen zählen nicht. Ist das Kontingent erschöpft, wird das Erstellen weiterer Rechnungen mit einer Fehlermeldung abgelehnt (im Pro-Tarif wird stattdessen der Mehrverbrauch berechnet).

Fehlerformat

Fehler werden mit einem passenden HTTP-Status und einheitlichem JSON-Body beantwortet. code ist ein maschinenlesbarer Bezeichner, message eine verständliche Beschreibung.

Fehlerantwort

{
  "error": {
    "code": "…",
    "message": "Beschreibung des Fehlers"
  }
}

HTTP-Statuscodes der API
Status	Bedeutung
200 / 201	Erfolg; 201 bei neu erstellter Rechnung
400	Ungültige Anfrage, z. B. fehlerhaftes JSON oder fehlende Pflichtfelder
401	API-Schlüssel fehlt oder ist ungültig
403	Ihr Tarif enthält keinen API-Zugriff (ab Business)
404	Rechnung nicht gefunden
422	Die Rechnung hat die Validierung nicht bestanden
429	Rate-Limit überschritten – kurz warten und erneut senden
5xx	Serverfehler – Anfrage später wiederholen

Rechnung erstellen und finalisieren

POST/api/v1/invoices

Legt eine Rechnung an, berechnet Summen und Steuern, erzeugt die E-Rechnung im gewünschten Format, prüft sie mit dem KoSIT-Validator und finalisiert sie. Mit sendEmail: true wird sie anschließend an den Kunden gesendet. Ihre Absenderdaten (Firma, Steuernummer, Bankverbindung) werden aus Ihrem Unternehmensprofil übernommen.

Request-Body

Felder des Request-Bodys
Feld	Typ	Pflicht	Beschreibung
customer	object	ja	Rechnungsempfänger (siehe unten)
customer.name	string	ja	Firmenname bzw. Name
customer.street	string	ja	Straße und Hausnummer
customer.zip	string	ja	Postleitzahl
customer.city	string	ja	Ort
customer.country	string	ja	Ländercode nach ISO 3166-1 alpha-2, z. B. DE
customer.vatId	string	nein	USt-IdNr. des Kunden
customer.email	string	nein	E-Mail-Adresse – erforderlich, wenn sendEmail true ist
customer.leitwegId	string	nein	Leitweg-ID bei öffentlichen Auftraggebern (wird als Käuferreferenz BT-10 gesetzt)
issueDate	string	nein	Rechnungsdatum im Format JJJJ-MM-TT; Standard: heute
dueDate	string	nein	Fälligkeitsdatum im Format JJJJ-MM-TT
format	string	ja	"zugferd", "xrechnung-ubl" oder "xrechnung-cii"
lines	array	ja	Mindestens eine Rechnungsposition
lines[].description	string	ja	Bezeichnung der Leistung
lines[].quantity	number	ja	Menge
lines[].unitCode	string	nein	Einheit nach UN/ECE Rec. 20, z. B. C62 (Stück), HUR (Stunde)
lines[].unitPrice	string	ja	Netto-Einzelpreis als Dezimal-String, z. B. "120.00"
lines[].vatRate	number	ja	Umsatzsteuersatz in Prozent, z. B. 19, 7 oder 0
note	string	nein	Freitext-Hinweis auf der Rechnung
sendEmail	boolean	nein	true: Rechnung nach erfolgreicher Prüfung an customer.email senden

Beispiel

curl -X POST https://erechnungspilot.de/api/v1/invoices \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "xrechnung-ubl",
    "customer": {
      "name": "Stadtverwaltung Musterstadt",
      "street": "Rathausplatz 1",
      "zip": "12345",
      "city": "Musterstadt",
      "country": "DE",
      "email": "rechnung@musterstadt.example",
      "leitwegId": "991-12345-67"
    },
    "issueDate": "2026-10-15",
    "dueDate": "2026-11-14",
    "lines": [
      { "description": "Beratung Digitalisierung", "quantity": 8, "unitCode": "HUR", "unitPrice": "120.00", "vatRate": 19 },
      { "description": "Reisekostenpauschale", "quantity": 1, "unitCode": "C62", "unitPrice": "85.00", "vatRate": 19 }
    ],
    "note": "Projekt P-2026-17",
    "sendEmail": true
  }'

Die Antwort enthält die angelegte Rechnung inklusive id, Rechnungsnummer, Summen und Validierungsergebnis. Besteht die Rechnung die Validierung nicht, antwortet die API mit Status 422 und beschreibt die verletzten Regeln in der Fehlermeldung; die Rechnung wird dann nicht finalisiert und zählt nicht gegen Ihr Kontingent.

Rechnungen auflisten

GET/api/v1/invoices

Liefert Ihre Rechnungen, neueste zuerst.

Beispiel

curl https://erechnungspilot.de/api/v1/invoices \
  -H "Authorization: Bearer $API_KEY"

Rechnung abrufen

GET/api/v1/invoices/{id}

Liefert eine einzelne Rechnung mit Status, Summen, Positionen und Validierungsergebnis.

Beispiel

curl https://erechnungspilot.de/api/v1/invoices/INVOICE_ID \
  -H "Authorization: Bearer $API_KEY"

PDF herunterladen

GET/api/v1/invoices/{id}/pdf

Lädt die PDF-Darstellung herunter (application/pdf). Bei ZUGFeRD ist das die hybride PDF/A-3 mit eingebetteter XML.

Beispiel

curl https://erechnungspilot.de/api/v1/invoices/INVOICE_ID/pdf \
  -H "Authorization: Bearer $API_KEY" \
  -o rechnung.pdf

XML herunterladen

GET/api/v1/invoices/{id}/xml

Lädt die strukturierte E-Rechnung als XML herunter (application/xml) – bei XRechnung die UBL- bzw. CII-Datei, bei ZUGFeRD die eingebettete CII-XML.

Beispiel

curl https://erechnungspilot.de/api/v1/invoices/INVOICE_ID/xml \
  -H "Authorization: Bearer $API_KEY" \
  -o rechnung.xml

XML validieren

POST/api/v1/validate

Prüft eine beliebige E-Rechnung im XML-Format (XRechnung UBL/CII oder CII-XML aus ZUGFeRD) mit dem KoSIT-Validator. Senden Sie die XML unverändert als Request-Body. Validierungen zählen nicht gegen Ihr Rechnungskontingent.

Beispiel

curl -X POST https://erechnungspilot.de/api/v1/validate \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/xml" \
  --data-binary @rechnung.xml

Die Antwort enthält das Prüfergebnis (gültig/ungültig) sowie die gefundenen Fehler und Warnungen mit Regel-ID und Beschreibung.

Fragen zur Integration?

Schreiben Sie uns über die Kontaktseite. Für Shopify, WooCommerce und Shopware sind fertige Anbindungen in Arbeit – siehe Integrationen.