# Invoice Converter – Externe API

Version: 1.17.0 · Zuletzt aktualisiert: 2026-10-01 · Basis-URL: `https://www.invoice-converter.com/api/v1`

Wandeln Sie Rechnungsdokumente (PDF, DOCX, TXT) oder strukturierte Rechnungsdaten aus Ihrem ERP-, Abrechnungs- oder CRM-System in validierte E-Rechnungen im Format XRechnung, ZUGFeRD/Factur-X, EN 16931, UBL oder CII um.

**Basis-URL** `https://www.invoice-converter.com/api/v1` · **Authentifizierung** `Authorization: Bearer <api_key>` · **Spezifikation** OpenAPI 3.1 (dieses Dokument)

Diese Seite ist die vollständige Dokumentation: Die Leitfadenabschnitte unten erklären den Ablauf, die Abschnitte zu Endpunkten und Schemas führen jedes Feld, jeden Wert und jede Antwort auf.

## Überblick

Die API wandelt pro Anfrage eine Rechnung in eine validierte E-Rechnung um. Jede Konvertierung läuft asynchron:

1. **Konvertieren.** `POST /invoices:convert` (Dokument als PDF, DOCX oder TXT) oder `POST /invoices:convert-structured` (Ihre Rechnungsdaten plus ein Träger-PDF). Antwort: `202` mit `task_id`.
2. **Abfragen.** `GET /tasks/{task_id}`, bis `status` den Wert `completed` oder `failed` hat.
3. **Herunterladen.** `GET /tasks/{task_id}/result?download=xml|pdf`. Optional: `GET /tasks/{task_id}/validation-report?download=html|xml`.

Eine Aufgabe wird nur abgeschlossen, wenn das Artefakt die Validierung für das angeforderte Profil bestanden hat. Es gibt keine Entwurfsausgabe und keine Ausgabe mit übersteuerten Warnungen. V1 hat keine Webhooks, keinen Batch-Endpunkt und keinen Endpunkt zum Auflisten von Aufgaben.

| Endpunkt | Zweck | Ratenlimit pro API-Schlüssel |
|---|---|---|
| `POST /invoices:convert` | Dokument umwandeln | 30/min, 500/h |
| `POST /invoices:convert-structured` | Strukturierte Daten umwandeln | 30/min, 500/h |
| `GET /tasks/{task_id}` | Aufgabenstatus | 60/min, 1.500/h |
| `GET /tasks/{task_id}/result` | Artefakt herunterladen | 60/min, 1.000/h |
| `GET /tasks/{task_id}/validation-report` | Prüfbericht herunterladen | 30/min, 500/h |

## Authentifizierung und Zugang

- Header: `Authorization: Bearer <api_key>`.
- Schlüssel sind mandantenbezogene Live-Zugangsdaten mit dem Präfix `icp_...`. Sie erstellen, rotieren und widerrufen sie auf der Profilseite, solange ein Enterprise-Abonnement aktiv ist. Eine separate Freigabe ist nicht nötig.
- Bewahren Sie Schlüssel auf Ihrem Server auf. Verwenden Sie sie nie in Browser- oder Mobile-Code, in Logs oder in Tickets.
- Fehlendes Token: `401 AUTHENTICATION_REQUIRED`. Unbekannter oder widerrufener Schlüssel: `401 INVALID_API_KEY`. Gültiger Schlüssel ohne API-Zugang: `403 API_NOT_ENABLED_FOR_TENANT`. Schlüssel eines gelöschten Kontos: `410 ACCOUNT_DELETED` (die Löschung ist endgültig; nicht wiederholen).

## Schnellstart

```bash
# 1. Convert
curl -X POST 'https://www.invoice-converter.com/api/v1/invoices:convert' \
  -H 'Authorization: Bearer <api_key>' \
  -H 'Idempotency-Key: erp-inv-2026-0001' \
  -F 'file=@invoice.pdf' \
  -F 'format=XRECHNUNG' \
  -F 'client_reference=ERP-2026-0001'

# 2. Poll (first call about 20 s later)
curl 'https://www.invoice-converter.com/api/v1/tasks/<task_id>' \
  -H 'Authorization: Bearer <api_key>'

# 3. Download
curl -o invoice.xml -D headers.txt \
  'https://www.invoice-converter.com/api/v1/tasks/<task_id>/result?download=xml' \
  -H 'Authorization: Bearer <api_key>'
```

Die `202`-Antwort enthält `task_id`, `status` (`pending` oder `processing`), `status_url` und `primary_result_url`. Werten Sie `status` aus, nicht `message`. Speichern Sie `X-Correlation-ID` aus jeder Antwort; der Support benötigt den Wert. Eine abgeschlossene Statusantwort (gekürzt):

```json
{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "progress": 100,
  "created_at": "2026-09-30T08:00:00+00:00",
  "completed_at": "2026-09-30T08:01:12+00:00",
  "error": null,
  "client_reference": "ERP-2026-0001",
  "primary_result_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=xml",
  "result_artifacts": {
    "xml": { "state": "cached", "artifact_state": "compliant", "validation_state": "passed" }
  }
}
```

Bei `failed` enthält `error` eine Zusammenfassung (String oder Objekt); den typisierten Fehler liefert `/result`.

## Formate und Profile

`format` ist Pflicht und bestimmt Syntax und Container. `profile` ist optional und bestimmt das Regelwerk. Ohne `profile` gilt der Standard des Formats.

| `format` | Zulässige `profile` | Standard | `download=xml` | `download=pdf` |
|---|---|---|---|---|
| `XRECHNUNG` | `XRECHNUNG` | `XRECHNUNG` | UBL | gerendertes PDF (ohne Garantie) |
| `EN16931` | `EN16931` | `EN16931` | UBL | gerendertes PDF (ohne Garantie) |
| `UBL` | `XRECHNUNG`, `PEPPOL`, `EN16931` | `EN16931` | UBL | gerendertes PDF (ohne Garantie) |
| `CII` | `XRECHNUNG`, `EN16931`, `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `EN16931` | CII | gerendertes PDF (ohne Garantie) |
| `ZUGFERD` | `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `ZUGFERD_EN16931` | CII | hybrides ZUGFeRD/Factur-X-PDF |

- Bei `format` und `profile` spielt die Groß- und Kleinschreibung keine Rolle. Aliasse: `EXTENDED` → `ZUGFERD_FACTURX_EXTENDED`; `ZUGFERD`, `FACTURX`, `FACTUR-X`, `FACTUR_X` → `ZUGFERD_EN16931`.
- Ein Profil, das für das Format nicht aufgeführt ist: `422 OUTPUT_PROFILE_CONFLICT`. Ein unbekannter Profilname: `422 INVALID_PROFILE` mit `details.allowed_profiles`.
- Bei XML-Formaten ist `download=xml` das primäre Artefakt. Die PDF-Darstellung ist eine Zusatzleistung und kann fehlen.
- `format=ZUGFERD` benötigt eine PDF-Quelle. Ein DOCX- oder TXT-Upload wird bereits beim Upload mit `422 ZUGFERD_SOURCE_PDF_REQUIRED` abgelehnt.
- `jurisdiction` (ISO 3166-1 alpha-2), `transaction_scope` (`B2B`, `B2G`, `B2C`) und `delivery_channel` (`PEPPOL`, `DIRECT_XML`, `PORTAL`, `EMAIL_PDF`, `UNKNOWN`) sind optionale Kontexthinweise. Geben Sie bei deutschen B2G- oder Peppol-Abläufen diesen Kontext beim Upload an. Ein ungültiger Wert liefert `422 UPLOAD_FAILED`.

## Dokumentkonvertierung

`POST /invoices:convert`, `multipart/form-data`:

- `file` (Pflicht): `.pdf`, `.docx` oder `.txt`. Eine Rechnung pro Datei. Ein Dokument mit mehreren Rechnungen schlägt mit `500 TASK_FAILED`, `details.code=MULTIPLE_INVOICES_IN_DOCUMENT` fehl.
- `format` (Pflicht), `profile` und Kontextfelder wie oben.
- `client_reference` (≤ 200 Zeichen) oder der Alias `external_invoice_id` sowie `source_system` (≤ 100 Zeichen): werden in der `202`-Antwort und im Aufgabenstatus zurückgegeben.
- `use_embedded_xml` (Standard `false`): In ein PDF eingebettetes Factur-X-/ZUGFeRD-/XRechnung-XML wird ignoriert, außer dieser Wert ist `true`.
- `email_input`: optionale Freitext-Anweisungen für die Extraktion (nur PDF, ≤ 10.000 Zeichen, nicht zusammen mit `use_embedded_xml=true`).
- `use_seller_master_data` und `seller_master_data`: siehe *Verkäufer-Stammdaten*.

Die Extraktion liest das Dokument. Sie erfindet keine rechtlichen, steuerlichen, Routing-, Bank- oder Käuferreferenzdaten. Fehlen Pflichtdaten, schlägt die Aufgabe fehl, und `/result` liefert `422 VALIDATION_FAILED`.

## Strukturierte Rechnungsdaten

`POST /invoices:convert-structured` wandelt Daten aus Ihrem ERP-, Abrechnungs- oder CRM-System um (zum Beispiel Salesforce).

- `pdf_file` (Pflicht): das Träger-PDF. Bei `ZUGFERD` wird das validierte XML darin eingebettet; bei XML-Formaten wird es als Original-PDF gespeichert. **Es liefert nie Rechnungsdaten.**
- `data_file` (Pflicht, wiederholbar; Aliasse `data_files`, `data_files[]`): `.json`, `.csv`, `.xml`, `.xlsx` oder `.txt`, zusammen ≤ 2 MB.
- `format`, `profile`, Kontext-, Kundenreferenz- und Verkäufer-Stammdatenfelder wie bei der Dokumentkonvertierung. `email_input` und `use_embedded_xml` werden nicht akzeptiert.

### Deterministische und interpretierte Zuordnung

| Eingabe | Zuordnung | Ergebnis |
|---|---|---|
| **Eine** JSON-`data_file` im kanonischen Rechnungs-JSON-Format, auf oberster Ebene oder in `invoice_data` eingebettet | Deterministisch, ohne KI | Gleiche Eingabe, gleiche Ausgabe |
| CSV, XLSX, TXT, XML (auch UBL-/CII-XML), eigenes oder flaches JSON | KI-Zuordnung | Funktioniert mit eindeutigen Bezeichnungen; nicht deterministisch |
| Mehrere `data_file`-Teile (auch wenn jeder Teil kanonisches JSON ist) | KI-Zuordnung des Bündels | Wie oben |

Für eine reproduzierbare Integration senden Sie eine kanonische JSON-Datei:

- JSON Schema: <https://www.invoice-converter.com/developer-api/v1/invoice-data.schema.json>
- Beispiel (deutsche B2G-XRechnung, besteht die Prüfungen für EN 16931, XRechnung und strikte ZUGFeRD-Ausgabe): <https://www.invoice-converter.com/developer-api/v1/invoice-data.example.json>

Das Format verwendet die Elementnamen von UBL 2.1 / EN 16931. Der kanonische Pfad wird erkannt, wenn mindestens 3 der Schlüssel `ID`, `IssueDate`, `InvoiceTypeCode`, `DocumentCurrencyCode`, `AccountingSupplierParty`, `AccountingCustomerParty`, `TaxTotal`, `LegalMonetaryTotal`, `InvoiceLine` auf oberster Ebene vorhanden sind, darunter `ID`, `InvoiceLine` oder `LegalMonetaryTotal`.

Die KI-Zuordnung ist angewiesen, fehlende Felder nicht zu erfinden. Fehlende Daten führen daher zu einem Validierungsfehler, statt geraten zu werden.

**Geteilte Exporte.** Ist eine Rechnung auf mehrere Dateien verteilt (zum Beispiel Kopf und Positionen), wiederholen Sie `data_file`. Senden Sie eine Anfrage pro Rechnung.

- Jeder Teil muss dieselbe Rechnungsnummer in einer Spalte oder einem Schlüssel namens `invoice number`, `invoice no`, `invoice no.`, `invoice id`, `rechnungsnr`, `rechnungsnr.`, `rechnung nr`, `rechnung nr.`, `belegnr` oder `belegnr.` enthalten.
- Bei den Namen spielt die Groß- und Kleinschreibung keine Rolle, und `_` sowie `-` gelten als Leerzeichen. `Invoice_Number` funktioniert also. `document no` und `document number` dienen als schwächere Rückfalloption.
- camelCase-Namen wie `invoiceNumber` und Salesforce-API-Namen wie `Invoice_Number__c` werden **nicht** erkannt. Benennen Sie die Spalte um.
- Eine fehlende oder widersprüchliche Nummer liefert `400 INVALID_UPLOAD` mit `details.reason` `bundle_invoice_id_missing` oder `bundle_invoice_id_mismatch`.

### Erforderliche Daten

| Immer | Für XRechnung (auch `UBL`/`CII` mit Profil `XRECHNUNG` sowie `ZUGFERD_XRECHNUNG`) | Für strikte ZUGFeRD-Ausgabe |
|---|---|---|
| `ID`, `IssueDate`, `InvoiceTypeCode`, `DocumentCurrencyCode`, Name von Verkäufer und Käufer, Steueraufschlüsselung, Summen, mindestens eine Position | `BuyerReference` (Leitweg-ID, BR-DE-15); `PaymentMeans` (BR-DE-1); Name, Telefon und E-Mail des Ansprechpartners beim Verkäufer (BR-DE-2/5/6/7); Ort und PLZ von Verkäufer und Käufer; `EndpointID` mit `@schemeID` für Verkäufer und Käufer; Steuersatz `Percent` je Teilsumme; USt-IdNr. oder Steuernummer des Verkäufers | Ein Lieferdatum, ein Rechnungszeitraum oder Positionszeiträume; gegebenenfalls ein Lieferland |

Fehlende Daten beenden die Aufgabe mit `failed`; `/result` liefert `422 VALIDATION_FAILED` mit `details.items[]` (`field`, `rule_id`, `severity`, `source`, `suggestion`).

### Die wichtigsten JSON-Pfade

`AccountingSupplierParty.Party` wird als `Seller` abgekürzt, `AccountingCustomerParty.Party` als `Buyer`. XR = Pflicht für XRechnung.

| JSON-Pfad | EN 16931 | XR |
|---|---|---|
| `ID` | BT-1 | ja |
| `IssueDate` | BT-2 | ja |
| `InvoiceTypeCode` (zum Beispiel `380` Handelsrechnung) | BT-3 | ja |
| `DocumentCurrencyCode` | BT-5 | ja |
| `DueDate` | BT-9 | – |
| `BuyerReference` | BT-10 | ja |
| `OrderReference.ID` | BT-13 | – |
| `InvoicePeriod.StartDate` / `.EndDate` | BT-73 / BT-74 | – |
| `PaymentTerms.Note` | BT-20 | – |
| `Seller.PartyLegalEntity.RegistrationName` | BT-27 | ja |
| `Seller.PartyTaxScheme.CompanyID` (USt-IdNr.) | BT-31 | ja¹ |
| `Seller.EndpointID` (`#text`, `@schemeID`) | BT-34 | ja |
| `Seller.PostalAddress.StreetName` | BT-35 | – |
| `Seller.PostalAddress.CityName` / `.PostalZone` | BT-37 / BT-38 | ja |
| `Seller.PostalAddress.Country.IdentificationCode` | BT-40 | ja |
| `Seller.Contact.Name` / `.Telephone` / `.ElectronicMail` | BT-41 / BT-42 / BT-43 | ja |
| `Buyer.PartyLegalEntity.RegistrationName` | BT-44 | ja |
| `Buyer.EndpointID` (`#text`, `@schemeID`) | BT-49 | ja |
| `Buyer.PostalAddress.CityName` / `.PostalZone` | BT-52 / BT-53 | ja |
| `Buyer.PostalAddress.Country.IdentificationCode` | BT-55 | ja |
| `Delivery.ActualDeliveryDate` | BT-72 | – |
| `PaymentMeans.PaymentMeansCode` | BT-81 | ja |
| `PaymentMeans.PayeeFinancialAccount.ID` (IBAN) | BT-84 | bei Überweisung |
| `TaxTotal.TaxAmount` | BT-110 | ja |
| `TaxTotal.TaxSubtotal[].TaxableAmount` / `.TaxAmount` | BT-116 / BT-117 | ja |
| `TaxTotal.TaxSubtotal[].TaxCategory.ID` / `.Percent` | BT-118 / BT-119 | ja |
| `LegalMonetaryTotal.LineExtensionAmount` / `.TaxExclusiveAmount` | BT-106 / BT-109 | ja |
| `LegalMonetaryTotal.TaxInclusiveAmount` / `.PayableAmount` | BT-112 / BT-115 | ja |
| `InvoiceLine[].ID` / `.InvoicedQuantity` / `.unitCode` | BT-126 / BT-129 / BT-130 | ja |
| `InvoiceLine[].LineExtensionAmount` | BT-131 | ja |
| `InvoiceLine[].Price.PriceAmount` | BT-146 | ja |
| `InvoiceLine[].Item.Name` | BT-153 | ja |
| `InvoiceLine[].Item.ClassifiedTaxCategory.ID` / `.Percent` | BT-151 / BT-152 | ja |

¹ USt-IdNr. des Verkäufers (BT-31) oder Steuernummer (BT-32, `PartyTaxScheme` mit `TaxScheme.ID` `FC`).

## Verkäufer-Stammdaten

`seller_master_data` ist ein JSON-Objekt als String. Es gilt nur bei `use_seller_master_data=true`; fehlt das Flag, gilt die Kontovorgabe. Schlüssel: `business_name`, `trading_name`, `street`, `additional_address`, `postal_code`, `city`, `country`, `vat_id`, `tax_number`, `electronic_address`, `electronic_address_scheme`, `contact_name`, `contact_email`, `contact_phone`, `payment_means_code` (`30`, `42` oder `58`), `payment_iban`, `payment_bic`, `payment_account_name`, `payment_terms_note`. Das OpenAPI-Schema `SellerMasterData` nennt zu jedem Schlüssel den Begriff aus EN 16931.

- Jeder übergebene Wert ersetzt den extrahierten Verkäufer- oder Zahlungswert. Fehlende Schlüssel lassen die Rechnung unverändert.
- `electronic_address` und `electronic_address_scheme` bilden ein Paar: Senden Sie beide oder keinen.
- Ungültiges JSON, unbekannte Schlüssel oder ein unvollständiges Paar: `400 INVALID_SELLER_MASTER_DATA`.

## Idempotenz und Wiederholungen

