Dokumentation & API

Standards & Konformität

Jede erzeugte Rechnung ist damit zugleich gültige ZUGFeRD-, Factur-X- und EN-16931-Datei.

Schnellstart

curl -X POST https://sichere-erechnung.de/v1/generate \
  -H "Authorization: Bearer IHR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @rechnung.json -o rechnung.pdf

Authentifizierung

Jeder Aufruf braucht Ihren API-Key im Header – als Bearer-Token oder X-API-Key:

Authorization: Bearer IHR_API_KEY

Keys verwalten Sie im Dashboard (Erstellen/Widerrufen). Der Schlüssel wird nur als Hash gespeichert und ist nur einmalig bei der Erstellung sichtbar.

Endpunkte

Beispiel-Eingabe (gilt für /v1/cii und /v1/generate):

{
  "invoice": { "number": "2026-0001", "issue_date": "2026-06-29",
                "currency": "EUR", "payment": { "iban": "DE02..." } },
  "seller": { "name": "Ihre GmbH", "street": "Weg 1", "zip": "10115",
               "city": "Berlin", "country": "DE", "vat_id": "DE123456789" },
  "buyer":  { "name": "Kunde AG", "street": "Allee 2", "zip": "80331",
               "city": "München", "country": "DE" },
  "lines": [ { "name": "Beratung", "qty": 10, "unit": "Stunden",
               "unit_price": 120.00, "vat_rate": 19 } ]
}

?validate=1 prüft vor der Auslieferung zusätzlich gegen KoSIT. Pflichtfelder folgen EN 16931 (vollständige Anschrift von Verkäufer und Käufer, USt-IdNr. oder Steuernummer, mind. eine Position).

Weitere Felder & Stornorechnung

Stornorechnung erzeugen Sie rein über die API: type_code: "384", reference_invoice auf die Originalnummer setzen und die Positionsmengen/-beträge negativ angeben:

{
  "invoice": { "number": "STORNO-2026-0001", "issue_date": "2026-07-01",
               "type_code": "384", "reference_invoice": "2026-0001" },
  "seller": { … }, "buyer": { … },
  "lines": [ { "name": "Beratung", "qty": -10, "unit": "HUR",
               "unit_price": 120.00, "vat_rate": 19 } ]
}

In Ihre Software einbinden

Jede Sprache mit HTTP genügt – Buchhaltung, ERP, Online-Shop oder eigenes Tool. Zwei Beispiele:

$ch = curl_init("https://sichere-erechnung.de/v1/cii");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer $key", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode($rechnung),
  CURLOPT_RETURNTRANSFER => true,
]);
$xml = curl_exec($ch); // fertiges EN-16931-CII-XML

import requests
r = requests.post("https://sichere-erechnung.de/v1/generate",
    headers={"Authorization": f"Bearer {key}"},
    json=rechnung)
open("rechnung.pdf", "wb").write(r.content)

Typischer Ablauf in einer Buchhaltung/ERP: bei „Rechnung finalisieren" die Rechnungsdaten an /v1/generate senden und das zurückgelieferte ZUGFeRD-PDF speichern/versenden. Eingehende Lieferantenrechnungen vor der Verbuchung über /v1/validate prüfen.

Abrechnung & Limits

• Jeder Aufruf von /v1/cii|generate|validate|extract kostet 1 Credit.
• Guthaben leer → 402 Payment Required (Credits im Shop nachkaufen).
• Rate-Limit: 60 Anfragen/Minute pro Key; bei Überschreitung 429 mit Retry-After. Jede Antwort trägt X-RateLimit-Remaining.
• Bei einem Serverfehler (5xx) wird der Credit automatisch zurückerstattet.

Fehlercodes

Schutz & Korrekturen

IBAN-Betrugsschutz (POST /v1/validate/fraud, 3 Credits): prüft eine eingegangene Rechnung gegen KoSIT und gleicht die Kontoverbindung des Ausstellers mit Ihrer Lieferanten-Historie ab. Antwort enthält fraud_risk: high|low|unknown + Warnmeldung. Es wird keine Klar-IBAN gespeichert (HMAC-Hash). Erkennt: abweichende IBAN, ungültige Prüfziffer, IBAN-Land ≠ Firmensitz.

Rechnungs-Diff (POST /v1/diff): Felder original + corrected (PDF/XML) hochladen → strukturierter Positions-Diff als JSON oder, mit ?format=html, als einbettbare Git-Diff-Ansicht (grün = neu/teurer, rot/durchgestrichen = alt/entfernt) – auch im White-Label-iframe nutzbar.

No-Code & White-Label

Ohne Code (CSV): Unter Aus Tabelle (CSV) eine Tabelle (Excel/Google Sheets als CSV) hochladen → ZIP mit allen ZUGFeRD-PDFs. Ideal für Sachbearbeiter ohne Technik.

Make / Zapier: Mit dem „Webhooks/HTTP"-Baustein POST /v1/generate je Zeile aufrufen – kein eigener Server nötig.

White-Label-Einbettung: Für SaaS-Anbieter. Ihr Server mintet ein kurzlebiges Token aus Ihrem API-Key und bettet das Rechnungsformular im eigenen Corporate Design per iframe ein – der Endkunde legt kein Konto an, Credits laufen auf Ihr Kontingent:

# 1) Token serverseitig erzeugen (API-Key bleibt geheim)
curl -X POST https://sichere-erechnung.de/v1/embed/token \
  -H "Authorization: Bearer IHR_API_KEY" -H "Content-Type: application/json" \
  -d '{"accent":"#e8590c","title":"Rechnung – Ihre Marke","ttl":3600}'
# -> { "token": "…", "embed_url": "https://sichere-erechnung.de/embed?token=…" }

# 2) embed_url im iframe einbetten
<iframe src="https://sichere-erechnung.de/embed?token=…" style="width:100%;height:900px;border:0"></iframe>

Theming: Akzentfarbe, Titel und Eckenradius über das Token (accent, title, radius) oder kosmetisch per URL (?accent=ff8800&radius=4). Ihr Logo kommt aus dem Profil.

Events ans Eltern-Fenster (postMessage): Das iframe sendet zugferd:resize (Höhe für Auto-Resize), zugferd:success (PDF erzeugt, inkl. filename) und zugferd:error (mit errors[]). So binden Sie es an:

window.addEventListener('message', function (ev) {
  var d = ev.data || {};
  if (d.type === 'zugferd:resize') iframe.style.height = d.height + 'px';
  if (d.type === 'zugferd:success') console.log('Rechnung erzeugt:', d.filename);
  if (d.type === 'zugferd:error') console.warn(d.errors);
});

Live ansehen: White-Label-Seite mit eingebetteter Demo.