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.

Mehrere Firmen (X-Company)

Führen Sie mehrere Absenderfirmen in einer Firmengruppe, gehört jeder API-Key einer Firma: ohne weitere Angabe entsteht alles in dieser Firma (Nummernkreis, Absender, Archiv, Forderungen). Eine andere Firma der Gruppe sprechen Sie mit der Kopfzeile X-Company an, als Wert das Kürzel, die Konto-ID oder die USt-IdNr. der Firma. Bei einem JSON-Body geht auch das Feld company auf oberster Ebene; bei /v1/automap nur neben data, weil ein JSON-Body ohne data dort selbst der Rohtext ist. Bei XML- und Datei-Uploads gilt nur die Kopfzeile.

X-Company: LTD

• Eine andere Firma als die des Schlüssels braucht das Gruppenrecht (beim Erstellen des Keys im Dashboard ankreuzen), sonst 403. Die eigene Firma darf jeder Key nennen.
• Unbekannt, mehrdeutig, stillgelegt oder eine Firma einer anderen Gruppe: 422, die Anfrage läuft nie still in einer anderen Firma. Kopfzeile und Feld zugleich, aber auf verschiedene Firmen: ebenfalls 422.
• Abgerechnet wird über das Guthaben der Firmengruppe, das Rate-Limit gilt je Key, ein Idempotency-Key je angesprochener Firma. Der Key einer stillgelegten Firma antwortet mit 403.
• Welche Firmen ein Key ansprechen darf, liefert GET /v1/companies (kostenlos, auch mit nur lesendem Key): je Firma id, code, name, country und vat_id; ohne Gruppenrecht nur die eigene.
• Die USt-IdNr. bzw. Steuernummer im seller muss zur angesprochenen Firma passen. Gehört sie einer anderen Firma der Gruppe, antwortet die API mit 422 und nennt diese Firma, statt die Rechnung still in der falschen Firma zu erzeugen.

Firmenverwaltung in der Weboberfläche

Unter Firmen legen Inhaber und Team-Admins weitere Firmen an (Kürzel, Name, Land, Gesellschaftsform; bei Sitz außerhalb Deutschlands ist die Gesellschaftsform ein freies Feld), legen sie still oder aktivieren sie wieder. Jede Firma hat eigene Stammdaten, Nummernkreis, Kunden, Katalog, Archiv, Mahnwesen und Postfach; Anmeldung, Team, Tarif, Credits und KI-Schalter gelten für die ganze Gruppe. Ab zwei Firmen wechseln Sie oben in der Leiste die aktive Firma; die Konzernsicht zeigt offene Forderungen je Firma und Währung und liefert den Gesamtexport mit einem Ordner je Firma. Im Datei-Import wählt die Spalte absender die Firma je Rechnung, eingehende Rechnungen aus dem Postfach landen in der adressierten Firma.

Preis: Die erste Firma ist inklusive. Jede weitere kostet 390 Credits im Monat vom gemeinsamen Guthaben der Gruppe, gebucht zu Monatsbeginn und beim Anlegen bzw. Reaktivieren. Reicht das Guthaben nicht, bleibt die Firma aktiv und alle Belege erreichbar, es lassen sich aber keine neuen Rechnungen aus ihr erzeugen (422 mit Hinweis), bis Credits aufgeladen sind. Stillgelegte Firmen kosten ab dem Folgemonat nichts.

Freischaltung: Weitere Firmen schalten wir je Konto frei. Schreiben Sie uns an office@fhcp.de.

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", "vat_id": "DE987654321",
               "contact_name": "Erika Muster" },
  "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).

Idempotenz (empfohlen bei Retries): POST /v1/generate akzeptiert den Header Idempotency-Key: <Ihre ID>. Ein Wiederholungsaufruf mit demselben Schlüssel und demselben Body liefert die gespeicherte Antwort erneut (Header X-Idempotent-Replay: true), ohne die Rechnung ein zweites Mal anzulegen oder Credits erneut zu ziehen. 24 Stunden gültig; derselbe Schlüssel mit abweichendem Body → 409.

Eigene Beschriftungen der Word-Vorlage: "invoice": {"label_overrides": {"de": {"label_payment_terms": "Zahlungsbedingungen"}, "en": {"label_payment_terms": "Terms of payment"}}} ersetzt die Texte der ${label_*}-Platzhalter in der Sprache des Belegs (höchstens 80 Zeichen, ohne Angabe gelten die im Profil hinterlegten eigenen Texte, sonst der Standard). Wirkt nur in der Word-Vorlage, nicht im Standard-Layout und nicht im XML. ${label_item_discount} steht nur bei Positionen mit Rabatt; ${item_discount_text} nennt den Rabatt mit Beschriftung und ohne Vorzeichen („Rabatt 10,00 %“). ${label_item_code} beschriftet ${item_code} (Standard „Artikelnummer“), ${label_order_confirmation} ist die kurze Beschriftung zu ${seller_order_ref} (Standard „Bestätigung“).