- `Idempotency-Key` ist bei beiden POST-Endpunkten Pflicht. Format: 1–200 Zeichen, erstes Zeichen ein Buchstabe oder eine Ziffer, danach Buchstaben, Ziffern, `.`, `_`, `:` oder `-` (`^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$`). Ein guter Schlüssel ist Ihre Rechnungs-ID plus eine Version, zum Beispiel `sf-a0B5g00000XyZ12-v1`.
- Geltungsbereich: Mandant und Endpunkt, nicht der einzelne API-Schlüssel. Einträge werden 24 Stunden aufbewahrt.
- Verwenden Sie bei jeder Wiederholung denselben Schlüssel **und** dieselbe Payload. Eine Wiederholung liefert die ursprüngliche `202` mit `Idempotency-Replayed: true` und ohne zweite Berechnung.
- **Ein Schlüssel, eine Aufgabe.** Sobald ein Upload angenommen ist, liefert jede Wiederholung mit demselben Schlüssel und derselben Payload diese Aufgabe: dieselbe `task_id` und denselben `202`-Body. Das gilt auch, wenn Sie die erste Antwort nicht erhalten haben oder nach Annahme der Aufgabe ein `5xx` erhalten haben. Eine Wiederholung startet nie eine zweite Aufgabe und reserviert oder berechnet nie eine zweite Einheit.
- Anfragen mit demselben Schlüssel laufen nacheinander: Die anderen erhalten `409 IDEMPOTENCY_IN_PROGRESS`. Eine Wiederholung nach einer fehlgeschlagenen Aufgabe liefert diese fehlgeschlagene Aufgabe; für einen neuen Versuch verwenden Sie einen neuen Schlüssel.
- Derselbe Schlüssel mit anderer Payload: `409 IDEMPOTENCY_CONFLICT`. Die erste Anfrage läuft noch: `409 IDEMPOTENCY_IN_PROGRESS` (denselben Schlüssel später wiederholen). Die ursprüngliche Aufgabe ist bereits gelöscht: `409 IDEMPOTENCY_REPLAY_EXPIRED` (neuer Schlüssel).
- `429` oder ein `5xx` mit demselben Schlüssel zu wiederholen ist sicher: Diese Antworten sperren den Schlüssel nicht. Eine Wiederholung mit demselben Schlüssel berechnet nie doppelt: Wurde bereits eine Aufgabe angenommen, liefert sie diese Aufgabe; sonst führt sie den Upload erneut aus. Ein `5xx` allein zeigt nicht, ob eine Aufgabe angenommen wurde. Wiederholen Sie daher immer mit demselben Schlüssel.

## Limits, Abfragen und Lastspitzen

**Ratenlimits** gelten pro API-Schlüssel, mit einem Kontingent pro Endpunkt (Tabelle unter *Überblick*), in festen Zeitfenstern (Kalenderminute und Kalenderstunde). Eine abgelehnte Anfrage zählt nicht. `429 RATE_LIMITED` enthält `Retry-After`, `X-RateLimit-Limit-Minute`, `X-RateLimit-Limit-Hour` sowie `details.minute_count`, `hour_count`, `limit_minute`, `limit_hour`. Erfolgreiche Antworten enthalten keine Kontingent-Header.

**Abfragen.** Erster Statusaufruf etwa 20 s nach der `202`, dann nach 20, 30, 45 und 60 s, danach alle 60 s. Bei `completed` oder `failed` aufhören. Die meisten Konvertierungen sind innerhalb von zwei Minuten fertig. Der Server lässt eine Aufgabe nach 5 Minuten ohne Fortschritt oder nach insgesamt 15 Minuten fehlschlagen. Setzen Sie Ihr Client-Timeout daher auf etwa 16 Minuten.

**Größe.** Alle Aufrufe passieren die Web-Edge unter `www.invoice-converter.com`. Sie lehnt eine Anfrage über etwa **4,5 MB** (gesamter Multipart-Body: Dateien plus Felder) mit `413` und dem reinen Text-Body `FUNCTION_PAYLOAD_TOO_LARGE` ab, nicht mit JSON. Innerhalb dieses Limits gilt: `data_file`-Teile zusammen ≤ 2 MB, höchstens 20 Dateiteile und 50 Textfelder (`400 INVALID_UPLOAD`). Komprimieren oder teilen Sie große Scans vor dem Upload.

**Lastspitzen** (zum Beispiel Hunderte wiederkehrende Rechnungen am Monatsersten): Angenommene Aufgaben warten in einer gemeinsamen Verarbeitungswarteschlange. Ist die Warteschlange voll, liefert der Konvertierungsaufruf `503 SERVER_BUSY` mit `Retry-After: 15`. Empfohlenes Client-Muster:

1. Führen Sie eine clientseitige Warteschlange mit etwa 5–8 gleichzeitig laufenden Konvertierungen.
2. Bei `429` und `503 SERVER_BUSY` warten Sie `Retry-After` ab und wiederholen dann mit **demselben** `Idempotency-Key`.
3. Fragen Sie jede Aufgabe mit dem obigen Backoff ab. Starten Sie die nächste Konvertierung, sobald eine abgeschlossen ist.

## Fehler

Jeder JSON-Fehler hat `code`, `message`, `correlation_id` und meist `details`. Werten Sie `code` aus, bei `500 TASK_FAILED` zusätzlich `details.code` und `details.retryable`. `details.type` ist meist vorhanden, aber nicht immer. Werten Sie nie nur den HTTP-Status oder `message` aus.

Der vollständige Katalog (jeder Code mit HTTP-Status, Wiederholungsregel und Maßnahme) steht unter `ErrorEnvelope.code` in der OpenAPI-Referenz. Die häufigsten Codes:

| Code | HTTP | Wiederholen? | Maßnahme |
|---|---|---|---|
| `AUTHENTICATION_REQUIRED`, `INVALID_API_KEY` | 401 | nein | Schlüssel korrigieren. |
| `ACCOUNT_DELETED` | 410 | nein | Das Konto dieses Schlüssels wurde gelöscht. Die Löschung ist endgültig. |
| `IDEMPOTENCY_KEY_REQUIRED`, `INVALID_IDEMPOTENCY_KEY` | 400 | nein | Gültigen `Idempotency-Key` senden. |
| `FORMAT_REQUIRED` / `INVALID_FORMAT` | 400 / 422 | nein | Unterstütztes `format` senden. |
| `OUTPUT_PROFILE_CONFLICT`, `INVALID_PROFILE` | 422 | nein | Ein Profil aus der Tabelle verwenden oder das Feld weglassen. |
| `INVALID_UPLOAD` | 400 / 415 | nein | Multipart-Body, Dateityp oder Rechnungsnummern des geteilten Exports korrigieren. |
| `FUNCTION_PAYLOAD_TOO_LARGE` (reiner Text) / `PAYLOAD_TOO_LARGE` | 413 | nein | Kleinere Anfrage senden. |
| `INSUFFICIENT_API_CREDITS` | 402 | nein | Guthaben kaufen oder auf den nächsten Monat warten. |
| `IDEMPOTENCY_IN_PROGRESS` | 409 | gleicher Schlüssel | Nach kurzer Pause wiederholen. |
| `IDEMPOTENCY_CONFLICT`, `IDEMPOTENCY_REPLAY_EXPIRED` | 409 | nein | Neuen Schlüssel verwenden. |
| `RATE_LIMITED` | 429 | gleicher Schlüssel | `Retry-After` abwarten. |
| `SERVER_BUSY` | 503 | gleicher Schlüssel | Verarbeitungswarteschlange voll. `Retry-After` abwarten. |
| `UPLOAD_FAILED` | 503 / 500 | gleicher Schlüssel | Der Upload wurde nicht angenommen, oder er wurde angenommen, aber seine erste Antwort konnte nicht wiederhergestellt werden. Mit Backoff und demselben Schlüssel wiederholen. |
| `UPLOAD_FAILED` | 422 | nein | Ungültiger Wert für `jurisdiction`, `transaction_scope` oder `delivery_channel`. |
| `TASK_NOT_READY` | 202 | abfragen | Status weiter abfragen. |
| `VALIDATION_FAILED` | 422 | nein | Daten korrigieren (`details.items`), dann neu konvertieren. |
| `TASK_FAILED` | 500 | wenn `details.retryable` | `details.code` lesen. Wiederholbar: neue Konvertierung mit neuem Schlüssel. |
| `AUTHORITATIVE_VALIDATION_UNAVAILABLE` | 503 | ja | Denselben Download später wiederholen. |
| `ARTIFACT_GENERATION_RERUN_REQUIRED`, `EXTRACTION_INCOMPLETE_GROUP_FAILURE` | 503 | neue Aufgabe | Neue Konvertierung starten. |
| `INTERNAL_ARTIFACT_INVARIANT_FAILED` | 500 | nein | Mit der Correlation-ID eskalieren. |
| `TASK_NOT_FOUND` | 404 | nein | Unbekannte Aufgabe, Aufgabe eines anderen Mandanten oder nach 24 h gelöscht. |
| `PROXY_ERROR` | 502 / 504 | gleicher Schlüssel | Mit Backoff wiederholen. |

Gründe für `500 TASK_FAILED` in `details.code`: `MULTIPLE_INVOICES_IN_DOCUMENT`, `NO_INVOICE_DETECTED`, `INSUFFICIENT_INVOICE_SIGNAL`, `SCHEMA_PARSE_FAILED`, `ARTIFACT_PARITY_FAILED` (endgültig); `SOURCE_TEXT_UNAVAILABLE`, `PROVIDER_ERROR` (nach `details.retryable` richten). Eine fehlgeschlagene Aufgabe bleibt fehlgeschlagen: Ein neuer Versuch ist nur mit einer neuen Konvertierung und einem neuen Schlüssel möglich.

## Ergebnisse, Nachweise und Prüfbericht

- `/result` ist ein reiner Abruf. Er liefert `200` nur für ein gespeichertes Artefakt mit aktuellem Validierungsnachweis.
- Speichern Sie die Antwort-Header: `X-Correlation-ID`, `X-Artifact-Sha256` (Hash der gelieferten Bytes), `X-Validation-Proof-Id`, `X-Artifact-State` (`compliant`), `X-Validation-State` (`passed`).
- `/validation-report?download=html|xml` (Pflichtparameter) liefert den Bericht, der an das gelieferte Artefakt gebunden ist: den KoSIT-Bericht oder bei Factur-X ein `validation-evidence`-XML mit `source="facturx_php"`. Der Factur-X-Nachweis belegt nur die Validierung des gespeicherten XML, nicht die Quelltreue oder die PDF/A-Konformität. Auf diesem Endpunkt ist `X-Artifact-Sha256` der Hash des validierten Ergebnisartefakts, nicht des Berichts. Kein Bericht zum aktuellen Artefakt: `404 VALIDATION_REPORT_NOT_FOUND`.
- `result_artifacts.<xml|pdf>.state` im Aufgabenstatus: `cached`, `not_ready`, `validation_failed`, `dependency_failed`, `artifact_generation_rerun_required`, `artifact_invariant_failed`.

## Aufbewahrung, Abrechnung und Archivierung

