{"openapi":"3.1.0","info":{"title":"finisma REST-API","version":"1.0.0","description":"Elektronische Rechnungen (ZUGFeRD/Factur-X, EN 16931) prüfen und erzeugen. Server-zu-Server-API; nicht für Browser-Aufrufe gedacht. Authentifizierung per API-Key (Bearer fnsm_…), erstellt unter /konto, oder OAuth 2.1 (Bearer fnso_…) für Integrationen, die das Konto des Nutzers verbinden. verify ist kostenlos (Credential nötig), invoices läuft mit Abo, Guthaben (Credits, 1 je Rechnung) oder dem kostenlosen Tageskontingent mit Wasserzeichen, extractions läuft mit Abo oder kostet 1 Credit je Aufruf (Sprachmodell). payments/validate und statements/validate haben ein kostenloses Tageskontingent je Konto, danach Zahlungsverkehr-Abo oder Prüfblock (1 Credit für 10 Prüfungen); statements/parse hat ein kostenloses Monatskontingent, danach Zahlungsverkehr-Abo oder 1 Credit je Aufruf (Details je Endpunkt, x-finisma-pricing). Operationen mit x-finisma-mcp-tool gibt es unter demselben Tool-Namen auch auf dem Remote-MCP-Server /api/mcp.","termsOfService":"https://finisma.de/agb","contact":{"name":"finisma","email":"erechnung@paulibytes.de","url":"https://finisma.de/entwickler"}},"servers":[{"url":"https://finisma.de/api/v1"}],"security":[{"bearerAuth":[]},{"oauth2":["invoice:verify","invoice:create"]}],"tags":[{"name":"Rechnungen","description":"E-Rechnungen prüfen, auslesen und erzeugen (ZUGFeRD/Factur-X, EN 16931)."},{"name":"Konto","description":"Konto- und Abo-Status zum vorgelegten Credential."},{"name":"Partner-Checks","description":"Geschäftspartner vor dem Rechnungsversand prüfen: USt-IdNr. live gegen VIES, Peppol-Erreichbarkeit per SML/SMP-Lookup. Kostenlos, Key nötig."},{"name":"Zahlungsverkehr","description":"Zahlungsdateien erzeugen (SEPA pain.001 und AXZ) und prüfen, BIC-Ermittlung und KI-gestützte Adress-Strukturierung für Auslandsüberweisungen."},{"name":"Kontoauszüge","description":"Kontoauszüge, Kontoberichte und Avise (camt.052/053/054) sowie Gebührenabrechnungen (camt.086) prüfen und als JSON lesen, einzeln oder als ZIP."}],"paths":{"/formats":{"get":{"operationId":"listFormats","summary":"Unterstützte Formate mit Fähigkeiten und Limits (anonym)","tags":["Selbstauskunft"],"security":[],"responses":{"200":{"description":"Formatverzeichnis.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/codelists/document-types":{"get":{"operationId":"listDocumentTypes","summary":"Dokumentarten (UNCL 1001, Teilmenge) mit Bezugsfeld-Hinweisen (anonym)","tags":["Selbstauskunft"],"security":[],"responses":{"200":{"description":"Codeliste.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/codelists/note-subjects":{"get":{"operationId":"listNoteSubjects","summary":"Betreff-Codes fuer Rechnungshinweise (UNTDID 4451, kuratierte Auswahl, anonym)","tags":["Selbstauskunft"],"security":[],"responses":{"200":{"description":"Codeliste.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/codelists/units":{"get":{"operationId":"listUnits","summary":"Mengeneinheiten (UN/ECE Rec 20) samt Normalisierungs-Aliassen (anonym)","tags":["Selbstauskunft"],"security":[],"responses":{"200":{"description":"Codeliste.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/codelists/vat-categories":{"get":{"operationId":"listVatCategories","summary":"USt-Kategorien (BT-118) mit Satz- und Befreiungsregeln (anonym)","tags":["Selbstauskunft"],"security":[],"responses":{"200":{"description":"Codeliste.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/codelists/payment-means":{"get":{"operationId":"listPaymentMeans","summary":"Zahlungsarten (BT-81, UNTDID-4461-Teilmenge) samt Lastschrift-Pflichten (anonym)","tags":["Selbstauskunft"],"security":[],"responses":{"200":{"description":"Codeliste.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/codelists/attachment-types":{"get":{"operationId":"listAttachmentTypes","summary":"Erlaubte Anhangstypen je Ebene (XML-Codeliste vs. PDF/A-3, anonym)","tags":["Selbstauskunft"],"security":[],"responses":{"200":{"description":"Codeliste.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/vat/check":{"get":{"operationId":"checkVatId","x-finisma-mcp-tool":"check_vat_id","summary":"USt-IdNr. live gegen VIES prüfen (kostenlos, Key nötig)","tags":["Partner-Checks"],"parameters":[{"name":"vatId","in":"query","required":true,"schema":{"type":"string"},"description":"USt-IdNr. mit Länderpräfix, z. B. \"DE325821677\"."}],"responses":{"200":{"description":"Prüfergebnis. status ist valid, invalid oder unavailable — unavailable heißt VIES/Mitgliedsstaat nicht erreichbar, NICHT ungültig.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Keine als USt-IdNr. erkennbare Eingabe."},"429":{"description":"Rate-Limit (30/min je Key)."}}}},"/peppol/check":{"get":{"operationId":"checkPeppolParticipant","x-finisma-mcp-tool":"check_peppol_participant","summary":"Peppol-Erreichbarkeit eines Partners prüfen (kostenlos, Key nötig)","tags":["Partner-Checks"],"parameters":[{"name":"participant","in":"query","required":true,"schema":{"type":"string"},"description":"Volle Kennung (\"0088:4399901550926\"), nackte GLN, deutsche USt-IdNr. oder Leitweg-ID."}],"responses":{"200":{"description":"Lookup-Ergebnis mit registered, Dokumenttypen und Directory-Name. registered:false ist ein normales Ergebnis, kein Fehler.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Keine als Peppol-Kennung erkennbare Eingabe."},"429":{"description":"Rate-Limit (30/min je Key)."},"503":{"description":"SML gestört — keine Auskunft möglich."}}}},"/verify":{"post":{"operationId":"verifyInvoice","x-finisma-mcp-tool":"verify_zugferd","summary":"E-Rechnung prüfen (kostenlos, Key nötig)","tags":["Rechnungen"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"pdf":{"type":"string","format":"binary","description":"Die zu prüfende PDF (max. 25 MB)."}},"required":["pdf"]}}}},"responses":{"200":{"description":"Prüfbericht.","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"string","description":"Kurzfassung des Ergebnisses."},"result":{"type":"object","properties":{"structure":{"type":"object","description":"Strukturelle Prüfung der PDF (ohne die eingebettete XML).","properties":{"file":{"type":"object","properties":{"present":{"type":"boolean"},"bytes":{"type":"integer"},"isPdf":{"type":"boolean"},"pdfVersion":{"type":["string","null"]}}},"zugferd":{"type":"object","properties":{"embeddedFiles":{"type":"boolean"},"facturXFilename":{"type":"boolean"},"associatedFile":{"type":"boolean"},"pdfAPart":{"type":["string","null"],"description":"z. B. \"3\" für PDF/A-3."},"pdfAConformance":{"type":["string","null"],"description":"z. B. \"B\", \"U\"."},"facturXMetadata":{"type":"boolean"},"xmlEmbedded":{"type":"boolean"},"xmlMatchesGenerated":{"type":["boolean","null"]}}}}},"en16931":{"type":["object","null"],"description":"EN-16931-Prüfung; null, wenn keine XML eingebettet war.","properties":{"checked":{"type":"boolean"},"errorCount":{"type":"integer"},"warningCount":{"type":"integer"},"profile":{"type":"string"},"findings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"z. B. \"BR-CO-25\"."},"message":{"type":"string"},"severity":{"type":"string","enum":["error","warning"]},"location":{"type":"string"},"source":{"type":"string","enum":["schematron","supplementary"]}},"required":["code","message","severity","source"]}}}},"pdfa3":{"type":["object","null"],"description":"PDF/A-3-Anbindung der eingebetteten Dateien (ISO 19005-3 §6.8).","properties":{"hasAfArray":{"type":"boolean"},"allOk":{"type":"boolean"},"files":{"type":"array","items":{"type":"object","properties":{"filename":{"type":"string"},"afRelationship":{"type":["string","null"]},"associated":{"type":"boolean"},"status":{"type":"string","enum":["ok","warning","error"]},"message":{"type":"string"}}}}}},"attachments":{"type":"array","description":"Im CII referenzierte Anhänge (BT-125).","items":{"type":"object","properties":{"filename":{"type":"string"},"mimeCode":{"type":"string"},"sizeBytes":{"type":"integer"}}}},"authoritative":{"type":"object","description":"Autoritative Prüfung: PDF/A-Konformität (ISO 19005-3), XML-Syntax (XSD) und Geschäftsregeln des erkannten Profils. available=false, wenn der Validator-Service nicht erreichbar war; das Ergebnis basiert dann nur auf der Schnellprüfung.","properties":{"available":{"type":"boolean"},"profile":{"type":"string"},"verdict":{"type":"string","enum":["valid","valid_with_warnings","invalid"]},"errorCount":{"type":"integer"},"warningCount":{"type":"integer"},"engines":{"type":"array","items":{"type":"string"}},"findings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"severity":{"type":"string","enum":["error","warning","info"]},"message":{"type":"string"},"location":{"type":["string","null"]},"source":{"type":"string","description":"xsd | schematron | pdfa | structure"},"ruleset":{"type":"string"},"engine":{"type":"string"}},"required":["code","severity","message","source"]}},"note":{"type":"string"}},"required":["available"]}},"required":["structure","attachments","authoritative"]}},"required":["summary","result"]}}}},"400":{"description":"Ungültige Eingabe.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Kein oder ungültiges Credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate-Limit oder kostenloses Tageskontingent erschöpft (siehe Retry-After).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Fehler im nachgelagerten Dienst.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me":{"get":{"operationId":"getAccount","summary":"Konto- und Abo-Status zum vorgelegten Credential","tags":["Konto"],"description":"Prüft, ob das Credential trägt, und meldet, welche Funktionen damit erlaubt sind. Gedacht für Verbindungstests in Integrationen.","responses":{"200":{"description":"Kontostatus.","content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"credits":{"type":"integer","description":"Guthaben-Saldo: 1 Credit = 1 Rechnung ohne Wasserzeichen (auch über POST /invoices, ohne Tageslimit). Aufladen unter https://finisma.de/konto."},"subscription":{"type":"object","properties":{"status":{"type":"string"},"active":{"type":"boolean"},"currentPeriodEnd":{"type":["string","null"],"format":"date-time"},"cancelAtPeriodEnd":{"type":"boolean"}},"required":["status","active"]},"scopes":{"type":["array","null"],"items":{"type":"string"},"description":"Bei OAuth die zugestimmten Scopes, bei API-Key null (voller Umfang)."},"capabilities":{"type":"object","properties":{"verify":{"type":"boolean"},"create":{"type":"boolean"}},"required":["verify","create"]},"features":{"type":"array","items":{"type":"string","enum":["converter","payments","paymentsAbroad"]},"description":"Gebuchte Bausteine des Kontos, unabhängig vom OAuth-Scope. converter ist in jedem aktiven Abo enthalten; payments (Zahlungsverkehr-Abo) schaltet GET /payments/bank-lookup und POST /payments/sepa frei, paymentsAbroad (Auslandsmodul-Add-on, setzt payments voraus) zusätzlich POST /payments/structure-addresses und POST /payments/axz."},"fairUse":{"type":["object","null"],"description":"Fair Use des Abos im laufenden Kalendermonat (Europe/Berlin), ohne aktives Abo null. limit = 100 + 1.000 je gebuchtem Zusatzpaket; used zählt die Rechnungen ohne Wasserzeichen aus dem Abo (Web, API, MCP) und ist null, wenn der Zähler gerade nicht lesbar ist. Die Grenze sperrt nichts. Wer regelmäßig darüber liegt, bucht im Konto ein Zusatzpaket.","properties":{"month":{"type":"string","description":"Kalendermonat, z. B. 2026-10."},"limit":{"type":"integer"},"used":{"type":["integer","null"]},"volumePackages":{"type":"integer"}}}},"required":["email","credits","subscription","capabilities","features"]}}}},"400":{"description":"Ungültige Eingabe.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Kein oder ungültiges Credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate-Limit oder kostenloses Tageskontingent erschöpft (siehe Retry-After).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Fehler im nachgelagerten Dienst.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices":{"post":{"operationId":"createInvoice","x-finisma-mcp-tool":"create_zugferd","summary":"ZUGFeRD-Rechnung erzeugen (Abo, Credits oder Freikontingent)","tags":["Rechnungen"],"description":"Bettet die EN-16931-Daten als CII-XML in die übergebene PDF ein und liefert die fertige ZUGFeRD-PDF (PDF/A-3). Ohne PDF setzt finisma die Rechnung aus den Daten, optional mit Logo (Part 'logo' bzw. logo_base64; PNG, JPEG oder SVG, max. 500 KB) und Sprache (lang: de oder en); die fertige Datei durchläuft dann vor der Auslieferung die autoritative Prüfung (PDF/A-3, EN 16931). Die Anfrage kommt als multipart/form-data oder als application/json im Format des MCP-Tools create_zugferd. Standardantwort ist die binäre PDF; mit 'Accept: application/json' kommt stattdessen { pdf_base64, bytes }. Ohne Abo zahlt zuerst das Guthaben (1 Credit je Rechnung, ohne Wasserzeichen und ohne Tageslimit; Saldo über GET /me). Ohne Guthaben kostenlos mit Konto: die PDF trägt dann das finisma-Prüfsiegel als Wasserzeichen, standardmäßig bis zu 5 Rechnungen pro Tag (danach 429 free_quota_exhausted). Mit 'format=xml' (oder 'Accept: application/xml') kommt nur das CII-XML: kein Träger-PDF nötig, kein Einbettungsschritt, deutlich schneller. Dieser Weg erfordert ein aktives Abo oder Guthaben, weil das kostenlose Tageskontingent mit dem Prüfsiegel als Wasserzeichen arbeitet und ein XML keines tragen kann.","parameters":[{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["pdf","xml"],"default":"pdf"},"description":"Ausgabeform. 'pdf' (Standard) liefert die ZUGFeRD-PDF, 'xml' nur das CII-XML. Bei 'xml' ist der pdf-Part nicht nötig und wird ignoriert; Anhänge landen weiterhin als BT-125 im XML, die PDF/A-3-Ebene entfällt."}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"pdf":{"type":"string","format":"binary","description":"Optional: die visuelle Rechnungs-PDF (max. 25 MB), in die das XML eingebettet wird. Fehlt sie, wird die Rechnung aus den Daten gesetzt. Bei format=xml wird sie ignoriert."},"invoice":{"$ref":"#/components/schemas/Invoice"},"attachments":{"type":"array","items":{"type":"string","format":"binary"},"description":"Optionale Anhänge (PDF, PNG, JPEG, CSV, XLSX, ODS, XML; je max. 10 MB)."},"attachmentDescriptions":{"type":"array","items":{"type":"string"},"description":"Beschreibung je Anhang (BT-123), als gleichnamige Text-Parts in derselben Reihenfolge wie die attachments-Datei-Parts. Fehlt ein Eintrag, wird der Dateiname als Beschreibung verwendet."},"filename":{"type":"string","description":"Ausgabedateiname (Standard: invoice.pdf). Bei format=xml wird eine .pdf-Endung durch .xml ersetzt."},"logo":{"type":"string","format":"binary","description":"Optionales Logo (PNG, JPEG oder SVG, max. 500 KB), nur ohne pdf: steht rechts oben im Kopf der gesetzten Rechnung. SVG nur ohne Skripte und ohne Verweise auf andere Dateien. Mit pdf: 400."},"lang":{"type":"string","enum":["de","en"],"default":"de","description":"Sprache der aus den Daten gesetzten Rechnung (Beschriftungen, Zahlen- und Datumsformat). Wirkt nur ohne pdf."}},"required":["invoice"]},"encoding":{"invoice":{"contentType":"application/json"},"logo":{"contentType":"image/png, image/jpeg, image/svg+xml"}}},"application/json":{"schema":{"type":"object","description":"Dasselbe Format wie das MCP-Tool create_zugferd. Dateien kommen hier Base64-kodiert.","properties":{"invoice":{"$ref":"#/components/schemas/Invoice"},"pdf_base64":{"type":"string","contentEncoding":"base64","description":"Optional: die visuelle Rechnungs-PDF (max. 25 MB). Fehlt sie, wird die Rechnung aus den Daten gesetzt."},"logo_base64":{"type":"string","contentEncoding":"base64","description":"Optionales Logo (PNG, JPEG oder SVG, max. 500 KB), Base64 oder data:-URI. Nur ohne pdf_base64."},"logo_mime":{"type":"string","enum":["image/png","image/jpeg","image/svg+xml"],"description":"Optional; der Typ wird sonst aus dem Inhalt erkannt."},"lang":{"type":"string","enum":["de","en"],"default":"de"},"filename":{"type":"string","description":"Ausgabedateiname (Standard: invoice.pdf)."},"attachments":{"type":"array","description":"Optionale Anhänge (PDF, PNG, JPEG, CSV, XLSX, ODS, XML; je max. 10 MB).","items":{"type":"object","properties":{"filename":{"type":"string"},"mime_type":{"type":"string"},"description":{"type":"string","description":"Beschreibung (BT-123)."},"data_base64":{"type":"string","contentEncoding":"base64"}},"required":["filename","data_base64"]}}},"required":["invoice"]}}}},"responses":{"200":{"description":"Erzeugte ZUGFeRD-PDF, bei format=xml das CII-XML. Die Größe der Antwort steht zusätzlich im Header X-Invoice-Bytes.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}},"application/xml":{"schema":{"type":"string","description":"Das CII-XML (nur bei format=xml)."}},"application/json":{"schema":{"oneOf":[{"type":"object","description":"Standardweg (format=pdf).","properties":{"pdf_base64":{"type":"string","contentEncoding":"base64"},"bytes":{"type":"integer"}},"required":["pdf_base64","bytes"]},{"type":"object","description":"XML-Weg (format=xml).","properties":{"xml":{"type":"string","description":"Das CII-XML als Text."},"bytes":{"type":"integer","description":"Länge des XML in Bytes (UTF-8)."}},"required":["xml","bytes"]}]}}}},"400":{"description":"Ungültige Eingabe.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Kein oder ungültiges Credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Kein aktives Abo. Bei format=xml gilt das Freikontingent nicht, weil ein XML kein Prüfsiegel als Wasserzeichen tragen kann.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate-Limit oder kostenloses Tageskontingent erschöpft (siehe Retry-After).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Fehler im nachgelagerten Dienst.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/extractions":{"post":{"operationId":"extractInvoice","x-finisma-mcp-tool":"extract_invoice","summary":"EN-16931-Daten aus einer PDF-Rechnung auslesen (Abo oder 1 Credit)","tags":["Rechnungen"],"description":"Liest eine PDF-Rechnung mit derselben Pipeline aus wie das Web-Formular (Textpfad oder Vision-Modell, Reparaturschleife, deterministische Backfills für IBAN und USt-IdNr.) und liefert die EN-16931-Felder plus offene Probleme. Enthält die PDF bereits eine eingebettete E-Rechnung (ZUGFeRD/Factur-X), kommen die Felder deterministisch aus der XML (source='xml'), ohne Sprachmodell. Gedacht als Vorstufe zu POST /invoices: Felder prüfen, korrigieren, dann erzeugen. Erfordert ein aktives Abo oder 1 Credit je Aufruf; das kostenlose Tageskontingent von /invoices gilt hier NICHT. Rate-Limit 10 Aufrufe pro Minute und Credential. Wichtig: Felder, die das Modell nicht sicher lesen konnte, kommen als Platzhalter zurück ('KORRIGIEREN' für Text, '1900-01-01' für Datum, 0 für Beträge) und stehen in 'repairedPaths'. Diese Werte müssen vor dem Aufruf von /invoices ersetzt werden: Text- und Datums-Platzhalter blockieren dort als EXTRACTION_UNCERTAIN, ein 0-Betrag dagegen kann unbemerkt durchlaufen.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"pdf":{"type":"string","format":"binary","description":"Die auszulesende PDF-Rechnung (max. 25 MB)."}},"required":["pdf"]}}}},"responses":{"200":{"description":"Ausgelesene Rechnungsdaten.","content":{"application/json":{"schema":{"type":"object","properties":{"invoice":{"$ref":"#/components/schemas/Invoice"},"issues":{"type":"array","description":"Offene Probleme der ausgelesenen Daten. severity='error' blockiert POST /invoices (dort läuft dieselbe Prüfung erneut), 'warning' nicht.","items":{"$ref":"#/components/schemas/ValidationIssue"}},"repairedPaths":{"type":"array","items":{"type":"string"},"description":"Punkt-Pfade der Felder, die mit einem Platzhalter gefüllt wurden, z. B. \"seller.name\" oder \"lines.0.lineNetAmount\". Vor dem Erzeugen prüfen und ersetzen."},"source":{"type":"string","enum":["xml","llm"],"description":"Herkunft der Felder: 'xml' = deterministisch aus der in der PDF eingebetteten E-Rechnung übernommen, 'llm' = per Sprachmodell aus dem Druckbild extrahiert."}},"required":["invoice","issues","repairedPaths","source"]}}}},"400":{"description":"Ungültige Eingabe.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Kein oder ungültiges Credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Kein aktives Abo und kein Guthaben. Diese Funktion ist nicht Teil des kostenlosen Tageskontingents.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate-Limit oder kostenloses Tageskontingent erschöpft (siehe Retry-After).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Fehler im nachgelagerten Dienst.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payments/bank-lookup":{"get":{"operationId":"bankLookup","summary":"BIC zu einer deutschen Bankleitzahl ermitteln","tags":["Zahlungsverkehr"],"description":"Liefert den BIC zu einer deutschen Bankleitzahl aus dem Bundesbank-Verzeichnis. Andere Länder liefern immer found=false mit reason='unsupported_country', dafür ist der BIC aus der Quelldatei (DTAZV) oder aus manueller Eingabe zu nehmen. Erfordert das Feature 'payments' ODER 'paymentsAbroad' (Zahlungsverkehr-Abo bzw. Auslandsmodul-Add-on schließt es ein). Auth per Login-Session oder Bearer-Credential (API-Key oder OAuth-Token), unabhängig vom Scope: diese Route prüft keinen OAuth-Scope, nur das Konto-Feature.","parameters":[{"name":"country","in":"query","required":false,"schema":{"type":"string"},"description":"ISO-3166-1-alpha-2-Ländercode. Nur 'DE' kann einen Treffer liefern; jeder andere Wert (auch ein leerer) liefert found=false mit reason='unsupported_country'."},{"name":"bankCode","in":"query","required":false,"schema":{"type":"string"},"description":"Die deutsche Bankleitzahl (BLZ), achtstellig."}],"responses":{"200":{"description":"Ergebnis der Suche: auch 'nicht gefunden' bzw. 'Land nicht unterstützt' ist ein 200.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BankLookupResult"}}}},"401":{"description":"Kein oder ungültiges Credential (code auth_required bzw. invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Feature 'payments'/'paymentsAbroad' fehlt (code subscription_required).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payments/structure-addresses":{"post":{"operationId":"structureAddresses","summary":"Adresszeilen für Auslandsüberweisungen KI-gestützt strukturieren","tags":["Zahlungsverkehr"],"description":"Zerlegt bis zu 50 Freitext-Adressen (je 1 bis 4 Zeilen, ISO-Ländercode dazu) per LLM in Ort, Postleitzahl, Straße und Hausnummer, ohne etwas zu erfinden. Bei Unsicherheit kommt confident=false zurück statt eines geratenen Feldes. Erfordert das Feature 'paymentsAbroad' (Auslandsmodul-Add-on, setzt das Zahlungsverkehr-Abo voraus; 'payments' allein reicht hier NICHT, anders als bei bank-lookup). Auth per Login-Session oder Bearer-Credential, unabhängig vom OAuth-Scope. Keine Persistenz der Adressdaten.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressStructureRequest"}}}},"responses":{"200":{"description":"Strukturierungsergebnis je Item, in derselben Reihenfolge wie die Anfrage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressStructureResponse"}}}},"400":{"description":"Request-Body entspricht nicht dem Schema (z. B. mehr als 50 Items).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Kein oder ungültiges Credential (code auth_required bzw. invalid_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Feature 'paymentsAbroad' fehlt (code subscription_required).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Der KI-Dienst (OpenAI) ist derzeit nicht erreichbar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payments/sepa":{"post":{"operationId":"createSepaPaymentFile","summary":"SEPA-Sammelüberweisung (pain.001.001.09) erzeugen","tags":["Zahlungsverkehr"],"description":"Erzeugt aus einem Zahllauf (JSON) die SEPA-Sammelüberweisung im SCT-Profil, mit derselben Erzeugung wie auf /zahlungen (byteidentisches XML). Erfordert das Feature 'payments' (Zahlungsverkehr-Abo). Auth per Login-Session oder Bearer-Credential, unabhängig vom OAuth-Scope. Vor der Erzeugung laufen die Geschäftsregeln (IBAN-Prüfziffern, Beträge, Fristen; Verstoß ⇒ 422 mit Issue-Liste in details, keine Datei), danach die autoritative Prüfung gegen das DK-TVS (Scheitern ⇒ 502 mit Befunden in details, keine Datei). categoryPurpose \"SALA\" an einer Zahlung kennzeichnet sie als Gehaltszahlung (CtgyPurp SALA, eigener PmtInf-Block); an /payments/axz ist das Feld ein 422. instrPrty \"HIGH\" setzt die Priorität (PmtTpInf/InstrPrty, ebenfalls eigener PmtInf-Block); weglassen bedeutet NORM, an /payments/axz ist das Feld ein 422. purposeCode (1 bis 4 Zeichen, z. B. SUPP) setzt den Zweckcode CdtTrfTxInf/Purp/Cd für den Empfänger. ultimateDebtor/ultimateCreditor (Name, Kennung) sind abweichender Auftraggeber und Empfänger (UltmtDbtr/UltmtCdtr), instructionId die Auftragsreferenz (PmtId/InstrId), creditorId und debtor.id Partei-Kennungen (LEI, BIC, sonstige), initiatingPartyId die Kennung des Einreichers. Standardantwort ist das XML als Datei (Content-Disposition: sepa-inland-<Datum>.xml); nur ein Accept-Header, der ausdrücklich und ohne */*-Platzhalter application/json verlangt, liefert stattdessen die JSON-Hülle.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRun"}}}},"responses":{"200":{"description":"Die erzeugte Zahlungsdatei, standardmäßig als XML; die JSON-Hülle nur auf ausdrücklichen Accept-Wunsch.","content":{"application/xml":{"schema":{"type":"string","description":"Die pain.001-XML."}},"application/json":{"schema":{"$ref":"#/components/schemas/PaymentFileResult"}}}},"400":{"description":"Ungültige Eingabe.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Kein oder ungültiges Credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Feature 'payments' fehlt (code subscription_required).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Der Zahllauf verletzt Geschäftsregeln (code invalid_input); details enthält die vollständige Issue-Liste (code, message, path, severity). Es wurde keine Datei erzeugt.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate-Limit oder kostenloses Tageskontingent erschöpft (siehe Retry-After).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Das QA-Gate ist gescheitert (code upstream_error): die erzeugte Datei hat die autoritative Prüfung nicht bestanden (details enthält die Fehler-Befunde) oder der Validator-Service war nicht erreichbar. Es wurde keine Datei ausgeliefert.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payments/axz":{"post":{"operationId":"createAxzPaymentFile","summary":"Auslandszahlungsdatei (pain.001.001.09, DK-AXZ) erzeugen","tags":["Zahlungsverkehr"],"description":"Erzeugt aus einem Zahllauf (JSON) die Auslandszahlungsdatei im DK-AXZ-Profil (GBIC_5): beliebige ISO-Währungen, Entgeltregelung je Zahlung (Default SHAR), Empfängeradresse mit Ort und Länderkennung ist Pflicht, purposeCode (Zweckcode Purp/Cd, z. B. SUPP) optional; ultimateDebtor/ultimateCreditor brauchen hier einen Namen (max 140) und dürfen eine Adresse tragen, instructionId, creditorId, debtor.id und initiatingPartyId wie bei /payments/sepa. Erfordert das Feature 'paymentsAbroad' (Auslandsmodul-Add-on; 'payments' allein reicht NICHT). Ablauf, Fehlerformen (422 mit Issue-Liste, 502 mit QA-Befunden) und Accept-Regel wie bei /payments/sepa; die autoritative Prüfung läuft hier gegen das AXZ-TVS. Dateiname: axz-ausland-<Datum>.xml.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRun"}}}},"responses":{"200":{"description":"Die erzeugte Zahlungsdatei, standardmäßig als XML; die JSON-Hülle nur auf ausdrücklichen Accept-Wunsch.","content":{"application/xml":{"schema":{"type":"string","description":"Die pain.001-XML."}},"application/json":{"schema":{"$ref":"#/components/schemas/PaymentFileResult"}}}},"400":{"description":"Ungültige Eingabe.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Kein oder ungültiges Credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Feature 'paymentsAbroad' fehlt (code subscription_required).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Der Zahllauf verletzt Geschäftsregeln (code invalid_input); details enthält die vollständige Issue-Liste (code, message, path, severity). Es wurde keine Datei erzeugt.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate-Limit oder kostenloses Tageskontingent erschöpft (siehe Retry-After).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Das QA-Gate ist gescheitert (code upstream_error): die erzeugte Datei hat die autoritative Prüfung nicht bestanden (details enthält die Fehler-Befunde) oder der Validator-Service war nicht erreichbar. Es wurde keine Datei ausgeliefert.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payments/validate":{"post":{"operationId":"validatePaymentFile","summary":"Zahlungsdatei pain.001 prüfen (SEPA oder AXZ)","tags":["Zahlungsverkehr"],"description":"Prüft eine pain.001-Datei (Versionen .09 und .03) mit denselben fachlichen Regeln wie der pain.001-Validator auf finisma.de und dazu gegen das Schema (DK-TVS für SEPA bzw. AXZ, ISO-Schema für .03). Das Profil (SEPA oder AXZ) wird erkannt; 'profile' setzt es fest. Antwort: Profil, Version, Zusammenfassung (Anzahl, Summe je Währung), Befunde der Prüfregeln, Ergebnis der Schemaprüfung mit Zeile und Spalte und ein Gesamturteil. Ist der Validierungsdienst nicht erreichbar, steht xsd.available=false und das Urteil beruht nur auf den Prüfregeln. Nichts wird gespeichert. Kostenlos bis 5 Aufrufe pro Tag und Konto. Mit dem Zahlungsverkehr-Abo (Feature payments) ohne Limit. Ohne Abo kauft 1 Credit einen Prüfblock mit 10 weiteren Prüfungen (für Zahlungsdateien und Kontoauszüge gemeinsam, ohne Ablaufdatum). Ein Konto (API-Key oder OAuth) ist immer nötig.","x-finisma-mcp-tool":"validate_payment_file","x-finisma-pricing":{"freeQuota":5,"freePeriod":"day","subscriptionFeature":"payments","checkBlock":{"credits":1,"checks":10}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"Die pain.001-XML (max. 10 MB)."},"profile":{"type":"string","enum":["auto","sct","axz"],"default":"auto","description":"Profil der Prüfung: auto (Erkennung aus der Datei), sct (SEPA-Überweisung) oder axz (Auslandszahlung)."}},"required":["file"]}},"application/json":{"schema":{"type":"object","properties":{"xml":{"type":"string","description":"Die Datei als XML-Text (max. 10 MB). Alternativ 'file_base64'."},"file_base64":{"type":"string","contentEncoding":"base64","description":"Die XML-Datei Base64-kodiert (max. 10 MB). Alternativ 'xml'."},"filename":{"type":"string","description":"Optionaler Dateiname, erscheint in den Meldungen."},"profile":{"type":"string","enum":["auto","sct","axz"],"default":"auto","description":"Profil der Prüfung: auto (Erkennung aus der Datei), sct (SEPA-Überweisung) oder axz (Auslandszahlung)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Ergebnis; billing nennt, womit bezahlt wurde.","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"string","description":"Kurzfassung des Ergebnisses."},"result":{"type":"object","properties":{"message":{"type":"string","enum":["pain.001"]},"version":{"type":"string","enum":["09","03"]},"profile":{"type":"string","enum":["sct","axz"]},"profileSource":{"type":"string","enum":["detected","requested"]},"profileReasons":{"type":"array","items":{"type":"string"}},"summary":{"type":"object","properties":{"payments":{"type":"integer"},"declaredPayments":{"type":["integer","null"],"description":"NbOfTxs aus dem Kopf."},"controlSum":{"type":"string","description":"Gerechnete Summe aller Zahlungen."},"declaredControlSum":{"type":["string","null"],"description":"CtrlSum aus dem Kopf."},"currencies":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string"},"payments":{"type":"integer"},"total":{"type":"string"}}}},"executionDates":{"type":"array","items":{"type":"string"}},"paymentBlocks":{"type":"integer","description":"Anzahl PmtInf-Blöcke."},"messageId":{"type":["string","null"]},"createdAt":{"type":["string","null"]}}},"findings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Maschinencode der Prüfregel."},"severity":{"type":"string","enum":["error","warning","info"]},"message":{"type":"string","description":"Deutsche Meldung."},"path":{"type":"string","description":"Punkt-Pfad in das gelesene Modell."}},"required":["code","severity","message"]}},"xsd":{"type":"object","description":"Schemaprüfung über den Validierungsdienst. available=false heißt: nicht verfügbar, das Urteil beruht dann nur auf den Prüfregeln.","properties":{"available":{"type":"boolean"},"ruleset":{"type":"string","description":"Prüfgrundlage, z. B. iso.20022:camt053:08."},"valid":{"type":"boolean"},"verdict":{"type":"string","enum":["valid","valid_with_warnings","invalid"]},"errorCount":{"type":"integer"},"warningCount":{"type":"integer"},"findings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"severity":{"type":"string","enum":["error","warning","info"]},"message":{"type":"string"},"line":{"type":["integer","null"]},"column":{"type":["integer","null"]},"location":{"type":["string","null"]}},"required":["code","severity","message"]}},"note":{"type":"string"}},"required":["available","ruleset"]},"verdict":{"type":"string","enum":["valid","valid_with_warnings","invalid"]},"schemaChecked":{"type":"boolean"},"billing":{"type":"object","description":"Womit der Aufruf bezahlt wurde: free_quota (Freikontingent), subscription (Zahlungsverkehr-Abo), check_block (Prüfblock: 1 Credit für 10 Prüfungen) oder credit (Guthaben).","properties":{"via":{"type":"string","enum":["free_quota","subscription","check_block","credit"]},"freeRemaining":{"type":["integer","null"],"description":"Verbleibende kostenlose Aufrufe im laufenden Zeitraum (Europe/Berlin); beim Abo null."},"freePeriod":{"type":"string","enum":["day","month"],"description":"Zeitraum des Freikontingents: day beim Prüfen, month beim Auslesen."},"checkBlockRemaining":{"type":"integer","description":"Nur bei via check_block: offene Prüfungen im Prüfblock nach diesem Aufruf."},"creditsCharged":{"type":"integer","description":"Abgebuchte Credits: bei via credit und beim Kauf eines neuen Prüfblocks."},"refunded":{"type":"boolean","description":"true, wenn der Aufruf zurückgebucht wurde, weil die Schemaprüfung nicht erreichbar war."}},"required":["via","freeRemaining","freePeriod"]}},"required":["message","version","profile","summary","findings","xsd","verdict","billing"]}},"required":["summary","result"]}}}},"400":{"description":"Keine Datei, kein unterstütztes Format oder eine nicht unterstützte Version (code invalid_input). Abgewiesene Dateien kosten nichts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Kein oder ungültiges Credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Tageskontingent (5 pro Tag) aufgebraucht, keine offene Prüfung im Prüfblock, kein Zahlungsverkehr-Abo und kein Guthaben (code payment_required). Retry-After nennt die Sekunden bis zum Neubeginn des Kontingents (Mitternacht, Europe/Berlin).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Datei größer als 10 MB (code payload_too_large).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate-Limit (30/min je Key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Fehler im nachgelagerten Dienst.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/statements/validate":{"post":{"operationId":"validateBankStatement","summary":"Kontoauszug prüfen (camt.052/053/054, camt.086)","tags":["Kontoauszüge"],"description":"Prüft camt.052, camt.053 und camt.054 (Versionen .02 und .08) sowie camt.086 (.01 bis .05), einzeln oder mehrere Dateien als ZIP. Je Datei: Nachricht, Version, Befunde der Prüfregeln (Salden, Summen, IBAN-Prüfziffern, Reihenfolge, bei camt.086 Menge mal Preis und Steuern), Schemaprüfung gegen das ISO-Schema mit Zeile und Spalte, Urteil; dazu ein Gesamturteil. Nichts wird gespeichert. Kostenlos bis 5 Aufrufe pro Tag und Konto. Mit dem Zahlungsverkehr-Abo (Feature payments) ohne Limit. Ohne Abo kauft 1 Credit einen Prüfblock mit 10 weiteren Prüfungen (für Zahlungsdateien und Kontoauszüge gemeinsam, ohne Ablaufdatum). Ein Konto (API-Key oder OAuth) ist immer nötig.","x-finisma-mcp-tool":"validate_bank_statement","x-finisma-pricing":{"freeQuota":5,"freePeriod":"day","subscriptionFeature":"payments","checkBlock":{"credits":1,"checks":10}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"Die Datei: eine XML-Datei oder ein ZIP mit mehreren XML-Dateien (max. 10 MB)."}},"required":["file"]}},"application/json":{"schema":{"type":"object","properties":{"xml":{"type":"string","description":"Die Datei als XML-Text (max. 10 MB). Alternativ 'file_base64'."},"file_base64":{"type":"string","contentEncoding":"base64","description":"Die Datei Base64-kodiert: eine XML-Datei oder ein ZIP mit mehreren XML-Dateien (max. 10 MB). Alternativ 'xml'."},"filename":{"type":"string","description":"Optionaler Dateiname, erscheint in den Meldungen."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Ergebnis; billing nennt, womit bezahlt wurde.","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"string","description":"Kurzfassung des Ergebnisses."},"result":{"type":"object","properties":{"files":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"message":{"type":"string","enum":["camt.052","camt.053","camt.054","camt.086"]},"version":{"type":"string","description":"Schema-Version, z. B. 08."},"statements":{"type":"integer"},"items":{"type":"integer","description":"Buchungen bzw. Services (camt.086)."},"findings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Maschinencode der Prüfregel."},"severity":{"type":"string","enum":["error","warning","info"]},"message":{"type":"string","description":"Deutsche Meldung."},"path":{"type":"string","description":"Punkt-Pfad in das gelesene Modell."}},"required":["code","severity","message"]}},"xsd":{"type":"object","description":"Schemaprüfung über den Validierungsdienst. available=false heißt: nicht verfügbar, das Urteil beruht dann nur auf den Prüfregeln.","properties":{"available":{"type":"boolean"},"ruleset":{"type":"string","description":"Prüfgrundlage, z. B. iso.20022:camt053:08."},"valid":{"type":"boolean"},"verdict":{"type":"string","enum":["valid","valid_with_warnings","invalid"]},"errorCount":{"type":"integer"},"warningCount":{"type":"integer"},"findings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"severity":{"type":"string","enum":["error","warning","info"]},"message":{"type":"string"},"line":{"type":["integer","null"]},"column":{"type":["integer","null"]},"location":{"type":["string","null"]}},"required":["code","severity","message"]}},"note":{"type":"string"}},"required":["available","ruleset"]},"verdict":{"type":"string","enum":["valid","valid_with_warnings","invalid"]}},"required":["name","message","version","findings","xsd","verdict"]}},"deliveryFindings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Maschinencode der Prüfregel."},"severity":{"type":"string","enum":["error","warning","info"]},"message":{"type":"string","description":"Deutsche Meldung."},"path":{"type":"string","description":"Punkt-Pfad in das gelesene Modell."}},"required":["code","severity","message"]}},"skipped":{"type":"array","description":"Dateien im ZIP-Archiv, die keine unterstützte camt-Datei sind.","items":{"type":"object","properties":{"name":{"type":"string"},"reason":{"type":"string"}},"required":["name","reason"]}},"verdict":{"type":"string","enum":["valid","valid_with_warnings","invalid"]},"schemaChecked":{"type":"boolean","description":"false, wenn die Schemaprüfung für mindestens eine Datei nicht verfügbar war."},"billing":{"type":"object","description":"Womit der Aufruf bezahlt wurde: free_quota (Freikontingent), subscription (Zahlungsverkehr-Abo), check_block (Prüfblock: 1 Credit für 10 Prüfungen) oder credit (Guthaben).","properties":{"via":{"type":"string","enum":["free_quota","subscription","check_block","credit"]},"freeRemaining":{"type":["integer","null"],"description":"Verbleibende kostenlose Aufrufe im laufenden Zeitraum (Europe/Berlin); beim Abo null."},"freePeriod":{"type":"string","enum":["day","month"],"description":"Zeitraum des Freikontingents: day beim Prüfen, month beim Auslesen."},"checkBlockRemaining":{"type":"integer","description":"Nur bei via check_block: offene Prüfungen im Prüfblock nach diesem Aufruf."},"creditsCharged":{"type":"integer","description":"Abgebuchte Credits: bei via credit und beim Kauf eines neuen Prüfblocks."},"refunded":{"type":"boolean","description":"true, wenn der Aufruf zurückgebucht wurde, weil die Schemaprüfung nicht erreichbar war."}},"required":["via","freeRemaining","freePeriod"]}},"required":["files","deliveryFindings","skipped","verdict","billing"]}},"required":["summary","result"]}}}},"400":{"description":"Keine Datei, kein unterstütztes Format oder eine nicht unterstützte Version (code invalid_input). Abgewiesene Dateien kosten nichts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Kein oder ungültiges Credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Tageskontingent (5 pro Tag) aufgebraucht, keine offene Prüfung im Prüfblock, kein Zahlungsverkehr-Abo und kein Guthaben (code payment_required). Retry-After nennt die Sekunden bis zum Neubeginn des Kontingents (Mitternacht, Europe/Berlin).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Datei größer als 10 MB (code payload_too_large).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate-Limit (30/min je Key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Fehler im nachgelagerten Dienst.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/statements/parse":{"post":{"operationId":"parseBankStatement","summary":"Kontoauszug als JSON lesen (camt.052/053/054, camt.086)","tags":["Kontoauszüge"],"description":"Liest dieselben Formate in strukturiertes JSON: bei camt.052/053/054 Konten, Salden und Buchungen mit Transaktionen (Gegenpartei, IBAN, Verwendungszweck, End-to-End-Referenz, BkTxCd mit GVC), bei camt.086 Abrechnungen mit Services und Summen je Währung. Keine Schemaprüfung. Nichts wird gespeichert. Kostenlos bis 5 Aufrufe pro Monat und Konto. Mit dem Zahlungsverkehr-Abo (Feature payments) ohne Limit. Ohne Abo kostet jeder weitere Aufruf 1 Credit. Ein Konto (API-Key oder OAuth) ist immer nötig.","x-finisma-mcp-tool":"parse_bank_statement","x-finisma-pricing":{"freeQuota":5,"freePeriod":"month","subscriptionFeature":"payments","creditsPerCall":1},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"Die Datei: eine XML-Datei oder ein ZIP mit mehreren XML-Dateien (max. 10 MB)."}},"required":["file"]}},"application/json":{"schema":{"type":"object","properties":{"xml":{"type":"string","description":"Die Datei als XML-Text (max. 10 MB). Alternativ 'file_base64'."},"file_base64":{"type":"string","contentEncoding":"base64","description":"Die Datei Base64-kodiert: eine XML-Datei oder ein ZIP mit mehreren XML-Dateien (max. 10 MB). Alternativ 'xml'."},"filename":{"type":"string","description":"Optionaler Dateiname, erscheint in den Meldungen."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Ergebnis; billing nennt, womit bezahlt wurde.","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"string","description":"Kurzfassung des Ergebnisses."},"result":{"type":"object","properties":{"files":{"type":"array","items":{"type":"object","description":"Eine gelesene Datei. statements folgt dem Modell aus @erechnung/camt: bei camt.052/053/054 je Auszug account, balances, summary und entries (bookingDate, valueDate, amount, currency, creditDebit, status, bankTxCode mit gvc, transactions[] mit counterparty, remittance, refs.endToEndId); bei camt.086 je Abrechnung account, services, taxRegions, balances.","properties":{"name":{"type":"string"},"message":{"type":"string","enum":["camt.052","camt.053","camt.054","camt.086"]},"version":{"type":"string"},"header":{"type":"object"},"statements":{"type":"array","items":{"type":"object"}},"totals":{"type":"array","description":"Nur camt.086: Summen je Preiswährung.","items":{"type":"object","properties":{"currency":{"type":"string"},"services":{"type":"integer"},"net":{"type":"number"},"waived":{"type":"number"},"tax":{"type":"number"},"gross":{"type":"number"}}}},"settlementTotals":{"type":"array","description":"Nur camt.086: Belastung in abweichender Abrechnungswährung.","items":{"type":"object","properties":{"value":{"type":"number"},"currency":{"type":"string"},"services":{"type":"integer"}}}},"parseFindings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Maschinencode der Prüfregel."},"severity":{"type":"string","enum":["error","warning","info"]},"message":{"type":"string","description":"Deutsche Meldung."},"path":{"type":"string","description":"Punkt-Pfad in das gelesene Modell."}},"required":["code","severity","message"]}}},"required":["name","message","version","header","statements","parseFindings"]}},"skipped":{"type":"array","description":"Dateien im ZIP-Archiv, die keine unterstützte camt-Datei sind.","items":{"type":"object","properties":{"name":{"type":"string"},"reason":{"type":"string"}},"required":["name","reason"]}},"billing":{"type":"object","description":"Womit der Aufruf bezahlt wurde: free_quota (Freikontingent), subscription (Zahlungsverkehr-Abo), check_block (Prüfblock: 1 Credit für 10 Prüfungen) oder credit (Guthaben).","properties":{"via":{"type":"string","enum":["free_quota","subscription","check_block","credit"]},"freeRemaining":{"type":["integer","null"],"description":"Verbleibende kostenlose Aufrufe im laufenden Zeitraum (Europe/Berlin); beim Abo null."},"freePeriod":{"type":"string","enum":["day","month"],"description":"Zeitraum des Freikontingents: day beim Prüfen, month beim Auslesen."},"checkBlockRemaining":{"type":"integer","description":"Nur bei via check_block: offene Prüfungen im Prüfblock nach diesem Aufruf."},"creditsCharged":{"type":"integer","description":"Abgebuchte Credits: bei via credit und beim Kauf eines neuen Prüfblocks."},"refunded":{"type":"boolean","description":"true, wenn der Aufruf zurückgebucht wurde, weil die Schemaprüfung nicht erreichbar war."}},"required":["via","freeRemaining","freePeriod"]}},"required":["files","skipped","billing"]}},"required":["summary","result"]}}}},"400":{"description":"Keine Datei, kein unterstütztes Format oder eine nicht unterstützte Version (code invalid_input). Abgewiesene Dateien kosten nichts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Kein oder ungültiges Credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Monatskontingent (5 pro Monat) aufgebraucht, kein Zahlungsverkehr-Abo und kein Guthaben (code payment_required). Retry-After nennt die Sekunden bis zum Neubeginn des Kontingents (Monatsanfang, Europe/Berlin).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Datei größer als 10 MB (code payload_too_large).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate-Limit (30/min je Key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Fehler im nachgelagerten Dienst.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API-Key (fnsm_…) aus dem finisma-Konto unter /konto oder OAuth-Zugriffstoken (fnso_…)."},"oauth2":{"type":"oauth2","description":"OAuth 2.1 mit PKCE (S256). Clients können sich per Dynamic Client Registration unter /api/oauth/register selbst anmelden.","flows":{"authorizationCode":{"authorizationUrl":"https://finisma.de/api/oauth/authorize","tokenUrl":"https://finisma.de/api/oauth/token","refreshUrl":"https://finisma.de/api/oauth/token","scopes":{"invoice:verify":"E-Rechnungen prüfen","invoice:create":"ZUGFeRD-Rechnungen erzeugen"}}}}},"schemas":{"Invoice":{"type":"object","properties":{"invoiceNumber":{"type":"string","minLength":1,"maxLength":60},"profile":{"type":"string","enum":["en16931","xrechnung"],"default":"en16931"},"documentTypeCode":{"type":"string","default":"380"},"precedingInvoiceNumber":{"type":"string","maxLength":60},"precedingInvoiceDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"issueDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"dueDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"deliveryDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"deliveryCountryCode":{"type":"string","minLength":2,"maxLength":2},"delivery":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"gln":{"type":"string","maxLength":20},"address":{"type":"object","properties":{"line1":{"type":"string","maxLength":150},"line2":{"type":"string","maxLength":150},"postalCode":{"type":"string","maxLength":20},"city":{"type":"string","maxLength":100},"countryCode":{"type":"string","minLength":2,"maxLength":2}},"additionalProperties":false}},"additionalProperties":false},"currency":{"type":"string","minLength":3,"maxLength":3,"default":"EUR"},"buyerReference":{"type":"string","maxLength":80},"costCenter":{"type":"string","maxLength":60},"purchaseOrderReference":{"type":"string","maxLength":60},"contractReference":{"type":"string","maxLength":200},"invoicingPeriod":{"type":"object","properties":{"start":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"end":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"additionalProperties":false},"projectReference":{"type":"string","maxLength":200},"despatchAdviceRef":{"type":"string","maxLength":200},"receivingAdviceRef":{"type":"string","maxLength":200},"allowanceCharges":{"type":"array","items":{"type":"object","properties":{"charge":{"type":"boolean","description":"true = Zuschlag (BG-21), false = Abzug/Nachlass (BG-20)."},"amount":{"type":"number","minimum":0,"description":"BT-92/BT-99: Betrag ohne Vorzeichen. Darf fehlen, wenn percent gesetzt ist: dann gilt round2(basisAmount × percent / 100)."},"basisAmount":{"type":"number","description":"BT-93/BT-100: Grundbetrag des Prozentsatzes. Ohne Angabe die Summe der lineNetAmount aller Positionen mit ratePercent (bei gemischten Kategorien desselben Satzes nur die mit categoryCode)."},"percent":{"type":"number","minimum":0,"maximum":100,"description":"BT-94/BT-101: Prozentsatz, z. B. 2 für 2 % Nachlass."},"categoryCode":{"type":"string","maxLength":12,"default":"S"},"ratePercent":{"type":"number","description":"BT-96/BT-103: Steuersatz in Prozent. Darf beim Prozent-Eintrag ohne basisAmount fehlen, wenn alle Positionen denselben Satz haben."},"reason":{"type":"string","maxLength":200},"reasonCode":{"type":"string","maxLength":10}},"required":["charge"],"additionalProperties":false},"maxItems":50},"seller":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"vatId":{"type":"string","maxLength":20},"gln":{"type":"string","maxLength":20},"registrationId":{"type":"string","maxLength":60,"description":"BT-30 (Verkäufer) / BT-47 (Käufer): Handelsregisternummer bzw. Registerkennung der Partei, z. B. \"HRB 12345, Amtsgericht München\". Nur angeben, wenn sie auf der Rechnung steht. Beim Käufer reicht sie bei Reverse Charge (Kategorie AE) statt der USt-IdNr., bei innergemeinschaftlicher Lieferung (K) nicht."},"address":{"type":"object","properties":{"line1":{"type":"string","maxLength":150},"line2":{"type":"string","maxLength":150},"city":{"type":"string","maxLength":100},"postalCode":{"type":"string","maxLength":20},"countryCode":{"type":"string","minLength":2,"maxLength":2,"default":"DE"}},"additionalProperties":false,"default":{}},"contact":{"type":"object","properties":{"name":{"type":"string","maxLength":150},"email":{"type":"string","maxLength":150},"phone":{"type":"string","maxLength":40}},"additionalProperties":false},"electronicAddress":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":200},"scheme":{"type":"string","maxLength":10,"default":"EM"}},"required":["id"],"additionalProperties":false},"customerAssignedId":{"type":"string","maxLength":100}},"required":["name"],"additionalProperties":false},"buyer":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"vatId":{"type":"string","maxLength":20},"gln":{"type":"string","maxLength":20},"registrationId":{"type":"string","maxLength":60,"description":"BT-30 (Verkäufer) / BT-47 (Käufer): Handelsregisternummer bzw. Registerkennung der Partei, z. B. \"HRB 12345, Amtsgericht München\". Nur angeben, wenn sie auf der Rechnung steht. Beim Käufer reicht sie bei Reverse Charge (Kategorie AE) statt der USt-IdNr., bei innergemeinschaftlicher Lieferung (K) nicht."},"address":{"type":"object","properties":{"line1":{"type":"string","maxLength":150},"line2":{"type":"string","maxLength":150},"city":{"type":"string","maxLength":100},"postalCode":{"type":"string","maxLength":20},"countryCode":{"type":"string","minLength":2,"maxLength":2,"default":"DE"}},"additionalProperties":false,"default":{}},"contact":{"type":"object","properties":{"name":{"type":"string","maxLength":150},"email":{"type":"string","maxLength":150},"phone":{"type":"string","maxLength":40}},"additionalProperties":false},"electronicAddress":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":200},"scheme":{"type":"string","maxLength":10,"default":"EM"}},"required":["id"],"additionalProperties":false}},"required":["name"],"additionalProperties":false},"lines":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":300},"quantity":{"type":"number"},"unitCode":{"type":"string","maxLength":12,"default":"C62"},"sellerArticleId":{"type":"string","maxLength":200},"buyerArticleId":{"type":"string","maxLength":200},"globalArticleId":{"type":"string","maxLength":60},"globalArticleScheme":{"type":"string","maxLength":10,"pattern":"^[0-9A-Za-z]+$"},"unitPriceNet":{"type":"number"},"vatRatePercent":{"type":"number"},"categoryCode":{"type":"string","maxLength":12},"allowanceCharges":{"type":"array","items":{"type":"object","properties":{"charge":{"type":"boolean","description":"true = Zuschlag (BG-28), false = Abzug/Rabatt (BG-27)."},"amount":{"type":"number","minimum":0,"description":"BT-136/BT-141: Betrag ohne Vorzeichen. Darf fehlen, wenn percent gesetzt ist: dann gilt round2(basisAmount × percent / 100)."},"basisAmount":{"type":"number","description":"BT-137/BT-142: Grundbetrag des Prozentsatzes. Ohne Angabe Menge × unitPriceNet der Position (je Eintrag, nicht gestaffelt)."},"percent":{"type":"number","minimum":0,"maximum":100,"description":"BT-138/BT-143: Prozentsatz, z. B. 10 für 10 % Rabatt."},"reason":{"type":"string","maxLength":200},"reasonCode":{"type":"string","maxLength":10}},"required":["charge"],"additionalProperties":false},"maxItems":10},"lineNetAmount":{"type":"number"}},"required":["name","quantity","unitPriceNet","vatRatePercent","lineNetAmount"],"additionalProperties":false},"minItems":1,"maxItems":500},"vatBreakdown":{"type":"array","items":{"type":"object","properties":{"ratePercent":{"type":"number"},"basisAmount":{"type":"number"},"taxAmount":{"type":"number"},"categoryCode":{"type":"string","maxLength":12,"default":"S"},"exemptionReason":{"type":"string","maxLength":500},"exemptionReasonCode":{"type":"string","maxLength":30}},"required":["ratePercent","basisAmount","taxAmount"],"additionalProperties":false},"minItems":1,"maxItems":50},"totalNet":{"type":"number"},"totalVat":{"type":"number"},"totalGross":{"type":"number"},"paidAmount":{"type":"number","minimum":0},"notes":{"type":"array","items":{"anyOf":[{"type":"string","maxLength":1000},{"type":"object","properties":{"text":{"type":"string","maxLength":1000},"subjectCode":{"type":"string"}},"required":["text"],"additionalProperties":false}]},"maxItems":20},"taxCurrencyCode":{"type":"string","minLength":3,"maxLength":3},"totalVatInTaxCurrency":{"type":"number"},"payee":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"gln":{"type":"string","maxLength":20},"registrationId":{"type":"string","maxLength":60}},"required":["name"],"additionalProperties":false},"payment":{"type":"object","properties":{"terms":{"type":"string","maxLength":1000},"iban":{"type":"string","maxLength":40,"pattern":"^[A-Za-z0-9 ]*$"},"bic":{"type":"string","maxLength":15,"pattern":"^[A-Za-z0-9 ]*$"},"reference":{"type":"string","maxLength":140},"meansCode":{"type":"string"},"mandateId":{"type":"string","maxLength":35},"creditorId":{"type":"string","maxLength":35},"debitedIban":{"type":"string","maxLength":40,"pattern":"^[A-Za-z0-9 ]*$"},"accountName":{"type":"string","maxLength":200},"discountPercent":{"type":"number","minimum":0,"maximum":100},"discountDays":{"type":"integer","minimum":0,"maximum":999}},"additionalProperties":false}},"required":["invoiceNumber","issueDate","seller","buyer","lines","vatBreakdown","totalNet","totalVat","totalGross"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"VerifyResult":{"type":"object","properties":{"structure":{"type":"object","description":"Strukturelle Prüfung der PDF (ohne die eingebettete XML).","properties":{"file":{"type":"object","properties":{"present":{"type":"boolean"},"bytes":{"type":"integer"},"isPdf":{"type":"boolean"},"pdfVersion":{"type":["string","null"]}}},"zugferd":{"type":"object","properties":{"embeddedFiles":{"type":"boolean"},"facturXFilename":{"type":"boolean"},"associatedFile":{"type":"boolean"},"pdfAPart":{"type":["string","null"],"description":"z. B. \"3\" für PDF/A-3."},"pdfAConformance":{"type":["string","null"],"description":"z. B. \"B\", \"U\"."},"facturXMetadata":{"type":"boolean"},"xmlEmbedded":{"type":"boolean"},"xmlMatchesGenerated":{"type":["boolean","null"]}}}}},"en16931":{"type":["object","null"],"description":"EN-16931-Prüfung; null, wenn keine XML eingebettet war.","properties":{"checked":{"type":"boolean"},"errorCount":{"type":"integer"},"warningCount":{"type":"integer"},"profile":{"type":"string"},"findings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"z. B. \"BR-CO-25\"."},"message":{"type":"string"},"severity":{"type":"string","enum":["error","warning"]},"location":{"type":"string"},"source":{"type":"string","enum":["schematron","supplementary"]}},"required":["code","message","severity","source"]}}}},"pdfa3":{"type":["object","null"],"description":"PDF/A-3-Anbindung der eingebetteten Dateien (ISO 19005-3 §6.8).","properties":{"hasAfArray":{"type":"boolean"},"allOk":{"type":"boolean"},"files":{"type":"array","items":{"type":"object","properties":{"filename":{"type":"string"},"afRelationship":{"type":["string","null"]},"associated":{"type":"boolean"},"status":{"type":"string","enum":["ok","warning","error"]},"message":{"type":"string"}}}}}},"attachments":{"type":"array","description":"Im CII referenzierte Anhänge (BT-125).","items":{"type":"object","properties":{"filename":{"type":"string"},"mimeCode":{"type":"string"},"sizeBytes":{"type":"integer"}}}},"authoritative":{"type":"object","description":"Autoritative Prüfung: PDF/A-Konformität (ISO 19005-3), XML-Syntax (XSD) und Geschäftsregeln des erkannten Profils. available=false, wenn der Validator-Service nicht erreichbar war; das Ergebnis basiert dann nur auf der Schnellprüfung.","properties":{"available":{"type":"boolean"},"profile":{"type":"string"},"verdict":{"type":"string","enum":["valid","valid_with_warnings","invalid"]},"errorCount":{"type":"integer"},"warningCount":{"type":"integer"},"engines":{"type":"array","items":{"type":"string"}},"findings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"severity":{"type":"string","enum":["error","warning","info"]},"message":{"type":"string"},"location":{"type":["string","null"]},"source":{"type":"string","description":"xsd | schematron | pdfa | structure"},"ruleset":{"type":"string"},"engine":{"type":"string"}},"required":["code","severity","message","source"]}},"note":{"type":"string"}},"required":["available"]}},"required":["structure","attachments","authoritative"]},"ValidationIssue":{"type":"object","properties":{"code":{"type":"string","description":"Maschinencode, z. B. \"BR-CO-26\" oder \"EXTRACTION_UNCERTAIN\"."},"path":{"type":"string","description":"Punkt-Pfad ins Invoice-Objekt, z. B. \"seller.vatId\"."},"message":{"type":"string","description":"Deutsche Fehlermeldung."},"severity":{"type":"string","enum":["error","warning"]}},"required":["code","message","severity"]},"Error":{"type":"object","properties":{"error":{"type":"string","description":"Menschenlesbare Fehlermeldung."},"code":{"type":"string","enum":["invalid_input","auth_required","invalid_key","subscription_required","free_quota_exhausted","payment_required","payload_too_large","insufficient_scope","rate_limited","not_found","upstream_error"]},"details":{"description":"Optionale strukturierte Details, z. B. Validierungs-Issues."}},"required":["error","code"]},"BankLookupResult":{"type":"object","description":"Von Hand gepflegt (siehe Kommentar am Dateianfang): die Route validiert Query-Parameter und Antwort nicht gegen ein zod-Schema.","properties":{"found":{"type":"boolean"},"bic":{"type":"string","description":"Nur bei found=true."},"bankName":{"type":"string","description":"Nur bei found=true."},"dataDate":{"type":"string","description":"Stichtag der zugrunde liegenden Bundesbank-Datei (YYYY-MM-DD). Nur bei found=true."},"reason":{"type":"string","enum":["unsupported_country"],"description":"Nur gesetzt, wenn country ungleich 'DE' war."}},"required":["found"]},"AddressStructureRequest":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":100},"countryCode":{"type":"string","minLength":1,"maxLength":8},"addressLines":{"type":"array","items":{"type":"string","maxLength":70},"minItems":1,"maxItems":4}},"required":["id","countryCode","addressLines"],"additionalProperties":false},"minItems":1,"maxItems":50}},"required":["items"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"AddressStructureResponse":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"townName":{"type":"string","maxLength":100},"postCode":{"type":"string","maxLength":20},"streetName":{"type":"string","maxLength":100},"buildingNumber":{"type":"string","maxLength":20},"addressLines":{"type":"array","items":{"type":"string","maxLength":70},"maxItems":4},"confident":{"type":"boolean"}},"required":["id","confident"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"PaymentRun":{"type":"object","properties":{"debtor":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":70},"iban":{"type":"string","minLength":1,"maxLength":34},"bic":{"type":"string","maxLength":11},"address":{"type":"object","properties":{"townName":{"type":"string","minLength":1,"maxLength":35},"countryCode":{"type":"string","pattern":"^[A-Z]{2}$"},"postCode":{"type":"string","minLength":1,"maxLength":16},"streetName":{"type":"string","minLength":1,"maxLength":70},"buildingNumber":{"type":"string","minLength":1,"maxLength":16},"addressLines":{"type":"array","items":{"type":"string","minLength":1,"maxLength":70},"maxItems":2},"department":{"type":"string","minLength":1,"maxLength":70},"subDepartment":{"type":"string","minLength":1,"maxLength":70},"buildingName":{"type":"string","minLength":1,"maxLength":35},"floor":{"type":"string","minLength":1,"maxLength":70},"postBox":{"type":"string","minLength":1,"maxLength":16},"room":{"type":"string","minLength":1,"maxLength":70},"townLocationName":{"type":"string","minLength":1,"maxLength":35},"districtName":{"type":"string","minLength":1,"maxLength":35},"countrySubDivision":{"type":"string","minLength":1,"maxLength":35,"description":"CtrySubDvsn: Bundesstaat oder Provinz"}},"additionalProperties":false},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"id":{"type":"object","properties":{"kind":{"type":"string","enum":["org","private"],"description":"org = Organisation (OrgId), private = Privatperson (PrvtId)"},"anyBic":{"type":"string","minLength":8,"maxLength":11,"description":"OrgId/AnyBIC, nur org"},"lei":{"type":"string","minLength":20,"maxLength":20,"description":"OrgId/LEI, nur org"},"otherId":{"type":"string","minLength":1,"maxLength":35,"description":"Othr/Id, z. B. Gläubiger-ID oder Kundennummer"},"otherSchemeCode":{"type":"string","minLength":1,"maxLength":4,"description":"Othr/SchmeNm/Cd, z. B. CUST, NIDN"},"otherSchemeProprietary":{"type":"string","minLength":1,"maxLength":35,"description":"Othr/SchmeNm/Prtry"},"otherIssuer":{"type":"string","minLength":1,"maxLength":35,"description":"Othr/Issr"},"birthDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"nur private: PrvtId/DtAndPlcOfBirth/BirthDt"},"birthProvince":{"type":"string","minLength":1,"maxLength":35},"birthCity":{"type":"string","minLength":1,"maxLength":35},"birthCountry":{"type":"string","pattern":"^[A-Z]{2}$"}},"required":["kind"],"additionalProperties":false,"description":"Dbtr/Id (T112): Kennung des Auftraggebers"},"countryOfResidence":{"type":"string","pattern":"^[A-Z]{2}$","description":"Dbtr/CtryOfRes: Sitzland des Auftraggebers (ISO 3166 alpha-2); nur AXZ."}},"required":["name","iban"],"additionalProperties":false},"requestedExecutionDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"payments":{"type":"array","items":{"type":"object","properties":{"creditorName":{"type":"string","minLength":1,"maxLength":70},"creditorIban":{"type":"string","maxLength":34},"creditorAccountOther":{"type":"string","maxLength":34},"creditorBic":{"type":"string","maxLength":11},"creditorAgent":{"type":"object","properties":{"name":{"type":"string","maxLength":140},"address":{"type":"object","properties":{"townName":{"type":"string","minLength":1,"maxLength":35},"countryCode":{"type":"string","pattern":"^[A-Z]{2}$"},"postCode":{"type":"string","minLength":1,"maxLength":16},"streetName":{"type":"string","minLength":1,"maxLength":70},"buildingNumber":{"type":"string","minLength":1,"maxLength":16},"addressLines":{"type":"array","items":{"type":"string","minLength":1,"maxLength":70},"maxItems":2},"department":{"type":"string","minLength":1,"maxLength":70},"subDepartment":{"type":"string","minLength":1,"maxLength":70},"buildingName":{"type":"string","minLength":1,"maxLength":35},"floor":{"type":"string","minLength":1,"maxLength":70},"postBox":{"type":"string","minLength":1,"maxLength":16},"room":{"type":"string","minLength":1,"maxLength":70},"townLocationName":{"type":"string","minLength":1,"maxLength":35},"districtName":{"type":"string","minLength":1,"maxLength":35},"countrySubDivision":{"type":"string","minLength":1,"maxLength":35,"description":"CtrySubDvsn: Bundesstaat oder Provinz"}},"additionalProperties":false}},"additionalProperties":false},"amount":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"remittanceInfo":{"type":"string","minLength":1,"maxLength":140},"endToEndId":{"type":"string","maxLength":35},"creditorAddress":{"type":"object","properties":{"townName":{"type":"string","minLength":1,"maxLength":35},"countryCode":{"type":"string","pattern":"^[A-Z]{2}$"},"postCode":{"type":"string","minLength":1,"maxLength":16},"streetName":{"type":"string","minLength":1,"maxLength":70},"buildingNumber":{"type":"string","minLength":1,"maxLength":16},"addressLines":{"type":"array","items":{"type":"string","minLength":1,"maxLength":70},"maxItems":2},"department":{"type":"string","minLength":1,"maxLength":70},"subDepartment":{"type":"string","minLength":1,"maxLength":70},"buildingName":{"type":"string","minLength":1,"maxLength":35},"floor":{"type":"string","minLength":1,"maxLength":70},"postBox":{"type":"string","minLength":1,"maxLength":16},"room":{"type":"string","minLength":1,"maxLength":70},"townLocationName":{"type":"string","minLength":1,"maxLength":35},"districtName":{"type":"string","minLength":1,"maxLength":35},"countrySubDivision":{"type":"string","minLength":1,"maxLength":35,"description":"CtrySubDvsn: Bundesstaat oder Provinz"}},"additionalProperties":false},"chargeBearer":{"type":"string","enum":["SLEV","SHAR","DEBT","CRED"]},"executionDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"serviceLevel":{"type":"string","enum":["NURG","URGP","SDVA"]},"categoryPurpose":{"type":"string","enum":["SALA"],"description":"Nur SEPA (/payments/sepa): \"SALA\" kennzeichnet die Zahlung als Lohn- oder Gehaltszahlung (PmtTpInf/CtgyPurp/Cd). Gehaltszahlungen kommen in einen eigenen PmtInf-Block. Im AXZ-Profil ist das Feld ein Fehler (PAY_CATEGORY_PURPOSE_AXZ)."},"localInstrument":{"type":"string","enum":["INST"],"description":"Nur SEPA (/payments/sepa): \"INST\" kennzeichnet die Zahlung als Echtzeitüberweisung (PmtTpInf/LclInstrm/Cd). Echtzeitüberweisungen kommen in einen eigenen PmtInf-Block; die Bank verlangt dafür einen eigenen Einreichungsweg. Im AXZ-Profil ein Fehler (PAY_LOCAL_INSTRUMENT_AXZ)."},"instrPrty":{"type":"string","enum":["HIGH"],"description":"Nur SEPA (/payments/sepa): \"HIGH\" setzt die Priorität PmtTpInf/InstrPrty; solche Zahlungen kommen in einen eigenen PmtInf-Block. Weglassen bedeutet NORM. Im AXZ-Profil ist das Feld ein Fehler (PAY_INSTR_PRTY_AXZ), dort kennzeichnet serviceLevel URGP eine eilige Zahlung."},"purposeCode":{"type":"string","pattern":"^[A-Z0-9]{1,4}$","description":"Zahlungszweck als ISO-20022-Code (CdtTrfTxInf/Purp/Cd, ExternalPurpose1Code), z. B. SUPP Lieferantenzahlung, SALA Gehalt, TAXS Steuer. Richtet sich an den Empfänger, nicht an die Bank; in SEPA- und AXZ-Dateien zulässig. Geprüft wird nur das Format (PAY_PURPOSE_CODE_FORMAT)."},"instructionId":{"type":"string","minLength":1,"maxLength":35,"description":"PmtId/InstrId: Auftragsreferenz des Einreichers, max 35 Zeichen, ohne Default."},"ultimateDebtor":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":140,"description":"SEPA max 70, AXZ Pflicht und max 140 (PAY_ULTIMATE_NAME_*)"},"address":{"type":"object","properties":{"townName":{"type":"string","minLength":1,"maxLength":35},"countryCode":{"type":"string","pattern":"^[A-Z]{2}$"},"postCode":{"type":"string","minLength":1,"maxLength":16},"streetName":{"type":"string","minLength":1,"maxLength":70},"buildingNumber":{"type":"string","minLength":1,"maxLength":16},"addressLines":{"type":"array","items":{"type":"string","minLength":1,"maxLength":70},"maxItems":2},"department":{"type":"string","minLength":1,"maxLength":70},"subDepartment":{"type":"string","minLength":1,"maxLength":70},"buildingName":{"type":"string","minLength":1,"maxLength":35},"floor":{"type":"string","minLength":1,"maxLength":70},"postBox":{"type":"string","minLength":1,"maxLength":16},"room":{"type":"string","minLength":1,"maxLength":70},"townLocationName":{"type":"string","minLength":1,"maxLength":35},"districtName":{"type":"string","minLength":1,"maxLength":35},"countrySubDivision":{"type":"string","minLength":1,"maxLength":35,"description":"CtrySubDvsn: Bundesstaat oder Provinz"}},"additionalProperties":false,"description":"nur AXZ; der SEPA-Generator schreibt sie nicht"},"id":{"type":"object","properties":{"kind":{"type":"string","enum":["org","private"],"description":"org = Organisation (OrgId), private = Privatperson (PrvtId)"},"anyBic":{"type":"string","minLength":8,"maxLength":11,"description":"OrgId/AnyBIC, nur org"},"lei":{"type":"string","minLength":20,"maxLength":20,"description":"OrgId/LEI, nur org"},"otherId":{"type":"string","minLength":1,"maxLength":35,"description":"Othr/Id, z. B. Gläubiger-ID oder Kundennummer"},"otherSchemeCode":{"type":"string","minLength":1,"maxLength":4,"description":"Othr/SchmeNm/Cd, z. B. CUST, NIDN"},"otherSchemeProprietary":{"type":"string","minLength":1,"maxLength":35,"description":"Othr/SchmeNm/Prtry"},"otherIssuer":{"type":"string","minLength":1,"maxLength":35,"description":"Othr/Issr"},"birthDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"nur private: PrvtId/DtAndPlcOfBirth/BirthDt"},"birthProvince":{"type":"string","minLength":1,"maxLength":35},"birthCity":{"type":"string","minLength":1,"maxLength":35},"birthCountry":{"type":"string","pattern":"^[A-Z]{2}$"}},"required":["kind"],"additionalProperties":false},"countryOfResidence":{"type":"string","pattern":"^[A-Z]{2}$","description":"CtryOfRes: Sitzland (ISO 3166 alpha-2); nur AXZ, der SEPA-Generator schreibt es nicht."}},"additionalProperties":false,"description":"UltmtDbtr: abweichender Auftraggeber (zahlt wirtschaftlich, ist aber nicht Kontoinhaber). SEPA: Name max 70 und/oder Kennung; AXZ: Name Pflicht, max 140, Adresse zulässig."},"ultimateCreditor":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":140,"description":"SEPA max 70, AXZ Pflicht und max 140 (PAY_ULTIMATE_NAME_*)"},"address":{"type":"object","properties":{"townName":{"type":"string","minLength":1,"maxLength":35},"countryCode":{"type":"string","pattern":"^[A-Z]{2}$"},"postCode":{"type":"string","minLength":1,"maxLength":16},"streetName":{"type":"string","minLength":1,"maxLength":70},"buildingNumber":{"type":"string","minLength":1,"maxLength":16},"addressLines":{"type":"array","items":{"type":"string","minLength":1,"maxLength":70},"maxItems":2},"department":{"type":"string","minLength":1,"maxLength":70},"subDepartment":{"type":"string","minLength":1,"maxLength":70},"buildingName":{"type":"string","minLength":1,"maxLength":35},"floor":{"type":"string","minLength":1,"maxLength":70},"postBox":{"type":"string","minLength":1,"maxLength":16},"room":{"type":"string","minLength":1,"maxLength":70},"townLocationName":{"type":"string","minLength":1,"maxLength":35},"districtName":{"type":"string","minLength":1,"maxLength":35},"countrySubDivision":{"type":"string","minLength":1,"maxLength":35,"description":"CtrySubDvsn: Bundesstaat oder Provinz"}},"additionalProperties":false,"description":"nur AXZ; der SEPA-Generator schreibt sie nicht"},"id":{"type":"object","properties":{"kind":{"type":"string","enum":["org","private"],"description":"org = Organisation (OrgId), private = Privatperson (PrvtId)"},"anyBic":{"type":"string","minLength":8,"maxLength":11,"description":"OrgId/AnyBIC, nur org"},"lei":{"type":"string","minLength":20,"maxLength":20,"description":"OrgId/LEI, nur org"},"otherId":{"type":"string","minLength":1,"maxLength":35,"description":"Othr/Id, z. B. Gläubiger-ID oder Kundennummer"},"otherSchemeCode":{"type":"string","minLength":1,"maxLength":4,"description":"Othr/SchmeNm/Cd, z. B. CUST, NIDN"},"otherSchemeProprietary":{"type":"string","minLength":1,"maxLength":35,"description":"Othr/SchmeNm/Prtry"},"otherIssuer":{"type":"string","minLength":1,"maxLength":35,"description":"Othr/Issr"},"birthDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"nur private: PrvtId/DtAndPlcOfBirth/BirthDt"},"birthProvince":{"type":"string","minLength":1,"maxLength":35},"birthCity":{"type":"string","minLength":1,"maxLength":35},"birthCountry":{"type":"string","pattern":"^[A-Z]{2}$"}},"required":["kind"],"additionalProperties":false},"countryOfResidence":{"type":"string","pattern":"^[A-Z]{2}$","description":"CtryOfRes: Sitzland (ISO 3166 alpha-2); nur AXZ, der SEPA-Generator schreibt es nicht."}},"additionalProperties":false,"description":"UltmtCdtr: abweichender Empfänger, Regeln wie ultimateDebtor."},"creditorId":{"type":"object","properties":{"kind":{"type":"string","enum":["org","private"],"description":"org = Organisation (OrgId), private = Privatperson (PrvtId)"},"anyBic":{"type":"string","minLength":8,"maxLength":11,"description":"OrgId/AnyBIC, nur org"},"lei":{"type":"string","minLength":20,"maxLength":20,"description":"OrgId/LEI, nur org"},"otherId":{"type":"string","minLength":1,"maxLength":35,"description":"Othr/Id, z. B. Gläubiger-ID oder Kundennummer"},"otherSchemeCode":{"type":"string","minLength":1,"maxLength":4,"description":"Othr/SchmeNm/Cd, z. B. CUST, NIDN"},"otherSchemeProprietary":{"type":"string","minLength":1,"maxLength":35,"description":"Othr/SchmeNm/Prtry"},"otherIssuer":{"type":"string","minLength":1,"maxLength":35,"description":"Othr/Issr"},"birthDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"nur private: PrvtId/DtAndPlcOfBirth/BirthDt"},"birthProvince":{"type":"string","minLength":1,"maxLength":35},"birthCity":{"type":"string","minLength":1,"maxLength":35},"birthCountry":{"type":"string","pattern":"^[A-Z]{2}$"}},"required":["kind"],"additionalProperties":false,"description":"Cdtr/Id: Kennung des Empfängers (LEI, BIC oder sonstige Kennung)."},"creditorCountryOfResidence":{"type":"string","pattern":"^[A-Z]{2}$","description":"Cdtr/CtryOfRes: Sitzland des Empfängers (ISO 3166 alpha-2); nur AXZ, in SEPA-Dateien nicht enthalten."},"uetr":{"type":"string","pattern":"^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$","description":"PmtId/UETR: eindeutige Transaktionsreferenz, UUID Version 4 in Kleinbuchstaben; nur AXZ."},"transferCurrency":{"type":"string","pattern":"^[A-Z]{3}$","description":"Amt/EqvtAmt/CcyOfTrf: Gegenwertzahlung, amount/currency in Kontowährung, Überweisung in dieser Währung; nur AXZ."},"intermediaryAgents":{"type":"array","items":{"type":"string","minLength":8,"maxLength":11},"maxItems":2,"description":"IntrmyAgt1/2: BICs der Korrespondenzbanken; nur AXZ."},"creditorClearingMember":{"type":"object","properties":{"systemCode":{"type":"string","minLength":1,"maxLength":5},"memberId":{"type":"string","minLength":1,"maxLength":35}},"required":["systemCode","memberId"],"additionalProperties":false,"description":"CdtrAgt/FinInstnId/ClrSysMmbId, zum Beispiel USABA mit Routing-Nummer; nur AXZ."},"instructionsForCreditorAgent":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["CHQB","HOLD","PHOB","TELB"]},"info":{"type":"string","minLength":1,"maxLength":140}},"additionalProperties":false},"maxItems":2,"description":"InstrForCdtrAgt: Weisungen an die Bank des Empfängers; nur AXZ."},"instructionForDebtorAgent":{"type":"string","minLength":1,"maxLength":140,"description":"InstrForDbtrAgt: Weisung an die eigene Bank; nur AXZ."},"batchBooking":{"type":"boolean","const":false,"description":"BtchBookg false: Einzelbuchung statt Sammelbuchung."}},"required":["creditorName","creditorIban","amount","currency","remittanceInfo"],"additionalProperties":false},"minItems":1},"initiatingPartyId":{"type":"object","properties":{"kind":{"type":"string","enum":["org","private"],"description":"org = Organisation (OrgId), private = Privatperson (PrvtId)"},"anyBic":{"type":"string","minLength":8,"maxLength":11,"description":"OrgId/AnyBIC, nur org"},"lei":{"type":"string","minLength":20,"maxLength":20,"description":"OrgId/LEI, nur org"},"otherId":{"type":"string","minLength":1,"maxLength":35,"description":"Othr/Id, z. B. Gläubiger-ID oder Kundennummer"},"otherSchemeCode":{"type":"string","minLength":1,"maxLength":4,"description":"Othr/SchmeNm/Cd, z. B. CUST, NIDN"},"otherSchemeProprietary":{"type":"string","minLength":1,"maxLength":35,"description":"Othr/SchmeNm/Prtry"},"otherIssuer":{"type":"string","minLength":1,"maxLength":35,"description":"Othr/Issr"},"birthDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"nur private: PrvtId/DtAndPlcOfBirth/BirthDt"},"birthProvince":{"type":"string","minLength":1,"maxLength":35},"birthCity":{"type":"string","minLength":1,"maxLength":35},"birthCountry":{"type":"string","pattern":"^[A-Z]{2}$"}},"required":["kind"],"additionalProperties":false,"description":"GrpHdr/InitgPty/Id (T112): Kennung des Einreichers; als Name steht weiterhin der Auftraggeber."}},"required":["debtor","requestedExecutionDate","payments"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"PaymentIssue":{"type":"object","description":"Eine Meldung der Zahllauf-Prüfung. error blockiert die Datei (422), warning und info nicht (sie stehen in der JSON-Antwort als warnings).","properties":{"code":{"type":"string","description":"Maschinencode, z. B. \"PAY_IBAN_INVALID\"."},"message":{"type":"string","description":"Deutsche Fehlermeldung."},"path":{"type":"string","description":"Punkt-Pfad in den Zahllauf, z. B. \"payments.0.creditorIban\"."},"severity":{"type":"string","enum":["error","warning","info"]}},"required":["code","message","severity"]},"PaymentFileResult":{"type":"object","description":"JSON-Hülle der Zahlungsdatei-Endpoints. Kommt nur bei ausdrücklichem Accept: application/json (ohne */*-Platzhalter), sonst antwortet der Endpoint direkt mit dem XML.","properties":{"xml":{"type":"string","description":"Die pain.001-XML als Text."},"filename":{"type":"string","description":"Vorgeschlagener Dateiname, gleiches Schema wie der Content-Disposition-Name der XML-Antwort (sepa-inland-<Datum>.xml bzw. axz-ausland-<Datum>.xml)."},"summary":{"type":"object","properties":{"payments":{"type":"integer","description":"Anzahl der Zahlungen."},"controlSum":{"type":"string","description":"Kontrollsumme, identisch mit CtrlSum im XML."},"requestedExecutionDate":{"type":"string","description":"Ausführungsdatum (yyyy-mm-dd)."}},"required":["payments","controlSum","requestedExecutionDate"]},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/PaymentIssue"},"description":"Nicht blockierende Meldungen (severity warning oder info)."},"verification":{"type":"string","enum":["autoritativ","eingeschränkt"],"description":"autoritativ = die Datei hat das QA-Gate (DK-TVS bzw. AXZ-TVS) durchlaufen; eingeschränkt = kein Validator konfiguriert, geprüft wurden nur Schema und Geschäftsregeln."}},"required":["xml","filename","summary","warnings","verification"]}}}}