Weitere Optionen für /v1/generate: "seal": true (Echtheits-Siegel, siehe unten) und "template": true (Rendering mit Ihrer im Profil hinterlegten Word-Vorlage/Corporate Design, Aufschlag laut Preisliste unten). Antwort-Header: X-Credits-Cost (verbrauchte Credits), X-Pay-Url (öffentliche „Jetzt zahlen"-Seite), X-Seal-Verify-Url (bei seal), X-Invoice-Template: used (Vorlage verwendet) bzw. X-Template-Warning mit dem Grund, wenn das PDF im Standard-Layout entstand. Eine Gutschrift und ein Beleg mit negativem Betrag laufen nur durch eine Vorlage mit dem Platzhalter ${payment_text} (alle ab dem 24.09.2026 erzeugten Vorlagen), sonst im Standard-Layout, der Aufschlag wird dann erstattet. Ebenso brauchen Anzahlungsrechnungen ${service_text}, Belege mit bereits bezahltem Betrag ${due_total} und Belege mit Vermerk ${advance_note} (siehe Anzahlung). Fremdwährungs-Rechnungen brauchen ${tax_total_tax_currency} (Umsatzsteuer in EUR), dazu gibt es ${tax_currency}, ${exchange_rate_text} (Kurs mit Quelle und Datum) und den Block ${fx_block}…${/fx_block}, der bei EUR entfällt.

Rechnungen mit Skonto brauchen ${skonto_text}, ${payment_terms} oder ${payment_text}: fehlt ${skonto_text}, steht der Skonto-Satz in einer eigenen Zeile unter ${payment_terms}, sonst vor ${payment_text}; fehlen alle drei, entsteht die Rechnung im Standard-Layout (Skonto ist Pflichtangabe nach § 14 Abs. 4 Nr. 7 UStG). ${item_net} ist der Positionsbetrag nach Rabatt und Zuschlag der Position, dazu gibt es ${item_gross} und ${item_discount}.

KI-Rechnung aus Freitext (ein Call, Freitext → fertiges PDF; nutzt Ihr Profil, Kundenstamm und Katalog):

curl -X POST "https://sichere-erechnung.de/v1/automap?generate=1" \
  -H "Authorization: Bearer IHR_API_KEY" -H "Content-Type: application/json" \
  -d '{"data": "Rechnung 2026-0007 an Muster AG, München: 10 Std Beratung a 120 EUR, 19% USt", "seal": true}' \
  -o rechnung.pdf

# Ohne generate: nur das erkannte JSON zurück (mapped + normalized), zum Vorbefüllen eigener Masken:
curl -X POST "https://sichere-erechnung.de/v1/automap" -H "Authorization: Bearer IHR_API_KEY" \
  -d 'Kunde Muster AG, München; 10 Std Beratung je 120 EUR; RgNr 2026-0007'

Erkennt die KI zu wenig für eine valide Rechnung, kommt bei generate kein PDF, sondern 422 mit den fehlenden Feldern (dann nur der KI-Import-Tarif, kein Generate-Tarif).

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. Genau das negierte Brutto eines eigenen Belegs gilt als Storno und schließt ihn in den Offenen Posten; der Storno einer Schlussrechnung hebt ihre Anrechnungen auf (Anzahlung):

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

Mengeneinheiten (BT-130)

Codes nach UN/ECE Recommendation 20 (BR-CL-23). Sie können den Code oder das deutsche Wort senden; unbekannte Codes reichen wir unverändert durch.

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. Bei Kernfeldern optional type_code (Belegart, z. B. 381 für eine Gutschrift): die Prüfseite nennt dann die Belegart und bei einer Gutschrift die IBAN als Erstattungskonto des Kunden, ohne Angabe spricht sie neutral von einem Beleg.
• Mehrere Bankverbindungen: Trägt die Rechnung eine weitere Bankverbindung (invoice.extra_bank), bestätigt das Siegel alle IBANs, die Prüfseite zeigt sie unter „Bestätigte Bankverbindungen" mit Bezeichnung und Bankland. /v1/seal antwortet zusätzlich mit fields.extra_ibans ([{"iban", "label"}], leer ohne); bei Kernfeldern optional extra_ibans als Liste von IBANs oder {"iban", "label"}. Die bisherigen Felder und alle älteren Siegel bleiben unverändert gültig.
• Prüfen: GET /verify/{token}, öffentlich, ohne Key, ohne Credit. Status: valid, revoked, tampered, notfound.
• Aussteller, USt-IdNr. und IBAN sind die Ihrer Firma: /v1/seal übernimmt sie aus Ihrem Profil und den Bankverbindungen. Fehlende Angaben werden ergänzt, abweichende mit 422 abgelehnt (bei einer Gutschrift oder Lastschrift ist die IBAN das Konto des Kunden und wird nicht geprüft). Die Währung ist ein dreistelliger Code, z. B. EUR. Das eingebettete White-Label-Formular nimmt Bankverbindung und Absender immer aus dem Profil des Token-Inhabers, nie aus der Anfrage.
• 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, /v1/diff, /v1/dunning = 1; /v1/check (Eingangsprüfung) = 2; /v1/seal (Echtheits-Siegel) = 2; /v1/validate/fraud = 3; /v1/automap (KI-Import) = 10.
• Aufschläge bei /v1/generate: "template": true (eigene Word-Vorlage) +2, je eingebetteter Anlage +1, "seal": true +2.
• Aufschlag bei /v1/automap: "catalog": true (Katalog bereits in der KI-Erkennung statt nur in der Nachbearbeitung) → 30 statt 10 Credits (3-fach, mehr Token je Aufruf).
• Kostenlos (aber Key + Rate-Limit): /v1/receivables, /v1/receivables/payment, /v1/receivables/paid, /v1/receivables/refund, /v1/partners, /v1/partners/archive, /v1/companies, /v1/embed/token, GET /v1. Ohne Key kostenlos: /verify/{token} und /health.
• 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.
• Sie zahlen nur für ein ausgeliefertes Ergebnis: Wird ein Aufruf abgelehnt, ob durch einen Serverfehler (5xx) oder weil die Daten nicht EN-16931-konform sind (422), erstatten wir die verbrauchten Credits automatisch, inklusive etwaiger Aufschläge. Ablehnungen wegen fehlendem Guthaben, Rate-Limit oder doppelter Rechnungsnummer kosten ohnehin nichts. Umgekehrt gilt: Ein Prüfergebnis „nicht konform" ist ein Ergebnis und wird berechnet, dafür haben Sie die Prüfung schließlich beauftragt (sie kommt als 200 mit valid: false).

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 (je type, level: red|yellow|info|green, message; info ist ein Hinweis ohne Risiko-Wirkung). Zusätzlich zu KoSIT, IBAN-Historie, Sperrliste, IBAN-Tresor, Factoring-Erkennung, Muldenkonto, IBAN-Land und Dublette erkennt die Prüfung Betrugsmuster aus Ihren eigenen Daten, ohne externe Abfragen: Zahlungsdruck (pressure, rot: neue oder geänderte IBAN + Fälligkeit ≤ 7 Tage + erste Rechnung des Lieferanten bzw. erste seit 90 Tagen), Betragsplausibilität (amount: ≥ 3-facher Median der letzten 12 Monate gelb, glatte Tausenderbeträge ab 5.000 € info, Beträge innerhalb 2 % unter den üblichen Freigabegrenzen 1.000/5.000/10.000/25.000 € gelb), Doppelrechnung mit neuer Nummer (duplicate_new_number, gelb: gleicher Lieferant, Betrag und IBAN innerhalb 30 Tagen, aber andere Rechnungsnummer; die nummerngleiche Dublette meldet weiterhin duplicate; beide können gleichzeitig auftreten und meinen dann zwei verschiedene Vorrechnungen), PDF-Forensik (consistency, rot: sichtbare IBAN, Betrag, Rechnungsnummer, Fälligkeit oder Aussteller widersprechen dem XML; pdf_meta: Erzeuger ist Textverarbeitung/Online-Editor info, nachträglich bearbeitet gelb, Erstelldatum > 30 Tage vom Rechnungsdatum entfernt gelb) und bei Eingang über das Postfach die Absender-Prüfung (sender: Lookalike-Domain zu einer bekannten Domain des Lieferanten rot, neue Domain gelb, Reply-To ≠ From gelb, SPF/DKIM-Fehlschlag gelb; die erste Domain je Lieferant wird als Referenz gespeichert). Mehrere Firmen: Die Prüfung kennt alle Firmen Ihrer Gruppe. Ist die Rechnung an eine andere Ihrer Firmen adressiert, enthält der Report company: {"status": "sister", "name"} und den Befund recipient (gelb, hier nicht zahlbar); prüfen Sie sie dann mit der Kopfzeile X-Company in dieser Firma. Passt der Empfänger zu mehreren Ihrer Firmen, meldet der Report company: {"status": "open", "candidates": [{"name"}]} und den Befund empfaenger_firma (gelb); die Rechnung ist bis zur Zuordnung nicht zahlbar. Ein API-Key mit Gruppenrecht erhält zu jeder Firma zusätzlich id und code (Kürzel). Die Sperrliste gilt für alle Firmen der Gruppe. Konten ohne weitere Firmen erhalten kein Feld company. 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).