- **Aufbewahrung.** Aufgaben, Artefakte und Idempotenz-Einträge werden 24 Stunden nach Abschluss der Aufgabe gelöscht. Danach liefert jeder Aufgaben-Endpunkt `404 TASK_NOT_FOUND`. Nachweise zur Qualitätssicherung folgen den Aufbewahrungsfristen in Abschnitt 9 des [Auftragsverarbeitungsvertrags](https://www.invoice-converter.com/de/dpa).
- **Abrechnung.** Jede angenommene Konvertierung verbraucht eine Einheit. Enterprise enthält 100 Einheiten pro Kalendermonat, gemeinsam mit dem E-Mail-Import. Weitere Einheiten werden aus Prepaid-Guthaben gedeckt: 100 für 50 €, 200 für 100 €, 500 für 250 €, 1.000 für 400 €. Wiederholungen mit demselben Schlüssel, fehlgeschlagene Konvertierungen und alle Aufgabenaufrufe sind kostenlos. Deckt nichts eine Einheit: `402 INSUFFICIENT_API_CREDITS` (zwei Formen von `details`, siehe die OpenAPI-Antwort `PaymentRequired`).
- **Archivierung.** Erstellen Sie Ihr Archivpaket während des Ablaufs, nicht später: Original-PDF, erzeugtes XML oder hybrides PDF, Prüfbericht und einen Metadatensatz mit `task_id`, `client_reference`, Format/Profil, `X-Artifact-Sha256`, `X-Validation-Proof-Id`, `X-Validation-Report-Proof-Id`, `created_at`/`completed_at` und den Correlation-IDs.

## Support und Vertrag

- Kontakt: `contact@invoice-converter.com`. Nennen Sie die `X-Correlation-ID`.
- Die API wird gemäß den Standard-Nutzungsbedingungen, dem AVV und einem etwaigen Enterprise-Bestellformular bereitgestellt. Es gilt kein SLA für Verfügbarkeit, Bearbeitungszeit oder Support, sofern ein Bestellformular nichts anderes regelt.
- Schlechte Quelldokumente und Sonderfälle erfordern eine Prüfung durch Menschen. Behalten Sie einen eigenen Prozess für Ausnahmen, Korrekturen, Zustellung und Archivierung bei.
- Der API-Zugang ist für Ihre eigene geschäftliche Nutzung bestimmt. Weiterverkauf, White-Label-Angebote oder die Nutzung als Dienstleister für Dritte erfordern eine Partnervereinbarung.

## Referenzdateien

- OpenAPI 3.1: <https://www.invoice-converter.com/developer-api/v1/openapi.json>
- Postman-Collection: <https://www.invoice-converter.com/developer-api/v1/postman.json> (`base_url`, `api_key`, `idempotency_key` setzen)
- JSON Schema und Beispiel für strukturierte Rechnungsdaten: siehe *Strukturierte Rechnungsdaten*
- E-Mail-Rechnungskanal: <https://www.invoice-converter.com/de/developer-api/email-invoices>
- Diese Dokumentation als Markdown (für LLMs und zum Offline-Lesen): <https://www.invoice-converter.com/de/developer-api/md>

## Endpunkte

### POST /invoices:convert — Rechnungsdokument umwandeln

Laden Sie ein Rechnungsdokument hoch und starten Sie eine strikte Konvertierung.

- `file`: `.pdf`, `.docx` oder `.txt`, eine Rechnung pro Datei. Halten Sie die gesamte Anfrage unter ~4,5 MB.
- `format` ist Pflicht; `profile` ist optional (Standard je Format siehe unten).
- In ein PDF eingebettetes XML wird ignoriert, außer bei `use_embedded_xml=true`.
- Ratenlimit: 30/min und 500/h pro API-Schlüssel.

| `format` | Zulässige `profile` | Standard | `download=xml` | `download=pdf` |
|---|---|---|---|---|
| `XRECHNUNG` | `XRECHNUNG` | `XRECHNUNG` | UBL | gerendertes PDF (ohne Garantie) |
| `EN16931` | `EN16931` | `EN16931` | UBL | gerendertes PDF (ohne Garantie) |
| `UBL` | `XRECHNUNG`, `PEPPOL`, `EN16931` | `EN16931` | UBL | gerendertes PDF (ohne Garantie) |
| `CII` | `XRECHNUNG`, `EN16931`, `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `EN16931` | CII | gerendertes PDF (ohne Garantie) |
| `ZUGFERD` | `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `ZUGFERD_EN16931` | CII | hybrides ZUGFeRD/Factur-X-PDF |

**Parameter**

| Name | Ort | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | ja | Pflicht bei beiden POST-Endpunkten. Verwenden Sie bei jeder Wiederholung denselben Schlüssel mit derselben Payload; eine Wiederholung liefert die ursprüngliche `202` ohne zweite Berechnung. Geltungsbereich: Mandant + Endpunkt, 24 h aufbewahrt. Fehlt → `400 IDEMPOTENCY_KEY_REQUIRED`; fehlerhaft → `400 INVALID_IDEMPOTENCY_KEY`; derselbe Schlüssel mit anderer Payload → `409 IDEMPOTENCY_CONFLICT`. |
| `X-Correlation-ID` | header | string (uuid) |  | Optionale UUID zur Nachverfolgung. Ein fehlender Wert oder ein Wert, der keine UUID ist, wird durch eine vom Server erzeugte UUID ersetzt. Wird im Antwort-Header `X-Correlation-ID` zurückgegeben; nennen Sie ihn dem Support. |

**Anfragekörper** (`multipart/form-data`)

| Name | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `file` | string (binary) | ja | Das Rechnungsdokument: `.pdf`, `.docx` oder `.txt`, eine Rechnung pro Datei. `.doc`, `.rtf` und Bilder werden abgelehnt (`400 INVALID_UPLOAD`). `format=ZUGFERD` benötigt ein PDF (`422 ZUGFERD_SOURCE_PDF_REQUIRED`). |
| `format` | string: `XRECHNUNG`, `ZUGFERD`, `EN16931`, `UBL`, `CII` | ja | Ausgabeformat. Pflicht; es gibt keinen Standard. Groß- und Kleinschreibung spielen keine Rolle. Fehlt → `400 FORMAT_REQUIRED`; unbekannt → `422 INVALID_FORMAT`. |
| `profile` | string: `XRECHNUNG`, `PEPPOL`, `EN16931`, `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` |  | Regelwerk, gegen das das Artefakt validiert wird. Optional: Jedes `format` hat einen Standard (siehe Tabelle der Operation). Groß- und Kleinschreibung spielen keine Rolle. Aliasse: `EXTENDED` → `ZUGFERD_FACTURX_EXTENDED`; `ZUGFERD`, `FACTURX`, `FACTUR-X`, `FACTUR_X` → `ZUGFERD_EN16931`; `ZUGFERD-XRECHNUNG` → `ZUGFERD_XRECHNUNG`. Für dieses Format nicht zulässig → `422 OUTPUT_PROFILE_CONFLICT`; unbekannter Name → `422 INVALID_PROFILE`. |
| `jurisdiction` | string |  | Land der Transaktion nach ISO 3166-1 alpha-2, zum Beispiel `DE`. Optionaler Kontext. Ungültig → `422 UPLOAD_FAILED`. |
| `transaction_scope` | string: `B2B`, `B2G`, `B2C` |  | Optionaler Kontexthinweis. Ungültig → `422 UPLOAD_FAILED`. |
| `delivery_channel` | string: `PEPPOL`, `DIRECT_XML`, `PORTAL`, `EMAIL_PDF`, `UNKNOWN` |  | Optionaler Kontexthinweis: `EMAIL_PDF` für die Zustellung als hybrides PDF, `DIRECT_XML` für die direkte XML-Integration, `PEPPOL` für die Zustellung über das Netzwerk. Ungültig → `422 UPLOAD_FAILED`. |
| `client_reference` | string |  | Ihre Rechnungs- oder Auftragsreferenz. Wird in der 202-Antwort und im Aufgabenstatus zurückgegeben. Keine Steuerzeichen. `external_invoice_id` wird als Alias akzeptiert; werden beide gesendet, müssen sie übereinstimmen, sonst `400 CLIENT_REFERENCE_CONFLICT`. |
| `source_system` | string |  | Bezeichnung des aufrufenden ERP- oder Abrechnungssystems. Wird in der 202-Antwort und im Aufgabenstatus zurückgegeben. |
| `use_embedded_xml` | boolean |  | In das PDF eingebettetes Factur-X-/ZUGFeRD-/XRechnung-XML als Quelle der Extraktion verwenden. Standard `false`: Das eingebettete XML wird ignoriert und das sichtbare Dokument gelesen. |
| `email_input` | string |  | Freitext-Anweisungen für die Extraktion in beliebiger Sprache (nur bei PDF-Quelle). Nicht kombinierbar mit `use_embedded_xml=true`. Teil der Idempotenz-Identität. Ungültig → `400 INVALID_EMAIL_INPUT`. |
| `use_seller_master_data` | boolean |  | Verkäufer-Stammdaten anwenden. Nicht angegeben: Die Kontovorgabe gilt. `false`: gespeicherte Verkäuferdaten für diese Anfrage ignorieren. `true`: gespeicherte Daten und `seller_master_data` anwenden. |
| `seller_master_data` | string |  | JSON-Objekt als String (Schema: `SellerMasterData`). Wird nur bei `use_seller_master_data=true` angewendet. Jeder übergebene Wert ersetzt den extrahierten Verkäufer- oder Zahlungswert; fehlende Schlüssel lassen die Rechnung unverändert. Ungültig → `400 INVALID_SELLER_MASTER_DATA`. |

```json
{
  "$ref": "#/components/schemas/ConvertInvoiceRequest"
}
```

**Antworten**

- `202`: Angenommen. Fragen Sie `status_url` ab. Eine Wiederholung mit demselben Idempotency-Key und derselben Payload liefert die bereits angenommene Aufgabe: dieselbe task_id und denselben 202-Body, mit dem Header Idempotency-Replayed: true. Das gilt auch, wenn die erste Antwort verloren ging oder nach Annahme der Aufgabe ein 5xx war, und auch nach einem Fehlschlag der Aufgabe. Es wird nie eine zweite Aufgabe gestartet und nie eine zweite Einheit reserviert oder berechnet.

`application/json`

```json
{
  "$ref": "#/components/schemas/ConvertAcceptedResponse"
}
```

- `400`: Ungültige Anfrage. Nicht wiederholbar: Korrigieren Sie die Anfrage. Alle 400-Codes finden Sie unter `ErrorEnvelope.code`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `401`: Authentifizierung fehlgeschlagen. Nicht wiederholbar.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `402`: `402 INSUFFICIENT_API_CREDITS`. Nicht wiederholbar: Kaufen Sie ein Prepaid-Guthabenpaket oder warten Sie auf das nächste Monatskontingent. Zwei Formen von `details`; lesen Sie die vorhandenen Schlüssel.

`application/json`

```json
{
  "oneOf": [
    {
      "$ref": "#/components/schemas/InsufficientApiCreditsPrepaidError"
    },
    {
      "$ref": "#/components/schemas/InsufficientApiCreditsAllowanceError"
    }
  ]
}
```

- `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Nicht wiederholbar: Wenden Sie sich an den Support.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `405`: `405 METHOD_NOT_ALLOWED`: Konvertierungspfade akzeptieren nur POST. Wird vom Edge-Proxy gesendet, daher enthält der Body keine `correlation_id`.

`application/json`

```json
{
  "$ref": "#/components/schemas/EdgeError"
}
```

- `409`: Idempotenzkonflikt. `IDEMPOTENCY_IN_PROGRESS`: Wiederholen Sie denselben Schlüssel nach einer kurzen Pause (eine hängende Reservierung wird nach 15 min freigegeben). `IDEMPOTENCY_CONFLICT` und `IDEMPOTENCY_REPLAY_EXPIRED`: Verwenden Sie einen neuen Schlüssel.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `410`: 410 ACCOUNT_DELETED. Der API-Schlüssel authentifiziert noch, aber sein Konto wurde gelöscht. Die Löschung ist endgültig, daher lautet die Antwort auf jedem Pfad, der sie meldet, 410 Gone. Nicht wiederholbar. Ein widerrufener Schlüssel liefert stattdessen 401 INVALID_API_KEY.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `413`: Anfrage zu groß. Nicht wiederholbar: Senden Sie eine kleinere Anfrage. - Über ~4,5 MB für die gesamte Multipart-Anfrage: Die Edge lehnt sie mit einem **reinen Text**-Body `FUNCTION_PAYLOAD_TOO_LARGE` ab (kein JSON). - Innerhalb dieses Limits: Eine Datei über 20 MB oder `data_file`-Teile über insgesamt 2 MB liefern JSON `PAYLOAD_TOO_LARGE` mit `details.limit_bytes`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

`text/plain`

```json
{
  "type": "string"
}
```

- `415`: `415 INVALID_UPLOAD`: Senden Sie `multipart/form-data`. Nicht wiederholbar.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `422`: Prüfung des Uploads oder der Anfrageoptionen fehlgeschlagen. Nicht wiederholbar: Korrigieren Sie die Anfrage. Codes: `INVALID_FORMAT`, `INVALID_PROFILE`, `OUTPUT_PROFILE_CONFLICT`, `OUTPUT_PROFILE_REQUIRED`, `UPLOAD_FAILED` (ungültiger Kontextwert), `ZUGFERD_SOURCE_PDF_REQUIRED`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `429`: `429 RATE_LIMITED`. Wiederholbar: Warten Sie `Retry-After` Sekunden und wiederholen Sie mit demselben Idempotency-Key. Die Limits gelten pro API-Schlüssel und Endpunkt in festen Zeitfenstern (Kalenderminute und Kalenderstunde). Abgelehnte Anfragen zählen nicht.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `500`: Serverseitiger Fehler. Ein 500 ist standardmäßig nicht wiederholbar. `TASK_FAILED`: Lesen Sie `details.code`; nur `details.retryable: true` erlaubt eine Wiederholung, und zwar nur als NEUE Konvertierung mit einem neuen Idempotency-Key. `INTERNAL_ARTIFACT_INVARIANT_FAILED`: eskalieren. `UPLOAD_FAILED` beim Upload: mit demselben Schlüssel wiederholen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `502`: `502 PROXY_ERROR`: Die Edge hat das Backend nicht erreicht. Mit Backoff und demselben Idempotency-Key wiederholen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `503`: Vorübergehend nicht verfügbar. Wiederholen Sie mit demselben Idempotency-Key. `SERVER_BUSY`: Die Verarbeitungswarteschlange ist voll; warten Sie `Retry-After` Sekunden. `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`, `API_CREDIT_SERVICE_UNAVAILABLE`, `UPLOAD_FAILED` (anderer Fehler bei der Annahme): mit Backoff wiederholen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `504`: `504 PROXY_ERROR`: Das Backend hat nicht rechtzeitig geantwortet. Mit Backoff und demselben Idempotency-Key wiederholen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

### POST /invoices:convert-structured — Strukturierte Rechnungsdaten umwandeln

Wandelt Rechnungsdaten aus Ihrem System um. `data_file` ist die einzige Datenquelle; `pdf_file` dient nur als Träger (bei ZUGFeRD eingebettet, sonst als Original-PDF gespeichert).

- **Deterministisch:** Eine JSON-`data_file` im Format `StructuredInvoiceData` wird ohne KI zugeordnet ([Schema](https://www.invoice-converter.com/developer-api/v1/invoice-data.schema.json), [Beispiel](https://www.invoice-converter.com/developer-api/v1/invoice-data.example.json)).
- **Interpretiert:** CSV, XLSX, TXT, XML, anderes JSON und jede Anfrage mit mehreren `data_file`-Teilen werden per KI zugeordnet; fehlende Felder bleiben leer.
- Geteilte Exporte: Wiederholen Sie `data_file`; jeder Teil benötigt dieselbe Rechnungsnummer in einer Spalte wie `Invoice Number` oder `Rechnungsnr`.
- Limits: `data_file`-Teile zusammen ≤ 2 MB, gesamte Anfrage ~4,5 MB. Ratenlimit: 30/min und 500/h pro API-Schlüssel.
- Für `format` und `profile` gelten dieselben Regeln wie bei `POST /invoices:convert`.

**Parameter**

| Name | Ort | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | ja | Pflicht bei beiden POST-Endpunkten. Verwenden Sie bei jeder Wiederholung denselben Schlüssel mit derselben Payload; eine Wiederholung liefert die ursprüngliche `202` ohne zweite Berechnung. Geltungsbereich: Mandant + Endpunkt, 24 h aufbewahrt. Fehlt → `400 IDEMPOTENCY_KEY_REQUIRED`; fehlerhaft → `400 INVALID_IDEMPOTENCY_KEY`; derselbe Schlüssel mit anderer Payload → `409 IDEMPOTENCY_CONFLICT`. |
| `X-Correlation-ID` | header | string (uuid) |  | Optionale UUID zur Nachverfolgung. Ein fehlender Wert oder ein Wert, der keine UUID ist, wird durch eine vom Server erzeugte UUID ersetzt. Wird im Antwort-Header `X-Correlation-ID` zurückgegeben; nennen Sie ihn dem Support. |

**Anfragekörper** (`multipart/form-data`)

| Name | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `pdf_file` | string (binary) | ja | Träger-PDF. Bei `ZUGFERD` wird das validierte XML darin eingebettet; bei XML-Formaten wird es als Original-PDF gespeichert. Es liefert nie Rechnungsdaten. |
| `data_file` | object | ja | Rechnungsdaten: `.json`, `.csv`, `.xml`, `.xlsx` oder `.txt` (zusammen ≤ 2 MB). Eine JSON-Datei im Format `StructuredInvoiceData` (auf oberster Ebene oder in `invoice_data` eingebettet) wird ohne KI zugeordnet; alles andere per KI. Wiederholen Sie den Teil, wenn eine Rechnung auf mehrere Dateien verteilt ist; jeder Teil muss dann dieselbe Rechnungsnummer enthalten. Schema: https://www.invoice-converter.com/developer-api/v1/invoice-data.schema.json. Die Feldnamen `data_files` und `data_files[]` werden als Aliasse akzeptiert. |
| `format` | string: `XRECHNUNG`, `ZUGFERD`, `EN16931`, `UBL`, `CII` | ja | Ausgabeformat. Pflicht; es gibt keinen Standard. Groß- und Kleinschreibung spielen keine Rolle. Fehlt → `400 FORMAT_REQUIRED`; unbekannt → `422 INVALID_FORMAT`. |
| `profile` | string: `XRECHNUNG`, `PEPPOL`, `EN16931`, `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` |  | Regelwerk, gegen das das Artefakt validiert wird. Optional: Jedes `format` hat einen Standard (siehe Tabelle der Operation). Groß- und Kleinschreibung spielen keine Rolle. Aliasse: `EXTENDED` → `ZUGFERD_FACTURX_EXTENDED`; `ZUGFERD`, `FACTURX`, `FACTUR-X`, `FACTUR_X` → `ZUGFERD_EN16931`; `ZUGFERD-XRECHNUNG` → `ZUGFERD_XRECHNUNG`. Für dieses Format nicht zulässig → `422 OUTPUT_PROFILE_CONFLICT`; unbekannter Name → `422 INVALID_PROFILE`. |
| `jurisdiction` | string |  | Land der Transaktion nach ISO 3166-1 alpha-2, zum Beispiel `DE`. Optionaler Kontext. Ungültig → `422 UPLOAD_FAILED`. |
| `transaction_scope` | string: `B2B`, `B2G`, `B2C` |  | Optionaler Kontexthinweis. Ungültig → `422 UPLOAD_FAILED`. |
| `delivery_channel` | string: `PEPPOL`, `DIRECT_XML`, `PORTAL`, `EMAIL_PDF`, `UNKNOWN` |  | Optionaler Kontexthinweis: `EMAIL_PDF` für die Zustellung als hybrides PDF, `DIRECT_XML` für die direkte XML-Integration, `PEPPOL` für die Zustellung über das Netzwerk. Ungültig → `422 UPLOAD_FAILED`. |
| `client_reference` | string |  | Ihre Rechnungs- oder Auftragsreferenz. Wird in der 202-Antwort und im Aufgabenstatus zurückgegeben. Keine Steuerzeichen. `external_invoice_id` wird als Alias akzeptiert; werden beide gesendet, müssen sie übereinstimmen, sonst `400 CLIENT_REFERENCE_CONFLICT`. |
| `source_system` | string |  | Bezeichnung des aufrufenden ERP- oder Abrechnungssystems. Wird in der 202-Antwort und im Aufgabenstatus zurückgegeben. |
| `use_seller_master_data` | boolean |  | Verkäufer-Stammdaten anwenden. Nicht angegeben: Die Kontovorgabe gilt. `false`: gespeicherte Verkäuferdaten für diese Anfrage ignorieren. `true`: gespeicherte Daten und `seller_master_data` anwenden. |
| `seller_master_data` | string |  | JSON-Objekt als String (Schema: `SellerMasterData`). Wird nur bei `use_seller_master_data=true` angewendet. Jeder übergebene Wert ersetzt den extrahierten Verkäufer- oder Zahlungswert; fehlende Schlüssel lassen die Rechnung unverändert. Ungültig → `400 INVALID_SELLER_MASTER_DATA`. |

```json
{
  "$ref": "#/components/schemas/ConvertStructuredInvoiceRequest"
}
```

**Antworten**

- `202`: Angenommen. Fragen Sie `status_url` ab. Eine Wiederholung mit demselben Idempotency-Key und derselben Payload liefert die bereits angenommene Aufgabe: dieselbe task_id und denselben 202-Body, mit dem Header Idempotency-Replayed: true. Das gilt auch, wenn die erste Antwort verloren ging oder nach Annahme der Aufgabe ein 5xx war, und auch nach einem Fehlschlag der Aufgabe. Es wird nie eine zweite Aufgabe gestartet und nie eine zweite Einheit reserviert oder berechnet.

`application/json`

```json
{
  "$ref": "#/components/schemas/ConvertAcceptedResponse"
}
```

- `400`: Ungültige Anfrage. Nicht wiederholbar: Korrigieren Sie die Anfrage. Alle 400-Codes finden Sie unter `ErrorEnvelope.code`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `401`: Authentifizierung fehlgeschlagen. Nicht wiederholbar.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `402`: `402 INSUFFICIENT_API_CREDITS`. Nicht wiederholbar: Kaufen Sie ein Prepaid-Guthabenpaket oder warten Sie auf das nächste Monatskontingent. Zwei Formen von `details`; lesen Sie die vorhandenen Schlüssel.

`application/json`

```json
{
  "oneOf": [
    {
      "$ref": "#/components/schemas/InsufficientApiCreditsPrepaidError"
    },
    {
      "$ref": "#/components/schemas/InsufficientApiCreditsAllowanceError"
    }
  ]
}
```

- `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Nicht wiederholbar: Wenden Sie sich an den Support.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `405`: `405 METHOD_NOT_ALLOWED`: Konvertierungspfade akzeptieren nur POST. Wird vom Edge-Proxy gesendet, daher enthält der Body keine `correlation_id`.

`application/json`

```json
{
  "$ref": "#/components/schemas/EdgeError"
}
```

- `409`: Idempotenzkonflikt. `IDEMPOTENCY_IN_PROGRESS`: Wiederholen Sie denselben Schlüssel nach einer kurzen Pause (eine hängende Reservierung wird nach 15 min freigegeben). `IDEMPOTENCY_CONFLICT` und `IDEMPOTENCY_REPLAY_EXPIRED`: Verwenden Sie einen neuen Schlüssel.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `410`: 410 ACCOUNT_DELETED. Der API-Schlüssel authentifiziert noch, aber sein Konto wurde gelöscht. Die Löschung ist endgültig, daher lautet die Antwort auf jedem Pfad, der sie meldet, 410 Gone. Nicht wiederholbar. Ein widerrufener Schlüssel liefert stattdessen 401 INVALID_API_KEY.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `413`: Anfrage zu groß. Nicht wiederholbar: Senden Sie eine kleinere Anfrage. - Über ~4,5 MB für die gesamte Multipart-Anfrage: Die Edge lehnt sie mit einem **reinen Text**-Body `FUNCTION_PAYLOAD_TOO_LARGE` ab (kein JSON). - Innerhalb dieses Limits: Eine Datei über 20 MB oder `data_file`-Teile über insgesamt 2 MB liefern JSON `PAYLOAD_TOO_LARGE` mit `details.limit_bytes`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

`text/plain`

```json
{
  "type": "string"
}
```

- `415`: `415 INVALID_UPLOAD`: Senden Sie `multipart/form-data`. Nicht wiederholbar.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `422`: Prüfung des Uploads oder der Anfrageoptionen fehlgeschlagen. Nicht wiederholbar: Korrigieren Sie die Anfrage. Codes: `INVALID_FORMAT`, `INVALID_PROFILE`, `OUTPUT_PROFILE_CONFLICT`, `OUTPUT_PROFILE_REQUIRED`, `UPLOAD_FAILED` (ungültiger Kontextwert), `ZUGFERD_SOURCE_PDF_REQUIRED`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `429`: `429 RATE_LIMITED`. Wiederholbar: Warten Sie `Retry-After` Sekunden und wiederholen Sie mit demselben Idempotency-Key. Die Limits gelten pro API-Schlüssel und Endpunkt in festen Zeitfenstern (Kalenderminute und Kalenderstunde). Abgelehnte Anfragen zählen nicht.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `500`: Serverseitiger Fehler. Ein 500 ist standardmäßig nicht wiederholbar. `TASK_FAILED`: Lesen Sie `details.code`; nur `details.retryable: true` erlaubt eine Wiederholung, und zwar nur als NEUE Konvertierung mit einem neuen Idempotency-Key. `INTERNAL_ARTIFACT_INVARIANT_FAILED`: eskalieren. `UPLOAD_FAILED` beim Upload: mit demselben Schlüssel wiederholen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `502`: `502 PROXY_ERROR`: Die Edge hat das Backend nicht erreicht. Mit Backoff und demselben Idempotency-Key wiederholen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `503`: Vorübergehend nicht verfügbar. Wiederholen Sie mit demselben Idempotency-Key. `SERVER_BUSY`: Die Verarbeitungswarteschlange ist voll; warten Sie `Retry-After` Sekunden. `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`, `API_CREDIT_SERVICE_UNAVAILABLE`, `UPLOAD_FAILED` (anderer Fehler bei der Annahme): mit Backoff wiederholen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `504`: `504 PROXY_ERROR`: Das Backend hat nicht rechtzeitig geantwortet. Mit Backoff und demselben Idempotency-Key wiederholen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

### GET /tasks/{task_id} — Aufgabenstatus abrufen

Liefert den Zustand der Aufgabe. Fragen Sie ab, bis `status` den Wert `completed` oder `failed` hat.

- Backoff: erster Aufruf ~20 s nach der `202`, dann nach 20, 30, 45, 60 s, danach alle 60 s. Nach ~16 min aufhören.
- `completed`: von `primary_result_url` herunterladen. `failed`: `/result` aufrufen, um den typisierten Fehler zu erhalten.
- Unbekannte Aufgabe oder mehr als 24 h nach Abschluss: `404 TASK_NOT_FOUND`.
- Ratenlimit: 60/min und 1.500/h pro API-Schlüssel.

**Parameter**

| Name | Ort | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- | --- |
| `task_id` | path | string (uuid) | ja | `task_id` aus der `202`-Antwort. Keine UUID → `400 BAD_REQUEST`. |
| `include_validation_report_html` | query | string: `true`, `false` |  | `true` fügt das bereinigte HTML des Prüfberichts als `validation_report_html` hinzu. Andere Werte als `true`/`false` → `400 INVALID_QUERY_PARAMETER`. |
| `X-Correlation-ID` | header | string (uuid) |  | Optionale UUID zur Nachverfolgung. Ein fehlender Wert oder ein Wert, der keine UUID ist, wird durch eine vom Server erzeugte UUID ersetzt. Wird im Antwort-Header `X-Correlation-ID` zurückgegeben; nennen Sie ihn dem Support. |

**Antworten**

- `200`: Aktueller Zustand der Aufgabe.

`application/json`

```json
{
  "$ref": "#/components/schemas/TaskStatusResponse"
}
```

- `400`: Ungültige Anfrage. Nicht wiederholbar: Korrigieren Sie die Anfrage. Alle 400-Codes finden Sie unter `ErrorEnvelope.code`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `401`: Authentifizierung fehlgeschlagen. Nicht wiederholbar.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Nicht wiederholbar: Wenden Sie sich an den Support.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `404`: `404 TASK_NOT_FOUND`: unbekannte Aufgabe, Aufgabe eines anderen Mandanten oder 24 h nach Abschluss gelöscht. Nicht wiederholbar.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `405`: `405 METHOD_NOT_ALLOWED`: Aufgabenpfade akzeptieren nur GET. Wird vom Edge-Proxy gesendet, daher enthält der Body keine `correlation_id`.

`application/json`

```json
{
  "$ref": "#/components/schemas/EdgeError"
}
```

- `410`: 410 ACCOUNT_DELETED. Der API-Schlüssel authentifiziert noch, aber sein Konto wurde gelöscht. Die Löschung ist endgültig, daher lautet die Antwort auf jedem Pfad, der sie meldet, 410 Gone. Nicht wiederholbar. Ein widerrufener Schlüssel liefert stattdessen 401 INVALID_API_KEY.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `429`: `429 RATE_LIMITED`. Wiederholbar: Warten Sie `Retry-After` Sekunden und wiederholen Sie mit demselben Idempotency-Key. Die Limits gelten pro API-Schlüssel und Endpunkt in festen Zeitfenstern (Kalenderminute und Kalenderstunde). Abgelehnte Anfragen zählen nicht.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `500`: Serverseitiger Fehler. Ein 500 ist standardmäßig nicht wiederholbar. `TASK_FAILED`: Lesen Sie `details.code`; nur `details.retryable: true` erlaubt eine Wiederholung, und zwar nur als NEUE Konvertierung mit einem neuen Idempotency-Key. `INTERNAL_ARTIFACT_INVARIANT_FAILED`: eskalieren. `UPLOAD_FAILED` beim Upload: mit demselben Schlüssel wiederholen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `502`: `502 PROXY_ERROR`: Die Edge hat das Backend nicht erreicht. Mit Backoff und demselben Idempotency-Key wiederholen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `503`: Vorübergehend nicht verfügbar. Mit Backoff wiederholen: `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`, `AUTHORITATIVE_VALIDATION_UNAVAILABLE`. Stattdessen eine NEUE Konvertierung starten: `ARTIFACT_GENERATION_RERUN_REQUIRED`, `EXTRACTION_INCOMPLETE_GROUP_FAILURE`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `504`: `504 PROXY_ERROR`: Das Backend hat nicht rechtzeitig geantwortet. Mit Backoff und demselben Idempotency-Key wiederholen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

### GET /tasks/{task_id}/result — Ergebnis herunterladen

Lädt das validierte Artefakt herunter. Reiner Abruf: Bei diesem Aufruf wird nichts erzeugt, repariert oder validiert.

- `download=xml`: UBL (`XRECHNUNG`, `EN16931`, `UBL`) oder CII (`CII`, `ZUGFERD`). Bei XML-Formaten immer das primäre Artefakt.
- `download=pdf`: hybrides ZUGFeRD/Factur-X-PDF bei `ZUGFERD`; bei den anderen Formaten eine Darstellung ohne Garantie.
- Während der Verarbeitung: `202 TASK_NOT_READY`. Fehlgeschlagene Aufgabe: ihr typisierter Fehler (`422 VALIDATION_FAILED`, `500 TASK_FAILED`, `503 ...`).
- Ratenlimit: 60/min und 1.000/h pro API-Schlüssel.

**Parameter**

| Name | Ort | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- | --- |
| `task_id` | path | string (uuid) | ja | `task_id` aus der `202`-Antwort. Keine UUID → `400 BAD_REQUEST`. |
| `download` | query | string: `xml`, `pdf` | ja | Herunterzuladendes Artefakt (Groß- und Kleinschreibung egal). Fehlt → `400 DOWNLOAD_FORMAT_REQUIRED`; andere Werte → `400 INVALID_DOWNLOAD_FORMAT`. |
| `X-Correlation-ID` | header | string (uuid) |  | Optionale UUID zur Nachverfolgung. Ein fehlender Wert oder ein Wert, der keine UUID ist, wird durch eine vom Server erzeugte UUID ersetzt. Wird im Antwort-Header `X-Correlation-ID` zurückgegeben; nennen Sie ihn dem Support. |

**Antworten**

- `200`: Die Bytes des Artefakts. Die `X-*`-Header beschreiben die gelieferten Bytes; speichern Sie sie für Ihr Archiv.

`application/xml`

```json
{
  "type": "string"
}
```

`application/pdf`

```json
{
  "type": "string",
  "format": "binary"
}
```

- `202`: `202 TASK_NOT_READY`: Die Verarbeitung läuft noch. Der Body ist eine Fehlerhülle, keine Datei. Fragen Sie den Aufgabenstatus weiter ab.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `400`: Ungültige Anfrage. Nicht wiederholbar: Korrigieren Sie die Anfrage. Alle 400-Codes finden Sie unter `ErrorEnvelope.code`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `401`: Authentifizierung fehlgeschlagen. Nicht wiederholbar.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Nicht wiederholbar: Wenden Sie sich an den Support.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `404`: `404 TASK_NOT_FOUND`: unbekannte Aufgabe, Aufgabe eines anderen Mandanten oder 24 h nach Abschluss gelöscht. `404 TASK_RESULT_FAILED`: Die Aufgabe existiert, aber ihre Ergebnisdaten sind nicht verfügbar; eskalieren Sie mit der Correlation-ID. Nicht wiederholbar.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `405`: `405 METHOD_NOT_ALLOWED`: Aufgabenpfade akzeptieren nur GET. Wird vom Edge-Proxy gesendet, daher enthält der Body keine `correlation_id`.

`application/json`

```json
{
  "$ref": "#/components/schemas/EdgeError"
}
```

- `410`: 410 ACCOUNT_DELETED. Der API-Schlüssel authentifiziert noch, aber sein Konto wurde gelöscht. Die Löschung ist endgültig, daher lautet die Antwort auf jedem Pfad, der sie meldet, 410 Gone. Nicht wiederholbar. Ein widerrufener Schlüssel liefert stattdessen 401 INVALID_API_KEY.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `422`: Die Rechnung kann nicht ausgestellt werden. Nicht wiederholbar: Korrigieren Sie die Daten und starten Sie eine neue Konvertierung. Codes: `VALIDATION_FAILED` (`details.items`), `PROFILE_MISMATCH`, `ZUGFERD_SOURCE_PDF_INCOMPATIBLE`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `429`: `429 RATE_LIMITED`. Wiederholbar: Warten Sie `Retry-After` Sekunden und wiederholen Sie mit demselben Idempotency-Key. Die Limits gelten pro API-Schlüssel und Endpunkt in festen Zeitfenstern (Kalenderminute und Kalenderstunde). Abgelehnte Anfragen zählen nicht.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `500`: Serverseitiger Fehler. Ein 500 ist standardmäßig nicht wiederholbar. `TASK_FAILED`: Lesen Sie `details.code`; nur `details.retryable: true` erlaubt eine Wiederholung, und zwar nur als NEUE Konvertierung mit einem neuen Idempotency-Key. `INTERNAL_ARTIFACT_INVARIANT_FAILED`: eskalieren. `UPLOAD_FAILED` beim Upload: mit demselben Schlüssel wiederholen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `502`: `502 PROXY_ERROR`: Die Edge hat das Backend nicht erreicht. Mit Backoff und demselben Idempotency-Key wiederholen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `503`: Vorübergehend nicht verfügbar. Mit Backoff wiederholen: `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`, `AUTHORITATIVE_VALIDATION_UNAVAILABLE`. Stattdessen eine NEUE Konvertierung starten: `ARTIFACT_GENERATION_RERUN_REQUIRED`, `EXTRACTION_INCOMPLETE_GROUP_FAILURE`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `504`: `504 PROXY_ERROR`: Das Backend hat nicht rechtzeitig geantwortet. Mit Backoff und demselben Idempotency-Key wiederholen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

### GET /tasks/{task_id}/validation-report — Prüfbericht herunterladen

Lädt den Prüfbericht herunter, der an das gelieferte Artefakt gebunden ist.

- `download=html` für Menschen; `download=xml` für den KoSIT-Bericht oder das Factur-X-XML `validation-evidence` (`source="facturx_php"`, nicht im KoSIT-Format).
- Die `X-Artifact-*`-Header beschreiben das validierte Ergebnisartefakt, nicht die Bytes des Berichts.
- Der Factur-X-Nachweis belegt nur die Validierung des gespeicherten XML, nicht die Quelltreue oder die PDF/A-Konformität.
- Ratenlimit: 30/min und 500/h pro API-Schlüssel.

**Parameter**

| Name | Ort | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- | --- |
| `task_id` | path | string (uuid) | ja | `task_id` aus der `202`-Antwort. Keine UUID → `400 BAD_REQUEST`. |
| `download` | query | string: `html`, `xml` | ja | `html` für einen lesbaren Bericht, `xml` für den maschinenlesbaren Bericht. Fehlt → `400 DOWNLOAD_FORMAT_REQUIRED`; andere Werte → `400 INVALID_DOWNLOAD_FORMAT`. |
| `X-Correlation-ID` | header | string (uuid) |  | Optionale UUID zur Nachverfolgung. Ein fehlender Wert oder ein Wert, der keine UUID ist, wird durch eine vom Server erzeugte UUID ersetzt. Wird im Antwort-Header `X-Correlation-ID` zurückgegeben; nennen Sie ihn dem Support. |

**Antworten**

- `200`: Der Bericht.

`text/html`

```json
{
  "type": "string"
}
```

`application/xml`

```json
{
  "type": "string"
}
```

- `202`: `202 TASK_NOT_READY`: Die Verarbeitung läuft noch. Der Body ist eine Fehlerhülle, keine Datei. Fragen Sie den Aufgabenstatus weiter ab.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `400`: Ungültige Anfrage. Nicht wiederholbar: Korrigieren Sie die Anfrage. Alle 400-Codes finden Sie unter `ErrorEnvelope.code`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `401`: Authentifizierung fehlgeschlagen. Nicht wiederholbar.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Nicht wiederholbar: Wenden Sie sich an den Support.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `404`: `404 TASK_NOT_FOUND` (unbekannte oder abgelaufene Aufgabe) oder `404 VALIDATION_REPORT_NOT_FOUND` (kein Bericht an das aktuelle Artefakt gebunden; `details.reason`). Nicht wiederholbar.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `405`: `405 METHOD_NOT_ALLOWED`: Aufgabenpfade akzeptieren nur GET. Wird vom Edge-Proxy gesendet, daher enthält der Body keine `correlation_id`.

`application/json`

```json
{
  "$ref": "#/components/schemas/EdgeError"
}
```

- `410`: 410 ACCOUNT_DELETED. Der API-Schlüssel authentifiziert noch, aber sein Konto wurde gelöscht. Die Löschung ist endgültig, daher lautet die Antwort auf jedem Pfad, der sie meldet, 410 Gone. Nicht wiederholbar. Ein widerrufener Schlüssel liefert stattdessen 401 INVALID_API_KEY.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `422`: Die Rechnung kann nicht ausgestellt werden. Nicht wiederholbar: Korrigieren Sie die Daten und starten Sie eine neue Konvertierung. Codes: `VALIDATION_FAILED` (`details.items`), `PROFILE_MISMATCH`, `ZUGFERD_SOURCE_PDF_INCOMPATIBLE`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `429`: `429 RATE_LIMITED`. Wiederholbar: Warten Sie `Retry-After` Sekunden und wiederholen Sie mit demselben Idempotency-Key. Die Limits gelten pro API-Schlüssel und Endpunkt in festen Zeitfenstern (Kalenderminute und Kalenderstunde). Abgelehnte Anfragen zählen nicht.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `500`: Serverseitiger Fehler. Ein 500 ist standardmäßig nicht wiederholbar. `TASK_FAILED`: Lesen Sie `details.code`; nur `details.retryable: true` erlaubt eine Wiederholung, und zwar nur als NEUE Konvertierung mit einem neuen Idempotency-Key. `INTERNAL_ARTIFACT_INVARIANT_FAILED`: eskalieren. `UPLOAD_FAILED` beim Upload: mit demselben Schlüssel wiederholen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `502`: `502 PROXY_ERROR`: Die Edge hat das Backend nicht erreicht. Mit Backoff und demselben Idempotency-Key wiederholen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `503`: Vorübergehend nicht verfügbar. Mit Backoff wiederholen: `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`, `AUTHORITATIVE_VALIDATION_UNAVAILABLE`. Stattdessen eine NEUE Konvertierung starten: `ARTIFACT_GENERATION_RERUN_REQUIRED`, `EXTRACTION_INCOMPLETE_GROUP_FAILURE`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `504`: `504 PROXY_ERROR`: Das Backend hat nicht rechtzeitig geantwortet. Mit Backoff und demselben Idempotency-Key wiederholen.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

## Schemata

### `ConvertInvoiceRequest`

```json
{
  "type": "object",
  "required": [
    "file",
    "format"
  ],
  "properties": {
    "file": {
      "type": "string",
      "format": "binary",
      "description": "Das Rechnungsdokument: `.pdf`, `.docx` oder `.txt`, eine Rechnung pro Datei. `.doc`, `.rtf` und Bilder werden abgelehnt (`400 INVALID_UPLOAD`). `format=ZUGFERD` benötigt ein PDF (`422 ZUGFERD_SOURCE_PDF_REQUIRED`)."
    },
    "format": {
      "type": "string",
      "enum": [
        "XRECHNUNG",
        "ZUGFERD",
        "EN16931",
        "UBL",
        "CII"
      ],
      "description": "Ausgabeformat. Pflicht; es gibt keinen Standard. Groß- und Kleinschreibung spielen keine Rolle. Fehlt → `400 FORMAT_REQUIRED`; unbekannt → `422 INVALID_FORMAT`.",
      "examples": [
        "XRECHNUNG"
      ]
    },
    "profile": {
      "type": "string",
      "enum": [
        "XRECHNUNG",
        "PEPPOL",
        "EN16931",
        "ZUGFERD_EN16931",
        "ZUGFERD_FACTURX_EXTENDED",
        "ZUGFERD_XRECHNUNG"
      ],
      "description": "Regelwerk, gegen das das Artefakt validiert wird. Optional: Jedes `format` hat einen Standard (siehe Tabelle der Operation). Groß- und Kleinschreibung spielen keine Rolle. Aliasse: `EXTENDED` → `ZUGFERD_FACTURX_EXTENDED`; `ZUGFERD`, `FACTURX`, `FACTUR-X`, `FACTUR_X` → `ZUGFERD_EN16931`; `ZUGFERD-XRECHNUNG` → `ZUGFERD_XRECHNUNG`. Für dieses Format nicht zulässig → `422 OUTPUT_PROFILE_CONFLICT`; unbekannter Name → `422 INVALID_PROFILE`.",
      "examples": [
        "XRECHNUNG"
      ]
    },
    "jurisdiction": {
      "type": "string",
      "description": "Land der Transaktion nach ISO 3166-1 alpha-2, zum Beispiel `DE`. Optionaler Kontext. Ungültig → `422 UPLOAD_FAILED`.",
      "examples": [
        "DE"
      ]
    },
    "transaction_scope": {
      "type": "string",
      "enum": [
        "B2B",
        "B2G",
        "B2C"
      ],
      "description": "Optionaler Kontexthinweis. Ungültig → `422 UPLOAD_FAILED`."
    },
    "delivery_channel": {
      "type": "string",
      "enum": [
        "PEPPOL",
        "DIRECT_XML",
        "PORTAL",
        "EMAIL_PDF",
        "UNKNOWN"
      ],
      "description": "Optionaler Kontexthinweis: `EMAIL_PDF` für die Zustellung als hybrides PDF, `DIRECT_XML` für die direkte XML-Integration, `PEPPOL` für die Zustellung über das Netzwerk. Ungültig → `422 UPLOAD_FAILED`."
    },
    "client_reference": {
      "type": "string",
      "maxLength": 200,
      "description": "Ihre Rechnungs- oder Auftragsreferenz. Wird in der 202-Antwort und im Aufgabenstatus zurückgegeben. Keine Steuerzeichen. `external_invoice_id` wird als Alias akzeptiert; werden beide gesendet, müssen sie übereinstimmen, sonst `400 CLIENT_REFERENCE_CONFLICT`.",
      "examples": [
        "ERP-2026-0001"
      ]
    },
    "source_system": {
      "type": "string",
      "maxLength": 100,
      "description": "Bezeichnung des aufrufenden ERP- oder Abrechnungssystems. Wird in der 202-Antwort und im Aufgabenstatus zurückgegeben.",
      "examples": [
        "salesforce"
      ]
    },
    "use_embedded_xml": {
      "type": "boolean",
      "default": false,
      "description": "In das PDF eingebettetes Factur-X-/ZUGFeRD-/XRechnung-XML als Quelle der Extraktion verwenden. Standard `false`: Das eingebettete XML wird ignoriert und das sichtbare Dokument gelesen."
    },
    "email_input": {
      "type": "string",
      "maxLength": 10000,
      "description": "Freitext-Anweisungen für die Extraktion in beliebiger Sprache (nur bei PDF-Quelle). Nicht kombinierbar mit `use_embedded_xml=true`. Teil der Idempotenz-Identität. Ungültig → `400 INVALID_EMAIL_INPUT`.",
      "examples": [
        "Use purchase order number PO-42."
      ]
    },
    "use_seller_master_data": {
      "type": "boolean",
      "description": "Verkäufer-Stammdaten anwenden. Nicht angegeben: Die Kontovorgabe gilt. `false`: gespeicherte Verkäuferdaten für diese Anfrage ignorieren. `true`: gespeicherte Daten und `seller_master_data` anwenden."
    },
    "seller_master_data": {
      "type": "string",
      "contentMediaType": "application/json",
      "contentSchema": {
        "$ref": "#/components/schemas/SellerMasterData"
      },
      "description": "JSON-Objekt als String (Schema: `SellerMasterData`). Wird nur bei `use_seller_master_data=true` angewendet. Jeder übergebene Wert ersetzt den extrahierten Verkäufer- oder Zahlungswert; fehlende Schlüssel lassen die Rechnung unverändert. Ungültig → `400 INVALID_SELLER_MASTER_DATA`.",
      "examples": [
        "{\"business_name\":\"Seller GmbH\",\"vat_id\":\"DE123456789\",\"city\":\"Berlin\",\"country\":\"DE\"}"
      ]
    }
  },
  "additionalProperties": false
}
```

### `ConvertStructuredInvoiceRequest`

```json
{
  "type": "object",
  "required": [
    "pdf_file",
    "data_file",
    "format"
  ],
  "properties": {
    "pdf_file": {
      "type": "string",
      "format": "binary",
      "description": "Träger-PDF. Bei `ZUGFERD` wird das validierte XML darin eingebettet; bei XML-Formaten wird es als Original-PDF gespeichert. Es liefert nie Rechnungsdaten."
    },
    "data_file": {
      "oneOf": [
        {
          "type": "string",
          "format": "binary"
        },
        {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "string",
            "format": "binary"
          }
        }
      ],
      "description": "Rechnungsdaten: `.json`, `.csv`, `.xml`, `.xlsx` oder `.txt` (zusammen ≤ 2 MB). Eine JSON-Datei im Format `StructuredInvoiceData` (auf oberster Ebene oder in `invoice_data` eingebettet) wird ohne KI zugeordnet; alles andere per KI. Wiederholen Sie den Teil, wenn eine Rechnung auf mehrere Dateien verteilt ist; jeder Teil muss dann dieselbe Rechnungsnummer enthalten. Schema: https://www.invoice-converter.com/developer-api/v1/invoice-data.schema.json. Die Feldnamen `data_files` und `data_files[]` werden als Aliasse akzeptiert."
    },
    "format": {
      "type": "string",
      "enum": [
        "XRECHNUNG",
        "ZUGFERD",
        "EN16931",
        "UBL",
        "CII"
      ],
      "description": "Ausgabeformat. Pflicht; es gibt keinen Standard. Groß- und Kleinschreibung spielen keine Rolle. Fehlt → `400 FORMAT_REQUIRED`; unbekannt → `422 INVALID_FORMAT`.",
      "examples": [
        "XRECHNUNG"
      ]
    },
    "profile": {
      "type": "string",
      "enum": [
        "XRECHNUNG",
        "PEPPOL",
        "EN16931",
        "ZUGFERD_EN16931",
        "ZUGFERD_FACTURX_EXTENDED",
        "ZUGFERD_XRECHNUNG"
      ],
      "description": "Regelwerk, gegen das das Artefakt validiert wird. Optional: Jedes `format` hat einen Standard (siehe Tabelle der Operation). Groß- und Kleinschreibung spielen keine Rolle. Aliasse: `EXTENDED` → `ZUGFERD_FACTURX_EXTENDED`; `ZUGFERD`, `FACTURX`, `FACTUR-X`, `FACTUR_X` → `ZUGFERD_EN16931`; `ZUGFERD-XRECHNUNG` → `ZUGFERD_XRECHNUNG`. Für dieses Format nicht zulässig → `422 OUTPUT_PROFILE_CONFLICT`; unbekannter Name → `422 INVALID_PROFILE`.",
      "examples": [
        "XRECHNUNG"
      ]
    },
    "jurisdiction": {
      "type": "string",
      "description": "Land der Transaktion nach ISO 3166-1 alpha-2, zum Beispiel `DE`. Optionaler Kontext. Ungültig → `422 UPLOAD_FAILED`.",
      "examples": [
        "DE"
      ]
    },
    "transaction_scope": {
      "type": "string",
      "enum": [
        "B2B",
        "B2G",
        "B2C"
      ],
      "description": "Optionaler Kontexthinweis. Ungültig → `422 UPLOAD_FAILED`."
    },
    "delivery_channel": {
      "type": "string",
      "enum": [
        "PEPPOL",
        "DIRECT_XML",
        "PORTAL",
        "EMAIL_PDF",
        "UNKNOWN"
      ],
      "description": "Optionaler Kontexthinweis: `EMAIL_PDF` für die Zustellung als hybrides PDF, `DIRECT_XML` für die direkte XML-Integration, `PEPPOL` für die Zustellung über das Netzwerk. Ungültig → `422 UPLOAD_FAILED`."
    },
    "client_reference": {
      "type": "string",
      "maxLength": 200,
      "description": "Ihre Rechnungs- oder Auftragsreferenz. Wird in der 202-Antwort und im Aufgabenstatus zurückgegeben. Keine Steuerzeichen. `external_invoice_id` wird als Alias akzeptiert; werden beide gesendet, müssen sie übereinstimmen, sonst `400 CLIENT_REFERENCE_CONFLICT`.",
      "examples": [
        "ERP-2026-0001"
      ]
    },
    "source_system": {
      "type": "string",
      "maxLength": 100,
      "description": "Bezeichnung des aufrufenden ERP- oder Abrechnungssystems. Wird in der 202-Antwort und im Aufgabenstatus zurückgegeben.",
      "examples": [
        "salesforce"
      ]
    },
    "use_seller_master_data": {
      "type": "boolean",
      "description": "Verkäufer-Stammdaten anwenden. Nicht angegeben: Die Kontovorgabe gilt. `false`: gespeicherte Verkäuferdaten für diese Anfrage ignorieren. `true`: gespeicherte Daten und `seller_master_data` anwenden."
    },
    "seller_master_data": {
      "type": "string",
      "contentMediaType": "application/json",
      "contentSchema": {
        "$ref": "#/components/schemas/SellerMasterData"
      },
      "description": "JSON-Objekt als String (Schema: `SellerMasterData`). Wird nur bei `use_seller_master_data=true` angewendet. Jeder übergebene Wert ersetzt den extrahierten Verkäufer- oder Zahlungswert; fehlende Schlüssel lassen die Rechnung unverändert. Ungültig → `400 INVALID_SELLER_MASTER_DATA`.",
      "examples": [
        "{\"business_name\":\"Seller GmbH\",\"vat_id\":\"DE123456789\",\"city\":\"Berlin\",\"country\":\"DE\"}"
      ]
    }
  },
  "additionalProperties": false
}
```

### `StructuredInvoiceData`

```json
{
  "additionalProperties": false,
  "properties": {
    "CustomizationID": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Customizationid"
    },
    "ProfileID": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Profileid"
    },
    "ID": {
      "title": "Id",
      "type": "string"
    },
    "IssueDate": {
      "title": "Issuedate",
      "type": "string"
    },
    "DueDate": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Duedate"
    },
    "TaxCurrencyCode": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Taxcurrencycode"
    },
    "TaxPointDate": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Taxpointdate"
    },
    "InvoicePeriod": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_InvoicePeriod"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "InvoiceTypeCode": {
      "title": "Invoicetypecode",
      "type": "string"
    },
    "DocumentCurrencyCode": {
      "title": "Documentcurrencycode",
      "type": "string"
    },
    "OrderReference": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_OrderReference"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "SalesOrderReference": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_SalesOrderReference"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "ContractDocumentReference": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_ContractDocumentReference"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "ProjectReference": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_ProjectReference"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "TenderOrLotReference": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_TenderOrLotReference"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "DespatchDocumentReference": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_DespatchDocumentReference"
        },
        {
          "items": {
            "$ref": "#/components/schemas/StructuredInvoice_DespatchDocumentReference"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Despatchdocumentreference"
    },
    "PrecedingInvoiceReference": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/components/schemas/StructuredInvoice_PrecedingInvoiceReference"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Precedinginvoicereference"
    },
    "AdditionalDocumentReference": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/components/schemas/StructuredInvoice_AdditionalDocumentReference"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Additionaldocumentreference"
    },
    "AllowanceCharge": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/components/schemas/StructuredInvoice_AllowanceCharge"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Allowancecharge"
    },
    "AccountingSupplierParty": {
      "$ref": "#/components/schemas/StructuredInvoice_AccountingSupplierParty"
    },
    "AccountingCustomerParty": {
      "$ref": "#/components/schemas/StructuredInvoice_AccountingCustomerParty"
    },
    "PayeeParty": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_PayeeParty"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "TaxRepresentativeParty": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_TaxRepresentativeParty"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "Delivery": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_Delivery"
        },
        {
          "items": {
            "$ref": "#/components/schemas/StructuredInvoice_Delivery"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Delivery"
    },
    "DeliveryTerms": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_DeliveryTerms"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "PaymentMeans": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_PaymentMeans"
        },
        {
          "items": {
            "$ref": "#/components/schemas/StructuredInvoice_PaymentMeans"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Paymentmeans"
    },
    "PaymentTerms": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_PaymentTerms"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "TaxTotal": {
      "$ref": "#/components/schemas/StructuredInvoice_TaxTotal"
    },
    "LegalMonetaryTotal": {
      "$ref": "#/components/schemas/StructuredInvoice_LegalMonetaryTotal"
    },
    "InvoiceLine": {
      "items": {
        "$ref": "#/components/schemas/StructuredInvoice_InvoiceLine"
      },
      "title": "Invoiceline",
      "type": "array"
    },
    "Note": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Note"
    },
    "BuyerReference": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Buyerreference"
    },
    "BuyerAccountingReference": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Buyeraccountingreference"
    }
  },
  "required": [
    "ID",
    "IssueDate",
    "InvoiceTypeCode",
    "DocumentCurrencyCode",
    "AccountingSupplierParty",
    "AccountingCustomerParty",
    "TaxTotal",
    "LegalMonetaryTotal",
    "InvoiceLine"
  ],
  "title": "Invoice Converter structured invoice JSON",
  "type": "object",
  "description": "Kanonisches Rechnungs-JSON für POST /api/v1/invoices:convert-structured. Die Elementnamen folgen UBL 2.1 / EN 16931. Senden Sie eine Rechnung als eine JSON-data_file, entweder auf oberster Ebene oder in einem Objekt 'invoice_data' eingebettet; dieses Format wird ohne KI-Interpretation zugeordnet. Für die Erkennung sind mindestens 3 der Schlüssel ID, IssueDate, InvoiceTypeCode, DocumentCurrencyCode, AccountingSupplierParty, AccountingCustomerParty, TaxTotal, LegalMonetaryTotal, InvoiceLine auf oberster Ebene nötig, darunter ID, InvoiceLine oder LegalMonetaryTotal. Download: https://www.invoice-converter.com/developer-api/v1/invoice-data.schema.json",
  "examples": [
    {
      "ID": "RE-2026-00123",
      "IssueDate": "2026-09-30",
      "DueDate": "2026-10-30",
      "InvoiceTypeCode": "380",
      "DocumentCurrencyCode": "EUR",
      "BuyerReference": "04011000-1234512345-06",
      "OrderReference": {
        "ID": "PO-4711"
      },
      "InvoicePeriod": {
        "StartDate": "2026-09-01",
        "EndDate": "2026-09-30"
      },
      "Note": "Monthly subscription September 2026",
      "AccountingSupplierParty": {
        "Party": {
          "EndpointID": {
            "#text": "billing@seller.example",
            "@schemeID": "EM"
          },
          "PartyName": {
            "Name": "Seller GmbH"
          },
          "PostalAddress": {
            "StreetName": "Hauptstraße 1",
            "CityName": "Berlin",
            "PostalZone": "10115",
            "Country": {
              "IdentificationCode": "DE"
            }
          },
          "PartyTaxScheme": {
            "CompanyID": "DE123456789",
            "TaxScheme": {
              "ID": "VAT"
            }
          },
          "PartyLegalEntity": {
            "RegistrationName": "Seller GmbH",
            "CompanyID": "HRB 12345"
          },
          "Contact": {
            "Name": "Erika Muster",
            "Telephone": "+49 30 123456",
            "ElectronicMail": "erika@seller.example"
          }
        }
      },
      "AccountingCustomerParty": {
        "Party": {
          "EndpointID": {
            "#text": "04011000-1234512345-06",
            "@schemeID": "0204"
          },
          "PartyName": {
            "Name": "Buyer AG"
          },
          "PostalAddress": {
            "StreetName": "Marktplatz 5",
            "CityName": "München",
            "PostalZone": "80331",
            "Country": {
              "IdentificationCode": "DE"
            }
          },
          "PartyTaxScheme": {
            "CompanyID": "DE987654321",
            "TaxScheme": {
              "ID": "VAT"
            }
          },
          "PartyLegalEntity": {
            "RegistrationName": "Buyer AG"
          }
        }
      },
      "Delivery": {
        "ActualDeliveryDate": "2026-09-30",
        "DeliveryLocation": {
          "Address": {
            "StreetName": "Marktplatz 5",
            "CityName": "München",
            "PostalZone": "80331",
            "Country": {
              "IdentificationCode": "DE"
            }
          }
        }
      },
      "PaymentMeans": {
        "PaymentMeansCode": "58",
        "PaymentID": "RE-2026-00123",
        "PayeeFinancialAccount": {
          "ID": "DE02120300000000202051",
          "Name": "Seller GmbH",
          "FinancialInstitutionBranch": {
            "ID": "BYLADEM1001"
          }
        }
      },
      "PaymentTerms": {
        "Note": "Zahlbar innerhalb von 30 Tagen ohne Abzug",
        "NetDays": 30
      },
      "TaxTotal": {
        "TaxAmount": "285.00",
        "TaxSubtotal": [
          {
            "TaxableAmount": "1500.00",
            "TaxAmount": "285.00",
            "TaxCategory": {
              "ID": "S",
              "Percent": 19,
              "TaxScheme": {
                "ID": "VAT"
              }
            }
          }
        ]
      },
      "LegalMonetaryTotal": {
        "LineExtensionAmount": "1500.00",
        "TaxExclusiveAmount": "1500.00",
        "TaxInclusiveAmount": "1785.00",
        "PayableAmount": "1785.00"
      },
      "InvoiceLine": [
        {
          "ID": "1",
          "InvoicedQuantity": 10,
          "unitCode": "HUR",
          "LineExtensionAmount": "1200.00",
          "Item": {
            "Name": "Consulting",
            "SellersItemIdentification": {
              "ID": "SRV-01"
            },
            "ClassifiedTaxCategory": {
              "ID": "S",
              "Percent": 19,
              "TaxScheme": {
                "ID": "VAT"
              }
            }
          },
          "Price": {
            "PriceAmount": "120.00"
          }
        },
        {
          "ID": "2",
          "InvoicedQuantity": 2,
          "unitCode": "C62",
          "LineExtensionAmount": "300.00",
          "Item": {
            "Name": "Software licence",
            "ClassifiedTaxCategory": {
              "ID": "S",
              "Percent": 19,
              "TaxScheme": {
                "ID": "VAT"
              }
            }
          },
          "Price": {
            "PriceAmount": "150.00"
          }
        }
      ]
    }
  ]
}
```

### `SellerMasterData`

```json
{
  "type": "object",
  "description": "Verkäufer-Vorgaben, gesendet als JSON-String im Formularfeld `seller_master_data`. Jeder Schlüssel ist optional. `electronic_address` und `electronic_address_scheme` bilden ein Paar: Senden Sie beide oder keinen.",
  "properties": {
    "business_name": {
      "type": "string",
      "maxLength": 240,
      "description": "Rechtlicher Name (BT-27)."
    },
    "trading_name": {
      "type": "string",
      "maxLength": 240,
      "description": "Handelsname (BT-28)."
    },
    "street": {
      "type": "string",
      "description": "Straße und Hausnummer (BT-35)."
    },
    "additional_address": {
      "type": "string",
      "description": "Zusätzliche Adresszeile (BT-36)."
    },
    "postal_code": {
      "type": "string",
      "description": "Postleitzahl (BT-38)."
    },
    "city": {
      "type": "string",
      "description": "Ort (BT-37)."
    },
    "country": {
      "type": "string",
      "description": "Ländercode nach ISO 3166-1 alpha-2 (BT-40).",
      "examples": [
        "DE"
      ]
    },
    "vat_id": {
      "type": "string",
      "description": "Umsatzsteuer-Identifikationsnummer (BT-31).",
      "examples": [
        "DE123456789"
      ]
    },
    "tax_number": {
      "type": "string",
      "description": "Steuernummer (BT-32)."
    },
    "electronic_address": {
      "type": "string",
      "description": "Elektronische Adresse (BT-34). Erfordert `electronic_address_scheme`."
    },
    "electronic_address_scheme": {
      "type": "string",
      "description": "EAS-Schema der elektronischen Adresse, zum Beispiel `EM` oder `0204`."
    },
    "contact_name": {
      "type": "string",
      "description": "Ansprechpartner (BT-41)."
    },
    "contact_email": {
      "type": "string",
      "description": "E-Mail des Ansprechpartners (BT-43)."
    },
    "contact_phone": {
      "type": "string",
      "description": "Telefon des Ansprechpartners (BT-42)."
    },
    "payment_means_code": {
      "type": "string",
      "enum": [
        "30",
        "42",
        "58"
      ],
      "description": "Code der Zahlungsart für Überweisungen (BT-81): 30 Überweisung, 42 Zahlung auf Bankkonto, 58 SEPA-Überweisung."
    },
    "payment_iban": {
      "type": "string",
      "description": "IBAN des Empfängerkontos (BT-84)."
    },
    "payment_bic": {
      "type": "string",
      "description": "BIC der Bank des Zahlungsempfängers (BT-86)."
    },
    "payment_account_name": {
      "type": "string",
      "description": "Name des Empfängerkontos (BT-85)."
    },
    "payment_terms_note": {
      "type": "string",
      "description": "Zahlungsbedingungen als Text (BT-20)."
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "business_name": "Seller GmbH",
      "street": "Hauptstraße 1",
      "postal_code": "10115",
      "city": "Berlin",
      "country": "DE",
      "vat_id": "DE123456789",
      "electronic_address": "billing@seller.example",
      "electronic_address_scheme": "EM",
      "contact_name": "Erika Muster",
      "contact_email": "erika@seller.example",
      "contact_phone": "+49 30 123456",
      "payment_means_code": "58",
      "payment_iban": "DE02120300000000202051"
    }
  ]
}
```

### `ConvertAcceptedResponse`

```json
{
  "type": "object",
  "required": [
    "task_id",
    "status",
    "correlation_id"
  ],
  "properties": {
    "task_id": {
      "type": "string",
      "format": "uuid",
      "description": "Verwenden Sie sie für alle Aufgabenaufrufe."
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "processing"
      ],
      "description": "`pending`: in der Warteschlange. `processing`: gestartet."
    },
    "message": {
      "type": "string",
      "description": "Lesbare Bestätigung. Treffen Sie keine Entscheidungen anhand dieses Werts."
    },
    "filename": {
      "type": [
        "string",
        "null"
      ],
      "description": "Dateiname des hochgeladenen Dokuments (oder des Träger-PDFs)."
    },
    "pdf_filename": {
      "type": [
        "string",
        "null"
      ],
      "description": "Dateiname des Träger-PDFs (strukturierter Endpunkt)."
    },
    "data_filename": {
      "type": [
        "string",
        "null"
      ],
      "description": "Name der ersten Datendatei (strukturierter Endpunkt)."
    },
    "data_filenames": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Namen aller Datendateien (strukturierter Endpunkt)."
    },
    "data_file_count": {
      "type": "integer",
      "minimum": 1,
      "description": "Anzahl der Datendateien (strukturierter Endpunkt)."
    },
    "file_size": {
      "type": "integer",
      "minimum": 0,
      "description": "Insgesamt angenommene Bytes."
    },
    "pdf_file_size": {
      "type": "integer",
      "minimum": 0,
      "description": "Bytes des Träger-PDFs (strukturierter Endpunkt)."
    },
    "data_file_size": {
      "type": "integer",
      "minimum": 0,
      "description": "Bytes aller Datendateien zusammen (strukturierter Endpunkt)."
    },
    "correlation_id": {
      "type": "string",
      "format": "uuid"
    },
    "status_url": {
      "type": "string",
      "description": "Relative URL für die Abfrage."
    },
    "primary_result_format": {
      "type": "string",
      "enum": [
        "xml",
        "pdf"
      ],
      "description": "Üblicher Download für das angeforderte Format: `pdf` bei ZUGFERD, sonst `xml`."
    },
    "primary_result_url": {
      "type": "string",
      "description": "Relative Ergebnis-URL mit `download=<primary_result_format>`."
    },
    "client_reference": {
      "type": "string",
      "description": "Rückgabe von `client_reference`."
    },
    "source_system": {
      "type": "string",
      "description": "Rückgabe von `source_system`."
    }
  },
  "additionalProperties": false
}
```

### `TaskStatusResponse`

```json
{
  "type": "object",
  "required": [
    "task_id",
    "status",
    "correlation_id"
  ],
  "properties": {
    "task_id": {
      "type": "string",
      "format": "uuid"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "processing",
        "completed",
        "failed"
      ],
      "description": "`pending`: in der Warteschlange. `processing`: läuft. `completed`: Ein validiertes Artefakt liegt vor. `failed`: endgültig, kein Artefakt."
    },
    "progress": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0,
      "maximum": 100,
      "description": "Ungefährer Fortschritt in Prozent. Nicht für Zeitplanung verwenden."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Zeitpunkt der Annahme der Aufgabe (UTC)."
    },
    "completed_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Zeitpunkt, zu dem die Aufgabe `completed` oder `failed` erreicht hat (UTC)."
    },
    "filename": {
      "type": [
        "string",
        "null"
      ]
    },
    "error": {
      "type": [
        "string",
        "object",
        "null"
      ],
      "additionalProperties": true,
      "description": "Zusammenfassung des Fehlers bei `status=failed`: eine Meldung oder ein Objekt mit `code`, `message`, `retryable`. Nur zur Information; `/result` liefert die typisierte Fehlerhülle."
    },
    "correlation_id": {
      "type": "string",
      "format": "uuid",
      "description": "Trace-ID dieses Statusaufrufs."
    },
    "client_reference": {
      "type": [
        "string",
        "null"
      ],
      "description": "Rückgabe von `client_reference`."
    },
    "source_system": {
      "type": [
        "string",
        "null"
      ],
      "description": "Rückgabe von `source_system`."
    },
    "primary_result_format": {
      "type": "string",
      "enum": [
        "xml",
        "pdf"
      ],
      "description": "Üblicher Download für das angeforderte Format."
    },
    "primary_result_url": {
      "type": "string",
      "description": "Relative Ergebnis-URL."
    },
    "result_artifacts": {
      "$ref": "#/components/schemas/ResultArtifacts"
    },
    "validation_report_html": {
      "$ref": "#/components/schemas/ValidationReportHtmlStatus"
    }
  },
  "additionalProperties": false
}
```

### `ResultArtifacts`

```json
{
  "type": "object",
  "description": "Download-Bereitschaft je Artefakt.",
  "properties": {
    "xml": {
      "$ref": "#/components/schemas/ResultArtifactStatus"
    },
    "pdf": {
      "$ref": "#/components/schemas/ResultArtifactStatus"
    }
  },
  "additionalProperties": false
}
```

### `ResultArtifactStatus`

```json
{
  "type": "object",
  "required": [
    "state",
    "download_url"
  ],
  "properties": {
    "state": {
      "type": "string",
      "enum": [
        "cached",
        "not_ready",
        "validation_failed",
        "dependency_failed",
        "artifact_generation_rerun_required",
        "artifact_invariant_failed"
      ],
      "description": "`cached`: herunterladbar. `not_ready`: noch nicht erzeugt. `validation_failed`: blockierendes Problem in den Daten oder im Quell-PDF. `dependency_failed`: Ausfall von Validator oder Speicher. `artifact_generation_rerun_required`: neue Konvertierung starten. `artifact_invariant_failed`: mit der Correlation-ID eskalieren."
    },
    "download_url": {
      "type": "string",
      "description": "Relative Download-URL."
    },
    "content_type": {
      "type": "string"
    },
    "filename": {
      "type": "string"
    },
    "bytes": {
      "type": "integer",
      "minimum": 0
    },
    "artifact_state": {
      "type": "string",
      "enum": [
        "compliant",
        "warning_only",
        "cannot_guarantee",
        "blocked"
      ],
      "description": "Konformitätsstatus. Bei jedem gelieferten API-Artefakt `compliant`."
    },
    "validation_state": {
      "type": "string",
      "enum": [
        "passed",
        "failed_overridable",
        "failed_blocking",
        "not_validated"
      ],
      "description": "Ergebnis der Validierung. Bei jedem gelieferten API-Artefakt `passed`."
    }
  },
  "additionalProperties": false
}
```

### `ValidationReportHtmlStatus`

```json
{
  "type": "object",
  "description": "Nur vorhanden bei `include_validation_report_html=true`.",
  "required": [
    "available"
  ],
  "properties": {
    "available": {
      "type": "boolean"
    },
    "content_type": {
      "type": "string",
      "enum": [
        "text/html; charset=utf-8"
      ]
    },
    "html": {
      "type": "string",
      "description": "Bereinigtes HTML des Berichts; Serverpfade sind entfernt."
    },
    "source": {
      "type": "string",
      "description": "Zum Beispiel `artifact`, `embedded_xml` oder `source_xml`."
    },
    "source_result_format": {
      "type": "string",
      "enum": [
        "xml",
        "pdf"
      ]
    },
    "reason": {
      "type": "string",
      "description": "Grund, warum kein Bericht verfügbar ist, zum Beispiel `task_not_completed`, `proof_not_found`, `artifact_not_current`."
    }
  },
  "additionalProperties": false
}
```

### `ErrorEnvelope`

```json
{
  "type": "object",
  "description": "Jeder JSON-Fehler. Werten Sie `code` aus, bei `500 TASK_FAILED` zusätzlich `details.code` und `details.retryable`. Wiederholen Sie einen schreibenden Aufruf nur mit demselben Idempotency-Key.",
  "required": [
    "code",
    "message",
    "correlation_id"
  ],
  "properties": {
    "code": {
      "type": "string",
      "enum": [
        "AUTHENTICATION_REQUIRED",
        "INVALID_API_KEY",
        "API_NOT_ENABLED_FOR_TENANT",
        "ACCOUNT_DELETED",
        "INSUFFICIENT_API_CREDITS",
        "AUTH_SERVICE_UNAVAILABLE",
        "PLAN_TIER_CHECK_FAILED",
        "RATE_LIMIT_SERVICE_UNAVAILABLE",
        "API_CREDIT_SERVICE_UNAVAILABLE",
        "RATE_LIMITED",
        "IDEMPOTENCY_KEY_REQUIRED",
        "INVALID_IDEMPOTENCY_KEY",
        "IDEMPOTENCY_IN_PROGRESS",
        "IDEMPOTENCY_CONFLICT",
        "IDEMPOTENCY_REPLAY_EXPIRED",
        "FORMAT_REQUIRED",
        "INVALID_FORMAT",
        "INVALID_PROFILE",
        "OUTPUT_PROFILE_CONFLICT",
        "OUTPUT_PROFILE_REQUIRED",
        "CLIENT_REFERENCE_CONFLICT",
        "INVALID_CLIENT_METADATA",
        "INVALID_SELLER_MASTER_DATA",
        "INVALID_EMBEDDED_XML_POLICY",
        "INVALID_EMAIL_INPUT",
        "INVALID_UPLOAD",
        "PAYLOAD_TOO_LARGE",
        "UPLOAD_FAILED",
        "SERVER_BUSY",
        "ZUGFERD_SOURCE_PDF_REQUIRED",
        "METHOD_NOT_ALLOWED",
        "NOT_FOUND",
        "BAD_REQUEST",
        "INVALID_QUERY_PARAMETER",
        "DOWNLOAD_FORMAT_REQUIRED",
        "INVALID_DOWNLOAD_FORMAT",
        "TASK_NOT_READY",
        "TASK_NOT_FOUND",
        "TASK_STATUS_FAILED",
        "TASK_RESULT_FAILED",
        "TASK_FAILED",
        "VALIDATION_FAILED",
        "PROFILE_MISMATCH",
        "ZUGFERD_SOURCE_PDF_INCOMPATIBLE",
        "ZUGFERD_CII_CONVERSION_FAILED",
        "ZUGFERD_PDF_GENERATION_FAILED",
        "XML_GENERATION_FAILED",
        "PDF_GENERATION_FAILED",
        "AUTHORITATIVE_VALIDATION_UNAVAILABLE",
        "ARTIFACT_GENERATION_RERUN_REQUIRED",
        "EXTRACTION_INCOMPLETE_GROUP_FAILURE",
        "INTERNAL_ARTIFACT_INVARIANT_FAILED",
        "VALIDATION_REPORT_NOT_FOUND",
        "VALIDATION_REPORT_FAILED",
        "PROXY_ERROR"
      ],
      "x-enumDescriptions": {
        "AUTHENTICATION_REQUIRED": "401 · nein · Senden Sie `Authorization: Bearer <api_key>`.",
        "INVALID_API_KEY": "401 · nein · Der Schlüssel ist unbekannt, widerrufen oder fehlerhaft. Korrigieren oder rotieren Sie ihn.",
        "API_NOT_ENABLED_FOR_TENANT": "403 · nein · Der Schlüssel ist gültig, aber das Konto hat keinen Zugang zur externen API. Wenden Sie sich an den Support.",
        "ACCOUNT_DELETED": "410 · nein · Das Konto dieses API-Schlüssels wurde gelöscht. Die Löschung ist endgültig. Ein widerrufener Schlüssel liefert `INVALID_API_KEY`.",
        "INSUFFICIENT_API_CREDITS": "402 · nein · Kontingent und Prepaid-Guthaben sind aufgebraucht. Kaufen Sie ein Guthabenpaket oder warten Sie auf den nächsten Monat. Zwei Formen von `details`.",
        "AUTH_SERVICE_UNAVAILABLE": "503 · ja · Die Authentifizierung ist vorübergehend nicht verfügbar. Mit Backoff und demselben Idempotency-Key wiederholen.",
        "PLAN_TIER_CHECK_FAILED": "503 · ja · Tarif bzw. API-Zugang konnte nicht geprüft werden. Mit Backoff und demselben Idempotency-Key wiederholen.",
        "RATE_LIMIT_SERVICE_UNAVAILABLE": "503 · ja · Der Ratenlimit-Dienst ist nicht verfügbar. Mit Backoff und demselben Idempotency-Key wiederholen.",
        "API_CREDIT_SERVICE_UNAVAILABLE": "503 · ja · Die Prüfung von Guthaben und Kontingent ist nicht verfügbar. Wiederholen Sie den Upload mit demselben Idempotency-Key.",
        "RATE_LIMITED": "429 · ja · Warten Sie `Retry-After` Sekunden und wiederholen Sie dann mit demselben Idempotency-Key.",
        "IDEMPOTENCY_KEY_REQUIRED": "400 · nein · Senden Sie bei beiden POST-Endpunkten einen `Idempotency-Key`-Header.",
        "INVALID_IDEMPOTENCY_KEY": "400 · nein · Verwenden Sie 1–200 Zeichen gemäß `^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$`.",
        "IDEMPOTENCY_IN_PROGRESS": "409 · ja · Die erste Anfrage mit diesem Schlüssel läuft noch. Wiederholen Sie denselben Schlüssel nach einer kurzen Pause.",
        "IDEMPOTENCY_CONFLICT": "409 · nein · Der Schlüssel wurde mit einer anderen Payload verwendet. Verwenden Sie für eine neue Payload einen neuen Schlüssel.",
        "IDEMPOTENCY_REPLAY_EXPIRED": "409 · nein · Die ursprüngliche Aufgabe hat ihre Aufbewahrungsfrist von 24 h überschritten. Starten Sie eine neue Konvertierung mit einem neuen Schlüssel.",
        "FORMAT_REQUIRED": "400 · nein · Senden Sie `format` bei jeder Konvertierungsanfrage.",
        "INVALID_FORMAT": "422 · nein · Senden Sie einen der Werte XRECHNUNG, ZUGFERD, EN16931, UBL, CII.",
        "INVALID_PROFILE": "422 · nein · Unbekannter Profilname. `details.allowed_profiles` listet die zulässigen Werte.",
        "OUTPUT_PROFILE_CONFLICT": "422 · nein · Das Profil ist für dieses `format` nicht zulässig. Senden Sie ein passendes Profil oder lassen Sie es weg.",
        "OUTPUT_PROFILE_REQUIRED": "422 · nein · Defensiv; V1 setzt für jedes Format ein Standardprofil, daher ist dieser Fehler nicht zu erwarten.",
        "CLIENT_REFERENCE_CONFLICT": "400 · nein · `client_reference` und `external_invoice_id` unterscheiden sich. Senden Sie einen der beiden Werte oder in beiden denselben Wert.",
        "INVALID_CLIENT_METADATA": "400 · nein · Halten Sie `client_reference`/`external_invoice_id` bei ≤ 200 und `source_system` bei ≤ 100 Zeichen, ohne Steuerzeichen.",
        "INVALID_SELLER_MASTER_DATA": "400 · nein · Senden Sie `seller_master_data` als JSON-Objekt-String mit unterstützten Schlüsseln; senden Sie `electronic_address` und `electronic_address_scheme` gemeinsam.",
        "INVALID_EMBEDDED_XML_POLICY": "400 · nein · Senden Sie `use_embedded_xml` als `true` oder `false`, oder lassen Sie das Feld weg.",
        "INVALID_EMAIL_INPUT": "400 · nein · Senden Sie `email_input` einmal, ≤ 10.000 Zeichen, nur bei PDF-Quelle, nicht mit `use_embedded_xml=true` und nie bei convert-structured.",
        "INVALID_UPLOAD": "400/415 · nein · Korrigieren Sie den Upload: multipart/form-data, unterstützter Dateityp, ≤ 20 Dateiteile und 50 Felder, eine Rechnungsnummer über alle `data_file`-Teile (`details.reason`).",
        "PAYLOAD_TOO_LARGE": "413 · nein · Eine Datei oder die Summe der `data_file`-Teile überschreitet das Backend-Limit. Anfragen über ~4,5 MB werden bereits vorher mit einem 413 als reinem Text abgelehnt.",
        "UPLOAD_FAILED": "422 · nein: ungültiger Wert für `jurisdiction`/`transaction_scope`/`delivery_channel`. 500/503 · ja: Der Upload wurde nicht angenommen, oder er wurde angenommen, aber seine erste Antwort konnte nicht wiederhergestellt werden. Mit Backoff und demselben Idempotency-Key wiederholen; die Wiederholung liefert die angenommene Aufgabe.",
        "SERVER_BUSY": "503 · ja · Die Verarbeitungswarteschlange ist voll. Warten Sie `Retry-After` Sekunden (15) und wiederholen Sie dann mit demselben Idempotency-Key.",
        "ZUGFERD_SOURCE_PDF_REQUIRED": "422 · nein · `format=ZUGFERD` benötigt eine PDF-Quelle. Laden Sie ein PDF hoch oder wählen Sie ein XML-Format.",
        "METHOD_NOT_ALLOWED": "405 · nein · Verwenden Sie POST auf Konvertierungspfaden und GET auf Aufgabenpfaden (siehe `Allow`).",
        "NOT_FOUND": "404 · nein · Unbekannter Pfad unter /api/v1.",
        "BAD_REQUEST": "400 · nein · `task_id` muss eine UUID sein.",
        "INVALID_QUERY_PARAMETER": "400 · nein · Senden Sie `include_validation_report_html` als `true` oder `false`.",
        "DOWNLOAD_FORMAT_REQUIRED": "400 · nein · Senden Sie den Pflicht-Query-Parameter `download`.",
        "INVALID_DOWNLOAD_FORMAT": "400 · nein · Verwenden Sie `download=xml|pdf` bei /result und `download=html|xml` bei /validation-report.",
        "TASK_NOT_READY": "202 · abfragen · Die Aufgabe läuft noch. Fragen Sie den Aufgabenstatus weiter mit Backoff ab.",
        "TASK_NOT_FOUND": "404 · nein · Unbekannte Aufgabe, Aufgabe eines anderen Mandanten oder 24 h nach Abschluss gelöscht. Alle Aufgaben-Endpunkte.",
        "TASK_STATUS_FAILED": "5xx · ja · Der Status konnte nicht gelesen werden. Wiederholen Sie die Abfrage mit Backoff.",
        "TASK_RESULT_FAILED": "404/5xx · nur 5xx · Das Ergebnis konnte nicht gelesen werden (zum Beispiel fehlende Aufgabenmetadaten). 5xx mit Backoff wiederholen; einen 404 mit der Correlation-ID eskalieren.",
        "TASK_FAILED": "500 · nur wenn `details.retryable` true ist · Lesen Sie `details.code`. Wiederholbare Fehler erfordern eine NEUE Konvertierung mit einem neuen Idempotency-Key.",
        "VALIDATION_FAILED": "422 · nein · Blockierende Validierungsfehler. Korrigieren Sie die Daten (`details.items`) und starten Sie eine neue Konvertierung.",
        "PROFILE_MISMATCH": "422 · nein · Das gespeicherte Dokument deklariert ein anderes Profil. Starten Sie eine neue Konvertierung mit dem richtigen Profil.",
        "ZUGFERD_SOURCE_PDF_INCOMPATIBLE": "422 · nein · Das Quell-PDF kann kein striktes PDF/A-3-Hybrid tragen. Normalisieren Sie das PDF oder verwenden Sie `download=xml`.",
        "ZUGFERD_CII_CONVERSION_FAILED": "422/500 · nein · Die hybride CII-Konvertierung ist fehlgeschlagen. Mit der Correlation-ID eskalieren.",
        "ZUGFERD_PDF_GENERATION_FAILED": "500 · nein · Die Erzeugung des hybriden PDFs ist fehlgeschlagen. Mit der Correlation-ID eskalieren.",
        "XML_GENERATION_FAILED": "500 · ja, mit Backoff · Veralteter Pfad für die Erzeugung auf Abruf; bei strikten API-Aufgaben nicht zu erwarten.",
        "PDF_GENERATION_FAILED": "500 · ja, mit Backoff · Veralteter Pfad für die Erzeugung auf Abruf; bei strikten API-Aufgaben nicht zu erwarten.",
        "AUTHORITATIVE_VALIDATION_UNAVAILABLE": "503 · ja · Der Validator ist vorübergehend nicht verfügbar. Wiederholen Sie denselben Download später.",
        "ARTIFACT_GENERATION_RERUN_REQUIRED": "503 · neue Aufgabe · Die Erzeugung des Artefakts ist nach serverseitigen Wiederholungen fehlgeschlagen. Starten Sie eine neue Konvertierung.",
        "EXTRACTION_INCOMPLETE_GROUP_FAILURE": "503 · neue Aufgabe · Extraktionsgruppen sind fehlgeschlagen (`details.failed_groups`). Starten Sie eine neue Konvertierung.",
        "INTERNAL_ARTIFACT_INVARIANT_FAILED": "500 · nein · Abgeschlossene Aufgabe ohne sicher gespeichertes Artefakt. Mit der Correlation-ID eskalieren.",
        "VALIDATION_REPORT_NOT_FOUND": "404 · nein · An das aktuelle Artefakt ist kein Bericht gebunden (`details.reason`).",
        "VALIDATION_REPORT_FAILED": "4xx/5xx · nur 5xx · Der Abruf des Berichts ist fehlgeschlagen. Vorübergehende 5xx mit Backoff wiederholen.",
        "PROXY_ERROR": "502/504 · ja · Übertragungsfehler zwischen Edge und Backend. Mit Backoff und demselben Idempotency-Key wiederholen."
      },
      "description": "Maschinenlesbarer Fehlercode. Aufbau jeder Beschreibung: HTTP-Status · wiederholen? · Maßnahme."
    },
    "message": {
      "type": "string",
      "description": "Lesbarer Text. Werten Sie ihn nicht maschinell aus."
    },
    "correlation_id": {
      "type": "string",
      "format": "uuid",
      "description": "Nennen Sie sie dem Support."
    },
    "details": {
      "$ref": "#/components/schemas/ErrorDetails"
    }
  },
  "additionalProperties": false
}
```

### `EdgeError`

```json
{
  "type": "object",
  "description": "Fehler vom Edge-Proxy, bevor die Anfrage die API erreicht (`404 NOT_FOUND`, `405 METHOD_NOT_ALLOWED`). Keine `correlation_id`.",
  "required": [
    "code",
    "message"
  ],
  "properties": {
    "code": {
      "type": "string",
      "enum": [
        "NOT_FOUND",
        "METHOD_NOT_ALLOWED"
      ]
    },
    "message": {
      "type": "string"
    }
  }
}
```

### `ErrorDetails`

```json
{
  "type": "object",
  "description": "Strukturierter Kontext. Die Schlüssel hängen vom Code ab; unbekannte Schlüssel können vorkommen. `type` ist meist vorhanden, aber nicht immer (zum Beispiel `{\"field\": \"download\"}`, `INVALID_UPLOAD`, `413`). Werten Sie daher den `code` der Fehlerhülle aus.",
  "properties": {
    "type": {
      "type": "string",
      "description": "Art der Details, zum Beispiel `validation`, `rate_limit`, `idempotency_conflict`, `idempotency_in_progress`, `profile_mismatch`, `context`, `dependency`, `artifact_generation`, `validation_report`, `message`."
    },
    "code": {
      "type": "string",
      "description": "Zugrunde liegender Fehlercode. Bei `500 TASK_FAILED` ist dies der Grund; siehe `x-enumDescriptions`.",
      "examples": [
        "MULTIPLE_INVOICES_IN_DOCUMENT",
        "NO_INVOICE_DETECTED",
        "INSUFFICIENT_INVOICE_SIGNAL",
        "SOURCE_TEXT_UNAVAILABLE",
        "SCHEMA_PARSE_FAILED",
        "ARTIFACT_PARITY_FAILED",
        "PROVIDER_ERROR"
      ],
      "x-enumDescriptions": {
        "MULTIPLE_INVOICES_IN_DOCUMENT": "Endgültig. Das Dokument enthält mehr als eine Rechnung. Teilen Sie es auf und konvertieren Sie jede Rechnung einzeln.",
        "NO_INVOICE_DETECTED": "Endgültig. Das Dokument ist keine Rechnung. Leiten Sie es an eine Person weiter.",
        "INSUFFICIENT_INVOICE_SIGNAL": "Endgültig. Zu wenige Rechnungsdaten. Senden Sie eine bessere Quelle oder verwenden Sie convert-structured.",
        "SOURCE_TEXT_UNAVAILABLE": "Siehe `retryable`. false: kein lesbarer Text (laden Sie ein Text-PDF oder einen deutlicheren Scan hoch). true: OCR war vorübergehend nicht verfügbar; starten Sie eine neue Konvertierung.",
        "SCHEMA_PARSE_FAILED": "Endgültig für diesen Versuch. Starten Sie eine neue Konvertierung; eskalieren Sie, wenn der Fehler erneut auftritt.",
        "ARTIFACT_PARITY_FAILED": "Endgültig. Das Artefakt stimmte nicht mit den finalen Rechnungsdaten überein. Mit der Correlation-ID eskalieren.",
        "PROVIDER_ERROR": "Siehe `retryable`. true: Starten Sie nach einer Pause eine neue Konvertierung. `classification=provider_context_too_large`: Senden Sie ein kleineres Dokument."
      }
    },
    "retryable": {
      "type": "boolean",
      "description": "Maßgeblich, wenn vorhanden. `true` bei `TASK_FAILED`: Starten Sie eine NEUE Konvertierung mit einem neuen Idempotency-Key."
    },
    "can_review": {
      "type": "boolean"
    },
    "classification": {
      "type": "string",
      "description": "Zum Beispiel `multiple_invoices`, `not_invoice`, `provider_context_too_large`."
    },
    "category": {
      "type": "string"
    },
    "recovery_hint": {
      "type": "string",
      "description": "Lesbarer nächster Schritt."
    },
    "same_task_retryable": {
      "type": "boolean",
      "description": "`false`: Dieselbe Aufgabe kann sich nicht erholen; starten Sie eine neue Konvertierung."
    },
    "recovery": {
      "type": "string",
      "description": "Zum Beispiel `start_new_conversion`."
    },
    "dependency": {
      "type": "string"
    },
    "stage": {
      "type": "string"
    },
    "failed_groups": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Fehlgeschlagene Extraktionsgruppen bei `EXTRACTION_INCOMPLETE_GROUP_FAILURE`."
    },
    "items": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ValidationDetail"
      },
      "description": "Blockierende Probleme bei `VALIDATION_FAILED`."
    },
    "field": {
      "type": "string",
      "description": "Betroffenes Anfragefeld, zum Beispiel `download` oder `file`."
    },
    "reason": {
      "type": "string",
      "description": "Genauerer Grund, zum Beispiel `bundle_invoice_id_missing`, `bundle_invoice_id_mismatch`, `different_payload_for_same_key`."
    },
    "profile": {
      "type": "string"
    },
    "format": {
      "type": "string"
    },
    "allowed_profiles": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Zulässige Profile bei den Profilfehlern."
    },
    "minute_count": {
      "type": "integer"
    },
    "hour_count": {
      "type": "integer"
    },
    "limit_minute": {
      "type": "integer"
    },
    "limit_hour": {
      "type": "integer"
    },
    "limit_bytes": {
      "type": "integer",
      "description": "Größenlimit bei `413 PAYLOAD_TOO_LARGE`."
    },
    "declared_size": {
      "type": "integer"
    },
    "received_bytes": {
      "type": "integer"
    },
    "remaining": {
      "type": "integer"
    },
    "included_remaining": {
      "type": "integer"
    },
    "credit_remaining": {
      "type": [
        "integer",
        "null"
      ]
    },
    "shortfall": {
      "type": "integer"
    },
    "minimum_purchase": {
      "type": "integer"
    },
    "bridge_status": {
      "type": "integer"
    }
  },
  "additionalProperties": true
}
```

### `ValidationDetail`

```json
{
  "type": "object",
  "description": "Ein blockierendes Validierungsproblem.",
  "properties": {
    "field": {
      "type": [
        "string",
        "null"
      ],
      "description": "Pfad des Rechnungsfelds, zum Beispiel `BuyerReference`."
    },
    "rule_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Regel-ID, zum Beispiel `BR-DE-15`."
    },
    "severity": {
      "type": [
        "string",
        "null"
      ]
    },
    "source": {
      "type": [
        "string",
        "null"
      ]
    },
    "suggestion": {
      "type": [
        "string",
        "null"
      ],
      "description": "Was zu korrigieren ist."
    },
    "message": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "additionalProperties": true
}
```

### `InsufficientApiCreditsPrepaidError`

```json
{
  "type": "object",
  "description": "402-Form für Konten nur mit Prepaid-Guthaben.",
  "required": [
    "code",
    "message",
    "correlation_id",
    "details"
  ],
  "properties": {
    "code": {
      "type": "string",
      "const": "INSUFFICIENT_API_CREDITS"
    },
    "message": {
      "type": "string"
    },
    "correlation_id": {
      "type": "string",
      "format": "uuid"
    },
    "details": {
      "type": "object",
      "required": [
        "type",
        "remaining",
        "minimum_purchase"
      ],
      "properties": {
        "type": {
          "type": "string",
          "const": "context"
        },
        "remaining": {
          "type": "integer",
          "description": "Verbleibendes Prepaid-Guthaben."
        },
        "minimum_purchase": {
          "type": "integer",
          "description": "Kleinstes Guthabenpaket (100)."
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": false
}
```

### `InsufficientApiCreditsAllowanceError`

```json
{
  "type": "object",
  "description": "402-Form für Konten mit verbindlichem Monatskontingent.",
  "required": [
    "code",
    "message",
    "correlation_id",
    "details"
  ],
  "properties": {
    "code": {
      "type": "string",
      "const": "INSUFFICIENT_API_CREDITS"
    },
    "message": {
      "type": "string"
    },
    "correlation_id": {
      "type": "string",
      "format": "uuid"
    },
    "details": {
      "type": "object",
      "required": [
        "type",
        "included_remaining",
        "credit_remaining",
        "shortfall",
        "minimum_purchase"
      ],
      "properties": {
        "type": {
          "type": "string",
          "const": "context"
        },
        "included_remaining": {
          "type": "integer",
          "description": "Verbleibendes Kontingent in diesem Monat."
        },
        "credit_remaining": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Verbleibendes Prepaid-Guthaben oder null."
        },
        "shortfall": {
          "type": "integer",
          "description": "Nicht gedeckte Einheiten."
        },
        "minimum_purchase": {
          "type": "integer",
          "description": "Kleinstes Guthabenpaket (100)."
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": false
}
```

### `StructuredInvoice_AccountingCustomerParty`

```json
{
  "additionalProperties": false,
  "properties": {
    "Party": {
      "$ref": "#/components/schemas/StructuredInvoice_Party"
    }
  },
  "required": [
    "Party"
  ],
  "title": "AccountingCustomerParty",
  "type": "object"
}
```

### `StructuredInvoice_AccountingSupplierParty`

```json
{
  "additionalProperties": false,
  "properties": {
    "Party": {
      "$ref": "#/components/schemas/StructuredInvoice_Party"
    }
  },
  "required": [
    "Party"
  ],
  "title": "AccountingSupplierParty",
  "type": "object"
}
```

### `StructuredInvoice_AdditionalDocumentReference`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Id"
    },
    "DocumentTypeCode": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Documenttypecode"
    },
    "DocumentDescription": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Documentdescription"
    },
    "Attachment": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_Attachment"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "title": "AdditionalDocumentReference",
  "type": "object"
}
```

### `StructuredInvoice_AllowanceCharge`

```json
{
  "additionalProperties": false,
  "description": "Nachlass oder Zuschlag auf Dokumentebene (BG-20/BG-21)",
  "properties": {
    "ChargeIndicator": {
      "title": "Chargeindicator",
      "type": "boolean"
    },
    "AllowanceChargeReasonCode": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Allowancechargereasoncode"
    },
    "AllowanceChargeReason": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Allowancechargereason"
    },
    "MultiplierFactorNumeric": {
      "anyOf": [
        {
          "maximum": 100,
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Prozentpunkte genau wie in der Quelle angegeben. 30 % ist 30, nie 0,3; 0,3 % bleibt 0,3. Prozentpunkte nie in Dezimalfaktoren umrechnen.",
      "title": "Multiplierfactornumeric"
    },
    "BaseAmount": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Baseamount"
    },
    "Amount": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "string"
        }
      ],
      "title": "Amount"
    },
    "TaxCategory": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_AllowanceChargeTaxCategory"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "required": [
    "ChargeIndicator",
    "Amount"
  ],
  "title": "AllowanceCharge",
  "type": "object"
}
```

### `StructuredInvoice_AllowanceChargeTaxCategory`

```json
{
  "additionalProperties": false,
  "description": "Steuerkategorie für Nachlass/Zuschlag auf Dokumentebene (BG-21)",
  "properties": {
    "ID": {
      "title": "Id",
      "type": "string"
    },
    "Percent": {
      "anyOf": [
        {
          "maximum": 100,
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Percent"
    },
    "TaxScheme": {
      "$ref": "#/components/schemas/StructuredInvoice_TaxScheme"
    }
  },
  "required": [
    "ID",
    "TaxScheme"
  ],
  "title": "AllowanceChargeTaxCategory",
  "type": "object"
}
```

### `StructuredInvoice_Attachment`

```json
{
  "additionalProperties": false,
  "properties": {
    "EmbeddedDocumentBinaryObject": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_EmbeddedDocumentBinaryObject"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "title": "Attachment",
  "type": "object"
}
```

### `StructuredInvoice_BuyersItemIdentification`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "BuyersItemIdentification",
  "type": "object"
}
```

### `StructuredInvoice_CardAccount`

```json
{
  "additionalProperties": false,
  "properties": {
    "PrimaryAccountNumberID": {
      "title": "Primaryaccountnumberid",
      "type": "string"
    },
    "NetworkID": {
      "title": "Networkid",
      "type": "string"
    },
    "HolderName": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Holdername"
    }
  },
  "required": [
    "PrimaryAccountNumberID",
    "NetworkID"
  ],
  "title": "CardAccount",
  "type": "object"
}
```

### `StructuredInvoice_ClassifiedTaxCategory`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "title": "Id",
      "type": "string"
    },
    "Percent": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Percent"
    },
    "TaxExemptionReasonCode": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Taxexemptionreasoncode"
    },
    "TaxExemptionReason": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Taxexemptionreason"
    },
    "TaxScheme": {
      "$ref": "#/components/schemas/StructuredInvoice_TaxScheme"
    }
  },
  "required": [
    "ID",
    "TaxScheme"
  ],
  "title": "ClassifiedTaxCategory",
  "type": "object"
}
```

### `StructuredInvoice_CommodityClassification`

```json
{
  "additionalProperties": false,
  "properties": {
    "ItemClassificationCode": {
      "$ref": "#/components/schemas/StructuredInvoice_ItemClassificationCode"
    }
  },
  "required": [
    "ItemClassificationCode"
  ],
  "title": "CommodityClassification",
  "type": "object"
}
```

### `StructuredInvoice_Contact`

```json
{
  "additionalProperties": false,
  "properties": {
    "Name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Name"
    },
    "Telephone": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Telephone"
    },
    "ElectronicMail": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Electronicmail"
    }
  },
  "title": "Contact",
  "type": "object"
}
```

### `StructuredInvoice_ContractDocumentReference`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "minLength": 1,
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "ContractDocumentReference",
  "type": "object"
}
```

### `StructuredInvoice_Country`

```json
{
  "additionalProperties": false,
  "properties": {
    "IdentificationCode": {
      "title": "Identificationcode",
      "type": "string"
    }
  },
  "required": [
    "IdentificationCode"
  ],
  "title": "Country",
  "type": "object"
}
```

### `StructuredInvoice_Delivery`

```json
{
  "additionalProperties": false,
  "properties": {
    "ActualDeliveryDate": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Actualdeliverydate"
    },
    "DeliveryLocation": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_DeliveryLocation"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "DeliveryParty": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_Party"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "title": "Delivery",
  "type": "object"
}
```

### `StructuredInvoice_DeliveryAddress`

```json
{
  "additionalProperties": false,
  "properties": {
    "StreetName": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Streetname"
    },
    "AdditionalStreetName": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Additionalstreetname"
    },
    "CityName": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cityname"
    },
    "PostalZone": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Postalzone"
    },
    "CountrySubentity": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Countrysubentity"
    },
    "Country": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_Country"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "title": "DeliveryAddress",
  "type": "object"
}
```

### `StructuredInvoice_DeliveryLocation`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Id"
    },
    "schemeID": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Schemeid"
    },
    "Address": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_DeliveryAddress"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "title": "DeliveryLocation",
  "type": "object"
}
```

