Schnittstelle

E-Rechnungen aus deinem System – über eine Schnittstelle, die zurückredet

Dein Shop schickt Empfänger und Positionen, Rechnungslotse gibt eine geprüfte E-Rechnung zurück: XRechnung, PDF und ZUGFeRD, mit einer Nummer aus dem Nummernkreis des Betriebs und derselben Prüfung nach EN 16931 wie im Portal. Wiederholte Aufrufe sind eingeplant, Fehler tragen ihren Grund mit.

Zugang anlegen Kontingente ansehen

Sie kostet nichts extra – bezahlt wird die Menge

Die Schnittstelle steht in jedem Tarif offen, auch im kostenlosen Konto. Kein Aufpreis je Aufruf, keine Gebühr je Bestellung. Was zählt, ist die Zahl der erzeugten Rechnungen – und die läuft gegen dasselbe Monatskontingent wie die im Portal. Ein Konto brauchst du trotzdem: Ein Schlüssel entsteht nur dort.

Kostenloses Konto

3 / Monat

Zum Ausprobieren: einmal durchlaufen lassen, die drei Dateien ansehen, dann entscheiden.

Pro

Anmelden

Jeder Zugang gehört zu genau einem Betrieb und trägt nur die Rechte, die du ihm gibst. Der Schlüssel gehört in die Kopfzeile – nie in die Adresse: Dort landet er im Zugriffsprotokoll jedes Proxys und ist nicht mehr geheim. Aufrufe mit einem Schlüssel in der Adresse weisen wir deshalb ausdrücklich ab.

Authorization: Bearer rl_live_…

Endpunkte

Verfügbare Endpunkte mit benötigtem Recht, Zweck und Antwort
Aufruf	Recht	Zweck
POST/api/v1/rechnungen	schreiben	Erzeugt eine Rechnung aus Empfänger und Positionen. Absenderangaben, Nummer und Zahlungsziel kommen aus dem Betrieb – der Aufruf liefert sie nicht mit.201 mit Nummer, Beträgen und den Abhol-Adressen der drei Dateien.
GET/api/v1/rechnungen/{id}/{format}	lesen	Holt eine erzeugte Datei. Format ist `xrechnung`, `pdf` oder `zugferd`.Die Datei als Download, sonst 404.
GET/api/v1/betrieb	lesen	Liest die Stammdaten des Betriebs, an dem der Schlüssel hängt.200 mit Anschrift, Steuernummer, Bankverbindung und Gestaltung.
PATCH/api/v1/betrieb	stammdaten	Ändert einzelne Felder des Betriebs. Nur mitgeschickte Felder werden angefasst – ein nicht genanntes Feld bleibt, wie es ist.200 mit dem neuen Stand.

Ein vollständiger Aufruf

So wie er ist, funktioniert er. Absender, Nummer und Fälligkeit stehen bewusst nicht darin – die kommen aus dem Betrieb.

Anfrage

curl -X POST https://rechnungslotse.de/api/v1/rechnungen \
  -H "Authorization: Bearer rl_live_DEIN_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: bestellung-4711" \
  -d '{
    "buyer": {
      "name": "Beispiel GmbH",
      "street": "Musterweg 3",
      "zip": "10115",
      "city": "Berlin",
      "email": "rechnung@beispiel.de"
    },
    "lines": [
      {
        "name": "Artikel A",
        "quantityMilli": 2000,
        "unitCode": "C62",
        "unitPriceCents": 4900,
        "taxCategory": "S",
        "taxRatePercentMilli": 19000
      }
    ],
    "buyerReference": "SHOP-4711"
  }'

Antwort · 201

{
  "id": "8ea593ca-4b43-4d69-a8a3-8a4087515a03",
  "number": "RE-2026-0003",
  "issueDate": "2026-07-31",
  "dueDate": "2026-08-14",
  "grossTotalCents": 11662,
  "documents": [
    { "format": "xrechnung", "filename": "RE-2026-0003.xml", "url": "…" },
    { "format": "pdf",       "filename": "RE-2026-0003.pdf", "url": "…" },
    { "format": "zugferd",   "filename": "RE-2026-0003_zugferd.pdf", "url": "…" }
  ]
}

Die Positionszeile

Hier geht die meiste Zeit verloren, deshalb ausführlich: Mengen und Steuersätze sind ganzzahlig in Tausendsteln, Beträge in Cent. Das ist unbequemer zu tippen und die einzige Art, bei der nichts gerundet wird.

Felder einer Position mit Pflichtangabe und Erklärung
Feld	Pflicht	Bedeutung
name	ja	Bezeichnung der Leistung, wie sie auf der Rechnung steht.
quantityMilli	ja	Menge in TAUSENDSTELN. 2 Stück sind 2000, eine halbe Stunde ist 500. Ganzzahlig, damit nichts gerundet wird.
unitCode	ja	Einheit nach UN/ECE Rec. 20: C62 (Stück), HUR (Stunde), DAY (Tag), MTR (Meter), MTK (m²), KGM (kg), LTR (Liter), KMT (km), H87 (Stück, alternativ).
unitPriceCents	ja	Einzelpreis NETTO in Cent. Ganzzahlig, nie negativ – eine Gutschrift läuft über eine negative Menge.
taxCategory	ja	Steuerkategorie: S (Regelsatz), Z (Nullsatz), E (befreit), AE (Reverse Charge), K (innergemeinschaftlich), G (Ausfuhr), O (nicht steuerbar).
taxRatePercentMilli	ja	Steuersatz in Tausendstel Prozent: 19 % sind 19000, 7 % sind 7000.
description	optional	Zusatztext unter der Bezeichnung.
allowanceCents	optional	Nachlass auf diese Position, in Cent.
chargeCents	optional	Zuschlag auf diese Position, in Cent.