Externe Quellen in der Eingangsprüfung (kostenlos, ohne Anmeldung, jeweils als eigener findings-Eintrag): vies: USt-IdNr. des Ausstellers gegen EU-VIES (ungültig = rot; liefert VIES den Firmennamen, wird er mit der Rechnung abgeglichen, Abweichung = gelb; DE liefert keinen Namen). bank: bei deutschen IBANs die Bankleitzahl gegen die Bankleitzahlendatei der Deutschen Bundesbank (BLZ existiert nicht = rot; Institut mit Sofort-Kontoeröffnung wie N26/Solaris/Revolut = gelb mit Begründung). sanctions: Ausstellername gegen die konsolidierte EU-Finanzsanktionsliste (exakter Treffer = rot, enger Treffer = gelb; keine Treffer auf Namen unter 5 Zeichen). address: Anschrift des Ausstellers (DE/AT) über unseren Adressdienst (nicht auffindbar oder PLZ/Ort passen nicht = gelb). Ist eine Quelle gerade nicht erreichbar, kommt level: info („Prüfung nicht möglich"); die Prüfung bricht nie ab und info beeinflusst das Gesamtrisiko nicht. VIES-Antworten werden 24 h gecacht, Bundesbank- und Sanktionsliste hält der Worker aktuell.

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): Im Profil (Abschnitt Postfach) verbinden Sie ein E-Mail-Postfach per IMAP (nur Lesezugriff, Passwort verschlüsselt). Wir holen daraus Eingangsrechnungen automatisch, prüfen sie wie oben einschließlich des Mail-Absenders (Domain-Historie je Lieferant, Lookalike-Domains, Reply-To, SPF/DKIM aus den Kopfzeilen, ohne Netzabfrage) 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.