### `StructuredInvoice_DeliveryTerms`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Id"
    },
    "SpecialTerms": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Specialterms"
    }
  },
  "title": "DeliveryTerms",
  "type": "object"
}
```

### `StructuredInvoice_DespatchDocumentReference`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "minLength": 1,
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "DespatchDocumentReference",
  "type": "object"
}
```

### `StructuredInvoice_EmbeddedDocumentBinaryObject`

```json
{
  "additionalProperties": false,
  "properties": {
    "#text": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "#Text"
    },
    "mimeCode": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Mimecode"
    },
    "filename": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Filename"
    }
  },
  "title": "EmbeddedDocumentBinaryObject",
  "type": "object"
}
```

### `StructuredInvoice_EndpointID`

```json
{
  "additionalProperties": false,
  "properties": {
    "#text": {
      "title": "#Text",
      "type": "string"
    },
    "@schemeID": {
      "title": "@Schemeid",
      "type": "string"
    }
  },
  "required": [
    "#text",
    "@schemeID"
  ],
  "title": "EndpointID",
  "type": "object"
}
```

### `StructuredInvoice_FinancialInstitutionBranch`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "FinancialInstitutionBranch",
  "type": "object"
}
```

### `StructuredInvoice_InvoiceLine`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "description": "Positionskennung – verwenden Sie die genaue Positionsnummer der Originalrechnung (z. B. '1.1.30', '10', '001'). Nur wenn keine ausdrücklichen Kennungen vorhanden sind, fortlaufend '1', '2', '3' vergeben. NICHT der Artikelname.",
      "title": "Id",
      "type": "string"
    },
    "Note": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Note"
    },
    "InvoicedQuantity": {
      "title": "Invoicedquantity",
      "type": "number"
    },
    "unitCode": {
      "title": "Unitcode",
      "type": "string"
    },
    "LineExtensionAmount": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ],
      "title": "Lineextensionamount"
    },
    "PeriodStart": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Periodstart"
    },
    "PeriodEnd": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Periodend"
    },
    "InvoicePeriod": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_InvoicePeriod"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "OrderLineReference": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Orderlinereference"
    },
    "Item": {
      "$ref": "#/components/schemas/StructuredInvoice_Item"
    },
    "Price": {
      "$ref": "#/components/schemas/StructuredInvoice_Price"
    },
    "AllowanceCharge": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_AllowanceCharge"
        },
        {
          "items": {
            "$ref": "#/components/schemas/StructuredInvoice_AllowanceCharge"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Allowancecharge"
    }
  },
  "required": [
    "ID",
    "InvoicedQuantity",
    "unitCode",
    "LineExtensionAmount",
    "Item",
    "Price"
  ],
  "title": "InvoiceLine",
  "type": "object"
}
```

