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 } ]
}

Echtheits-Siegel & öffentliche Verifikation

Ein Echtheits-Siegel bindet die Kernfelder (Aussteller, Nummer, Datum, Betrag, IBAN) kryptografisch an eine Ed25519-Signatur. Ihr Kunde scannt den QR-Code bzw. öffnet den Link und sieht sofort: echt, unverändert, richtige IBAN. Das schützt Ihre Kunden vor gefälschten „Rechnungen von Ihnen" mit fremder Bankverbindung.

• Beim Erzeugen: /v1/generate mit "seal": true → der QR wird direkt ins ZUGFeRD-PDF eingebettet, die verify_url kommt im Header X-Seal-Verify-Url (+2 Credits, Kunden-Key, IBAN erforderlich).
• Eigenes PDF: /v1/embed mit "seal": true → Siegel wird erzeugt, verify_url im Header; das Kundenlayout bleibt unverändert (QR selbst platzieren).
• Nur Siegel: /v1/seal (JSON wie /generate oder Kernfelder) → gibt verify_url und Token zurück, ohne PDF.
• Prüfen: GET /verify/{token} – öffentlich, ohne Key, ohne Credit. Status: valid, revoked, tampered, notfound.
• White-Label: Die Verify-Seite trägt Logo und Namen des Ausstellers (aus dessen Profil).
• Widerruf: Nach Storno/Korrektur im Dashboard widerrufen – die Verify-Seite zeigt dann „widerrufen".

curl -X POST https://sichere-erechnung.de/v1/generate \
  -H "Authorization: Bearer IHR_API_KEY" -H "Content-Type: application/json" \
  -d '{"seal":true,"invoice":{…},"seller":{…},"buyer":{…},"lines":[…]}'

# Antwort: ZUGFeRD-PDF mit QR   ·   Header: X-Seal-Verify-Url: https://sichere-erechnung.de/verify/AbC123…

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

• Credits je Aufruf: /v1/cii, /v1/generate, /v1/embed, /v1/validate, /v1/extract = 1; /v1/check (Eingangsprüfung) = 2; /v1/seal (Echtheits-Siegel) = 2; /v1/validate/fraud = 3; /v1/automap (KI-Import) = 10. Die öffentliche Verifikation /verify/{token} ist immer kostenlos.
• 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

Eingangsprüfung (POST /v1/check, 2 Credits): die umfassende Prüfung einer eingegangenen Rechnung (PDF oder XML) in einem Aufruf – KoSIT-Validierung + IBAN-Betrugsabgleich (Lieferanten-Historie) + Dublettencheck. Antwort ist ein einheitlicher Risk-Report mit risk: green|yellow|red und einer Liste von findings. Jede Prüfung wird in der Prüf-Historie gespeichert (in der Weboberfläche unter Geprüfte Rechnungen einsehbar). Geprüfte Rechnungen lassen sich dort zur Zahlung vormerken und als SEPA-Sammelüberweisung (pain.001) exportieren – die Datei laden Sie in Ihrem Online-Banking hoch (kein Geldfluss über uns, die Empfänger-IBANs sind bereits geprüft). Über den IBAN-Tresor geben Sie vertrauenswürdige Lieferanten-Bankverbindungen frei oder sperren sie – eine gesperrte IBAN löst bei jeder Prüfung eine rote Warnung aus. Es wird keine Klar-IBAN gespeichert (HMAC-Hash).

Team & Vier-Augen-Freigabe: Unter Team laden Sie weitere Nutzer in Ihr Konto ein (Rollen Admin/Member; gemeinsames Guthaben, gemeinsame Daten und Prüf-Historie). Sobald mindestens zwei Personen im Team sind, greift im IBAN-Tresor automatisch das Vier-Augen-Prinzip: eine Freigabe wird angefordert und muss von einer zweiten Person bestätigt werden. Abrechnung, API-Keys und Konto-Löschung bleiben Inhabern und Admins vorbehalten.

USt-IdNr-Überwachung & Alarme: Unter USt-IdNr-Prüfung überwachen wir hinterlegte USt-IdNrn Ihrer Kunden regelmäßig automatisch über EU-VIES und melden per Alarm (Dashboard + E-Mail), sobald eine zuvor gültige Nummer ungültig wird – wichtig für Reverse-Charge und Steuerfreiheit.

Postfach-Anbindung (automatische Eingangsprüfung): Unter Postfach verbinden Sie ein E-Mail-Postfach per IMAP (nur Lesezugriff, Passwort verschlüsselt). Wir holen daraus Eingangsrechnungen automatisch, prüfen sie wie oben und warnen bei Auffälligkeit per Alarm – ohne manuelles Hochladen.

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.