Mehrere IBANs in einer Eingangsrechnung (weitere Überweisungsverbindungen, BG-17): Jede weitere IBAN wird wie die erste gegen Sperrliste, IBAN-Tresor, Historie des Lieferanten und Muldenkonten geprüft. Eine bekannte weitere IBAN ist kein Befund, eine bisher unbekannte erscheint als gelber Hinweis (kein Betrugsverdacht), eine gesperrte oder ungültige als rot. In der Antwort stehen sie unter fraud.extra_ibans (iban maskiert, status, risk, message), das Urteil der ersten IBAN unter fraud.iban_risk. Rechnungen mit einer IBAN werden wie bisher bewertet.

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.

Forderungsmanagement: Mahnwesen je Partner und je Rechnung

Das Mahnwesen kennt drei Ebenen, jede erbt von der darüber: Konto (Einstellungen unter Offene Posten), Geschäftspartner (Karte „Mahnwesen" in der Partnerakte, per API die Felder dunning_* an POST /v1/partners) und Rechnung („Mahnwesen anpassen" an der offenen Rechnung). Acht Felder je Ebene: Modus (auto = der Dienst mahnt, manual = nur von Hand, off = nie, auch Knopf und API lehnen ab), Tonalität, Mahntexte je Stufe, Mahnkosten der 1. und letzten Mahnung, 40-€-Pauschale, Verzugsschaden, Stufen-Fristen (Tage nach Fälligkeit für Zahlungserinnerung, 1. und 2. Mahnung, Standard 3/10/21) und Zahlungsfrist im Schreiben (Standard 10 Tage). Ein leeres Feld bedeutet „wie übergeordnet"; die Oberfläche zeigt neben jedem Feld, welche Ebene den Wert liefert. Der automatische Lauf beachtet die Ebenen ebenso: ein Partner auf auto wird gemahnt, auch wenn das Konto auf manuell steht, und umgekehrt.

Import aus Excel, CSV und XML