### `StructuredInvoice_InvoicePeriod`

```json
{
  "additionalProperties": false,
  "properties": {
    "StartDate": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Startdate"
    },
    "EndDate": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Enddate"
    },
    "DescriptionCode": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Descriptioncode"
    }
  },
  "title": "InvoicePeriod",
  "type": "object"
}
```

### `StructuredInvoice_Item`

```json
{
  "additionalProperties": false,
  "properties": {
    "Description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Description"
    },
    "Name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Name"
    },
    "BuyersItemIdentification": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_BuyersItemIdentification"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "SellersItemIdentification": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_SellersItemIdentification"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "StandardItemIdentification": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_StandardItemIdentification"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "OriginCountry": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_OriginCountry"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "CommodityClassification": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_CommodityClassification"
        },
        {
          "items": {
            "$ref": "#/components/schemas/StructuredInvoice_CommodityClassification"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Commodityclassification"
    },
    "ClassifiedTaxCategory": {
      "$ref": "#/components/schemas/StructuredInvoice_ClassifiedTaxCategory"
    }
  },
  "required": [
    "ClassifiedTaxCategory"
  ],
  "title": "Item",
  "type": "object"
}
```

### `StructuredInvoice_ItemClassificationCode`

```json
{
  "additionalProperties": false,
  "properties": {
    "#text": {
      "title": "#Text",
      "type": "string"
    },
    "listID": {
      "title": "Listid",
      "type": "string"
    },
    "listVersionID": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Listversionid"
    }
  },
  "required": [
    "#text",
    "listID"
  ],
  "title": "ItemClassificationCode",
  "type": "object"
}
```

