finisma – ZUGFeRD e-invoices

{'type': 'object', 'required': ['participant'], 'properties': {'participant': {'type': 'string', 'description': 'Kennung des Partners: volle Peppol-Kennung ("0088:4399901550926"), nackte GLN, deutsche USt-IdNr. ("DE123456789") oder Leitweg-ID ("991-33333TEST-33").'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['input', 'participantId', 'scheme', 'value', 'registered', 'documentTypes', 'checkedAt', 'cached'], 'properties': {'name': {'type': ['string', 'null'], 'description': 'Name laut Peppol Directory, falls gelistet'}, 'input': {'type': 'string'}, 'value': {'type': 'string'}, 'cached': {'type': 'boolean'}, 'scheme': {'type': 'string'}, 'checkedAt': {'type': 'string', 'description': 'Zeitpunkt der echten Prüfung (ISO 8601)'}, 'registered': {'type': 'boolean'}, 'countryCode': {'type': ['string', 'null']}, 'documentTypes': {'type': 'array', 'items': {'type': 'string'}, 'description': 'registrierte Dokumenttypen laut SMP (leer bei registered:false)'}, 'participantId': {'type': 'string', 'description': 'volle Kennung inkl. Meta-Schema, z. B. "iso6523-actorid-upis::0088:4399901550926"'}}}

{'type': 'object', 'required': ['vat_id'], 'properties': {'vat_id': {'type': 'string', 'description': 'Die zu prüfende USt-IdNr. mit Länderpräfix, z. B. "DE325821677" oder "ATU12345675". Leerzeichen, Punkte und Bindestriche werden toleriert.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['vatId', 'countryCode', 'status', 'checkedAt', 'cached'], 'properties': {'name': {'type': ['string', 'null'], 'description': 'Firmenname laut Mitgliedsstaat, oft nicht herausgegeben'}, 'vatId': {'type': 'string', 'description': 'normalisierte Nummer, wie geprüft wurde'}, 'cached': {'type': 'boolean'}, 'status': {'enum': ['valid', 'invalid', 'unavailable'], 'type': 'string'}, 'checkedAt': {'type': 'string', 'description': 'Zeitpunkt der echten Prüfung (ISO 8601)'}, 'countryCode': {'type': 'string'}}}

{'type': 'object', 'required': ['invoice'], 'properties': {'invoice': {'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['invoiceNumber', 'issueDate', 'seller', 'buyer', 'lines', 'vatBreakdown', 'totalNet', 'totalVat', 'totalGross'], 'properties': {'buyer': {'type': 'object', 'required': ['name'], 'properties': {'gln': {'type': 'string', 'maxLength': 20}, 'name': {'type': 'string', 'maxLength': 200, 'minLength': 1}, 'vatId': {'type': 'string', 'maxLength': 20}, 'address': {'type': 'object', 'default': {}, 'properties': {'city': {'type': 'string', 'maxLength': 100}, 'line1': {'type': 'string', 'maxLength': 150}, 'line2': {'type': 'string', 'maxLength': 150}, 'postalCode': {'type': 'string', 'maxLength': 20}, 'countryCode': {'type': 'string', 'default': 'DE', 'maxLength': 2, 'minLength': 2}}, 'additionalProperties': False}, 'contact': {'type': 'object', 'properties': {'name': {'type': 'string', 'maxLength': 150}, 'email': {'type': 'string', 'maxLength': 150}, 'phone': {'type': 'string', 'maxLength': 40}}, 'additionalProperties': False}, '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.'}, 'electronicAddress': {'type': 'object', 'required': ['id'], 'properties': {'id': {'type': 'string', 'maxLength': 200, 'minLength': 1}, 'scheme': {'type': 'string', 'default': 'EM', 'maxLength': 10}}, 'additionalProperties': False}}, 'additionalProperties': False}, 'lines': {'type': 'array', 'items': {'type': 'object', 'required': ['name', 'quantity', 'unitPriceNet', 'vatRatePercent', 'lineNetAmount'], 'properties': {'name': {'type': 'string', 'maxLength': 300, 'minLength': 1}, 'quantity': {'type': 'number'}, 'unitCode': {'type': 'string', 'default': 'C62', 'maxLength': 12}, 'categoryCode': {'type': 'string', 'maxLength': 12}, 'unitPriceNet': {'type': 'number'}, 'lineNetAmount': {'type': 'number'}, 'buyerArticleId': {'type': 'string', 'maxLength': 200}, 'vatRatePercent': {'type': 'number'}, 'globalArticleId': {'type': 'string', 'maxLength': 60}, 'sellerArticleId': {'type': 'string', 'maxLength': 200}, 'allowanceCharges': {'type': 'array', 'items': {'type': 'object', 'required': ['charge'], 'properties': {'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).'}, 'charge': {'type': 'boolean', 'description': 'true = Zuschlag (BG-28), false = Abzug/Rabatt (BG-27).'}, 'reason': {'type': 'string', 'maxLength': 200}, 'percent': {'type': 'number', 'maximum': 100, 'minimum': 0, 'description': 'BT-138/BT-143: Prozentsatz, z. B. 10 für 10 % Rabatt.'}, 'reasonCode': {'type': 'string', 'maxLength': 10}, 'basisAmount': {'type': 'number', 'description': 'BT-137/BT-142: Grundbetrag des Prozentsatzes. Ohne Angabe Menge × unitPriceNet der Position (je Eintrag, nicht gestaffelt).'}}, 'additionalProperties': False}, 'maxItems': 10}, 'globalArticleScheme': {'type': 'string', 'pattern': '^[0-9A-Za-z]+$', 'maxLength': 10}}, 'additionalProperties': False}, 'maxItems': 500, 'minItems': 1}, 'notes': {'type': 'array', 'items': {'anyOf': [{'type': 'string', 'maxLength': 1000}, {'type': 'object', 'required': ['text'], 'properties': {'text': {'type': 'string', 'maxLength': 1000}, 'subjectCode': {'type': 'string'}}, 'additionalProperties': False}]}, 'maxItems': 20}, 'payee': {'type': 'object', 'required': ['name'], 'properties': {'gln': {'type': 'string', 'maxLength': 20}, 'name': {'type': 'string', 'maxLength': 200, 'minLength': 1}, 'registrationId': {'type': 'string', 'maxLength': 60}}, 'additionalProperties': False}, 'seller': {'type': 'object', 'required': ['name'], 'properties': {'gln': {'type': 'string', 'maxLength': 20}, 'name': {'type': 'string', 'maxLength': 200, 'minLength': 1}, 'vatId': {'type': 'string', 'maxLength': 20}, 'address': {'type': 'object', 'default': {}, 'properties': {'city': {'type': 'string', 'maxLength': 100}, 'line1': {'type': 'string', 'maxLength': 150}, 'line2': {'type': 'string', 'maxLength': 150}, 'postalCode': {'type': 'string', 'maxLength': 20}, 'countryCode': {'type': 'string', 'default': 'DE', 'maxLength': 2, 'minLength': 2}}, 'additionalProperties': False}, 'contact': {'type': 'object', 'properties': {'name': {'type': 'string', 'maxLength': 150}, 'email': {'type': 'string', 'maxLength': 150}, 'phone': {'type': 'string', 'maxLength': 40}}, 'additionalProperties': False}, '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.'}, 'electronicAddress': {'type': 'object', 'required': ['id'], 'properties': {'id': {'type': 'string', 'maxLength': 200, 'minLength': 1}, 'scheme': {'type': 'string', 'default': 'EM', 'maxLength': 10}}, 'additionalProperties': False}}, 'additionalProperties': False}, 'dueDate': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$'}, 'payment': {'type': 'object', 'properties': {'bic': {'type': 'string', 'pattern': '^[A-Za-z0-9 ]*$', 'maxLength': 15}, 'iban': {'type': 'string', 'pattern': '^[A-Za-z0-9 ]*$', 'maxLength': 40}, 'terms': {'type': 'string', 'maxLength': 1000}, 'mandateId': {'type': 'string', 'maxLength': 35}, 'meansCode': {'type': 'string'}, 'reference': {'type': 'string', 'maxLength': 140}, 'creditorId': {'type': 'string', 'maxLength': 35}, 'accountName': {'type': 'string', 'maxLength': 200}, 'debitedIban': {'type': 'string', 'pattern': '^[A-Za-z0-9 ]*$', 'maxLength': 40}, 'discountDays': {'type': 'integer', 'maximum': 999, 'minimum': 0}, 'discountPercent': {'type': 'number', 'maximum': 100, 'minimum': 0}}, 'additionalProperties': False}, 'profile': {'enum': ['en16931', 'xrechnung'], 'type': 'string', 'default': 'en16931'}, 'currency': {'type': 'string', 'default': 'EUR', 'maxLength': 3, 'minLength': 3}, 'delivery': {'type': 'object', 'properties': {'name': {'type': 'string', 'maxLength': 200}, 'address': {'type': 'object', 'properties': {'city': {'type': 'string', 'maxLength': 100}, 'line1': {'type': 'string', 'maxLength': 150}, 'line2': {'type': 'string', 'maxLength': 150}, 'postalCode': {'type': 'string', 'maxLength': 20}, 'countryCode': {'type': 'string', 'maxLength': 2, 'minLength': 2}}, 'additionalProperties': False}}, 'additionalProperties': False}, 'totalNet': {'type': 'number'}, 'totalVat': {'type': 'number'}, 'issueDate': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$'}, 'costCenter': {'type': 'string', 'maxLength': 60}, 'paidAmount': {'type': 'number', 'minimum': 0}, 'totalGross': {'type': 'number'}, 'deliveryDate': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$'}, 'vatBreakdown': {'type': 'array', 'items': {'type': 'object', 'required': ['ratePercent', 'basisAmount', 'taxAmount'], 'properties': {'taxAmount': {'type': 'number'}, 'basisAmount': {'type': 'number'}, 'ratePercent': {'type': 'number'}, 'categoryCode': {'type': 'string', 'default': 'S', 'maxLength': 12}, 'exemptionReason': {'type': 'string', 'maxLength': 500}, 'exemptionReasonCode': {'type': 'string', 'maxLength': 30}}, 'additionalProperties': False}, 'maxItems': 50, 'minItems': 1}, 'invoiceNumber': {'type': 'string', 'maxLength': 60, 'minLength': 1}, 'buyerReference': {'type': 'string', 'maxLength': 80}, 'invoicingPeriod': {'type': 'object', 'properties': {'end': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$'}, 'start': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$'}}, 'additionalProperties': False}, 'taxCurrencyCode': {'type': 'string', 'maxLength': 3, 'minLength': 3}, 'allowanceCharges': {'type': 'array', 'items': {'type': 'object', 'required': ['charge'], 'properties': {'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).'}, 'charge': {'type': 'boolean', 'description': 'true = Zuschlag (BG-21), false = Abzug/Nachlass (BG-20).'}, 'reason': {'type': 'string', 'maxLength': 200}, 'percent': {'type': 'number', 'maximum': 100, 'minimum': 0, 'description': 'BT-94/BT-101: Prozentsatz, z. B. 2 für 2 % Nachlass.'}, 'reasonCode': {'type': 'string', 'maxLength': 10}, '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).'}, 'ratePercent': {'type': 'number', 'description': 'BT-96/BT-103: Steuersatz in Prozent. Darf beim Prozent-Eintrag ohne basisAmount fehlen, wenn alle Positionen denselben Satz haben.'}, 'categoryCode': {'type': 'string', 'default': 'S', 'maxLength': 12}}, 'additionalProperties': False}, 'maxItems': 50}, 'documentTypeCode': {'type': 'string', 'default': '380'}, 'projectReference': {'type': 'string', 'maxLength': 200}, 'contractReference': {'type': 'string', 'maxLength': 200}, 'despatchAdviceRef': {'type': 'string', 'maxLength': 200}, 'receivingAdviceRef': {'type': 'string', 'maxLength': 200}, 'deliveryCountryCode': {'type': 'string', 'maxLength': 2, 'minLength': 2}, 'precedingInvoiceDate': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$'}, 'totalVatInTaxCurrency': {'type': 'number'}, 'precedingInvoiceNumber': {'type': 'string', 'maxLength': 60}, 'purchaseOrderReference': {'type': 'string', 'maxLength': 60}}, 'description': 'Strukturierte Rechnungsdaten nach EN 16931 (wird gegen Schema und Geschäftsregeln geprüft).', 'additionalProperties': False}, 'filename': {'type': 'string', 'description': 'Dateiname der erzeugten Rechnung (Standard: invoice.pdf).'}, 'upload_id': {'type': 'string', 'description': 'Referenz auf eine zuvor über request_upload_link hochgeladene Datei, anstelle von pdf_base64. Genau eines von beiden angeben.'}, 'pdf_base64': {'type': 'string', 'description': "Die visuelle Rechnungs-PDF, Base64-kodiert (max. 25 MB). In sie wird das CII-XML eingebettet. Alternativ 'upload_id' angeben. Chat-Clients, die eine angehängte Datei nicht zuverlässig als Base64 übergeben können, rufen zuerst request_upload_link auf.", 'contentEncoding': 'base64', 'contentMediaType': 'application/pdf'}, 'attachments': {'type': 'array', 'items': {'type': 'object', 'required': ['filename', 'data_base64'], 'properties': {'filename': {'type': 'string'}, 'mime_type': {'type': 'string', 'description': 'Optional; wird sonst aus der Dateiendung abgeleitet.'}, 'data_base64': {'type': 'string', 'description': 'Dateiinhalt, Base64-kodiert (max. 10 MB).', 'contentEncoding': 'base64'}, 'description': {'type': 'string', 'description': 'Optionale Beschreibung der rechnungsbegründenden Unterlage (BT-123), z. B. "Stundennachweis März 2026". Ohne Angabe steht dort der Dateiname.'}}, 'additionalProperties': False}, 'description': 'Optionale Anhänge (z. B. Stundennachweise). Erlaubt: PDF, PNG, JPEG, CSV, XLSX, ODS, XML; je max. 10 MB.'}}, 'additionalProperties': False}

{'type': 'object', 'required': [], 'properties': {'bytes': {'type': 'integer', 'description': 'Größe der erzeugten PDF in Bytes.'}, 'issues': {'type': 'array', 'items': {'type': 'object', 'required': ['code', 'message', 'severity'], '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': {'enum': ['error', 'warning'], 'type': 'string'}}}, 'description': 'Nur gesetzt, wenn die übergebenen Rechnungsdaten EN-16931-Geschäftsregeln verletzen: es wurde keine Datei erzeugt (Korrekturschleife, T20). Felder anhand der Issues korrigieren und create_zugferd mit denselben Quelldaten (upload_id/pdf_base64) und dem korrigierten invoice erneut aufrufen.'}, 'expires_at': {'type': 'string', 'description': 'ISO-8601-Zeitpunkt, ab dem download_url verfällt (nur mit download_url gesetzt).'}, 'pdf_base64': {'type': 'string', 'description': "Die erzeugte ZUGFeRD-Rechnung (PDF/A-3 mit eingebettetem CII-XML). Nur gesetzt, wenn die Eingabe als 'pdf_base64' kam; wurde 'upload_id' verwendet, steht stattdessen download_url im Ergebnis.", 'contentEncoding': 'base64', 'contentMediaType': 'application/pdf'}, 'watermarked': {'type': 'boolean', 'description': 'true, wenn die PDF aus dem kostenlosen Tageskontingent stammt und das finisma-Prüfsiegel als Wasserzeichen trägt (Aufruf ohne aktives Abo).'}, 'download_url': {'type': 'string', 'description': "Kurzlebiger Download-Link zur erzeugten PDF. Nur gesetzt, wenn die Eingabe als 'upload_id' kam (Chat-Client-Fallback)."}}, 'additionalProperties': False}

{'type': 'object', 'properties': {'upload_id': {'type': 'string', 'description': "Referenz auf eine zuvor über request_upload_link hochgeladene Datei, anstelle von pdf_base64. Genau eines von beiden angeben. Wird im Ergebnis erneut zurückgegeben und kann anschließend bei create_zugferd als 'upload_id' verwendet werden, damit dieselbe Quell-PDF eingebettet wird."}, 'pdf_base64': {'type': 'string', 'description': "Die zu extrahierende PDF-Rechnung, Base64-kodiert (max. 25 MB). Alternativ 'upload_id' angeben. Chat-Clients, die eine angehängte Datei nicht zuverlässig als Base64 übergeben können, rufen zuerst request_upload_link auf.", 'contentEncoding': 'base64', 'contentMediaType': 'application/pdf'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['invoice', 'validation_issues', 'upload_id', 'expires_at', 'source'], 'properties': {'source': {'enum': ['xml', 'llm'], 'type': 'string', 'description': "Herkunft der Felder: 'xml' = deterministisch aus der in der PDF eingebetteten E-Rechnung übernommen, 'llm' = per Sprachmodell aus dem Druckbild extrahiert."}, 'invoice': {'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['invoiceNumber', 'issueDate', 'seller', 'buyer', 'lines', 'vatBreakdown', 'totalNet', 'totalVat', 'totalGross'], 'properties': {'buyer': {'type': 'object', 'required': ['name'], 'properties': {'gln': {'type': 'string', 'maxLength': 20}, 'name': {'type': 'string', 'maxLength': 200, 'minLength': 1}, 'vatId': {'type': 'string', 'maxLength': 20}, 'address': {'type': 'object', 'default': {}, 'properties': {'city': {'type': 'string', 'maxLength': 100}, 'line1': {'type': 'string', 'maxLength': 150}, 'line2': {'type': 'string', 'maxLength': 150}, 'postalCode': {'type': 'string', 'maxLength': 20}, 'countryCode': {'type': 'string', 'default': 'DE', 'maxLength': 2, 'minLength': 2}}, 'additionalProperties': False}, 'contact': {'type': 'object', 'properties': {'name': {'type': 'string', 'maxLength': 150}, 'email': {'type': 'string', 'maxLength': 150}, 'phone': {'type': 'string', 'maxLength': 40}}, 'additionalProperties': False}, '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.'}, 'electronicAddress': {'type': 'object', 'required': ['id'], 'properties': {'id': {'type': 'string', 'maxLength': 200, 'minLength': 1}, 'scheme': {'type': 'string', 'default': 'EM', 'maxLength': 10}}, 'additionalProperties': False}}, 'additionalProperties': False}, 'lines': {'type': 'array', 'items': {'type': 'object', 'required': ['name', 'quantity', 'unitPriceNet', 'vatRatePercent', 'lineNetAmount'], 'properties': {'name': {'type': 'string', 'maxLength': 300, 'minLength': 1}, 'quantity': {'type': 'number'}, 'unitCode': {'type': 'string', 'default': 'C62', 'maxLength': 12}, 'categoryCode': {'type': 'string', 'maxLength': 12}, 'unitPriceNet': {'type': 'number'}, 'lineNetAmount': {'type': 'number'}, 'buyerArticleId': {'type': 'string', 'maxLength': 200}, 'vatRatePercent': {'type': 'number'}, 'globalArticleId': {'type': 'string', 'maxLength': 60}, 'sellerArticleId': {'type': 'string', 'maxLength': 200}, 'allowanceCharges': {'type': 'array', 'items': {'type': 'object', 'required': ['charge'], 'properties': {'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).'}, 'charge': {'type': 'boolean', 'description': 'true = Zuschlag (BG-28), false = Abzug/Rabatt (BG-27).'}, 'reason': {'type': 'string', 'maxLength': 200}, 'percent': {'type': 'number', 'maximum': 100, 'minimum': 0, 'description': 'BT-138/BT-143: Prozentsatz, z. B. 10 für 10 % Rabatt.'}, 'reasonCode': {'type': 'string', 'maxLength': 10}, 'basisAmount': {'type': 'number', 'description': 'BT-137/BT-142: Grundbetrag des Prozentsatzes. Ohne Angabe Menge × unitPriceNet der Position (je Eintrag, nicht gestaffelt).'}}, 'additionalProperties': False}, 'maxItems': 10}, 'globalArticleScheme': {'type': 'string', 'pattern': '^[0-9A-Za-z]+$', 'maxLength': 10}}, 'additionalProperties': False}, 'maxItems': 500, 'minItems': 1}, 'notes': {'type': 'array', 'items': {'anyOf': [{'type': 'string', 'maxLength': 1000}, {'type': 'object', 'required': ['text'], 'properties': {'text': {'type': 'string', 'maxLength': 1000}, 'subjectCode': {'type': 'string'}}, 'additionalProperties': False}]}, 'maxItems': 20}, 'payee': {'type': 'object', 'required': ['name'], 'properties': {'gln': {'type': 'string', 'maxLength': 20}, 'name': {'type': 'string', 'maxLength': 200, 'minLength': 1}, 'registrationId': {'type': 'string', 'maxLength': 60}}, 'additionalProperties': False}, 'seller': {'type': 'object', 'required': ['name'], 'properties': {'gln': {'type': 'string', 'maxLength': 20}, 'name': {'type': 'string', 'maxLength': 200, 'minLength': 1}, 'vatId': {'type': 'string', 'maxLength': 20}, 'address': {'type': 'object', 'default': {}, 'properties': {'city': {'type': 'string', 'maxLength': 100}, 'line1': {'type': 'string', 'maxLength': 150}, 'line2': {'type': 'string', 'maxLength': 150}, 'postalCode': {'type': 'string', 'maxLength': 20}, 'countryCode': {'type': 'string', 'default': 'DE', 'maxLength': 2, 'minLength': 2}}, 'additionalProperties': False}, 'contact': {'type': 'object', 'properties': {'name': {'type': 'string', 'maxLength': 150}, 'email': {'type': 'string', 'maxLength': 150}, 'phone': {'type': 'string', 'maxLength': 40}}, 'additionalProperties': False}, '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.'}, 'electronicAddress': {'type': 'object', 'required': ['id'], 'properties': {'id': {'type': 'string', 'maxLength': 200, 'minLength': 1}, 'scheme': {'type': 'string', 'default': 'EM', 'maxLength': 10}}, 'additionalProperties': False}}, 'additionalProperties': False}, 'dueDate': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$'}, 'payment': {'type': 'object', 'properties': {'bic': {'type': 'string', 'pattern': '^[A-Za-z0-9 ]*$', 'maxLength': 15}, 'iban': {'type': 'string', 'pattern': '^[A-Za-z0-9 ]*$', 'maxLength': 40}, 'terms': {'type': 'string', 'maxLength': 1000}, 'mandateId': {'type': 'string', 'maxLength': 35}, 'meansCode': {'type': 'string'}, 'reference': {'type': 'string', 'maxLength': 140}, 'creditorId': {'type': 'string', 'maxLength': 35}, 'accountName': {'type': 'string', 'maxLength': 200}, 'debitedIban': {'type': 'string', 'pattern': '^[A-Za-z0-9 ]*$', 'maxLength': 40}, 'discountDays': {'type': 'integer', 'maximum': 999, 'minimum': 0}, 'discountPercent': {'type': 'number', 'maximum': 100, 'minimum': 0}}, 'additionalProperties': False}, 'profile': {'enum': ['en16931', 'xrechnung'], 'type': 'string', 'default': 'en16931'}, 'currency': {'type': 'string', 'default': 'EUR', 'maxLength': 3, 'minLength': 3}, 'delivery': {'type': 'object', 'properties': {'name': {'type': 'string', 'maxLength': 200}, 'address': {'type': 'object', 'properties': {'city': {'type': 'string', 'maxLength': 100}, 'line1': {'type': 'string', 'maxLength': 150}, 'line2': {'type': 'string', 'maxLength': 150}, 'postalCode': {'type': 'string', 'maxLength': 20}, 'countryCode': {'type': 'string', 'maxLength': 2, 'minLength': 2}}, 'additionalProperties': False}}, 'additionalProperties': False}, 'totalNet': {'type': 'number'}, 'totalVat': {'type': 'number'}, 'issueDate': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$'}, 'costCenter': {'type': 'string', 'maxLength': 60}, 'paidAmount': {'type': 'number', 'minimum': 0}, 'totalGross': {'type': 'number'}, 'deliveryDate': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$'}, 'vatBreakdown': {'type': 'array', 'items': {'type': 'object', 'required': ['ratePercent', 'basisAmount', 'taxAmount'], 'properties': {'taxAmount': {'type': 'number'}, 'basisAmount': {'type': 'number'}, 'ratePercent': {'type': 'number'}, 'categoryCode': {'type': 'string', 'default': 'S', 'maxLength': 12}, 'exemptionReason': {'type': 'string', 'maxLength': 500}, 'exemptionReasonCode': {'type': 'string', 'maxLength': 30}}, 'additionalProperties': False}, 'maxItems': 50, 'minItems': 1}, 'invoiceNumber': {'type': 'string', 'maxLength': 60, 'minLength': 1}, 'buyerReference': {'type': 'string', 'maxLength': 80}, 'invoicingPeriod': {'type': 'object', 'properties': {'end': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$'}, 'start': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$'}}, 'additionalProperties': False}, 'taxCurrencyCode': {'type': 'string', 'maxLength': 3, 'minLength': 3}, 'allowanceCharges': {'type': 'array', 'items': {'type': 'object', 'required': ['charge'], 'properties': {'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).'}, 'charge': {'type': 'boolean', 'description': 'true = Zuschlag (BG-21), false = Abzug/Nachlass (BG-20).'}, 'reason': {'type': 'string', 'maxLength': 200}, 'percent': {'type': 'number', 'maximum': 100, 'minimum': 0, 'description': 'BT-94/BT-101: Prozentsatz, z. B. 2 für 2 % Nachlass.'}, 'reasonCode': {'type': 'string', 'maxLength': 10}, '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).'}, 'ratePercent': {'type': 'number', 'description': 'BT-96/BT-103: Steuersatz in Prozent. Darf beim Prozent-Eintrag ohne basisAmount fehlen, wenn alle Positionen denselben Satz haben.'}, 'categoryCode': {'type': 'string', 'default': 'S', 'maxLength': 12}}, 'additionalProperties': False}, 'maxItems': 50}, 'documentTypeCode': {'type': 'string', 'default': '380'}, 'projectReference': {'type': 'string', 'maxLength': 200}, 'contractReference': {'type': 'string', 'maxLength': 200}, 'despatchAdviceRef': {'type': 'string', 'maxLength': 200}, 'receivingAdviceRef': {'type': 'string', 'maxLength': 200}, 'deliveryCountryCode': {'type': 'string', 'maxLength': 2, 'minLength': 2}, 'precedingInvoiceDate': {'type': 'string', 'pattern': '^\\d{4}-\\d{2}-\\d{2}$'}, 'totalVatInTaxCurrency': {'type': 'number'}, 'precedingInvoiceNumber': {'type': 'string', 'maxLength': 60}, 'purchaseOrderReference': {'type': 'string', 'maxLength': 60}}, 'description': "Extrahierte EN-16931-Rechnungsdaten (Formularfelder). Vor create_zugferd prüfen und korrigieren, insbesondere Felder mit dem Wert 'KORRIGIEREN' bzw. '1900-01-01'.", 'additionalProperties': False}, 'upload_id': {'type': 'string', 'description': "Bei create_zugferd als 'upload_id' übergeben, damit dieselbe Quell-PDF eingebettet wird."}, 'expires_at': {'type': 'string', 'description': 'ISO-8601-Zeitpunkt, ab dem upload_id verfällt. Danach erneut request_upload_link und extract_invoice aufrufen.'}, 'validation_issues': {'type': 'array', 'items': {'type': 'object', 'required': ['code', 'message', 'severity'], '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': {'enum': ['error', 'warning'], 'type': 'string'}}}, 'description': "Offene Probleme der extrahierten Daten. severity='error' blockiert create_zugferd (dort wird dieselbe Prüfung erneut ausgeführt), 'warning' nicht."}}, 'additionalProperties': False}