Drei Wege, eine Erzeugungsstrecke: Unter Aus Datei erstellen laden Sie eine Datei hoch und sehen zuerst eine Vorschau (Rechnungen, Positionen, Summen, Fehler mit Blatt und Zeile), erst danach wird erzeugt. Dieselben Dateien nimmt POST /v1/import entgegen. Gelesen werden Excel (.xlsx, .xls), LibreOffice (.ods), CSV (Trennzeichen Semikolon, Komma oder Tab) und EN-16931-XML (ZUGFeRD/Factur-X-CII sowie XRechnung in beiden Syntaxen, CII und UBL). Excel-Dateien werden in einem abgeschotteten Container gelesen, Formeln kommen berechnet, Makros werden nie ausgeführt.

Viele Rechnungen aus einer Tabelle: eine Zeile je Position, Zeilen mit derselben Rechnungsnummer bilden eine Rechnung. Kopffelder (Empfänger, Zahlung, Lieferanschrift) dürfen in jeder Zeile stehen, die erste Zeile je Rechnung zählt. Die Kopfzeile darf auch unterhalb von Titelzeilen liegen. Pflicht sind rechnungsnummer, kunde, position und einzelpreis (oder netto). Der Absender kommt immer aus Ihrem Profil. Vorlage mit allen Spalten herunterladen.

Eine Excel-Rechnung als Ganzes: Rechnungen, die Sie bisher in Excel geschrieben haben (Briefkopf, Empfängerblock, Positionstabelle), werden erkannt und in die Rechnungsmaske übernommen. Ist das Layout nicht eindeutig, bietet die Oberfläche die KI-Zuordnung an (Opt-in, Kosten wie der KI-Import).

XML: eine vorhandene E-Rechnung (etwa aus einem anderen Tool) wird vollständig ins Rechnungsschema zurückgelesen, einschließlich Storno-Bezug, Leitweg-ID, Zahlungsbedingungen, Skonto, Lieferanschrift und Anlagen. Was keinen Platz hat, wird als Hinweis gemeldet. Aus UBL wird dabei CII, für XRechnung-Empfänger zulässig. Beta Fremd-XML (z. B. ein ERP-Export ohne EN-16931-Syntax) lesen wir nicht deterministisch; auf Wunsch ordnet die KI die Felder zu (Opt-in mit Kosten wie der KI-Import, Ergebnis in der Maske prüfen).

No-Code & White-Label

Ohne Code: Unter Aus Datei erstellen eine Tabelle (Excel, LibreOffice oder CSV) hochladen → Vorschau, dann 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.

Empfänger-Ansprechpartner & Katalog: Das eingebettete Formular enthält ein „z. Hd."-Feld (BT-56, erscheint auf der Rechnung) und schlägt Positionen aus Ihrem Katalog per Autovervollständigung vor (füllt Einheit, Nettopreis und USt), identisch zur Haupt-Oberfläche und unter Ihrer Marke.

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.

Anzahlung, Teil- und Schlussrechnung

Belegarten: 386 Anzahlungsrechnung, 875 Abschlagsrechnung Bauleistung, 326 Teilrechnung (ausgeführte Teilleistung), 876 Teilschlussrechnung Bauleistung, 877 Schlussrechnung Bauleistung. Eine Schlussrechnung ist eine Restrechnung (UStAE 14.8 Abs. 11, BMF-Schreiben vom 15.10.2024 Rn. 47 und 48): Sie enthält alle Positionen der Gesamtleistung und je Vorbeleg und Steuersatz eine Minusposition (Menge -1, Preis netto positiv). Steuer, Brutto und Zahlbetrag betreffen nur den Rest. Das Feld invoice.prepaid (BT-113) wird dafür nicht benutzt. Eine Rechnung 380 mit Anrechnung heißt auf Beleg, Mail, Liste und Mahnung „Schlussrechnung“, im XML bleibt sie 380.

Schlussrechnung per API

Für eine eigene Anzahlungsrechnung genügt die Nummer. Wir ergänzen Datum, Belegart, den anzurechnenden Betrag und die Aufteilung je Steuersatz aus Ihrem Konto:

{ "invoice": { "type_code": "380", "number": "SR-2026-001", "issue_date": "2026-09-30",
               "delivery_date": "2026-09-25", "seller_order_ref": "AB-2026-0815",
               "deductions": [ { "number": "AZ-2026-001" } ] },
  "seller": { … }, "buyer": { … },
  "lines": [ { "name": "Umbau Halle 3 gemäß Auftrag AB-2026-0815", "qty": 1, "unit_price": 30000.00, "vat_rate": 19 } ] }