### `StructuredInvoice_LegalMonetaryTotal`

```json
{
  "additionalProperties": false,
  "properties": {
    "LineExtensionAmount": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ],
      "title": "Lineextensionamount"
    },
    "AllowanceTotalAmount": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Allowancetotalamount"
    },
    "ChargeTotalAmount": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Chargetotalamount"
    },
    "TaxExclusiveAmount": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ],
      "title": "Taxexclusiveamount"
    },
    "TaxInclusiveAmount": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ],
      "title": "Taxinclusiveamount"
    },
    "PrepaidAmount": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Prepaidamount"
    },
    "PayableRoundingAmount": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Payableroundingamount"
    },
    "PayableAmount": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ],
      "title": "Payableamount"
    }
  },
  "required": [
    "LineExtensionAmount",
    "TaxExclusiveAmount",
    "TaxInclusiveAmount",
    "PayableAmount"
  ],
  "title": "LegalMonetaryTotal",
  "type": "object"
}
```

### `StructuredInvoice_OrderReference`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "minLength": 1,
      "title": "Id",
      "type": "string"
    },
    "IssueDate": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Issuedate"
    }
  },
  "required": [
    "ID"
  ],
  "title": "OrderReference",
  "type": "object"
}
```

### `StructuredInvoice_OriginCountry`

```json
{
  "additionalProperties": false,
  "properties": {
    "IdentificationCode": {
      "title": "Identificationcode",
      "type": "string"
    }
  },
  "required": [
    "IdentificationCode"
  ],
  "title": "OriginCountry",
  "type": "object"
}
```

### `StructuredInvoice_Party`

```json
{
  "additionalProperties": false,
  "properties": {
    "EndpointID": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_EndpointID"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "PartyIdentification": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_PartyIdentification"
        },
        {
          "items": {
            "$ref": "#/components/schemas/StructuredInvoice_PartyIdentification"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Partyidentification"
    },
    "PartyName": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Partyname"
    },
    "PostalAddress": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_PostalAddress"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "PartyTaxScheme": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_PartyTaxScheme"
        },
        {
          "items": {
            "$ref": "#/components/schemas/StructuredInvoice_PartyTaxScheme"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Partytaxscheme"
    },
    "PartyLegalEntity": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_PartyLegalEntity"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "Contact": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_Contact"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "title": "Party",
  "type": "object"
}
```

### `StructuredInvoice_PartyIdentification`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "title": "Id",
      "type": "string"
    },
    "schemeID": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Schemeid"
    }
  },
  "required": [
    "ID"
  ],
  "title": "PartyIdentification",
  "type": "object"
}
```