Wenn etwas schiefgeht

Jede Fehlerantwort trägt einen code, eine Meldung in Klartext und – wo es hilft – eine Liste checks mit den betroffenen Feldern. Die letzte Spalte ist die wichtigste: Sie sagt, ob eine Wiederholung Sinn hat.

Fehlercodes mit Status, Bedeutung und Handlungsempfehlung
Code	HTTP	Bedeutet	Was tun
invalid_input	400	Der Datensatz ist unvollständig oder widersprüchlich. Die Antwort trägt `checks` mit den betroffenen Feldern.	Nicht wiederholen – die Angaben korrigieren. Die Liste nennt das Feld.
validation_failed	422	Der Datensatz war vollständig, aber das Ergebnis besteht die Prüfung nach EN 16931 nicht. `checks` trägt die Regelmeldungen.	Nicht wiederholen. Meist fehlt eine Pflichtangabe am Betrieb (Telefon, Bankverbindung).
api_schluessel_ungueltig	401	Unbekannter oder gesperrter Schlüssel.	Nicht wiederholen. Im Portal einen neuen Zugang anlegen.
api_schluessel_abgelaufen	401	Der Schlüssel hatte ein Ablaufdatum, und das ist überschritten.	Nicht wiederholen. Neuen Zugang anlegen und im Plugin hinterlegen.
api_recht_fehlt	403	Der Schlüssel ist gültig, trägt dieses Recht aber nicht.	Nicht wiederholen. Im Portal einen Zugang mit dem passenden Recht anlegen.
quota_exhausted	429	Das Monatskontingent des Tarifs ist aufgebraucht.	Später wiederholen – im nächsten Monat, oder wenn der Betrieb aufstockt.
rate_limited	429	Zu viele Aufrufe in kurzer Zeit.	Wiederholen, mit wachsendem Abstand (exponentiell).
service_unavailable	503	Ein nachgelagerter Dienst antwortet gerade nicht.	Wiederholen. MIT demselben Idempotency-Key, dann entsteht keine zweite Rechnung.

Fertige Plugins für WooCommerce und Shopify

Sie sind in Arbeit und benutzen genau diese Schnittstelle – nichts Eigenes, nichts Verstecktes. Wer heute schon anbinden will, kommt mit dieser Seite und einem Zugang aus dem Portal aus. Sag uns Bescheid, wenn du etwas brauchst, das hier fehlt: kontakt@rechnungslotse.de

Zugang anlegen Erzeugte Datei gegenprüfen

Häufige Fragen

Was kostet die Schnittstelle?

Sie steht in jedem Tarif offen und kostet keinen Aufpreis – auch nicht je Aufruf. Bezahlt wird die Menge: Im kostenlosen Konto sind drei Rechnungen im Monat drin, in Pro 200, ab Büro gibt es keine Mengengrenze. Erzeugte Rechnungen zählen gegen dasselbe Kontingent wie die im Portal – die Schnittstelle ist eine zweite Tür zur selben Engine, keine Umgehung.

Wie verhindere ich doppelte Rechnungen bei einem wiederholten Webhook?

Schick einen Idempotency-Key mit, zum Beispiel die Bestellnummer deines Shops. Ein zweiter Aufruf mit demselben Schlüssel gibt die erste Antwort zurück – gleiche Rechnungsnummer, keine zweite Rechnung, keine Lücke im Nummernkreis. Ohne den Kopf legen wir beide Aufrufe an, weil zwei gleich aussehende Bestellungen am selben Tag normal sind.

Warum kann ich die Absenderangaben nicht mitschicken?

Weil sie sonst zweimal existieren. Anschrift, Steuernummer und Bankverbindung stehen am Betrieb und kommen bei jeder Erzeugung frisch von dort. Liefe eine zweite Fassung im Plugin mit, stünde auf der Rechnung irgendwann etwas anderes als im Portal – und das sind Pflichtangaben nach § 14 UStG, an denen der Vorsteuerabzug des Empfängers hängt.

Kann ein Schlüssel ablaufen?

Auf Wunsch. Beim Anlegen lässt sich 90 Tage, ein Jahr oder zwei Jahre wählen; ohne Angabe gilt er unbefristet. Ein abgelaufener Schlüssel antwortet mit einer eigenen Meldung, damit im Plugin erkennbar ist, warum es stehenbleibt.

Gibt es fertige Plugins?

Für WooCommerce und Shopify sind sie in Arbeit. Die Schnittstelle darunter ist dieselbe – wer nicht warten will, baut mit dieser Seite in einem Nachmittag seine eigene Anbindung.