Ergebnis bei bezahlter Anzahlung über 10.710,00 (9.000,00 netto): 30.000,00 abzüglich 9.000,00 = 21.000,00 netto, 3.990,00 USt, Zahlbetrag 24.990,00. Ein fremder Vorbeleg (nicht in Ihrem Konto) braucht die Nettobeträge je Steuersatz; amount allein genügt nur bei genau einem Steuersatz in den Positionen (dann mit Hinweis, dass net genauer ist):

"deductions": [ { "number": "A-77", "issue_date": "2026-03-01", "type_code": "386",
                  "received_date": "2026-03-10", "rates": [ { "vat_rate": 19, "net": 9000.00 } ] } ]

Eine Anzahlungsrechnung nennt den voraussichtlichen Zeitpunkt der Leistung statt eines Leistungsdatums:

{ "invoice": { "type_code": "386", "number": "AZ-2026-001", "issue_date": "2026-07-01",
               "expected_delivery_from": "2026-10", "seller_order_ref": "AB-2026-0815", "order_total_net": 30000.00 },
  "seller": { … }, "buyer": { … },
  "lines": [ { "name": "Anzahlung 30 % auf Auftrag AB-2026-0815", "qty": 1, "unit_price": 9000.00, "vat_rate": 19 } ] }

Neue Felder

Was angerechnet wird

• 386 und 875: der eingegangene Betrag, anteilig je Steuersatz. Ist die Anzahlungsrechnung nicht oder nur teilweise bezahlt, fordert die Schlussrechnung den Rest, die Anzahlungsrechnung gilt als abgelöst und wird nicht mehr gemahnt.
• 326 und 876: das abgerechnete Teilentgelt samt Steuer, unabhängig von der Zahlung; die Teilrechnung bleibt eine eigene Forderung.
• Ausdrückliches amount bei einem eigenen Vorbeleg: höchstens sein Betrag, mindestens der eingegangene Betrag (386, 875) bzw. das abgerechnete Teilentgelt (326, 876), sonst 422 (§ 14 Abs. 5 Satz 2 UStG). Mehr als eingegangen gilt als Bestätigung: Die Differenz bleibt auf der Anzahlungsrechnung offen und wird weiter gemahnt, der Vermerk nennt beide Beträge.
• Gleiche Währung und Steuerregelung, ein Vorbeleg nur in einer wirksamen Schlussrechnung. Ein stornierter, bezahlter Vorbeleg nur mit cancelled_confirmed: true und ohne gebuchte Erstattung (UStAE 14.8 Abs. 9).

Vermerke im Beleg (BT-22 und PDF)

• Restrechnung, wenn eine Minusposition entsteht: „Restrechnung: Die angerechneten Teilentgelte sind netto als Minuspositionen abgesetzt. Ausgewiesen ist nur die Umsatzsteuer auf das restliche Entgelt.“
• Je eigener Anzahlungsrechnung, die nicht voll angerechnet ist: „Die Anzahlungsrechnung AZ-2 vom 01.08.2026 wurde nicht bezahlt. Ihr Betrag ist in dieser Rechnung enthalten und nicht gesondert zu zahlen.“ bzw. „Von der Anzahlungsrechnung AZ-2 vom 01.08.2026 wurden 4.000,00 EUR vereinnahmt und angerechnet. Der Rest ist in dieser Rechnung enthalten und nicht gesondert zu zahlen.“ Ist mehr bestätigt als eingegangen: „… wurden 4.000,00 EUR vereinnahmt. Angerechnet sind 8.000,00 EUR. Die Differenz von 4.000,00 EUR ist weiterhin auf die Anzahlungsrechnung AZ-2 zu zahlen. …“
• Anzahlungsrechnung: „Anzahlungsrechnung: Mit dieser Rechnung wird eine Anzahlung vor Ausführung der Leistung abgerechnet.“, Abschlagsrechnung: „Abschlagsrechnung: Mit dieser Rechnung wird eine Abschlagszahlung vor Abnahme der Bauleistung abgerechnet.“, dazu der voraussichtliche Zeitpunkt. Kein Leistungsdatum (BT-72) und kein Leistungszeitraum (BG-14); ein mitgeschicktes delivery_date oder period_* wird mit Hinweis zum voraussichtlichen Zeitpunkt. Vor dieser Änderung erzeugte Anzahlungsrechnungen bleiben beim erneuten Herunterladen, wie sie ausgestellt wurden.
• XRechnung: eine 386 wird als 380 mit dem Vermerk „Anzahlungsrechnung:“ geschrieben (BStBK-FAQ 4.5, BR-DE-17 ist nur eine Warnung). 875, 876 und 877 bleiben. Eine 384 verlangt dort invoice.reference_invoice (§ 31 Abs. 5 Satz 2 UStDV, BR-DE-26), in den anderen Profilen gibt es einen Hinweis.