### `StructuredInvoice_PartyLegalEntity`

```json
{
  "additionalProperties": false,
  "properties": {
    "RegistrationName": {
      "title": "Registrationname",
      "type": "string"
    },
    "CompanyID": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Companyid"
    },
    "CompanyLegalForm": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Companylegalform"
    }
  },
  "required": [
    "RegistrationName"
  ],
  "title": "PartyLegalEntity",
  "type": "object"
}
```

### `StructuredInvoice_PartyTaxScheme`

```json
{
  "additionalProperties": false,
  "properties": {
    "CompanyID": {
      "title": "Companyid",
      "type": "string"
    },
    "TaxScheme": {
      "$ref": "#/components/schemas/StructuredInvoice_TaxScheme"
    }
  },
  "required": [
    "CompanyID",
    "TaxScheme"
  ],
  "title": "PartyTaxScheme",
  "type": "object"
}
```

### `StructuredInvoice_PayeeFinancialAccount`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "title": "Id",
      "type": "string"
    },
    "Name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Name"
    },
    "FinancialInstitutionBranch": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_FinancialInstitutionBranch"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "required": [
    "ID"
  ],
  "title": "PayeeFinancialAccount",
  "type": "object"
}
```

### `StructuredInvoice_PayeeParty`

```json
{
  "additionalProperties": false,
  "properties": {
    "Party": {
      "$ref": "#/components/schemas/StructuredInvoice_Party"
    }
  },
  "required": [
    "Party"
  ],
  "title": "PayeeParty",
  "type": "object"
}
```

### `StructuredInvoice_PaymentMandate`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "title": "Id",
      "type": "string"
    },
    "PayerFinancialAccount": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_PayeeFinancialAccount"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "required": [
    "ID"
  ],
  "title": "PaymentMandate",
  "type": "object"
}
```