{'type': 'object', 'properties': {}, 'additionalProperties': False}

{'type': 'object', 'required': ['upload_id', 'upload_url', 'upload_api_url', 'expires_at'], 'properties': {'upload_id': {'type': 'string', 'description': "An create_zugferd/verify_zugferd als 'upload_id' übergeben."}, 'expires_at': {'type': 'string', 'description': 'ISO-8601-Zeitpunkt, ab dem der Link verfällt.'}, 'upload_url': {'type': 'string', 'description': 'Dem Nutzer zum Öffnen im Browser geben, dort die PDF hochladen.'}, 'upload_api_url': {'type': 'string', 'description': "Direkter Upload-Endpunkt für Clients mit Netzzugriff auf finisma.de: die PDF per POST als Multipart-Feld 'file' hierher senden, dann entfällt der Browser-Schritt."}}, 'additionalProperties': False}

{'type': 'object', 'properties': {'upload_id': {'type': 'string', 'description': 'Referenz auf eine zuvor über request_upload_link hochgeladene Datei, anstelle von pdf_base64. Genau eines von beiden angeben.'}, 'pdf_base64': {'type': 'string', 'description': "Die zu prüfende PDF-Datei, Base64-kodiert (max. 25 MB). Alternativ 'upload_id' angeben. Chat-Clients, die eine angehängte Datei nicht zuverlässig als Base64 übergeben können, rufen zuerst request_upload_link auf.", 'contentEncoding': 'base64', 'contentMediaType': 'application/pdf'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['structure', 'attachments', 'authoritative'], 'properties': {'pdfa3': {'type': ['object', 'null'], 'properties': {'allOk': {'type': 'boolean'}, 'files': {'type': 'array', 'items': {'type': 'object', 'properties': {'status': {'enum': ['ok', 'warning', 'error'], 'type': 'string'}, 'message': {'type': 'string'}, 'filename': {'type': 'string'}, 'associated': {'type': 'boolean'}, 'afRelationship': {'type': ['string', 'null']}}}}, 'hasAfArray': {'type': 'boolean'}}, 'description': 'PDF/A-3-Anbindung der eingebetteten Dateien (ISO 19005-3 §6.8).'}, 'en16931': {'type': ['object', 'null'], 'properties': {'checked': {'type': 'boolean'}, 'profile': {'type': 'string'}, 'findings': {'type': 'array', 'items': {'type': 'object', 'required': ['code', 'message', 'severity', 'source'], 'properties': {'code': {'type': 'string', 'description': 'z. B. "BR-CO-25".'}, 'source': {'enum': ['schematron', 'supplementary'], 'type': 'string'}, 'message': {'type': 'string'}, 'location': {'type': 'string'}, 'severity': {'enum': ['error', 'warning'], 'type': 'string'}}}}, 'errorCount': {'type': 'integer'}, 'warningCount': {'type': 'integer'}}, 'description': 'EN-16931-Prüfung; null, wenn keine XML eingebettet war.'}, 'structure': {'type': 'object', 'properties': {'file': {'type': 'object', 'properties': {'bytes': {'type': 'integer'}, 'isPdf': {'type': 'boolean'}, 'present': {'type': 'boolean'}, 'pdfVersion': {'type': ['string', 'null']}}}, 'zugferd': {'type': 'object', 'properties': {'pdfAPart': {'type': ['string', 'null'], 'description': 'z. B. "3" für PDF/A-3.'}, 'xmlEmbedded': {'type': 'boolean'}, 'embeddedFiles': {'type': 'boolean'}, 'associatedFile': {'type': 'boolean'}, 'facturXFilename': {'type': 'boolean'}, 'facturXMetadata': {'type': 'boolean'}, 'pdfAConformance': {'type': ['string', 'null'], 'description': 'z. B. "B", "U".'}, 'xmlMatchesGenerated': {'type': ['boolean', 'null']}}}}, 'description': 'Strukturelle Prüfung der PDF (ohne die eingebettete XML).'}, 'attachments': {'type': 'array', 'items': {'type': 'object', 'properties': {'filename': {'type': 'string'}, 'mimeCode': {'type': 'string'}, 'sizeBytes': {'type': 'integer'}}}, 'description': 'Im CII referenzierte Anhänge (BT-125).'}, 'authoritative': {'type': 'object', 'required': ['available'], 'properties': {'note': {'type': 'string'}, 'engines': {'type': 'array', 'items': {'type': 'string'}}, 'profile': {'type': 'string'}, 'verdict': {'enum': ['valid', 'valid_with_warnings', 'invalid'], 'type': 'string'}, 'findings': {'type': 'array', 'items': {'type': 'object', 'required': ['code', 'severity', 'message', 'source'], 'properties': {'code': {'type': 'string'}, 'engine': {'type': 'string'}, 'source': {'type': 'string', 'description': 'xsd | schematron | pdfa | structure'}, 'message': {'type': 'string'}, 'ruleset': {'type': 'string'}, 'location': {'type': ['string', 'null']}, 'severity': {'enum': ['error', 'warning', 'info'], 'type': 'string'}}}}, 'available': {'type': 'boolean'}, 'errorCount': {'type': 'integer'}, 'warningCount': {'type': 'integer'}}, '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.'}}}