Storno und Korrektur

Eine 384 mit Bezug auf einen eigenen Beleg und genau dessen negiertem Brutto ist ein Vollstorno und schließt ihn; ein kleinerer negativer Betrag ist eine Teilkorrektur, ein positiver eine Nachberechnung. Der Storno einer Schlussrechnung hebt ihre Anrechnungen auf, die Anzahlungsrechnungen leben wieder auf. Storno oder Korrektur einer angerechneten Anzahlungsrechnung sind gesperrt, solange die Schlussrechnung wirksam ist, auch wenn der Bezug als Liste kommt. Ein Storno übernimmt invoice.prepaid negiert (Zeile „zuzüglich Rücknahme bereits bezahlt“ im PDF) und trägt keine deductions: Storno mit bereits bezahltem Betrag (invoice.prepaid, BT-113): Mit diesem Beleg wird nur der Zahlbetrag erstattet. Den bereits bezahlten Betrag erstatten Sie gesondert oder übernehmen ihn in die neue Rechnung.

Hinweise und Kopfzeilen

• X-Invoice-Hints bei PDF- und XML-Antworten (/v1/generate, /v1/automap?generate=1, /v1/embed, /v1/cii als XML): Hinweise der Prüfung, mit „ | “ getrennt, höchstens 2000 Byte, danach „und N weitere Hinweise“. JSON-Antworten tragen hints (nur wenn es welche gibt).
• Mit ?validate=1 kommen die Warnungen und Informationen des KoSIT-Validators in denselben Kanal. Gültig ist, was der Validator zur Annahme empfiehlt; /v1/validate, /v1/validate/fraud und /v1/check (unter kosit.hints) liefern die Hinweise getrennt von den Fehlern. Endet die Prüfung ohne Prüfbericht (Zeitüberschreitung), gilt der Beleg als nicht geprüft: „Prüfung nicht abgeschlossen: Der KoSIT-Validator hat keinen Prüfbericht geliefert (Zeitüberschreitung oder Abbruch). Bitte erneut prüfen.“
• X-Invoice-Stored: 0: das PDF ist ausgeliefert, das Ablegen in Ihrer Rechnungsliste ist gescheitert (steht im Fehlerprotokoll). X-Invoice-PayLink: 0: der Zahllink fehlt, die Rechnung ist gespeichert.

Forderungen und Zahlungen

GET /v1/receivables nennt je Eintrag zusätzlich type_code, prepaid_cents, due_cents (Zahlbetrag), claim_cents (Forderung nach Verrechnung, null = Zahlbetrag), open_cents, overpaid_cents, closed_reason (payment, offset verrechnet, superseded abgelöst, cancelled, covered_by_prepayment, nothing_due) und links.predecessors[] / links.successors[] mit {number, type_code, kind, applied_cents} (kind: offset, cancellation, correction, reference). payments[] tragen value_date, kind (payment, settlement, refund) und note. Gutschriften, Storno- und Korrekturbelege stehen nicht in der Liste. paid_cents ist die Summe echter Zahlungen, ohne Kappung.

• POST /v1/receivables/payment {number, amount_cents, value_date?, note?}: ein Datum in der Zukunft oder ein amount_cents, das keine ganze Zahl ist, ergibt 422; eine Überzahlung wird gebucht und in overpaid_cents genannt; Storno- und Korrekturbelege nehmen keine Zahlung an (409).
• POST /v1/receivables/paid {number, value_date?}: bucht den offenen Rest als Ausgleich; nichts offen ergibt 409.
• POST /v1/receivables/refund {number, amount_cents, value_date?, note?}: Erstattung einer Überzahlung, höchstens bis overpaid_cents, sonst 409.

Eingangsprüfung

POST /v1/check liest BT-113, BT-114 und BT-115 und nennt unter invoice zusätzlich prepaid_total und due_payable (Dezimalzahl wie grand_total). Der Befund zahlbetrag meldet eine abgezogene Anzahlung (Hinweis), einen Widerspruch zwischen Zahlbetrag und Brutto minus Anzahlung plus Rundung über 1 Cent, ein negatives BT-113 bei positivem Brutto oder eine Rundung über 0,99 (gelb, Vormerken nur mit Bestätigung) und bei MINIMUM einen kleineren Zahlbetrag (Hinweis). Weicht der Zahlbetrag vom Brutto ab und steht er nicht im lesbaren PDF, meldet consistency gelb. Die SEPA-Sammelzahlung überweist den Zahlbetrag, nicht das Brutto; ein Zahlbetrag von 0 lässt sich nicht vormerken, eine Rechnung in fremder Währung ebenso wenig (eine unlesbare Währung steht als XXX). Belege ohne gelesenen Zahlbetrag aus der Zeit davor bestätigen Sie einmal in der Zahllauf-Box.