### `StructuredInvoice_PaymentMeans`

```json
{
  "additionalProperties": false,
  "properties": {
    "PaymentMeansCode": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Paymentmeanscode"
    },
    "PaymentID": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Paymentid"
    },
    "PaymentChannelCode": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Paymentchannelcode"
    },
    "InstructionID": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Instructionid"
    },
    "InstructionNote": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Instructionnote"
    },
    "PayeeFinancialAccount": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_PayeeFinancialAccount"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "CardAccount": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_CardAccount"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "PaymentMandate": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_PaymentMandate"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "title": "PaymentMeans",
  "type": "object"
}
```

### `StructuredInvoice_PaymentTerms`

```json
{
  "additionalProperties": false,
  "properties": {
    "Note": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Note"
    },
    "PenaltySurchargePercent": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Penaltysurchargepercent"
    },
    "Amount": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Amount"
    },
    "NetDays": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Netdays"
    },
    "DiscountDays": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Discountdays"
    },
    "DiscountPercent": {
      "anyOf": [
        {
          "maximum": 100,
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Discountpercent"
    },
    "ExplicitDueDate": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Explicitduedate"
    }
  },
  "title": "PaymentTerms",
  "type": "object"
}
```

### `StructuredInvoice_PostalAddress`

```json
{
  "additionalProperties": false,
  "properties": {
    "StreetName": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Streetname"
    },
    "CityName": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cityname"
    },
    "PostalZone": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Postalzone"
    },
    "Country": {
      "$ref": "#/components/schemas/StructuredInvoice_Country"
    },
    "AdditionalStreetName": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Additionalstreetname"
    },
    "CountrySubentity": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Countrysubentity"
    }
  },
  "required": [
    "Country"
  ],
  "title": "PostalAddress",
  "type": "object"
}
```

### `StructuredInvoice_PrecedingInvoiceReference`

```json
{
  "additionalProperties": false,
  "description": "BG-3: Verweis auf eine vorausgegangene Rechnung (z. B. bei einer Schlussrechnung mit Verweis auf Abschlagsrechnungen)",
  "properties": {
    "ID": {
      "minLength": 1,
      "title": "Id",
      "type": "string"
    },
    "IssueDate": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Issuedate"
    }
  },
  "required": [
    "ID"
  ],
  "title": "PrecedingInvoiceReference",
  "type": "object"
}
```

### `StructuredInvoice_Price`

```json
{
  "additionalProperties": false,
  "properties": {
    "PriceAmount": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ],
      "title": "Priceamount"
    },
    "BaseQuantity": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "additionalProperties": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              }
            ]
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Basequantity"
    },
    "AllowanceCharge": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_AllowanceCharge"
        },
        {
          "items": {
            "$ref": "#/components/schemas/StructuredInvoice_AllowanceCharge"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Allowancecharge"
    }
  },
  "required": [
    "PriceAmount"
  ],
  "title": "Price",
  "type": "object"
}
```

### `StructuredInvoice_ProjectReference`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "minLength": 1,
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "ProjectReference",
  "type": "object"
}
```

### `StructuredInvoice_SalesOrderReference`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "minLength": 1,
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "SalesOrderReference",
  "type": "object"
}
```

### `StructuredInvoice_SellersItemIdentification`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "SellersItemIdentification",
  "type": "object"
}
```

### `StructuredInvoice_StandardItemIdentification`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "title": "Id",
      "type": "string"
    },
    "schemeID": {
      "default": "0160",
      "title": "Schemeid",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "StandardItemIdentification",
  "type": "object"
}
```

### `StructuredInvoice_TaxCategory`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "title": "Id",
      "type": "string"
    },
    "Percent": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Percent"
    },
    "TaxExemptionReasonCode": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Taxexemptionreasoncode"
    },
    "TaxExemptionReason": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Taxexemptionreason"
    },
    "TaxScheme": {
      "$ref": "#/components/schemas/StructuredInvoice_TaxScheme"
    }
  },
  "required": [
    "ID",
    "TaxScheme"
  ],
  "title": "TaxCategory",
  "type": "object"
}
```

### `StructuredInvoice_TaxRepresentativeParty`

```json
{
  "additionalProperties": false,
  "description": "BG-11: Steuerlicher Vertreter des Verkäufers\nPflicht, wenn die Steuerkategorien S, Z, E, AE, K, G, L, M verwendet werden\nund weder BT-31 noch BT-32 angegeben ist (BR-DE-16)",
  "properties": {
    "PartyName": {
      "minLength": 1,
      "title": "Partyname",
      "type": "string"
    },
    "PostalAddress": {
      "$ref": "#/components/schemas/StructuredInvoice_TaxRepresentativePostalAddress"
    },
    "PartyTaxScheme": {
      "$ref": "#/components/schemas/StructuredInvoice_PartyTaxScheme"
    }
  },
  "required": [
    "PartyName",
    "PostalAddress",
    "PartyTaxScheme"
  ],
  "title": "TaxRepresentativeParty",
  "type": "object"
}
```

### `StructuredInvoice_TaxRepresentativePostalAddress`

```json
{
  "additionalProperties": false,
  "description": "BG-12: Postanschrift des steuerlichen Vertreters des Verkäufers",
  "properties": {
    "StreetName": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Streetname"
    },
    "AdditionalStreetName": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Additionalstreetname"
    },
    "CityName": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cityname"
    },
    "PostalZone": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Postalzone"
    },
    "CountrySubentity": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Countrysubentity"
    },
    "Country": {
      "$ref": "#/components/schemas/StructuredInvoice_Country"
    }
  },
  "required": [
    "Country"
  ],
  "title": "TaxRepresentativePostalAddress",
  "type": "object"
}
```

### `StructuredInvoice_TaxScheme`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "TaxScheme",
  "type": "object"
}
```

### `StructuredInvoice_TaxSubtotal`

```json
{
  "additionalProperties": false,
  "properties": {
    "TaxableAmount": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ],
      "title": "Taxableamount"
    },
    "TaxAmount": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ],
      "title": "Taxamount"
    },
    "TaxCategory": {
      "$ref": "#/components/schemas/StructuredInvoice_TaxCategory"
    }
  },
  "required": [
    "TaxableAmount",
    "TaxAmount",
    "TaxCategory"
  ],
  "title": "TaxSubtotal",
  "type": "object"
}
```

### `StructuredInvoice_TaxTotal`

```json
{
  "additionalProperties": false,
  "properties": {
    "TaxAmount": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ],
      "title": "Taxamount"
    },
    "TaxSubtotal": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_TaxSubtotal"
        },
        {
          "items": {
            "$ref": "#/components/schemas/StructuredInvoice_TaxSubtotal"
          },
          "type": "array"
        }
      ],
      "title": "Taxsubtotal"
    }
  },
  "required": [
    "TaxAmount",
    "TaxSubtotal"
  ],
  "title": "TaxTotal",
  "type": "object"
}
```

### `StructuredInvoice_TenderOrLotReference`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "minLength": 1,
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "TenderOrLotReference",
  "type": "object"
}
```

## Fehlercodes

| Code | Beschreibung |
| --- | --- |
| `AUTHENTICATION_REQUIRED` | 401 · nein · Senden Sie `Authorization: Bearer <api_key>`. |
| `INVALID_API_KEY` | 401 · nein · Der Schlüssel ist unbekannt, widerrufen oder fehlerhaft. Korrigieren oder rotieren Sie ihn. |
| `API_NOT_ENABLED_FOR_TENANT` | 403 · nein · Der Schlüssel ist gültig, aber das Konto hat keinen Zugang zur externen API. Wenden Sie sich an den Support. |
| `ACCOUNT_DELETED` | 410 · nein · Das Konto dieses API-Schlüssels wurde gelöscht. Die Löschung ist endgültig. Ein widerrufener Schlüssel liefert `INVALID_API_KEY`. |
| `INSUFFICIENT_API_CREDITS` | 402 · nein · Kontingent und Prepaid-Guthaben sind aufgebraucht. Kaufen Sie ein Guthabenpaket oder warten Sie auf den nächsten Monat. Zwei Formen von `details`. |
| `AUTH_SERVICE_UNAVAILABLE` | 503 · ja · Die Authentifizierung ist vorübergehend nicht verfügbar. Mit Backoff und demselben Idempotency-Key wiederholen. |
| `PLAN_TIER_CHECK_FAILED` | 503 · ja · Tarif bzw. API-Zugang konnte nicht geprüft werden. Mit Backoff und demselben Idempotency-Key wiederholen. |
| `RATE_LIMIT_SERVICE_UNAVAILABLE` | 503 · ja · Der Ratenlimit-Dienst ist nicht verfügbar. Mit Backoff und demselben Idempotency-Key wiederholen. |
| `API_CREDIT_SERVICE_UNAVAILABLE` | 503 · ja · Die Prüfung von Guthaben und Kontingent ist nicht verfügbar. Wiederholen Sie den Upload mit demselben Idempotency-Key. |
| `RATE_LIMITED` | 429 · ja · Warten Sie `Retry-After` Sekunden und wiederholen Sie dann mit demselben Idempotency-Key. |
| `IDEMPOTENCY_KEY_REQUIRED` | 400 · nein · Senden Sie bei beiden POST-Endpunkten einen `Idempotency-Key`-Header. |
| `INVALID_IDEMPOTENCY_KEY` | 400 · nein · Verwenden Sie 1–200 Zeichen gemäß `^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$`. |
| `IDEMPOTENCY_IN_PROGRESS` | 409 · ja · Die erste Anfrage mit diesem Schlüssel läuft noch. Wiederholen Sie denselben Schlüssel nach einer kurzen Pause. |
| `IDEMPOTENCY_CONFLICT` | 409 · nein · Der Schlüssel wurde mit einer anderen Payload verwendet. Verwenden Sie für eine neue Payload einen neuen Schlüssel. |
| `IDEMPOTENCY_REPLAY_EXPIRED` | 409 · nein · Die ursprüngliche Aufgabe hat ihre Aufbewahrungsfrist von 24 h überschritten. Starten Sie eine neue Konvertierung mit einem neuen Schlüssel. |
| `FORMAT_REQUIRED` | 400 · nein · Senden Sie `format` bei jeder Konvertierungsanfrage. |
| `INVALID_FORMAT` | 422 · nein · Senden Sie einen der Werte XRECHNUNG, ZUGFERD, EN16931, UBL, CII. |
| `INVALID_PROFILE` | 422 · nein · Unbekannter Profilname. `details.allowed_profiles` listet die zulässigen Werte. |
| `OUTPUT_PROFILE_CONFLICT` | 422 · nein · Das Profil ist für dieses `format` nicht zulässig. Senden Sie ein passendes Profil oder lassen Sie es weg. |
| `OUTPUT_PROFILE_REQUIRED` | 422 · nein · Defensiv; V1 setzt für jedes Format ein Standardprofil, daher ist dieser Fehler nicht zu erwarten. |
| `CLIENT_REFERENCE_CONFLICT` | 400 · nein · `client_reference` und `external_invoice_id` unterscheiden sich. Senden Sie einen der beiden Werte oder in beiden denselben Wert. |
| `INVALID_CLIENT_METADATA` | 400 · nein · Halten Sie `client_reference`/`external_invoice_id` bei ≤ 200 und `source_system` bei ≤ 100 Zeichen, ohne Steuerzeichen. |
| `INVALID_SELLER_MASTER_DATA` | 400 · nein · Senden Sie `seller_master_data` als JSON-Objekt-String mit unterstützten Schlüsseln; senden Sie `electronic_address` und `electronic_address_scheme` gemeinsam. |
| `INVALID_EMBEDDED_XML_POLICY` | 400 · nein · Senden Sie `use_embedded_xml` als `true` oder `false`, oder lassen Sie das Feld weg. |
| `INVALID_EMAIL_INPUT` | 400 · nein · Senden Sie `email_input` einmal, ≤ 10.000 Zeichen, nur bei PDF-Quelle, nicht mit `use_embedded_xml=true` und nie bei convert-structured. |
| `INVALID_UPLOAD` | 400/415 · nein · Korrigieren Sie den Upload: multipart/form-data, unterstützter Dateityp, ≤ 20 Dateiteile und 50 Felder, eine Rechnungsnummer über alle `data_file`-Teile (`details.reason`). |
| `PAYLOAD_TOO_LARGE` | 413 · nein · Eine Datei oder die Summe der `data_file`-Teile überschreitet das Backend-Limit. Anfragen über ~4,5 MB werden bereits vorher mit einem 413 als reinem Text abgelehnt. |
| `UPLOAD_FAILED` | 422 · nein: ungültiger Wert für `jurisdiction`/`transaction_scope`/`delivery_channel`. 500/503 · ja: Der Upload wurde nicht angenommen, oder er wurde angenommen, aber seine erste Antwort konnte nicht wiederhergestellt werden. Mit Backoff und demselben Idempotency-Key wiederholen; die Wiederholung liefert die angenommene Aufgabe. |
| `SERVER_BUSY` | 503 · ja · Die Verarbeitungswarteschlange ist voll. Warten Sie `Retry-After` Sekunden (15) und wiederholen Sie dann mit demselben Idempotency-Key. |
| `ZUGFERD_SOURCE_PDF_REQUIRED` | 422 · nein · `format=ZUGFERD` benötigt eine PDF-Quelle. Laden Sie ein PDF hoch oder wählen Sie ein XML-Format. |
| `METHOD_NOT_ALLOWED` | 405 · nein · Verwenden Sie POST auf Konvertierungspfaden und GET auf Aufgabenpfaden (siehe `Allow`). |
| `NOT_FOUND` | 404 · nein · Unbekannter Pfad unter /api/v1. |
| `BAD_REQUEST` | 400 · nein · `task_id` muss eine UUID sein. |
| `INVALID_QUERY_PARAMETER` | 400 · nein · Senden Sie `include_validation_report_html` als `true` oder `false`. |
| `DOWNLOAD_FORMAT_REQUIRED` | 400 · nein · Senden Sie den Pflicht-Query-Parameter `download`. |
| `INVALID_DOWNLOAD_FORMAT` | 400 · nein · Verwenden Sie `download=xml\|pdf` bei /result und `download=html\|xml` bei /validation-report. |
| `TASK_NOT_READY` | 202 · abfragen · Die Aufgabe läuft noch. Fragen Sie den Aufgabenstatus weiter mit Backoff ab. |
| `TASK_NOT_FOUND` | 404 · nein · Unbekannte Aufgabe, Aufgabe eines anderen Mandanten oder 24 h nach Abschluss gelöscht. Alle Aufgaben-Endpunkte. |
| `TASK_STATUS_FAILED` | 5xx · ja · Der Status konnte nicht gelesen werden. Wiederholen Sie die Abfrage mit Backoff. |
| `TASK_RESULT_FAILED` | 404/5xx · nur 5xx · Das Ergebnis konnte nicht gelesen werden (zum Beispiel fehlende Aufgabenmetadaten). 5xx mit Backoff wiederholen; einen 404 mit der Correlation-ID eskalieren. |
| `TASK_FAILED` | 500 · nur wenn `details.retryable` true ist · Lesen Sie `details.code`. Wiederholbare Fehler erfordern eine NEUE Konvertierung mit einem neuen Idempotency-Key. |
| `VALIDATION_FAILED` | 422 · nein · Blockierende Validierungsfehler. Korrigieren Sie die Daten (`details.items`) und starten Sie eine neue Konvertierung. |
| `PROFILE_MISMATCH` | 422 · nein · Das gespeicherte Dokument deklariert ein anderes Profil. Starten Sie eine neue Konvertierung mit dem richtigen Profil. |
| `ZUGFERD_SOURCE_PDF_INCOMPATIBLE` | 422 · nein · Das Quell-PDF kann kein striktes PDF/A-3-Hybrid tragen. Normalisieren Sie das PDF oder verwenden Sie `download=xml`. |
| `ZUGFERD_CII_CONVERSION_FAILED` | 422/500 · nein · Die hybride CII-Konvertierung ist fehlgeschlagen. Mit der Correlation-ID eskalieren. |
| `ZUGFERD_PDF_GENERATION_FAILED` | 500 · nein · Die Erzeugung des hybriden PDFs ist fehlgeschlagen. Mit der Correlation-ID eskalieren. |
| `XML_GENERATION_FAILED` | 500 · ja, mit Backoff · Veralteter Pfad für die Erzeugung auf Abruf; bei strikten API-Aufgaben nicht zu erwarten. |
| `PDF_GENERATION_FAILED` | 500 · ja, mit Backoff · Veralteter Pfad für die Erzeugung auf Abruf; bei strikten API-Aufgaben nicht zu erwarten. |
| `AUTHORITATIVE_VALIDATION_UNAVAILABLE` | 503 · ja · Der Validator ist vorübergehend nicht verfügbar. Wiederholen Sie denselben Download später. |
| `ARTIFACT_GENERATION_RERUN_REQUIRED` | 503 · neue Aufgabe · Die Erzeugung des Artefakts ist nach serverseitigen Wiederholungen fehlgeschlagen. Starten Sie eine neue Konvertierung. |
| `EXTRACTION_INCOMPLETE_GROUP_FAILURE` | 503 · neue Aufgabe · Extraktionsgruppen sind fehlgeschlagen (`details.failed_groups`). Starten Sie eine neue Konvertierung. |
| `INTERNAL_ARTIFACT_INVARIANT_FAILED` | 500 · nein · Abgeschlossene Aufgabe ohne sicher gespeichertes Artefakt. Mit der Correlation-ID eskalieren. |
| `VALIDATION_REPORT_NOT_FOUND` | 404 · nein · An das aktuelle Artefakt ist kein Bericht gebunden (`details.reason`). |
| `VALIDATION_REPORT_FAILED` | 4xx/5xx · nur 5xx · Der Abruf des Berichts ist fehlgeschlagen. Vorübergehende 5xx mit Backoff wiederholen. |
| `PROXY_ERROR` | 502/504 · ja · Übertragungsfehler zwischen Edge und Backend. Mit Backoff und demselben Idempotency-Key wiederholen. |