{ "openapi": "3.1.0", "info": { "title": "sichere-erechnung.de API", "version": "sha-fd306ef3ae", "description": "Authorization: Bearer (Keys im Dashboard erstellen; Scope \"Nur lesend\" beschränkt einen Key auf GET-Endpunkte)\n\nAbrechnung: Gewichtetes Credit-Modell: Standard 1, /v1/validate/fraud 3 Credits. Abgelehnte Aufrufe kosten nichts: bei 5xx und bei 422 (Daten nicht EN-16931-konform) werden die verbrauchten Credits inkl. Aufschlaegen automatisch erstattet. Ein geliefertes Ergebnis wird dagegen berechnet, auch wenn es negativ ausfaellt -- eine Pruefung mit dem Ergebnis \"nicht konform\" ist das bestellte Ergebnis (HTTP 200, valid:false).\n\nAusführliche Beschreibung mit Beispielen: https://sichere-erechnung.de/docs" }, "externalDocs": { "description": "Dokumentation mit Beispielen", "url": "https://sichere-erechnung.de/docs" }, "servers": [ { "url": "https://sichere-erechnung.de" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/v1/automap": { "post": { "operationId": "postV1Automap", "summary": "KI-Import: unstrukturierter Text/Excel-Zeile (roh im Body oder {\"data\": \"...\"}) -> erkanntes Rechnungs-JSON (mapped + normalized) im voll…", "description": "KI-Import: unstrukturierter Text/Excel-Zeile (roh im Body oder {\"data\": \"...\"}) -> erkanntes Rechnungs-JSON (mapped + normalized) im vollen Rechnungsschema (Referenzen, Leitweg-ID, Zeitraum, Skonto, Nachlass/Zuschlag, Zahlungsempfaenger, Lieferanschrift, Positionsdetails), ergaenzt um Profil/Kundenstamm/Katalog. Mit ?generate=1 bzw. {\"generate\":true} direkt das fertige ZUGFeRD-PDF (dann zusaetzlich der Generate-Tarif). (10 Credits, Kunden-Key)", "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Key fehlt oder ungültig" }, "402": { "description": "Guthaben reicht nicht" }, "422": { "description": "Daten nicht EN-16931-konform oder ungültig (kostet nichts)" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v1/check": { "post": { "operationId": "postV1Check", "summary": "PDF/XML -> Eingangsprüfung: KoSIT + IBAN-Historie + Dublette + Betrugsmuster (Zahlungsdruck, Betragsplausibilität, Doppelrechnung mit neu…", "description": "PDF/XML -> Eingangsprüfung: KoSIT + IBAN-Historie + Dublette + Betrugsmuster (Zahlungsdruck, Betragsplausibilität, Doppelrechnung mit neuer Nummer, PDF-Forensik/Metadaten) + externe Quellen (VIES, Bundesbank-BLZ, EU-Sanktionsliste, Anschrift) -> Risk-Report (grün/gelb/rot), in Historie gespeichert (2 Credits, Kunden-Key)", "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Key fehlt oder ungültig" }, "402": { "description": "Guthaben reicht nicht" }, "422": { "description": "Daten nicht EN-16931-konform oder ungültig (kostet nichts)" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } } } }, "/v1/cii": { "post": { "operationId": "postV1Cii", "summary": "JSON-Rechnung -> EN-16931 CII-XML (1 Credit); invoice.profile=\"xrechnung\" -> XRechnung-XML (B2G)", "description": "JSON-Rechnung -> EN-16931 CII-XML (1 Credit); invoice.profile=\"xrechnung\" -> XRechnung-XML (B2G)", "responses": { "200": { "description": "Erfolg", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Key fehlt oder ungültig" }, "402": { "description": "Guthaben reicht nicht" }, "422": { "description": "Daten nicht EN-16931-konform oder ungültig (kostet nichts)" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } } } }, "/v1/companies": { "get": { "operationId": "getV1Companies", "summary": "Firmen der Firmengruppe als JSON (id, code, name, country, vat_id), die dieser Key per X-Company ansprechen darf; ohne Gruppenrecht nur d…", "description": "Firmen der Firmengruppe als JSON (id, code, name, country, vat_id), die dieser Key per X-Company ansprechen darf; ohne Gruppenrecht nur die eigene. Kostenlos, auch mit nur-lesendem Key.", "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Key fehlt oder ungültig" }, "402": { "description": "Guthaben reicht nicht" }, "422": { "description": "Daten nicht EN-16931-konform oder ungültig (kostet nichts)" } } } }, "/v1/diff": { "post": { "operationId": "postV1Diff", "summary": "original + corrected -> Positions-Diff (JSON | ?format=html) (1 Credit)", "description": "original + corrected -> Positions-Diff (JSON | ?format=html) (1 Credit)", "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Key fehlt oder ungültig" }, "402": { "description": "Guthaben reicht nicht" }, "422": { "description": "Daten nicht EN-16931-konform oder ungültig (kostet nichts)" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } } } }, "/v1/dunning": { "post": { "operationId": "postV1Dunning", "summary": "Mahnschreiben-PDF zu eigener Rechnung, zählt die Mahnstufe hoch.", "description": "Mahnschreiben-PDF zu eigener Rechnung, zählt die Mahnstufe hoch. Body {number, level?} (1 Credit, Kunden-Key)", "responses": { "200": { "description": "Erfolg", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Key fehlt oder ungültig" }, "402": { "description": "Guthaben reicht nicht" }, "422": { "description": "Daten nicht EN-16931-konform oder ungültig (kostet nichts)" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v1/embed": { "post": { "operationId": "postV1Embed", "summary": "Eigenes PDF (PDF/A-1b) + JSON -> Factur-X-PDF/A-3, Layout bleibt (2 Credit).", "description": "Eigenes PDF (PDF/A-1b) + JSON -> Factur-X-PDF/A-3, Layout bleibt (2 Credit). Statt \"invoice\" auch \"invoice_xml\" (EN-16931-XML als Text, CII oder UBL) bzw. multipart-Feld \"xml\" (Datei). Mit \"seal\":true zusätzlich Echtheits-Siegel: verify_url im Header X-Seal-Verify-Url (Layout bleibt unverändert, QR selbst platzieren; +2 Credits, Kunden-Key)", "responses": { "200": { "description": "Erfolg", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Key fehlt oder ungültig" }, "402": { "description": "Guthaben reicht nicht" }, "422": { "description": "Daten oder PDF ungültig (kostet nichts). PDF abgelehnt, wenn eine Längenangabe (/Length) größer als die Datei ist, mehr als 64 Verschachtelungsebenen, mehr als 50000 Objekte oder mehr als 50 Seiten vorkommen: PDF beschädigt oder nicht unterstützt." } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } } } }, "/v1/embed/token": { "post": { "operationId": "postV1EmbedToken", "summary": "White-Label: Embed-Token minten (kostenlos, nur POST, Kunden-Key mit vollem Zugriff, ein nur lesender Key erhält 403).", "description": "White-Label: Embed-Token minten (kostenlos, nur POST, Kunden-Key mit vollem Zugriff, ein nur lesender Key erhält 403). Body {ttl?, accent?, title?}: ttl in Sekunden, mindestens 60, höchstens 7 Tage (604800), Standard 24 Stunden; expires_in nennt die wirksame Laufzeit", "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Key fehlt oder ungültig" }, "402": { "description": "Guthaben reicht nicht" }, "422": { "description": "Daten nicht EN-16931-konform oder ungültig (kostet nichts)" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v1/extract": { "post": { "operationId": "postV1Extract", "summary": "PDF -> eingebettetes XML + Felder (1 Credit)", "description": "PDF -> eingebettetes XML + Felder (1 Credit)", "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Key fehlt oder ungültig" }, "402": { "description": "Guthaben reicht nicht" }, "422": { "description": "Daten nicht EN-16931-konform oder ungültig (kostet nichts)" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } } } }, "/v1/generate": { "post": { "operationId": "postV1Generate", "summary": "JSON-Rechnung -> ZUGFeRD-PDF/A-3 (1 Credit), inkl.", "description": "JSON-Rechnung -> ZUGFeRD-PDF/A-3 (1 Credit), inkl. GiroCode + Jetzt-zahlen-Zahlseite (URL im Header X-Pay-Url, pro Profil abschaltbar); Rechnung erscheint in der Konto-Historie (Mahnwesen). Optional invoice.payee.name = abweichender Zahlungsempfänger (BG-10). Mit \"seal\":true zusätzlich Echtheits-Siegel: QR wird ins PDF eingebettet, verify_url im Header X-Seal-Verify-Url (+2 Credits, Kunden-Key). Auch als Content-Type: application/xml mit einer fertigen EN-16931-Rechnung im Body, als CII (ZUGFeRD/Factur-X/XRechnung) oder als XRechnung-UBL (Invoice/CreditNote; aus UBL wird bei uns CII); Optionen dann als ?seal=1&template=1, Hinweise zum Import im Header X-Import-Warnings. Fremd-XML ohne EN-16931-Syntax -> 422, dafuer /v1/import?ai=1. Mit ?validate=1 wird vor der Auslieferung gegen KoSIT geprüft; ist der Validator nicht verfügbar, kommt die Rechnung trotzdem, mit Header X-Validation: unavailable. Siehe \"idempotency\" oben.", "responses": { "200": { "description": "Erfolg", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Key fehlt oder ungültig" }, "402": { "description": "Guthaben reicht nicht" }, "422": { "description": "Daten nicht EN-16931-konform oder ungültig (kostet nichts)" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } } } }, "/v1/import": { "post": { "operationId": "postV1Import", "summary": "Import aus Excel (.xlsx/.xls), LibreOffice (.ods), CSV oder EN-16931-XML (CII oder XRechnung-UBL): multipart-Feld \"file\" (Endung im Datei…", "description": "Import aus Excel (.xlsx/.xls), LibreOffice (.ods), CSV oder EN-16931-XML (CII oder XRechnung-UBL): multipart-Feld \"file\" (Endung im Dateinamen) oder Datei als roher Body. ?mode=preview (Standard, kostenlos): erkannte Rechnungen als JSON mit Summen und Fehlern je Rechnung; Tabellen = eine Zeile je Position (Spalten siehe /docs), eine einzelne Excel-Rechnung wird als Ganzes gelesen (needs_ai:true, wenn die Struktur nicht erkennbar ist oder ein XML weder CII noch UBL ist, Antwort dann mit kind:fremd; dann ?ai=1 fuer die KI-Zuordnung, Beta, 10 Credits). ?mode=generate: je Rechnung ZUGFeRD-PDF/A-3 (1 Credit je Rechnung; bei .xlsx/.xls/.ods zusaetzlich 2 Credits Umwandlung je Datei; ?template=1 eigene Word-Vorlage, ?seal=1 Echtheitssiegel, Kosten vorab in costs der Vorschau, Hinweise im Header X-Import-Notes), Antwort ZIP, bei genau einer Rechnung direkt das PDF (Header X-Invoice-Number); bei Validierungsfehlern 422 mit Liste und ohne Erzeugung; ab 51 Rechnungen 202 mit job_id (Hintergrundlauf). Spalte absender (Kürzel, USt-IdNr., Steuernummer oder voller Name einer eigenen Firma): ein Aufruf erzeugt nur in der Firma des Schlüssels bzw. von X-Company; eine andere eigene Firma oder ein unbekannter Absender ist ein Fehler der Rechnung („Zeile N: …“), ebenso Zeilen ohne Absender vor der ersten Zeile mit Absender derselben Rechnungsnummer. Kunden-Key.", "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Key fehlt oder ungültig" }, "402": { "description": "Guthaben reicht nicht" }, "422": { "description": "Daten nicht EN-16931-konform oder ungültig (kostet nichts)" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } } } }, "/v1/import/{id}": { "get": { "operationId": "getV1ImportId", "summary": "Stand eines Hintergrundlaufs: status queued|running|done|failed, total/done/failed, errors.", "description": "Stand eines Hintergrundlaufs: status queued|running|done|failed, total/done/failed, errors. Kostenlos, auch mit nur-lesendem Key.", "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Key fehlt oder ungültig" }, "402": { "description": "Guthaben reicht nicht" }, "422": { "description": "Daten nicht EN-16931-konform oder ungültig (kostet nichts)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/import/{id}/zip": { "get": { "operationId": "getV1ImportIdZip", "summary": "Ergebnis-ZIP eines fertigen Laufs (7 Tage aufbewahrt).", "description": "Ergebnis-ZIP eines fertigen Laufs (7 Tage aufbewahrt). Kostenlos.", "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Key fehlt oder ungültig" }, "402": { "description": "Guthaben reicht nicht" }, "422": { "description": "Daten nicht EN-16931-konform oder ungültig (kostet nichts)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/openapi.json": { "get": { "operationId": "getV1OpenapiJson", "summary": "Maschinenlesbare Beschreibung dieser Schnittstelle (OpenAPI 3.1: Pfade, Rechnungsschema mit allen Feldern, Datentypen und Auswahlwerten).", "description": "Maschinenlesbare Beschreibung dieser Schnittstelle (OpenAPI 3.1: Pfade, Rechnungsschema mit allen Feldern, Datentypen und Auswahlwerten). Wird aus Prüfung, Importmapping und diesem Index erzeugt, bleibt also mit den Feldern deckungsgleich. Kein Key nötig, kostenlos.", "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Key fehlt oder ungültig" }, "402": { "description": "Guthaben reicht nicht" }, "422": { "description": "Daten nicht EN-16931-konform oder ungültig (kostet nichts)" } }, "security": [] } }, "/v1/partners": { "get": { "operationId": "getV1Partners", "summary": "Business partner master data as JSON.", "description": "Business partner master data as JSON. Query: q=, role=customer|supplier|prospect, country=, archived=1, page, per_page; no= returns one partner (incl. archived ones). Empty list is HTTP 200. (free, customer key)", "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Key fehlt oder ungültig" }, "402": { "description": "Guthaben reicht nicht" }, "422": { "description": "Daten nicht EN-16931-konform oder ungültig (kostet nichts)" } } }, "post": { "operationId": "postV1Partners", "summary": "Create or update a partner, keyed by its partner number.", "description": "Create or update a partner, keyed by its partner number. Body {partner_no, name, street, zip, city, country, vat_id, tax_number, email, phone, is_customer, is_supplier, is_prospect, legal_status, sepa_mandate, sepa_iban, payment_terms_days, skonto_days, skonto_percent, tax_scheme_override, currency, invoice_profile, leitweg_id, billing_*, credit_limit_cents, dunning_mode (auto|manual|off), dunning_tone (freundlich|neutral|bestimmt), dunning_fees {\"2\": cents, \"3\": cents}, dunning_pauschale, dunning_damages, dunning_stage_days {\"1\": days, \"2\": days, \"3\": days}, dunning_deadline_days, dunning_texts {\"1\"..\"3\": text}, dunning_texts_en {\"1\"..\"3\": English text, empty = English default}; dunning_* null = inherit from account}. Omitted fields keep their stored value; 201 on create, 200 on update; invalid dunning values -> 422. (free, customer key)", "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Key fehlt oder ungültig" }, "402": { "description": "Guthaben reicht nicht" }, "422": { "description": "Daten nicht EN-16931-konform oder ungültig (kostet nichts)" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v1/partners/archive": { "post": { "operationId": "postV1PartnersArchive", "summary": "Archive a partner (never deleted -- records stay, GoBD).", "description": "Archive a partner (never deleted -- records stay, GoBD). Body {no} (free, customer key)", "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Key fehlt oder ungültig" }, "402": { "description": "Guthaben reicht nicht" }, "422": { "description": "Daten nicht EN-16931-konform oder ungültig (kostet nichts)" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v1/receivables": { "get": { "operationId": "getV1Receivables", "summary": "Accounts receivable as JSON (amounts in cents).", "description": "Accounts receivable as JSON (amounts in cents). Query: status=open|overdue|paid|all, since=, page, per_page; number= returns one item incl. payments[]. Empty list is HTTP 200. (free, customer key)", "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Key fehlt oder ungültig" }, "402": { "description": "Guthaben reicht nicht" }, "422": { "description": "Daten nicht EN-16931-konform oder ungültig (kostet nichts)" } } } }, "/v1/receivables/paid": { "post": { "operationId": "postV1ReceivablesPaid", "summary": "Mark an invoice fully paid.", "description": "Mark an invoice fully paid. Body {number} (free, customer key)", "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Key fehlt oder ungültig" }, "402": { "description": "Guthaben reicht nicht" }, "422": { "description": "Daten nicht EN-16931-konform oder ungültig (kostet nichts)" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v1/receivables/payment": { "post": { "operationId": "postV1ReceivablesPayment", "summary": "Book an incoming payment.", "description": "Book an incoming payment. Body {number, amount_cents} (partial or full, free, customer key)", "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Key fehlt oder ungültig" }, "402": { "description": "Guthaben reicht nicht" }, "422": { "description": "Daten nicht EN-16931-konform oder ungültig (kostet nichts)" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v1/receivables/refund": { "post": { "operationId": "postV1ReceivablesRefund", "summary": "Book the refund of an overpayment.", "description": "Book the refund of an overpayment. Body {number, amount_cents, value_date?, note?}; at most the overpaid amount, stored as a negative payment (free, customer key)", "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Key fehlt oder ungültig" }, "402": { "description": "Guthaben reicht nicht" }, "422": { "description": "Daten nicht EN-16931-konform oder ungültig (kostet nichts)" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v1/seal": { "post": { "operationId": "postV1Seal", "summary": "Rechnung (JSON wie /generate ODER Kernfelder) -> Echtheits-Siegel: Ed25519-signiert, gibt verify_url zurück; Empfänger prüft öffentlich u…", "description": "Rechnung (JSON wie /generate ODER Kernfelder) -> Echtheits-Siegel: Ed25519-signiert, gibt verify_url zurück; Empfänger prüft öffentlich unter GET /verify/{token} (2 Credits, Kunden-Key)", "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Key fehlt oder ungültig" }, "402": { "description": "Guthaben reicht nicht" }, "422": { "description": "Daten nicht EN-16931-konform oder ungültig (kostet nichts)" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } } } }, "/v1/validate": { "post": { "operationId": "postV1Validate", "summary": "XML/PDF -> KoSIT-Prüfung (1 Credit).", "description": "XML/PDF -> KoSIT-Prüfung (1 Credit). Auch eine nicht konforme Rechnung antwortet mit HTTP 200; das Urteil steht im Feld \"valid\", die Verstöße in \"messages\" -- werten Sie \"valid\" aus, nicht den Statuscode. HTTP 503 nur bei nicht laufendem Validator (kostenlos).", "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Key fehlt oder ungültig" }, "402": { "description": "Guthaben reicht nicht" }, "422": { "description": "Daten nicht EN-16931-konform oder ungültig (kostet nichts)" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } } } }, "/v1/validate/fraud": { "post": { "operationId": "postV1ValidateFraud", "summary": "PDF/XML -> KoSIT + IBAN-Betrugsabgleich (3 Credits, Kunden-Key)", "description": "PDF/XML -> KoSIT + IBAN-Betrugsabgleich (3 Credits, Kunden-Key)", "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Key fehlt oder ungültig" }, "402": { "description": "Guthaben reicht nicht" }, "422": { "description": "Daten nicht EN-16931-konform oder ungültig (kostet nichts)" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } } } }, "/verify/{token}": { "get": { "operationId": "getVerifyToken", "summary": "Öffentliche Verifikation eines Siegels (kein Auth, kostenlos): zeigt Aussteller, Nr., Betrag, IBAN + „echt/unverändert\"", "description": "Öffentliche Verifikation eines Siegels (kein Auth, kostenlos): zeigt Aussteller, Nr., Betrag, IBAN + „echt/unverändert\"", "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Key fehlt oder ungültig" }, "402": { "description": "Guthaben reicht nicht" }, "422": { "description": "Daten nicht EN-16931-konform oder ungültig (kostet nichts)" } }, "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API-Key aus dem Dashboard" } }, "schemas": { "Invoice": { "type": "object", "description": "Rechnung als JSON; Prüfregeln und Beispiele: /docs. Unbekannte Felder werden ignoriert.", "properties": { "invoice": { "$ref": "#/components/schemas/InvoiceHeader" }, "seller": { "$ref": "#/components/schemas/Party" }, "buyer": { "$ref": "#/components/schemas/Party" }, "ship_to": { "$ref": "#/components/schemas/ShipTo" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/Line" }, "minItems": 1 }, "seal": { "type": "boolean", "description": "Echtheits-Siegel mitliefern (Aufschlag in Credits)" } }, "required": [ "invoice", "buyer", "lines" ] }, "InvoiceHeader": { "type": "object", "properties": { "accounting_ref": { "type": "string" }, "advance_received_date": { "type": "string", "format": "date" }, "allowance": { "type": "number" }, "allowance2": { "type": "number" }, "allowance2_percent": { "type": "number" }, "allowance2_reason": { "type": "string" }, "allowance_percent": { "type": "number" }, "allowance_reason": { "type": "string" }, "attachments": { "type": "array", "description": "Anlagen (BG-24), je Anlage ein Aufschlag in Credits", "items": { "type": "object" } }, "buyer_reference": { "type": "string" }, "currency": { "type": "string" }, "deductions": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "string" }, "amount": { "type": "number", "description": "brutto" } }, "required": [ "number" ] } }, "delivery_date": { "type": "string", "format": "date" }, "delivery_note": { "type": "string" }, "delivery_terms": { "type": "string" }, "due_date": { "type": "string", "format": "date" }, "exchange_rate": { "type": "number" }, "expected_delivery_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}(-\\d{2})?$", "description": "Datum JJJJ-MM-TT oder Monat JJJJ-MM" }, "expected_delivery_to": { "type": "string", "pattern": "^\\d{4}-\\d{2}(-\\d{2})?$", "description": "Datum JJJJ-MM-TT oder Monat JJJJ-MM" }, "extra_charge_amount": { "type": "number" }, "extra_charge_reason": { "type": "string" }, "extra_charge_tax_scheme": { "type": "string", "enum": [ "standard", "kleinunternehmer", "reverse_charge", "innergemeinschaftlich", "steuerfrei", "ausfuhr", "nullsatz", "nicht_steuerbar" ] }, "extra_charge_vat_rate": { "type": "number" }, "footer": { "type": "string" }, "header_text": { "type": "string" }, "issue_date": { "type": "string", "format": "date" }, "label_overrides": { "type": "object", "description": "Eigene Beschriftungen der Word-Vorlage je Sprache" }, "language": { "type": "string", "enum": [ "de", "en" ] }, "number": { "type": "string" }, "order_ref": { "type": "string" }, "order_total_net": { "type": "number" }, "our_reference": { "type": "string" }, "payee": { "$ref": "#/components/schemas/Payee" }, "payment": { "$ref": "#/components/schemas/Payment" }, "payment_terms": { "type": "string" }, "period_end": { "type": "string", "format": "date" }, "period_start": { "type": "string", "format": "date" }, "prepaid": { "type": "number" }, "profile": { "type": "string", "enum": [ "en16931", "xrechnung", "minimum", "basicwl", "basic", "extended" ] }, "project_name": { "type": "string" }, "project_ref": { "type": "string" }, "reference": { "type": "string" }, "reference_invoice": { "type": "string" }, "reference_issue_date": { "type": "string", "format": "date" }, "references": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "string" }, "issue_date": { "type": "string", "format": "date" }, "type_code": { "type": "string" } }, "required": [ "number" ] } }, "rounding": { "type": "number" }, "seller_order_ref": { "type": "string" }, "skonto2_days": { "type": "integer" }, "skonto2_percent": { "type": "number" }, "skonto_days": { "type": "integer" }, "skonto_percent": { "type": "number" }, "tax_currency": { "type": "string" }, "tax_exemption_reason": { "type": "string" }, "tax_scheme": { "type": "string", "enum": [ "standard", "kleinunternehmer", "reverse_charge", "innergemeinschaftlich", "steuerfrei", "ausfuhr", "nullsatz", "nicht_steuerbar" ] }, "type_code": { "type": "string", "enum": [ "380", "326", "386", "381", "384", "389", "875", "876", "877" ] } }, "required": [ "number" ] }, "Payment": { "type": "object", "properties": { "iban": { "type": "string" }, "bic": { "type": "string" }, "bank": { "type": "string" }, "method": { "type": "string", "enum": [ "transfer", "direct_debit" ] }, "mandate": { "type": "string" }, "creditor_id": { "type": "string" }, "reference": { "type": "string" } } }, "Payee": { "type": "object", "description": "Abweichender Zahlungsempfänger (Factoring)", "properties": { "name": { "type": "string" } } }, "Party": { "type": "object", "description": "Rechnungssteller (seller) oder Empfänger (buyer); Absender-Stammdaten fehlender Felder kommen aus dem Profil", "properties": { "city": { "type": "string" }, "contact_name": { "type": "string" }, "country": { "type": "string", "description": "ISO-3166-Alpha-2-Code, z. B. DE" }, "email": { "type": "string" }, "iban": { "type": "string" }, "logo": { "type": "string" }, "managing_directors": { "type": "string" }, "name": { "type": "string" }, "partner_no": { "type": "string" }, "phone": { "type": "string" }, "rechtsform": { "type": "string" }, "register_court": { "type": "string" }, "register_number": { "type": "string" }, "state": { "type": "string" }, "street": { "type": "string" }, "street2": { "type": "string" }, "tax_number": { "type": "string" }, "trading_name": { "type": "string" }, "vat_id": { "type": "string" }, "website": { "type": "string" }, "zip": { "type": "string" } }, "required": [ "name" ] }, "ShipTo": { "type": "object", "properties": { "name": { "type": "string" }, "id": { "type": "string" }, "street": { "type": "string" }, "street2": { "type": "string" }, "street3": { "type": "string" }, "zip": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string", "description": "ISO-3166-Alpha-2-Code, z. B. DE" } } }, "Line": { "type": "object", "description": "Position: entweder qty × unit_price oder net", "properties": { "attributes": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name", "value" ] } }, { "type": "string", "description": "Text: ein Merkmal je Zeile als „Name: Wert\", oder ohne Zeilenumbruch „Name: Wert; Name: Wert\"" } ], "description": "Artikelmerkmale (BG-32): Liste aus name (BT-160) und value (BT-161) oder Text; höchstens 40; nur ab EN 16931" }, "buyer_item_id": { "type": "string" }, "description": { "type": "string" }, "discount": { "type": "number" }, "discount_percent": { "type": "number" }, "gtin": { "type": "string" }, "item_id": { "type": "string" }, "list_price": { "type": "number" }, "name": { "type": "string" }, "net": { "type": "number" }, "note": { "type": "string" }, "origin_country": { "type": "string", "description": "ISO-3166-Alpha-2-Code, z. B. DE" }, "price_base_qty": { "type": "number" }, "price_discount": { "type": "number" }, "qty": { "type": "number" }, "surcharge": { "type": "number" }, "tax_exemption_reason": { "type": "string" }, "tax_scheme": { "type": "string", "enum": [ "standard", "reverse_charge", "innergemeinschaftlich", "steuerfrei", "ausfuhr", "nullsatz" ], "description": "Abweichende Steuerregel dieser Position (gemischte Steuerarten)" }, "unit": { "type": "string" }, "unit_price": { "type": "number" }, "vat_rate": { "type": "number" } }, "required": [ "name" ] } } } }