Import und KI

Die Import-Spalte belegart kennt „Schlussrechnung“, „Endrechnung“, „Restrechnung“ (380), „Teilschlussrechnung“ (876), „Schlussrechnung Bau“ (877), „Abschlagsrechnung“ (386, mit „Bau“ 875). Neue Spalten: anrechnung (Nummern, mit „;“ oder „,“ getrennt), leistung_voraussichtlich und _bis, anzahlung_eingang, weitere_bezuege, bezug_datum, auftragssumme. Eine Anrechnung geht nur auf Rechnungen, die schon erzeugt sind: Anzahlungs- und Schlussrechnung importieren Sie in zwei Läufen. Mehrere Beträge in anzahlung sind ein Zeilenfehler. Die Vorlage zeigt beides (Anzahlungsrechnung 2026-002, Schlussrechnung 2026-003). /v1/import nennt Zeilenfehler und Hinweise je Rechnung unter invoices[i].errors und invoices[i].hints, in info zusätzlich fehlerJeRechnung und hinweiseJeRechnung; eine Rechnung mit Zeilenfehler wird nicht erzeugt. Die KI-Erfassung (/v1/automap) erkennt Anzahlungs-, Teil- und Schlussrechnungen und „abzüglich Anzahlung AR-…“ als Anrechnung.

Word-Vorlage

Neue Platzhalter: ${service_label}, ${service_text}, ${prepaid_line}, ${net_before_deductions}, ${deductions_net}, ${advance_note}, ${grand_label}, dazu die Blöcke ${deductions_block}, ${net_block} und ${prepaid_block}. Vorlagen, die vor dieser Änderung erzeugt wurden, kennen ${service_text}, ${due_total} oder ${advance_note} nicht: Anzahlungsrechnungen, Belege mit bereits bezahltem Betrag und Belege mit Vermerk entstehen dann im Standard-Layout, der Vorlagen-Aufschlag wird erstattet, der Grund steht in X-Template-Warning. Abhilfe: im Profil „Vorlage neu erzeugen“.

Gewollte Änderungen für bestehende Aufrufe

• invoice.prepaid über dem Brutto ist ein Fehler statt stiller Kappung; negativ nur bei negativem Brutto.
• 386 und 875 tragen kein Leistungsdatum mehr; XRechnung mit 386 ist kein Fehler mehr, sondern 380 mit Vermerk.
• Ein negativer Einzelpreis ohne Listenpreis wird umgedreht (Menge und Preis mal -1, Betrag gleich), mit Hinweis.
• lines[].net: null oder "" rechnet jetzt wie ein fehlendes Feld (Menge mal Preis), vorher als Nettobetrag 0.
• Die Forderungs-API bucht Überzahlungen, statt sie zu kappen, und nennt Storno- und Korrekturbelege nicht mehr.
• /v1/cii mit Accept: application/json und /v1/import: Bei negativem Rechnungsbetrag (Storno) ist totals.prepaid jetzt 0 und totals.due der negative Betrag; vorher stand das Brutto als bereits bezahlt und der Zahlbetrag bei 0.
• Ein zweiter Vollstorno derselben Rechnung ergibt 422 („R-100 ist bereits durch ST-102 storniert.“) statt 200.
• Leerzeichen am Rand von invoice.reference_invoice werden entfernt (BT-25). Bereits gespeicherte Belege entstehen beim erneuten Herunterladen wie ausgestellt.
• Der Storno einer eigenen Anzahlungs- oder Abschlagsrechnung (386, 875) trägt kein Leistungsdatum (BT-72), dazu kommt ein Hinweis in X-Invoice-Hints.
• invoice.prepaid als Text mit Komma ("100,50") ergibt 422; vorher wurde still 100.00 daraus.
• Profil minimum mit invoice.prepaid oder invoice.rounding: DuePayableAmount ist der Zahlbetrag statt des Bruttos. Bereits gespeicherte Belege entstehen beim erneuten Herunterladen wie ausgestellt.

Beispiel mit Hinweisen im Kopf: curl -i -X POST https://sichere-erechnung.de/v1/generate … zeigt X-Invoice-Hints in der Antwort.