{"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. verify ist kostenlos (Key nötig), invoices erfordert ein aktives Abo."},"servers":[{"url":"https://finisma.de/api/v1"}],"security":[{"bearerAuth":[]}],"paths":{"/verify":{"post":{"operationId":"verifyInvoice","summary":"E-Rechnung prüfen (kostenlos, Key nötig)","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ültiger API-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate-Limit erreicht (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","summary":"ZUGFeRD-Rechnung erzeugen (Abo nötig)","description":"Bettet die EN-16931-Daten als CII-XML in die übergebene PDF ein und liefert die fertige ZUGFeRD-PDF (PDF/A-3). Standardantwort ist die binäre PDF; mit 'Accept: application/json' kommt stattdessen { pdf_base64, bytes }.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"pdf":{"type":"string","format":"binary","description":"Die visuelle Rechnungs-PDF (max. 25 MB)."},"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)."},"filename":{"type":"string","description":"Ausgabedateiname (Standard: invoice.pdf)."}},"required":["pdf","invoice"]},"encoding":{"invoice":{"contentType":"application/json"}}}}},"responses":{"200":{"description":"Erzeugte ZUGFeRD-PDF.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"type":"object","properties":{"pdf_base64":{"type":"string","contentEncoding":"base64"},"bytes":{"type":"integer"}},"required":["pdf_base64","bytes"]}}}},"400":{"description":"Ungültige Eingabe.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Kein oder ungültiger API-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Kein aktives Abo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate-Limit erreicht (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"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API-Key (fnsm_…) aus dem finisma-Konto unter /konto."}},"schemas":{"Invoice":{"type":"object","properties":{"invoiceNumber":{"type":"string","minLength":1,"maxLength":60},"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}$"},"currency":{"type":"string","minLength":3,"maxLength":3,"default":"EUR"},"buyerReference":{"type":"string","maxLength":80},"costCenter":{"type":"string","maxLength":60},"seller":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"vatId":{"type":"string","maxLength":20},"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}},"required":["name"],"additionalProperties":false},"buyer":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"vatId":{"type":"string","maxLength":20},"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}},"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"},"unitPriceNet":{"type":"number"},"vatRatePercent":{"type":"number"},"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"}},"required":["ratePercent","basisAmount","taxAmount"],"additionalProperties":false},"minItems":1,"maxItems":50},"totalNet":{"type":"number"},"totalVat":{"type":"number"},"totalGross":{"type":"number"},"payment":{"type":"object","properties":{"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},"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"]},"Error":{"type":"object","properties":{"error":{"type":"string","description":"Menschenlesbare Fehlermeldung."},"code":{"type":"string","enum":["invalid_input","auth_required","invalid_key","subscription_required","rate_limited","not_found","upstream_error"]},"details":{"description":"Optionale strukturierte Details, z. B. Validierungs-Issues."}},"required":["error","code"]}}}}