{"openapi":"3.1.0","info":{"title":"Invoice.xhub API","description":"\n## Overview\n\nThe Invoice.xhub API provides REST endpoints for generating, parsing, and validating electronic invoices across 37 countries.\n\n## Authentication\n\nAll endpoints require API Key authentication using a Bearer token:\n\n```\nAuthorization: Bearer sk_live_xxxxx\n```\n\nAPI keys can be created in test mode (`sk_test_*`) or live mode (`sk_live_*`).\n\n## Supported Countries\n\n<!-- BEGIN_COUNTRY_FORMATS -->\n| Country | Formats |\n|---------|---------|\n| Germany (DE) | PDF, ZUGFeRD 2.3/2.4/2.5, XRechnung 3.0/3.0.2 |\n| Austria (AT) | PDF, ebInterface, UBL (Peppol BIS 3.0) |\n| Switzerland (CH) | PDF, ZUGFeRD (CH), QR-Bill |\n| Liechtenstein (LI) | PDF, QR-Bill, UBL (Peppol BIS 3.0) |\n| France (FR) | PDF, Factur-X 1.0/1.08/1.09, UBL (Peppol BIS 3.0) |\n| Netherlands (NL) | PDF, UBL (Peppol BIS 3.0 / NL-CIUS) |\n| Belgium (BE) | PDF, UBL (Peppol BIS 3.0), Factur-X |\n| Luxembourg (LU) | PDF, UBL (Peppol BIS 3.0) |\n| Ireland (IE) | PDF, UBL (Peppol BIS 3.0) |\n| United Kingdom (GB) | PDF, UBL (Peppol BIS 3.0 / UK) |\n| Denmark (DK) | PDF, UBL (Peppol BIS 3.0) |\n| Finland (FI) | PDF, UBL (Peppol BIS 3.0) |\n| Sweden (SE) | PDF, UBL (Peppol BIS 3.0) |\n| Norway (NO) | PDF, UBL (Peppol BIS 3.0) |\n| Iceland (IS) | PDF, UBL (Peppol BIS 3.0) |\n| Italy (IT) | PDF, FatturaPA 1.2.3 |\n| Spain (ES) | PDF, Facturae, UBL (Peppol BIS 3.0) |\n| Portugal (PT) | PDF, CIUS-PT (national UBL), UBL (Peppol BIS 3.0) |\n| Greece (GR) | PDF, myDATA |\n| Cyprus (CY) | PDF, UBL (Peppol BIS 3.0) |\n| Malta (MT) | PDF, UBL (Peppol BIS 3.0) |\n| Slovenia (SI) | PDF, UBL (Peppol BIS 3.0) |\n| Croatia (HR) | PDF, UBL (Peppol BIS 3.0) |\n| Poland (PL) | PDF, KSeF FA(3) (national UBL slot), UBL (Peppol BIS 3.0) |\n| Czech Republic (CZ) | PDF, ISDOC, UBL (Peppol BIS 3.0) |\n| Slovakia (SK) | PDF, CIUS-SK (national UBL), UBL (Peppol BIS 3.0) |\n| Hungary (HU) | PDF, NAV |\n| Romania (RO) | PDF, eFactura (CIUS-RO), UBL (Peppol BIS 3.0) |\n| Bulgaria (BG) | PDF, UBL (Peppol BIS 3.0) |\n| Estonia (EE) | PDF, UBL (Peppol BIS 3.0) |\n| Latvia (LV) | PDF, UBL (Peppol BIS 3.0) |\n| Lithuania (LT) | PDF, UBL (Peppol BIS 3.0) |\n| United Arab Emirates (AE) | PDF, UBL (PINT-AE) |\n| Australia (AU) | PDF, UBL (PINT AU-NZ) |\n| New Zealand (NZ) | PDF, UBL (PINT AU-NZ) |\n| Japan (JP) | PDF, UBL (PINT-JP) |\n| Oman (OM) | PDF, UBL (PINT-OM) |\n<!-- END_COUNTRY_FORMATS -->\n\n## Rate Limits & Quotas\n\nAPI usage is tracked per entitlement. When quota is exceeded, endpoints return HTTP 429 with quota details.\n\n## Entitlements\n\nAccess is controlled by entitlements on the API key:\n- `pdf:{country}:generate` - PDF generation\n- `e-invoice:{country}:{format}:create` - E-invoice generation\n- `e-invoice:{country}:{format}:parse` - E-invoice parsing\n    ","version":"1.4.0 (2026-06-10)","contact":{"name":"xhub.io Support","email":"support@xhub.io"}},"servers":[{"url":"/","description":"Invoice API v1"}],"tags":[{"name":"Invoice Generation","description":"Generate invoice documents (PDF, e-invoices)"},{"name":"Invoice Parsing","description":"Parse e-invoice documents and extract data"},{"name":"Invoice Validation","description":"Validate invoice data against country rules"},{"name":"Formats","description":"Query supported countries and formats"},{"name":"Peppol","description":"Send UBL documents over the Peppol network and track transmissions (configure the Access Point provider under Settings → Peppol first)"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API Key authentication. Use `sk_live_*` for production or `sk_test_*` for testing."}}},"security":[{"bearerAuth":[]}],"paths":{"/api/v1/invoice/{countryCode}/{format}/generate":{"post":{"operationId":"postApiV1InvoiceByCountryCodeByFormatGenerate","tags":["Invoice Generation"],"summary":"Generate invoice document","description":"Generate an invoice document in the specified format (PDF, XRechnung, ZUGFeRD, etc.). Supports 14 European countries with country-specific e-invoice formats.\n\n### Template selection (PDF-based formats only: `pdf`, `zugferd`, `facturx`)\n\nYou have **three ways** to control the PDF template — pick exactly one:\n\n1. **`templateId`** — reference a template previously saved via the web UI or the tRPC `pdf.templateCreate` mutation. The template is loaded from the database using the organization of the API key.\n2. **`formatOptions.template`** — inline a complete `BlockTemplate` JSON object in the request body. Use this if you want to ship a template bundled with your integration without storing it server-side.\n3. **Omit both** — the server uses the built-in default template (the \"Gumbonaut\" sample template shipped with the API). This is the easiest way to get started.\n\n**Priority if multiple are provided:** `templateId` > `formatOptions.template` > default. For non-PDF formats (e.g. `xrechnung`, `ubl`) the template is ignored — these formats produce pure XML output.\n\n### Body examples\nUse the \"Examples\" dropdown below to toggle between the three variants.","security":[{"bearerAuth":[]}],"parameters":[{"name":"countryCode","in":"path","required":true,"description":"ISO 3166-1 alpha-2 country code (lowercase). Determines country-specific validation and available e-invoice formats. Supported countries (37): ae, at, au, be, bg, ch, cy, cz, de, dk, ee, es, fi, fr, gb, gr, hr, hu, ie, is, it, jp, li, lt, lu, lv, mt, nl, no, nz, om, pl, pt, ro, se, si, sk.","schema":{"type":"string","enum":["ae","at","au","be","bg","ch","cy","cz","de","dk","ee","es","fi","fr","gb","gr","hr","hu","ie","is","it","jp","li","lt","lu","lv","mt","nl","no","nz","om","pl","pt","ro","se","si","sk"],"example":"de"}},{"name":"format","in":"path","required":true,"description":"Output/input format identifier (lowercase). Valid format values depend on the country — call `GET /api/v1/invoice/{countryCode}/formats` to discover the exact set for a country. Overview:\n\n- **pdf** — all 37 countries.\n- **ubl** — generic Peppol BIS 3.0 UBL on most countries (incl. PINT flavours for AE/AU/NZ); on **PL** it emits the national KSeF FA(3), on **PT** CIUS-PT, on **RO** eFactura (CIUS-RO), on **SK** CIUS-SK.\n- **xrechnung** (DE), **zugferd** (DE — `formatOptions.profile` selects `EN16931`/`BASIC`/`EXTENDED`; CH — Swiss CII flavour for cross-border DE/AT customers).\n- **ebinterface** (AT).\n- **facturx** (FR/BE — `formatOptions.profile` selects `EN16931`/`BASIC`).\n- **fatturapa** (IT — 6-char SDI codes for PA accepted).\n- **facturae** (ES).\n- **isdoc** (CZ), **nav** (HU), **mydata** (GR), **ksef** (PL).\n- **peppol-ubl** — generic Peppol BIS 3.0 UBL for HR/PL/PT/RO/SK whose `ubl` slot is (or can be) occupied by the national CIUS.\n- **hr-fisk** (HR — HR-FISK 2.0 CIUS, validate only).\n- **qr-bill** (CH/LI — structured 32-line QR-Bill payload as text/plain).\n\nExact spelling matters — values must be lowercase. The `peppol-ubl`, `qr-bill` and `hr-fisk` slots are dash-separated.","schema":{"type":"string","enum":["ebinterface","facturae","facturx","fatturapa","hr-fisk","isdoc","ksef","mydata","nav","pdf","peppol-ubl","qr-bill","ubl","xrechnung","zugferd"],"example":"pdf"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"invoice":{"type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{},"description":"Invoice data to generate document from"},"templateId":{"description":"**Option B** — reference a PDF template previously saved via the web UI (or the `pdf.templateCreate` tRPC mutation) by its UUID. The template is loaded from the database for the organization of the API key. Only used for PDF-based formats (`pdf`, `zugferd`, `facturx`). **Priority:** `templateId` > `formatOptions.template` > built-in default template. If all three are omitted, the built-in default \"Gumbonaut\" template is used.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"formatOptions":{"description":"Format-specific options. `template` (inline BlockTemplate, option C — see above), `zugferdProfile` (legacy alias for `profile`), `profile` (EN16931 / BASIC / EXTENDED — ZUGFeRD + Factur-X), `version` (2.3/2.4/2.5 for ZUGFeRD, 1.0/1.07/1.08/1.09 for Factur-X).","type":"object","properties":{"template":{"description":"**Option C** — inline a complete BlockTemplate JSON object in the request. Only used for PDF-based formats (`pdf`, `zugferd`, `facturx`). **Priority:** `templateId` > `formatOptions.template` > built-in default template. If all three are omitted, the built-in default \"Gumbonaut\" template is used.\n\nA BlockTemplate is a JSON document with the top-level fields `version`, `name`, `page` (size, margins, colorScheme, fontSizes), `header`, `body.blocks`, `footer`, and optional `styles`. The `body.blocks` array contains typed blocks: `text`, `table`, `keyvalue`, `columns`, `summary`, `image`, `spacer`, `line`, `qrcode`. Use placeholders like `{{buyer.name}}`, `{{invoiceNumber}}`, `{{items}}`, `{{total}}`, `{{paymentTerms.dueDays}}` — they are resolved from the Invoice data at generation time. A trailing `?` (e.g. `{{buyer.street?}}`) marks a placeholder as optional. See the `withInlineTemplate` example in the Examples dropdown for a full, working template (the default \"Gumbonaut\" invoice template).","type":"object","properties":{"version":{"type":"string","description":"Template version (semver, e.g., 1.0.0)","example":"1.0.0"},"name":{"type":"string","description":"Template name","example":"default-invoice"},"page":{"type":"object","properties":{"size":{"type":"string","enum":["A4","A3","A5","LETTER","LEGAL","CUSTOM"],"description":"Page size (use CUSTOM with customWidth/customHeight)"},"orientation":{"description":"Page orientation","type":"string","enum":["portrait","landscape"]},"margins":{"type":"object","properties":{"top":{"type":"number","description":"Top margin in points"},"right":{"type":"number","description":"Right margin in points"},"bottom":{"type":"number","description":"Bottom margin in points"},"left":{"type":"number","description":"Left margin in points"}},"required":["top","right","bottom","left"],"description":"Page margins"},"customWidth":{"description":"Custom page width in mm (only for CUSTOM size)","type":"number"},"customHeight":{"description":"Custom page height in mm (only for CUSTOM size)","type":"number"},"defaultFont":{"description":"Default font family for the document","type":"string"},"colorScheme":{"description":"Named color tokens (e.g., { primaryColor: \"#47c918\", textColor: \"#000000\" })","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"fontSizes":{"description":"Named font size tokens (e.g., { textSize: 10, headingSize: 14 })","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}},"background":{"description":"Background image configuration","type":"object","properties":{"image":{"description":"Base64 encoded image or URL","type":"string"},"opacity":{"description":"Opacity (0-1)","type":"number"},"position":{"description":"Position mode","type":"string","enum":["stretch","center","tile"]}}}},"required":["size","margins"],"description":"Page configuration"},"header":{"description":"Header section (repeated on each page)","type":"object","properties":{"height":{"description":"Height in points (for header/footer)","type":"number"},"blocks":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"condition":{"description":"Conditional rendering: block is only rendered when the placeholder resolves to a non-empty value. Use any scalar placeholder, e.g., {{notes}}, {{deliveryDate}}, {{buyer.taxId}}.","type":"string"},"data":{"type":"object","properties":{"content":{"type":"string","description":"Text content with optional placeholders resolved from Invoice data. Available placeholders: {{invoiceNumber}}, {{type}}, {{issueDate}}, {{dueDate}}, {{deliveryDate}}, {{currency}}, {{seller.name}}, {{seller.street}}, {{seller.postalCode}}, {{seller.city}}, {{seller.countryCode}}, {{seller.taxId}}, {{seller.vatId}}, {{seller.email}}, {{seller.phone}}, {{buyer.name}}, {{buyer.street}}, {{buyer.postalCode}}, {{buyer.city}}, {{buyer.countryCode}}, {{buyer.taxId}}, {{buyer.vatId}}, {{buyer.email}}, {{buyer.phone}}, {{subtotal}}, {{total}}, {{notes}}, {{paymentTerms.dueDays}}, {{paymentTerms.description}}. For array data (items, taxSummary) use a table block with dataSource instead."},"style":{"description":"Reference to a named style","type":"string"},"fontSize":{"description":"Font size in points or token","anyOf":[{"type":"number"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"fontFamily":{"description":"Font family (overrides document default)","type":"string"},"bold":{"description":"Bold text","type":"boolean"},"italic":{"description":"Italic text","type":"boolean"},"italics":{"description":"Italic text (alias)","type":"boolean"},"color":{"description":"Text color (hex or token)","anyOf":[{"type":"string"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"hideMode":{"description":"Hide block when placeholders are empty","type":"string","enum":["anyEmpty","allEmpty"]},"alignment":{"description":"Text alignment","type":"string","enum":["left","center","right","justify"]},"margin":{"description":"Margin in points: number | [h, v] | [left, top, right, bottom]","anyOf":[{"type":"array","prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]},{"type":"number"}]}},"required":["content"]}},"required":["type","data"],"description":"Text block"},{"type":"object","properties":{"type":{"type":"string","const":"spacer"},"condition":{"type":"string"},"data":{"type":"object","properties":{"height":{"type":"number","description":"Height in points"}},"required":["height"]}},"required":["type","data"],"description":"Vertical spacer block"},{"type":"object","properties":{"type":{"type":"string","const":"line"},"condition":{"type":"string"},"data":{"type":"object","properties":{"color":{"description":"Line color (hex or token)","anyOf":[{"type":"string"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"thickness":{"description":"Line thickness in points","type":"number"},"margin":{"description":"Margin in points: number | [h, v] | [left, top, right, bottom]","anyOf":[{"type":"array","prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]},{"type":"number"}]}}}},"required":["type","data"],"description":"Horizontal line block"},{"type":"object","properties":{"type":{"type":"string","const":"image"},"condition":{"type":"string"},"data":{"type":"object","properties":{"src":{"type":"string","description":"Image source: placeholder (e.g., {{logo}} for company logo), base64-encoded data URI (data:image/png;base64,...), or HTTPS URL. When using a placeholder, the image must be provided in the Invoice data under that key."},"width":{"description":"Width in points","type":"number"},"height":{"description":"Height in points","type":"number"},"fit":{"description":"Fit into [width, height] box","type":"array","prefixItems":[{"type":"number"},{"type":"number"}]},"alignment":{"description":"Alignment","type":"string","enum":["left","center","right"]}},"required":["src"]}},"required":["type","data"],"description":"Image block"},{"type":"object","properties":{"type":{"type":"string","const":"keyvalue"},"condition":{"type":"string"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Label text"},"value":{"type":"string","description":"Value text with optional placeholders resolved from Invoice data. Examples: {{invoiceNumber}}, {{issueDate}}, {{dueDate}}, {{seller.name}}, {{buyer.city}}, {{subtotal}}, {{total}}."},"labelAlign":{"type":"string","enum":["left","center","right"]},"valueAlign":{"type":"string","enum":["left","center","right"]},"optionalMode":{"description":"Behavior when value placeholder resolves to empty","type":"string","enum":["required","optional-visible","optional-hidden"]}},"required":["label","value"],"description":"Key-value pair"},"description":"Key-value items"},"layout":{"description":"Layout direction (default: vertical)","type":"string","enum":["vertical","horizontal","inline"]},"labelStyle":{"description":"Named style for labels","type":"string"},"valueStyle":{"description":"Named style for values","type":"string"},"valueAlignment":{"description":"Value alignment (vertical layout)","type":"string","enum":["left","center","right"]},"labelNoWrap":{"type":"boolean"},"valueNoWrap":{"type":"boolean"},"widths":{"description":"Column widths: [labelWidth, valueWidth]","type":"array","prefixItems":[{"anyOf":[{"type":"number"},{"type":"string","const":"*"},{"type":"string","const":"auto"}]},{"anyOf":[{"type":"number"},{"type":"string","const":"*"},{"type":"string","const":"auto"}]}]},"labelWidth":{"description":"Label width in points","type":"number"},"labelBold":{"description":"Bold labels","type":"boolean"},"labelColor":{"description":"Label text color (hex or token)","anyOf":[{"type":"string"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"valueColor":{"description":"Value text color (hex or token)","anyOf":[{"type":"string"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"fontSize":{"description":"Font size for label and value (or token)","anyOf":[{"type":"number"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]}},"required":["items"]}},"required":["type","data"],"description":"Key-value pairs block"},{"type":"object","properties":{"type":{"type":"string","const":"table"},"condition":{"type":"string"},"data":{"type":"object","properties":{"dataSource":{"type":"string","description":"Placeholder for array binding. Use {{items}} for invoice line items or {{taxSummary}} for tax breakdown. Fields available in {{items}}: position, description, articleNumber, quantity, unit, unitPrice, taxRate, taxCategoryCode, netAmount, taxAmount, grossAmount. Fields available in {{taxSummary}}: taxRate, taxCategoryCode, netAmount, taxAmount. Reference these fields in column definitions via the \"field\" property."},"repeatHeader":{"description":"Repeat header on each page","type":"boolean"},"dontBreakRows":{"description":"Don't break rows across pages","type":"boolean"},"columns":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","description":"Field name in data source items. For {{items}}: position, description, articleNumber, quantity, unit, unitPrice, taxRate, netAmount, taxAmount, grossAmount. For {{taxSummary}}: taxRate, taxCategoryCode, netAmount, taxAmount."},"header":{"type":"string","description":"Column header text"},"width":{"anyOf":[{"type":"number"},{"type":"string"}],"description":"Column width: number (pt), '*' (fill), 'auto', or percentage ('50%')"},"align":{"description":"Text alignment","type":"string","enum":["left","center","right"]},"format":{"description":"Value format (currency=2 decimals, percent=adds %)","type":"string","enum":["currency","percent","number"]},"decimalPlaces":{"description":"Decimal places for formatted values","type":"number"},"template":{"description":"Template string with placeholders (e.g., {{field:currency:2}})","type":"string"},"currencySymbol":{"description":"Show currency symbol","type":"boolean"},"locale":{"description":"Locale for number formatting (e.g., de-DE). Overrides table-level locale.","type":"string"}},"required":["field","header","width"],"description":"Table column definition"},"description":"Column definitions"},"headerStyle":{"description":"Named style for header row","type":"string"},"bodyStyle":{"description":"Named style for body rows","type":"string"},"layout":{"description":"Table border layout (default: with borders)","type":"string","enum":["noBorders","headerLineOnly","lightHorizontalLines"]},"headerFillColor":{"description":"Header background color (hex or token)","anyOf":[{"type":"string"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"headerTextColor":{"description":"Header text color (hex or token)","anyOf":[{"type":"string"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"fontSize":{"description":"Font size for table content (or token)","anyOf":[{"type":"number"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"showHeader":{"description":"Show table header row","type":"boolean"},"cellPadding":{"description":"Cell padding in points","type":"object","properties":{"left":{"type":"number"},"right":{"type":"number"},"top":{"type":"number"},"bottom":{"type":"number"}}},"locale":{"description":"Locale for number formatting (e.g., de-DE). Can be overridden per column.","type":"string"}},"required":["dataSource","columns"]}},"required":["type","data"],"description":"Data-bound table block"},{"type":"object","properties":{"type":{"type":"string","const":"summary"},"condition":{"type":"string"},"data":{"type":"object","properties":{"rows":{"description":"Simple summary rows","type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Row label"},"value":{"type":"string","description":"Value with optional placeholder (e.g., {{subtotal}}, {{total}})"},"bold":{"description":"Bold text","type":"boolean"},"fontSize":{"description":"Font size in points or token","anyOf":[{"type":"number"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"separator":{"description":"Show separator line above this row","type":"boolean"},"valueAlign":{"type":"string","enum":["left","center","right"]},"valueFormat":{"type":"string","enum":["currency","percent","number"]},"currencySymbol":{"type":"boolean"}},"required":["label","value"],"additionalProperties":{},"description":"Summary row"}},"headerRows":{"description":"Rows above dynamic section","type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Row label"},"value":{"type":"string","description":"Value with optional placeholder (e.g., {{subtotal}}, {{total}})"},"bold":{"description":"Bold text","type":"boolean"},"fontSize":{"description":"Font size in points or token","anyOf":[{"type":"number"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"separator":{"description":"Show separator line above this row","type":"boolean"},"valueAlign":{"type":"string","enum":["left","center","right"]},"valueFormat":{"type":"string","enum":["currency","percent","number"]},"currencySymbol":{"type":"boolean"}},"required":["label","value"],"additionalProperties":{},"description":"Summary row"}},"dynamicRows":{"description":"Dynamic rows from array data","type":"object","properties":{"dataSource":{"type":"string","description":"Placeholder for array (e.g., {{taxSummary}})"},"valueField":{"type":"string","description":"Field name for value (e.g., taxAmount)"},"valueFormat":{"type":"string","enum":["currency","percent","number"]},"labelTemplate":{"description":"Label template (e.g., \"MwSt: {{taxRate}}%\")","type":"string"},"currencySymbol":{"type":"boolean"}},"required":["dataSource","valueField"],"additionalProperties":{}},"footerRows":{"description":"Rows below dynamic section (e.g., total)","type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Row label"},"value":{"type":"string","description":"Value with optional placeholder (e.g., {{subtotal}}, {{total}})"},"bold":{"description":"Bold text","type":"boolean"},"fontSize":{"description":"Font size in points or token","anyOf":[{"type":"number"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"separator":{"description":"Show separator line above this row","type":"boolean"},"valueAlign":{"type":"string","enum":["left","center","right"]},"valueFormat":{"type":"string","enum":["currency","percent","number"]},"currencySymbol":{"type":"boolean"}},"required":["label","value"],"additionalProperties":{},"description":"Summary row"}},"width":{"description":"Total width of the summary block (e.g., '50%', 250)","anyOf":[{"type":"number"},{"type":"string"}]},"widths":{"description":"Column widths: [labelWidth, valueWidth]","type":"array","items":{"anyOf":[{"type":"number"},{"type":"string","const":"*"},{"type":"string","const":"auto"}]}},"alignment":{"description":"Horizontal alignment of the block (default: right)","type":"string","enum":["left","center","right"]},"labelWidth":{"description":"Label column width","anyOf":[{"type":"number"},{"type":"string"}]},"valueWidth":{"description":"Value column width","anyOf":[{"type":"number"},{"type":"string"}]},"labelColor":{"description":"Label text color","anyOf":[{"type":"string"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"valueColor":{"description":"Value text color","anyOf":[{"type":"string"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"fontSize":{"description":"Default font size or token","anyOf":[{"type":"number"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"separatorBeforeFooter":{"description":"Show separator line before footer rows","type":"boolean"},"locale":{"description":"Locale for number formatting (e.g., de-DE)","type":"string"}}}},"required":["type","data"],"description":"Summary block for totals (subtotal, tax, total)"},{"type":"object","properties":{"type":{"type":"string","const":"qrcode"},"condition":{"type":"string"},"data":{"type":"object","properties":{"content":{"type":"string","description":"QR code content with optional placeholders. Example for Swiss QR-Bill: \"SPC\\n0200\\n1\\n{{seller.iban}}\\nK\\n{{seller.name}}\\n{{seller.street}}\\n{{seller.postalCode}} {{seller.city}}\\n\\n\\nCH\\n\\n\\n\\n\\n\\n\\n\\n{{total}}\\n{{currency}}\". Any Invoice placeholder can be used (e.g., {{invoiceNumber}}, {{total}}, {{buyer.name}})."},"size":{"description":"Size in points","type":"number"},"alignment":{"description":"Alignment","type":"string","enum":["left","center","right"]},"foreground":{"description":"Foreground color (hex)","type":"string"},"background":{"description":"Background color (hex)","type":"string"},"eccLevel":{"description":"Error correction level (L=7%, M=15%, Q=25%, H=30%)","type":"string","enum":["L","M","Q","H"]}},"required":["content"]}},"required":["type","data"],"description":"QR code block"},{"type":"object","properties":{"type":{"type":"string","const":"columns"},"condition":{"type":"string"},"data":{"type":"object","properties":{"columns":{"type":"array","items":{"type":"object","properties":{"width":{"anyOf":[{"type":"number"},{"type":"string"}],"description":"Column width: number (pt), percentage ('50%'), '*', or 'auto'"},"blocks":{"type":"array","items":{},"description":"Blocks in this column (same block types as top-level, recursive)"}},"required":["width","blocks"]},"description":"Column definitions"},"columnGap":{"description":"Gap between columns in points","type":"number"}},"required":["columns"]}},"required":["type","data"],"description":"Multi-column layout block"}],"description":"Template block (text | table | columns | keyvalue | summary | image | spacer | line | qrcode)"},"description":"Blocks in this section"},"repeatOnAllPages":{"description":"Repeat on all pages (header/footer only, default: last page only)","type":"boolean"}},"required":["blocks"]},"body":{"type":"object","properties":{"blocks":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"condition":{"description":"Conditional rendering: block is only rendered when the placeholder resolves to a non-empty value. Use any scalar placeholder, e.g., {{notes}}, {{deliveryDate}}, {{buyer.taxId}}.","type":"string"},"data":{"type":"object","properties":{"content":{"type":"string","description":"Text content with optional placeholders resolved from Invoice data. Available placeholders: {{invoiceNumber}}, {{type}}, {{issueDate}}, {{dueDate}}, {{deliveryDate}}, {{currency}}, {{seller.name}}, {{seller.street}}, {{seller.postalCode}}, {{seller.city}}, {{seller.countryCode}}, {{seller.taxId}}, {{seller.vatId}}, {{seller.email}}, {{seller.phone}}, {{buyer.name}}, {{buyer.street}}, {{buyer.postalCode}}, {{buyer.city}}, {{buyer.countryCode}}, {{buyer.taxId}}, {{buyer.vatId}}, {{buyer.email}}, {{buyer.phone}}, {{subtotal}}, {{total}}, {{notes}}, {{paymentTerms.dueDays}}, {{paymentTerms.description}}. For array data (items, taxSummary) use a table block with dataSource instead."},"style":{"description":"Reference to a named style","type":"string"},"fontSize":{"description":"Font size in points or token","anyOf":[{"type":"number"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"fontFamily":{"description":"Font family (overrides document default)","type":"string"},"bold":{"description":"Bold text","type":"boolean"},"italic":{"description":"Italic text","type":"boolean"},"italics":{"description":"Italic text (alias)","type":"boolean"},"color":{"description":"Text color (hex or token)","anyOf":[{"type":"string"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"hideMode":{"description":"Hide block when placeholders are empty","type":"string","enum":["anyEmpty","allEmpty"]},"alignment":{"description":"Text alignment","type":"string","enum":["left","center","right","justify"]},"margin":{"description":"Margin in points: number | [h, v] | [left, top, right, bottom]","anyOf":[{"type":"array","prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]},{"type":"number"}]}},"required":["content"]}},"required":["type","data"],"description":"Text block"},{"type":"object","properties":{"type":{"type":"string","const":"spacer"},"condition":{"type":"string"},"data":{"type":"object","properties":{"height":{"type":"number","description":"Height in points"}},"required":["height"]}},"required":["type","data"],"description":"Vertical spacer block"},{"type":"object","properties":{"type":{"type":"string","const":"line"},"condition":{"type":"string"},"data":{"type":"object","properties":{"color":{"description":"Line color (hex or token)","anyOf":[{"type":"string"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"thickness":{"description":"Line thickness in points","type":"number"},"margin":{"description":"Margin in points: number | [h, v] | [left, top, right, bottom]","anyOf":[{"type":"array","prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]},{"type":"number"}]}}}},"required":["type","data"],"description":"Horizontal line block"},{"type":"object","properties":{"type":{"type":"string","const":"image"},"condition":{"type":"string"},"data":{"type":"object","properties":{"src":{"type":"string","description":"Image source: placeholder (e.g., {{logo}} for company logo), base64-encoded data URI (data:image/png;base64,...), or HTTPS URL. When using a placeholder, the image must be provided in the Invoice data under that key."},"width":{"description":"Width in points","type":"number"},"height":{"description":"Height in points","type":"number"},"fit":{"description":"Fit into [width, height] box","type":"array","prefixItems":[{"type":"number"},{"type":"number"}]},"alignment":{"description":"Alignment","type":"string","enum":["left","center","right"]}},"required":["src"]}},"required":["type","data"],"description":"Image block"},{"type":"object","properties":{"type":{"type":"string","const":"keyvalue"},"condition":{"type":"string"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Label text"},"value":{"type":"string","description":"Value text with optional placeholders resolved from Invoice data. Examples: {{invoiceNumber}}, {{issueDate}}, {{dueDate}}, {{seller.name}}, {{buyer.city}}, {{subtotal}}, {{total}}."},"labelAlign":{"type":"string","enum":["left","center","right"]},"valueAlign":{"type":"string","enum":["left","center","right"]},"optionalMode":{"description":"Behavior when value placeholder resolves to empty","type":"string","enum":["required","optional-visible","optional-hidden"]}},"required":["label","value"],"description":"Key-value pair"},"description":"Key-value items"},"layout":{"description":"Layout direction (default: vertical)","type":"string","enum":["vertical","horizontal","inline"]},"labelStyle":{"description":"Named style for labels","type":"string"},"valueStyle":{"description":"Named style for values","type":"string"},"valueAlignment":{"description":"Value alignment (vertical layout)","type":"string","enum":["left","center","right"]},"labelNoWrap":{"type":"boolean"},"valueNoWrap":{"type":"boolean"},"widths":{"description":"Column widths: [labelWidth, valueWidth]","type":"array","prefixItems":[{"anyOf":[{"type":"number"},{"type":"string","const":"*"},{"type":"string","const":"auto"}]},{"anyOf":[{"type":"number"},{"type":"string","const":"*"},{"type":"string","const":"auto"}]}]},"labelWidth":{"description":"Label width in points","type":"number"},"labelBold":{"description":"Bold labels","type":"boolean"},"labelColor":{"description":"Label text color (hex or token)","anyOf":[{"type":"string"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"valueColor":{"description":"Value text color (hex or token)","anyOf":[{"type":"string"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"fontSize":{"description":"Font size for label and value (or token)","anyOf":[{"type":"number"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]}},"required":["items"]}},"required":["type","data"],"description":"Key-value pairs block"},{"type":"object","properties":{"type":{"type":"string","const":"table"},"condition":{"type":"string"},"data":{"type":"object","properties":{"dataSource":{"type":"string","description":"Placeholder for array binding. Use {{items}} for invoice line items or {{taxSummary}} for tax breakdown. Fields available in {{items}}: position, description, articleNumber, quantity, unit, unitPrice, taxRate, taxCategoryCode, netAmount, taxAmount, grossAmount. Fields available in {{taxSummary}}: taxRate, taxCategoryCode, netAmount, taxAmount. Reference these fields in column definitions via the \"field\" property."},"repeatHeader":{"description":"Repeat header on each page","type":"boolean"},"dontBreakRows":{"description":"Don't break rows across pages","type":"boolean"},"columns":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","description":"Field name in data source items. For {{items}}: position, description, articleNumber, quantity, unit, unitPrice, taxRate, netAmount, taxAmount, grossAmount. For {{taxSummary}}: taxRate, taxCategoryCode, netAmount, taxAmount."},"header":{"type":"string","description":"Column header text"},"width":{"anyOf":[{"type":"number"},{"type":"string"}],"description":"Column width: number (pt), '*' (fill), 'auto', or percentage ('50%')"},"align":{"description":"Text alignment","type":"string","enum":["left","center","right"]},"format":{"description":"Value format (currency=2 decimals, percent=adds %)","type":"string","enum":["currency","percent","number"]},"decimalPlaces":{"description":"Decimal places for formatted values","type":"number"},"template":{"description":"Template string with placeholders (e.g., {{field:currency:2}})","type":"string"},"currencySymbol":{"description":"Show currency symbol","type":"boolean"},"locale":{"description":"Locale for number formatting (e.g., de-DE). Overrides table-level locale.","type":"string"}},"required":["field","header","width"],"description":"Table column definition"},"description":"Column definitions"},"headerStyle":{"description":"Named style for header row","type":"string"},"bodyStyle":{"description":"Named style for body rows","type":"string"},"layout":{"description":"Table border layout (default: with borders)","type":"string","enum":["noBorders","headerLineOnly","lightHorizontalLines"]},"headerFillColor":{"description":"Header background color (hex or token)","anyOf":[{"type":"string"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"headerTextColor":{"description":"Header text color (hex or token)","anyOf":[{"type":"string"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"fontSize":{"description":"Font size for table content (or token)","anyOf":[{"type":"number"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"showHeader":{"description":"Show table header row","type":"boolean"},"cellPadding":{"description":"Cell padding in points","type":"object","properties":{"left":{"type":"number"},"right":{"type":"number"},"top":{"type":"number"},"bottom":{"type":"number"}}},"locale":{"description":"Locale for number formatting (e.g., de-DE). Can be overridden per column.","type":"string"}},"required":["dataSource","columns"]}},"required":["type","data"],"description":"Data-bound table block"},{"type":"object","properties":{"type":{"type":"string","const":"summary"},"condition":{"type":"string"},"data":{"type":"object","properties":{"rows":{"description":"Simple summary rows","type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Row label"},"value":{"type":"string","description":"Value with optional placeholder (e.g., {{subtotal}}, {{total}})"},"bold":{"description":"Bold text","type":"boolean"},"fontSize":{"description":"Font size in points or token","anyOf":[{"type":"number"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"separator":{"description":"Show separator line above this row","type":"boolean"},"valueAlign":{"type":"string","enum":["left","center","right"]},"valueFormat":{"type":"string","enum":["currency","percent","number"]},"currencySymbol":{"type":"boolean"}},"required":["label","value"],"additionalProperties":{},"description":"Summary row"}},"headerRows":{"description":"Rows above dynamic section","type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Row label"},"value":{"type":"string","description":"Value with optional placeholder (e.g., {{subtotal}}, {{total}})"},"bold":{"description":"Bold text","type":"boolean"},"fontSize":{"description":"Font size in points or token","anyOf":[{"type":"number"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"separator":{"description":"Show separator line above this row","type":"boolean"},"valueAlign":{"type":"string","enum":["left","center","right"]},"valueFormat":{"type":"string","enum":["currency","percent","number"]},"currencySymbol":{"type":"boolean"}},"required":["label","value"],"additionalProperties":{},"description":"Summary row"}},"dynamicRows":{"description":"Dynamic rows from array data","type":"object","properties":{"dataSource":{"type":"string","description":"Placeholder for array (e.g., {{taxSummary}})"},"valueField":{"type":"string","description":"Field name for value (e.g., taxAmount)"},"valueFormat":{"type":"string","enum":["currency","percent","number"]},"labelTemplate":{"description":"Label template (e.g., \"MwSt: {{taxRate}}%\")","type":"string"},"currencySymbol":{"type":"boolean"}},"required":["dataSource","valueField"],"additionalProperties":{}},"footerRows":{"description":"Rows below dynamic section (e.g., total)","type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Row label"},"value":{"type":"string","description":"Value with optional placeholder (e.g., {{subtotal}}, {{total}})"},"bold":{"description":"Bold text","type":"boolean"},"fontSize":{"description":"Font size in points or token","anyOf":[{"type":"number"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"separator":{"description":"Show separator line above this row","type":"boolean"},"valueAlign":{"type":"string","enum":["left","center","right"]},"valueFormat":{"type":"string","enum":["currency","percent","number"]},"currencySymbol":{"type":"boolean"}},"required":["label","value"],"additionalProperties":{},"description":"Summary row"}},"width":{"description":"Total width of the summary block (e.g., '50%', 250)","anyOf":[{"type":"number"},{"type":"string"}]},"widths":{"description":"Column widths: [labelWidth, valueWidth]","type":"array","items":{"anyOf":[{"type":"number"},{"type":"string","const":"*"},{"type":"string","const":"auto"}]}},"alignment":{"description":"Horizontal alignment of the block (default: right)","type":"string","enum":["left","center","right"]},"labelWidth":{"description":"Label column width","anyOf":[{"type":"number"},{"type":"string"}]},"valueWidth":{"description":"Value column width","anyOf":[{"type":"number"},{"type":"string"}]},"labelColor":{"description":"Label text color","anyOf":[{"type":"string"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"valueColor":{"description":"Value text color","anyOf":[{"type":"string"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"fontSize":{"description":"Default font size or token","anyOf":[{"type":"number"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"separatorBeforeFooter":{"description":"Show separator line before footer rows","type":"boolean"},"locale":{"description":"Locale for number formatting (e.g., de-DE)","type":"string"}}}},"required":["type","data"],"description":"Summary block for totals (subtotal, tax, total)"},{"type":"object","properties":{"type":{"type":"string","const":"qrcode"},"condition":{"type":"string"},"data":{"type":"object","properties":{"content":{"type":"string","description":"QR code content with optional placeholders. Example for Swiss QR-Bill: \"SPC\\n0200\\n1\\n{{seller.iban}}\\nK\\n{{seller.name}}\\n{{seller.street}}\\n{{seller.postalCode}} {{seller.city}}\\n\\n\\nCH\\n\\n\\n\\n\\n\\n\\n\\n{{total}}\\n{{currency}}\". Any Invoice placeholder can be used (e.g., {{invoiceNumber}}, {{total}}, {{buyer.name}})."},"size":{"description":"Size in points","type":"number"},"alignment":{"description":"Alignment","type":"string","enum":["left","center","right"]},"foreground":{"description":"Foreground color (hex)","type":"string"},"background":{"description":"Background color (hex)","type":"string"},"eccLevel":{"description":"Error correction level (L=7%, M=15%, Q=25%, H=30%)","type":"string","enum":["L","M","Q","H"]}},"required":["content"]}},"required":["type","data"],"description":"QR code block"},{"type":"object","properties":{"type":{"type":"string","const":"columns"},"condition":{"type":"string"},"data":{"type":"object","properties":{"columns":{"type":"array","items":{"type":"object","properties":{"width":{"anyOf":[{"type":"number"},{"type":"string"}],"description":"Column width: number (pt), percentage ('50%'), '*', or 'auto'"},"blocks":{"type":"array","items":{},"description":"Blocks in this column (same block types as top-level, recursive)"}},"required":["width","blocks"]},"description":"Column definitions"},"columnGap":{"description":"Gap between columns in points","type":"number"}},"required":["columns"]}},"required":["type","data"],"description":"Multi-column layout block"}],"description":"Template block (text | table | columns | keyvalue | summary | image | spacer | line | qrcode)"},"description":"Content blocks"}},"required":["blocks"],"description":"Body section (main content)"},"footer":{"description":"Footer section (repeated on each page)","type":"object","properties":{"height":{"description":"Height in points (for header/footer)","type":"number"},"blocks":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"condition":{"description":"Conditional rendering: block is only rendered when the placeholder resolves to a non-empty value. Use any scalar placeholder, e.g., {{notes}}, {{deliveryDate}}, {{buyer.taxId}}.","type":"string"},"data":{"type":"object","properties":{"content":{"type":"string","description":"Text content with optional placeholders resolved from Invoice data. Available placeholders: {{invoiceNumber}}, {{type}}, {{issueDate}}, {{dueDate}}, {{deliveryDate}}, {{currency}}, {{seller.name}}, {{seller.street}}, {{seller.postalCode}}, {{seller.city}}, {{seller.countryCode}}, {{seller.taxId}}, {{seller.vatId}}, {{seller.email}}, {{seller.phone}}, {{buyer.name}}, {{buyer.street}}, {{buyer.postalCode}}, {{buyer.city}}, {{buyer.countryCode}}, {{buyer.taxId}}, {{buyer.vatId}}, {{buyer.email}}, {{buyer.phone}}, {{subtotal}}, {{total}}, {{notes}}, {{paymentTerms.dueDays}}, {{paymentTerms.description}}. For array data (items, taxSummary) use a table block with dataSource instead."},"style":{"description":"Reference to a named style","type":"string"},"fontSize":{"description":"Font size in points or token","anyOf":[{"type":"number"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"fontFamily":{"description":"Font family (overrides document default)","type":"string"},"bold":{"description":"Bold text","type":"boolean"},"italic":{"description":"Italic text","type":"boolean"},"italics":{"description":"Italic text (alias)","type":"boolean"},"color":{"description":"Text color (hex or token)","anyOf":[{"type":"string"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"hideMode":{"description":"Hide block when placeholders are empty","type":"string","enum":["anyEmpty","allEmpty"]},"alignment":{"description":"Text alignment","type":"string","enum":["left","center","right","justify"]},"margin":{"description":"Margin in points: number | [h, v] | [left, top, right, bottom]","anyOf":[{"type":"array","prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]},{"type":"number"}]}},"required":["content"]}},"required":["type","data"],"description":"Text block"},{"type":"object","properties":{"type":{"type":"string","const":"spacer"},"condition":{"type":"string"},"data":{"type":"object","properties":{"height":{"type":"number","description":"Height in points"}},"required":["height"]}},"required":["type","data"],"description":"Vertical spacer block"},{"type":"object","properties":{"type":{"type":"string","const":"line"},"condition":{"type":"string"},"data":{"type":"object","properties":{"color":{"description":"Line color (hex or token)","anyOf":[{"type":"string"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"thickness":{"description":"Line thickness in points","type":"number"},"margin":{"description":"Margin in points: number | [h, v] | [left, top, right, bottom]","anyOf":[{"type":"array","prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]},{"type":"number"}]}}}},"required":["type","data"],"description":"Horizontal line block"},{"type":"object","properties":{"type":{"type":"string","const":"image"},"condition":{"type":"string"},"data":{"type":"object","properties":{"src":{"type":"string","description":"Image source: placeholder (e.g., {{logo}} for company logo), base64-encoded data URI (data:image/png;base64,...), or HTTPS URL. When using a placeholder, the image must be provided in the Invoice data under that key."},"width":{"description":"Width in points","type":"number"},"height":{"description":"Height in points","type":"number"},"fit":{"description":"Fit into [width, height] box","type":"array","prefixItems":[{"type":"number"},{"type":"number"}]},"alignment":{"description":"Alignment","type":"string","enum":["left","center","right"]}},"required":["src"]}},"required":["type","data"],"description":"Image block"},{"type":"object","properties":{"type":{"type":"string","const":"keyvalue"},"condition":{"type":"string"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Label text"},"value":{"type":"string","description":"Value text with optional placeholders resolved from Invoice data. Examples: {{invoiceNumber}}, {{issueDate}}, {{dueDate}}, {{seller.name}}, {{buyer.city}}, {{subtotal}}, {{total}}."},"labelAlign":{"type":"string","enum":["left","center","right"]},"valueAlign":{"type":"string","enum":["left","center","right"]},"optionalMode":{"description":"Behavior when value placeholder resolves to empty","type":"string","enum":["required","optional-visible","optional-hidden"]}},"required":["label","value"],"description":"Key-value pair"},"description":"Key-value items"},"layout":{"description":"Layout direction (default: vertical)","type":"string","enum":["vertical","horizontal","inline"]},"labelStyle":{"description":"Named style for labels","type":"string"},"valueStyle":{"description":"Named style for values","type":"string"},"valueAlignment":{"description":"Value alignment (vertical layout)","type":"string","enum":["left","center","right"]},"labelNoWrap":{"type":"boolean"},"valueNoWrap":{"type":"boolean"},"widths":{"description":"Column widths: [labelWidth, valueWidth]","type":"array","prefixItems":[{"anyOf":[{"type":"number"},{"type":"string","const":"*"},{"type":"string","const":"auto"}]},{"anyOf":[{"type":"number"},{"type":"string","const":"*"},{"type":"string","const":"auto"}]}]},"labelWidth":{"description":"Label width in points","type":"number"},"labelBold":{"description":"Bold labels","type":"boolean"},"labelColor":{"description":"Label text color (hex or token)","anyOf":[{"type":"string"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"valueColor":{"description":"Value text color (hex or token)","anyOf":[{"type":"string"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"fontSize":{"description":"Font size for label and value (or token)","anyOf":[{"type":"number"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]}},"required":["items"]}},"required":["type","data"],"description":"Key-value pairs block"},{"type":"object","properties":{"type":{"type":"string","const":"table"},"condition":{"type":"string"},"data":{"type":"object","properties":{"dataSource":{"type":"string","description":"Placeholder for array binding. Use {{items}} for invoice line items or {{taxSummary}} for tax breakdown. Fields available in {{items}}: position, description, articleNumber, quantity, unit, unitPrice, taxRate, taxCategoryCode, netAmount, taxAmount, grossAmount. Fields available in {{taxSummary}}: taxRate, taxCategoryCode, netAmount, taxAmount. Reference these fields in column definitions via the \"field\" property."},"repeatHeader":{"description":"Repeat header on each page","type":"boolean"},"dontBreakRows":{"description":"Don't break rows across pages","type":"boolean"},"columns":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","description":"Field name in data source items. For {{items}}: position, description, articleNumber, quantity, unit, unitPrice, taxRate, netAmount, taxAmount, grossAmount. For {{taxSummary}}: taxRate, taxCategoryCode, netAmount, taxAmount."},"header":{"type":"string","description":"Column header text"},"width":{"anyOf":[{"type":"number"},{"type":"string"}],"description":"Column width: number (pt), '*' (fill), 'auto', or percentage ('50%')"},"align":{"description":"Text alignment","type":"string","enum":["left","center","right"]},"format":{"description":"Value format (currency=2 decimals, percent=adds %)","type":"string","enum":["currency","percent","number"]},"decimalPlaces":{"description":"Decimal places for formatted values","type":"number"},"template":{"description":"Template string with placeholders (e.g., {{field:currency:2}})","type":"string"},"currencySymbol":{"description":"Show currency symbol","type":"boolean"},"locale":{"description":"Locale for number formatting (e.g., de-DE). Overrides table-level locale.","type":"string"}},"required":["field","header","width"],"description":"Table column definition"},"description":"Column definitions"},"headerStyle":{"description":"Named style for header row","type":"string"},"bodyStyle":{"description":"Named style for body rows","type":"string"},"layout":{"description":"Table border layout (default: with borders)","type":"string","enum":["noBorders","headerLineOnly","lightHorizontalLines"]},"headerFillColor":{"description":"Header background color (hex or token)","anyOf":[{"type":"string"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"headerTextColor":{"description":"Header text color (hex or token)","anyOf":[{"type":"string"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"fontSize":{"description":"Font size for table content (or token)","anyOf":[{"type":"number"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"showHeader":{"description":"Show table header row","type":"boolean"},"cellPadding":{"description":"Cell padding in points","type":"object","properties":{"left":{"type":"number"},"right":{"type":"number"},"top":{"type":"number"},"bottom":{"type":"number"}}},"locale":{"description":"Locale for number formatting (e.g., de-DE). Can be overridden per column.","type":"string"}},"required":["dataSource","columns"]}},"required":["type","data"],"description":"Data-bound table block"},{"type":"object","properties":{"type":{"type":"string","const":"summary"},"condition":{"type":"string"},"data":{"type":"object","properties":{"rows":{"description":"Simple summary rows","type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Row label"},"value":{"type":"string","description":"Value with optional placeholder (e.g., {{subtotal}}, {{total}})"},"bold":{"description":"Bold text","type":"boolean"},"fontSize":{"description":"Font size in points or token","anyOf":[{"type":"number"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"separator":{"description":"Show separator line above this row","type":"boolean"},"valueAlign":{"type":"string","enum":["left","center","right"]},"valueFormat":{"type":"string","enum":["currency","percent","number"]},"currencySymbol":{"type":"boolean"}},"required":["label","value"],"additionalProperties":{},"description":"Summary row"}},"headerRows":{"description":"Rows above dynamic section","type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Row label"},"value":{"type":"string","description":"Value with optional placeholder (e.g., {{subtotal}}, {{total}})"},"bold":{"description":"Bold text","type":"boolean"},"fontSize":{"description":"Font size in points or token","anyOf":[{"type":"number"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"separator":{"description":"Show separator line above this row","type":"boolean"},"valueAlign":{"type":"string","enum":["left","center","right"]},"valueFormat":{"type":"string","enum":["currency","percent","number"]},"currencySymbol":{"type":"boolean"}},"required":["label","value"],"additionalProperties":{},"description":"Summary row"}},"dynamicRows":{"description":"Dynamic rows from array data","type":"object","properties":{"dataSource":{"type":"string","description":"Placeholder for array (e.g., {{taxSummary}})"},"valueField":{"type":"string","description":"Field name for value (e.g., taxAmount)"},"valueFormat":{"type":"string","enum":["currency","percent","number"]},"labelTemplate":{"description":"Label template (e.g., \"MwSt: {{taxRate}}%\")","type":"string"},"currencySymbol":{"type":"boolean"}},"required":["dataSource","valueField"],"additionalProperties":{}},"footerRows":{"description":"Rows below dynamic section (e.g., total)","type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Row label"},"value":{"type":"string","description":"Value with optional placeholder (e.g., {{subtotal}}, {{total}})"},"bold":{"description":"Bold text","type":"boolean"},"fontSize":{"description":"Font size in points or token","anyOf":[{"type":"number"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"separator":{"description":"Show separator line above this row","type":"boolean"},"valueAlign":{"type":"string","enum":["left","center","right"]},"valueFormat":{"type":"string","enum":["currency","percent","number"]},"currencySymbol":{"type":"boolean"}},"required":["label","value"],"additionalProperties":{},"description":"Summary row"}},"width":{"description":"Total width of the summary block (e.g., '50%', 250)","anyOf":[{"type":"number"},{"type":"string"}]},"widths":{"description":"Column widths: [labelWidth, valueWidth]","type":"array","items":{"anyOf":[{"type":"number"},{"type":"string","const":"*"},{"type":"string","const":"auto"}]}},"alignment":{"description":"Horizontal alignment of the block (default: right)","type":"string","enum":["left","center","right"]},"labelWidth":{"description":"Label column width","anyOf":[{"type":"number"},{"type":"string"}]},"valueWidth":{"description":"Value column width","anyOf":[{"type":"number"},{"type":"string"}]},"labelColor":{"description":"Label text color","anyOf":[{"type":"string"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"valueColor":{"description":"Value text color","anyOf":[{"type":"string"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"fontSize":{"description":"Default font size or token","anyOf":[{"type":"number"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"separatorBeforeFooter":{"description":"Show separator line before footer rows","type":"boolean"},"locale":{"description":"Locale for number formatting (e.g., de-DE)","type":"string"}}}},"required":["type","data"],"description":"Summary block for totals (subtotal, tax, total)"},{"type":"object","properties":{"type":{"type":"string","const":"qrcode"},"condition":{"type":"string"},"data":{"type":"object","properties":{"content":{"type":"string","description":"QR code content with optional placeholders. Example for Swiss QR-Bill: \"SPC\\n0200\\n1\\n{{seller.iban}}\\nK\\n{{seller.name}}\\n{{seller.street}}\\n{{seller.postalCode}} {{seller.city}}\\n\\n\\nCH\\n\\n\\n\\n\\n\\n\\n\\n{{total}}\\n{{currency}}\". Any Invoice placeholder can be used (e.g., {{invoiceNumber}}, {{total}}, {{buyer.name}})."},"size":{"description":"Size in points","type":"number"},"alignment":{"description":"Alignment","type":"string","enum":["left","center","right"]},"foreground":{"description":"Foreground color (hex)","type":"string"},"background":{"description":"Background color (hex)","type":"string"},"eccLevel":{"description":"Error correction level (L=7%, M=15%, Q=25%, H=30%)","type":"string","enum":["L","M","Q","H"]}},"required":["content"]}},"required":["type","data"],"description":"QR code block"},{"type":"object","properties":{"type":{"type":"string","const":"columns"},"condition":{"type":"string"},"data":{"type":"object","properties":{"columns":{"type":"array","items":{"type":"object","properties":{"width":{"anyOf":[{"type":"number"},{"type":"string"}],"description":"Column width: number (pt), percentage ('50%'), '*', or 'auto'"},"blocks":{"type":"array","items":{},"description":"Blocks in this column (same block types as top-level, recursive)"}},"required":["width","blocks"]},"description":"Column definitions"},"columnGap":{"description":"Gap between columns in points","type":"number"}},"required":["columns"]}},"required":["type","data"],"description":"Multi-column layout block"}],"description":"Template block (text | table | columns | keyvalue | summary | image | spacer | line | qrcode)"},"description":"Blocks in this section"},"repeatOnAllPages":{"description":"Repeat on all pages (header/footer only, default: last page only)","type":"boolean"}},"required":["blocks"]},"styles":{"description":"Named styles, referenced by blocks via the style property","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"fontSize":{"description":"Font size in points or token","anyOf":[{"type":"number"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"bold":{"description":"Bold text","type":"boolean"},"italics":{"description":"Italic text","type":"boolean"},"color":{"description":"Text color (hex or token)","anyOf":[{"type":"string"},{"type":"object","properties":{"token":{"type":"string","description":"Token name from colorScheme or fontSizes"}},"required":["token"],"description":"Reference to a design token"}]},"alignment":{"description":"Text alignment","type":"string","enum":["left","center","right","justify"]},"margin":{"description":"Margin in points: number | [h, v] | [left, top, right, bottom]","anyOf":[{"type":"array","prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]},{"type":"number"}]},"lineHeight":{"description":"Line height multiplier","type":"number"},"font":{"description":"Font family name","type":"string"}},"description":"Named style configuration"}}},"required":["version","name","page","body"],"example":{"version":"1.0.0","name":"default-invoice","page":{"size":"A4","orientation":"portrait","margins":{"top":40,"right":40,"bottom":40,"left":40}},"body":{"blocks":[{"type":"text","data":{"content":"RECHNUNG","fontSize":24,"bold":true,"margin":[0,0,0,20]}},{"type":"columns","data":{"columns":[{"width":"50%","blocks":[{"type":"text","data":{"content":"AN:","fontSize":10,"bold":true}},{"type":"text","data":{"content":"{{buyer.name}}","fontSize":10,"bold":true}},{"type":"text","data":{"content":"{{buyer.street}}","fontSize":9}},{"type":"text","data":{"content":"{{buyer.postalCode}} {{buyer.city}}","fontSize":9}}]},{"width":"50%","blocks":[{"type":"text","data":{"content":"VON:","fontSize":10,"bold":true}},{"type":"text","data":{"content":"{{seller.name}}","fontSize":10,"bold":true}},{"type":"text","data":{"content":"{{seller.street}}","fontSize":9}},{"type":"text","data":{"content":"{{seller.postalCode}} {{seller.city}}","fontSize":9}}]}],"columnGap":20}},{"type":"spacer","data":{"height":20}},{"type":"keyvalue","data":{"items":[{"label":"Rechnungsnr.","value":"{{invoiceNumber}}"},{"label":"Datum","value":"{{issueDate}}"},{"label":"Fällig","value":"{{dueDate}}"}],"layout":"horizontal","labelWidth":100,"labelBold":true,"fontSize":9}},{"type":"spacer","data":{"height":20}},{"type":"table","data":{"dataSource":"{{items}}","columns":[{"field":"position","header":"Pos","width":"8%","align":"left"},{"field":"description","header":"Beschreibung","width":"40%","align":"left"},{"field":"quantity","header":"Menge","width":"12%","align":"center"},{"field":"unitPrice","header":"Einzelpreis","width":"15%","align":"right"},{"field":"netAmount","header":"Netto","width":"12%","align":"right"},{"field":"grossAmount","header":"Brutto","width":"13%","align":"right"}],"headerFillColor":"#333333","headerTextColor":"#FFFFFF","fontSize":9,"layout":"lightHorizontalLines","repeatHeader":true}},{"type":"spacer","data":{"height":20}},{"type":"keyvalue","data":{"items":[{"label":"Nettobetrag","value":"{{subtotal}}"},{"label":"MwSt","value":"{{taxSummary[0].taxAmount}}"},{"label":"Gesamtbetrag","value":"{{total}}"}],"layout":"horizontal","labelWidth":100,"labelBold":true,"fontSize":10}}]}}},"zugferdProfile":{"description":"ZUGFeRD profile (e.g., EN16931). Only for zugferd format.","example":"EN16931","type":"string"},"profile":{"description":"Format profile selector. Used by `zugferd` (DE) and `facturx` (FR).\n\n- `EN16931` (default for both): full EN-16931 Comfort profile.\n- `BASIC`: minimal-required EN-16931 subset for simple invoices.\n- `EXTENDED` (ZUGFeRD only): superset with sub-line-items (BG-DEX-01), allowance-charge per category, third-party payments.\n- `BASIC_WL` / `BASIC WL` / `MINIMUM` (ZUGFeRD only): legacy/PDF-only profiles, no document-level line items. `BASIC WL` (with space) is the historical ZUGFeRD spelling; `BASIC_WL` is the canonical form.","example":"EN16931","type":"string","enum":["EN16931","BASIC","BASIC_WL","BASIC WL","EXTENDED","MINIMUM"]},"version":{"description":"Format version selector. ZUGFeRD: `2.3` (legacy), `2.4` (default) or `2.5` (latest, EN 16931 code lists v17b). Factur-X: `1.0` / `1.07` / `1.08` (default) / `1.09` (latest). All emit the same `1p0:` URN scheme — the version selects the spec edition the output claims conformance with and the validation rulebook.","example":"2.5","type":"string","enum":["1.0","1.07","1.08","1.09","2.3","2.4","2.5"]}},"additionalProperties":{}}},"required":["invoice"],"example":{"templateId":"550e8400-e29b-41d4-a716-446655440000","invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","deliveryDate":"2026-03-20","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE","taxId":"27/123/45678","vatId":"DE136695976","email":"billing@techcorp.de","phone":"+49 30 1234567","bankAccount":{"iban":"DE89370400440532013000","bic":"COBADEFFXXX","bankName":"Commerzbank"}},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE","vatId":"DE811569869","email":"invoice@muster.de"},"items":[{"position":1,"description":"Software Development Services — March 2026","articleNumber":"SVC-DEV-001","quantity":40,"unit":"HUR","unitPrice":120,"taxRate":19,"taxCategoryCode":"S","netAmount":4800,"taxAmount":912,"grossAmount":5712}],"subtotal":4800,"total":5712,"taxSummary":[{"taxRate":19,"taxCategoryCode":"S","netAmount":4800,"taxAmount":912}],"paymentTerms":{"dueDays":30,"description":"Zahlbar innerhalb von 30 Tagen ohne Abzug","earlyPaymentDiscount":{"days":10,"discountPercent":2}},"paymentMethods":[{"type":"bank_transfer","details":"SEPA-Überweisung"}],"countrySpecific":{"countryCode":"DE","buyerReference":"04011000-12345-34","paymentMeansCode":"58"},"notes":"Vielen Dank für Ihren Auftrag!"}},"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}}}}},"responses":{"200":{"description":"Invoice document generated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether generation was successful","example":true},"format":{"type":"string","description":"Output format used","example":"pdf"},"filename":{"type":"string","description":"Suggested filename","example":"INV-2026-0042.pdf"},"mimeType":{"type":"string","description":"MIME type of the document","example":"application/pdf"},"hash":{"type":"string","description":"SHA-256 hash of the document","example":"a1b2c3d4e5f6..."},"data":{"type":"string","description":"Base64 encoded document","example":"JVBERi0xLjcKJeLjz9MK..."},"embeddedXml":{"description":"Embedded XML content (for hybrid PDF formats like ZUGFeRD/Factur-X). The PDF/A-3 in `data` already contains this XML; it is exposed here for convenient display/inspection.","type":"string"},"errors":{"description":"Validation errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Validation warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}}},"required":["success","format","filename","mimeType","hash","data"]},"examples":{"pdfSuccess":{"summary":"PDF generated successfully","x-country":"de","x-format":"pdf","value":{"success":true,"format":"pdf","filename":"INV-2026-0042.pdf","mimeType":"application/pdf","hash":"a1b2c3d4e5f6...","data":"JVBERi0xLjcKJeLjz9MK..."}},"zugferdSuccess":{"summary":"ZUGFeRD generated successfully","x-country":"de","x-format":"zugferd","value":{"success":true,"format":"zugferd","filename":"INV-2026-0042-zugferd.pdf","mimeType":"application/pdf","hash":"f6e5d4c3b2a1...","data":"JVBERi0xLjcKJeLjz9MK..."}}}}}},"400":{"description":"Bad Request - Invalid invoice data or unsupported country/format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Country XY is not supported"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: pdf:de:generate"}}}},"404":{"description":"Not Found - Referenced templateId does not exist or is not accessible","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Not Found","message":"Template with ID 550e8400-e29b-41d4-a716-446655440000 not found"}}}},"422":{"description":"Unprocessable Entity - the request was well-formed but the data could not be turned into a conforming document. Either pre-generation validation failed (no output) or the generated document has spec/compliance errors. The response body still carries any generated `data` plus `errors` / `complianceErrors` so the caller can inspect the non-conforming output.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether generation was successful","example":true},"format":{"type":"string","description":"Output format used","example":"pdf"},"filename":{"type":"string","description":"Suggested filename","example":"INV-2026-0042.pdf"},"mimeType":{"type":"string","description":"MIME type of the document","example":"application/pdf"},"hash":{"type":"string","description":"SHA-256 hash of the document","example":"a1b2c3d4e5f6..."},"data":{"type":"string","description":"Base64 encoded document","example":"JVBERi0xLjcKJeLjz9MK..."},"embeddedXml":{"description":"Embedded XML content (for hybrid PDF formats like ZUGFeRD/Factur-X). The PDF/A-3 in `data` already contains this XML; it is exposed here for convenient display/inspection.","type":"string"},"errors":{"description":"Validation errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Validation warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}}},"required":["success","format","filename","mimeType","hash","data"]},"example":{"success":false,"format":"xrechnung","complianceErrors":[{"code":"BR-DE-6","message":"[BR-DE-6] Das Element \"Seller contact telephone number\" (BT-42) muss übermittelt werden."}]}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for pdf:de:generate","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error - unexpected failure while generating the document","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to generate invoice"}}}}}}},"/api/v1/invoice/de/xrechnung/parse":{"post":{"operationId":"postApiV1InvoiceDeXrechnungParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"DE — XRechnung (UBL XML)","x-country":"de","x-format":"xrechnung","value":{"data":"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHVibDpJbnZvaWNlIHhtbG5zOnVibD0idXJuOm9hc2lzOm5hbWVzOnNwZWNpZmljYXRpb246dWJsOnNjaGVtYTp4c2Q6SW52b2ljZS0yIiB4bWxuczpjYWM9InVybjpvYXNpczpuYW1lczpzcGVjaWZpY2F0aW9uOnVibDpzY2hlbWE6eHNkOkNvbW1vbkFnZ3JlZ2F0ZUNvbXBvbmVudHMtMiIgeG1sbnM6Y2JjPSJ1cm46b2FzaXM6bmFtZXM6c3BlY2lmaWNhdGlvbjp1Ymw6c2NoZW1hOnhzZDpDb21tb25CYXNpY0NvbXBvbmVudHMtMiI+CiAgPGNiYzpDdXN0b21pemF0aW9uSUQ+dXJuOmNlbi5ldTplbjE2OTMxOjIwMTcjY29tcGxpYW50I3Vybjp4ZWlua2F1Zi5kZTprb3NpdDp4cmVjaG51bmdfMy4wPC9jYmM6Q3VzdG9taXphdGlvbklEPgogIDxjYmM6UHJvZmlsZUlEPnVybjpmZGM6cGVwcG9sLmV1OjIwMTc6cG9hY2M6YmlsbGluZzowMToxLjA8L2NiYzpQcm9maWxlSUQ+CiAgPGNiYzpJRD5JTlYtMjAyNi0wMDQyPC9jYmM6SUQ+CiAgPGNiYzpJc3N1ZURhdGU+MjAyNi0wMy0yMDwvY2JjOklzc3VlRGF0ZT4KICA8Y2JjOkR1ZURhdGU+MjAyNi0wNC0xOTwvY2JjOkR1ZURhdGU+CiAgPGNiYzpJbnZvaWNlVHlwZUNvZGU+MzgwPC9jYmM6SW52b2ljZVR5cGVDb2RlPgogIDxjYmM6Tm90ZT5WaWVsZW4gRGFuayBmw7xyIElocmVuIEF1ZnRyYWchPC9jYmM6Tm90ZT4KICA8Y2JjOkRvY3VtZW50Q3VycmVuY3lDb2RlPkVVUjwvY2JjOkRvY3VtZW50Q3VycmVuY3lDb2RlPgogIDxjYmM6QnV5ZXJSZWZlcmVuY2U+MDQwMTEwMDAtMTIzNDUtMzQ8L2NiYzpCdXllclJlZmVyZW5jZT4KICA8Y2FjOk9yZGVyUmVmZXJlbmNlPgogICAgPGNiYzpJRD4wNDAxMTAwMC0xMjM0NS0zNDwvY2JjOklEPgogIDwvY2FjOk9yZGVyUmVmZXJlbmNlPgogIDxjYWM6QWNjb3VudGluZ1N1cHBsaWVyUGFydHk+CiAgICA8Y2FjOlBhcnR5PgogICAgICA8Y2JjOkVuZHBvaW50SUQgc2NoZW1lSUQ9IkVNIj5iaWxsaW5nQHRlY2hjb3JwLmRlPC9jYmM6RW5kcG9pbnRJRD4KICAgICAgPGNhYzpQYXJ0eUlkZW50aWZpY2F0aW9uPgogICAgICAgIDxjYmM6SUQ+REUxMzY2OTU5NzY8L2NiYzpJRD4KICAgICAgPC9jYWM6UGFydHlJZGVudGlmaWNhdGlvbj4KICAgICAgPGNhYzpQYXJ0eU5hbWU+CiAgICAgICAgPGNiYzpOYW1lPlRlY2hDb3JwIEdtYkg8L2NiYzpOYW1lPgogICAgICA8L2NhYzpQYXJ0eU5hbWU+CiAgICAgIDxjYWM6UG9zdGFsQWRkcmVzcz4KICAgICAgICA8Y2JjOlN0cmVldE5hbWU+S2FudHN0cmHDn2UgMTI8L2NiYzpTdHJlZXROYW1lPgogICAgICAgIDxjYmM6Q2l0eU5hbWU+QmVybGluPC9jYmM6Q2l0eU5hbWU+CiAgICAgICAgPGNiYzpQb3N0YWxab25lPjEwNjIzPC9jYmM6UG9zdGFsWm9uZT4KICAgICAgICA8Y2FjOkNvdW50cnk+CiAgICAgICAgICA8Y2JjOklkZW50aWZpY2F0aW9uQ29kZT5ERTwvY2JjOklkZW50aWZpY2F0aW9uQ29kZT4KICAgICAgICA8L2NhYzpDb3VudHJ5PgogICAgICA8L2NhYzpQb3N0YWxBZGRyZXNzPgogICAgICA8Y2FjOlBhcnR5VGF4U2NoZW1lPgogICAgICAgIDxjYmM6Q29tcGFueUlEPkRFMTM2Njk1OTc2PC9jYmM6Q29tcGFueUlEPgogICAgICAgIDxjYWM6VGF4U2NoZW1lPgogICAgICAgICAgPGNiYzpJRD5WQVQ8L2NiYzpJRD4KICAgICAgICA8L2NhYzpUYXhTY2hlbWU+CiAgICAgIDwvY2FjOlBhcnR5VGF4U2NoZW1lPgogICAgICA8Y2FjOlBhcnR5VGF4U2NoZW1lPgogICAgICAgIDxjYmM6Q29tcGFueUlEPjI3LzEyMy80NTY3ODwvY2JjOkNvbXBhbnlJRD4KICAgICAgICA8Y2FjOlRheFNjaGVtZT4KICAgICAgICAgIDxjYmM6SUQ+RkM8L2NiYzpJRD4KICAgICAgICA8L2NhYzpUYXhTY2hlbWU+CiAgICAgIDwvY2FjOlBhcnR5VGF4U2NoZW1lPgogICAgICA8Y2FjOlBhcnR5TGVnYWxFbnRpdHk+CiAgICAgICAgPGNiYzpSZWdpc3RyYXRpb25OYW1lPlRlY2hDb3JwIEdtYkg8L2NiYzpSZWdpc3RyYXRpb25OYW1lPgogICAgICAgIDxjYmM6Q29tcGFueUlEPkRFMTM2Njk1OTc2PC9jYmM6Q29tcGFueUlEPgogICAgICA8L2NhYzpQYXJ0eUxlZ2FsRW50aXR5PgogICAgICA8Y2FjOkNvbnRhY3Q+CiAgICAgICAgPGNiYzpOYW1lPlRlY2hDb3JwIEdtYkg8L2NiYzpOYW1lPgogICAgICAgIDxjYmM6VGVsZXBob25lPis0OSAzMCAxMjM0NTY3PC9jYmM6VGVsZXBob25lPgogICAgICAgIDxjYmM6RWxlY3Ryb25pY01haWw+YmlsbGluZ0B0ZWNoY29ycC5kZTwvY2JjOkVsZWN0cm9uaWNNYWlsPgogICAgICA8L2NhYzpDb250YWN0PgogICAgPC9jYWM6UGFydHk+CiAgPC9jYWM6QWNjb3VudGluZ1N1cHBsaWVyUGFydHk+CiAgPGNhYzpBY2NvdW50aW5nQ3VzdG9tZXJQYXJ0eT4KICAgIDxjYWM6UGFydHk+CiAgICAgIDxjYmM6RW5kcG9pbnRJRCBzY2hlbWVJRD0iRU0iPmludm9pY2VAbXVzdGVyLmRlPC9jYmM6RW5kcG9pbnRJRD4KICAgICAgPGNhYzpQYXJ0eU5hbWU+CiAgICAgICAgPGNiYzpOYW1lPk11c3RlciBHbWJIPC9jYmM6TmFtZT4KICAgICAgPC9jYWM6UGFydHlOYW1lPgogICAgICA8Y2FjOlBvc3RhbEFkZHJlc3M+CiAgICAgICAgPGNiYzpTdHJlZXROYW1lPkhhdXB0c3RyYcOfZSA0MjwvY2JjOlN0cmVldE5hbWU+CiAgICAgICAgPGNiYzpDaXR5TmFtZT5Nw7xuY2hlbjwvY2JjOkNpdHlOYW1lPgogICAgICAgIDxjYmM6UG9zdGFsWm9uZT44MDMzMTwvY2JjOlBvc3RhbFpvbmU+CiAgICAgICAgPGNhYzpDb3VudHJ5PgogICAgICAgICAgPGNiYzpJZGVudGlmaWNhdGlvbkNvZGU+REU8L2NiYzpJZGVudGlmaWNhdGlvbkNvZGU+CiAgICAgICAgPC9jYWM6Q291bnRyeT4KICAgICAgPC9jYWM6UG9zdGFsQWRkcmVzcz4KICAgICAgPGNhYzpQYXJ0eVRheFNjaGVtZT4KICAgICAgICA8Y2JjOkNvbXBhbnlJRD5ERTgxMTU2OTg2OTwvY2JjOkNvbXBhbnlJRD4KICAgICAgICA8Y2FjOlRheFNjaGVtZT4KICAgICAgICAgIDxjYmM6SUQ+VkFUPC9jYmM6SUQ+CiAgICAgICAgPC9jYWM6VGF4U2NoZW1lPgogICAgICA8L2NhYzpQYXJ0eVRheFNjaGVtZT4KICAgICAgPGNhYzpQYXJ0eUxlZ2FsRW50aXR5PgogICAgICAgIDxjYmM6UmVnaXN0cmF0aW9uTmFtZT5NdXN0ZXIgR21iSDwvY2JjOlJlZ2lzdHJhdGlvbk5hbWU+CiAgICAgICAgPGNiYzpDb21wYW55SUQ+REU4MTE1Njk4Njk8L2NiYzpDb21wYW55SUQ+CiAgICAgIDwvY2FjOlBhcnR5TGVnYWxFbnRpdHk+CiAgICA8L2NhYzpQYXJ0eT4KICA8L2NhYzpBY2NvdW50aW5nQ3VzdG9tZXJQYXJ0eT4KICA8Y2FjOkRlbGl2ZXJ5PgogICAgPGNiYzpBY3R1YWxEZWxpdmVyeURhdGU+MjAyNi0wMy0yMDwvY2JjOkFjdHVhbERlbGl2ZXJ5RGF0ZT4KICA8L2NhYzpEZWxpdmVyeT4KICA8Y2FjOlBheW1lbnRNZWFucz4KICAgIDxjYmM6UGF5bWVudE1lYW5zQ29kZT41ODwvY2JjOlBheW1lbnRNZWFuc0NvZGU+CiAgICA8Y2FjOlBheWVlRmluYW5jaWFsQWNjb3VudD4KICAgICAgPGNiYzpJRD5ERTg5MzcwNDAwNDQwNTMyMDEzMDAwPC9jYmM6SUQ+CiAgICAgIDxjYmM6TmFtZT5UZWNoQ29ycCBHbWJIPC9jYmM6TmFtZT4KICAgICAgPGNhYzpGaW5hbmNpYWxJbnN0aXR1dGlvbkJyYW5jaD4KICAgICAgICA8Y2JjOklEPkNPQkFERUZGWFhYPC9jYmM6SUQ+CiAgICAgIDwvY2FjOkZpbmFuY2lhbEluc3RpdHV0aW9uQnJhbmNoPgogICAgPC9jYWM6UGF5ZWVGaW5hbmNpYWxBY2NvdW50PgogIDwvY2FjOlBheW1lbnRNZWFucz4KICA8Y2FjOlBheW1lbnRUZXJtcz4KICAgIDxjYmM6Tm90ZT5aYWhsYmFyIGlubmVyaGFsYiB2b24gMzAgVGFnZW4gb2huZSBBYnp1ZzwvY2JjOk5vdGU+CiAgPC9jYWM6UGF5bWVudFRlcm1zPgogIDxjYWM6VGF4VG90YWw+CiAgICA8Y2JjOlRheEFtb3VudCBjdXJyZW5jeUlEPSJFVVIiPjkxMi4wMDwvY2JjOlRheEFtb3VudD4KICAgIDxjYWM6VGF4U3VidG90YWw+CiAgICAgIDxjYmM6VGF4YWJsZUFtb3VudCBjdXJyZW5jeUlEPSJFVVIiPjQ4MDAuMDA8L2NiYzpUYXhhYmxlQW1vdW50PgogICAgICA8Y2JjOlRheEFtb3VudCBjdXJyZW5jeUlEPSJFVVIiPjkxMi4wMDwvY2JjOlRheEFtb3VudD4KICAgICAgPGNhYzpUYXhDYXRlZ29yeT4KICAgICAgICA8Y2JjOklEPlM8L2NiYzpJRD4KICAgICAgICA8Y2JjOlBlcmNlbnQ+MTkuMDA8L2NiYzpQZXJjZW50PgogICAgICAgIDxjYWM6VGF4U2NoZW1lPgogICAgICAgICAgPGNiYzpJRD5WQVQ8L2NiYzpJRD4KICAgICAgICA8L2NhYzpUYXhTY2hlbWU+CiAgICAgIDwvY2FjOlRheENhdGVnb3J5PgogICAgPC9jYWM6VGF4U3VidG90YWw+CiAgPC9jYWM6VGF4VG90YWw+CiAgPGNhYzpMZWdhbE1vbmV0YXJ5VG90YWw+CiAgICA8Y2JjOkxpbmVFeHRlbnNpb25BbW91bnQgY3VycmVuY3lJRD0iRVVSIj40ODAwLjAwPC9jYmM6TGluZUV4dGVuc2lvbkFtb3VudD4KICAgIDxjYmM6VGF4RXhjbHVzaXZlQW1vdW50IGN1cnJlbmN5SUQ9IkVVUiI+NDgwMC4wMDwvY2JjOlRheEV4Y2x1c2l2ZUFtb3VudD4KICAgIDxjYmM6VGF4SW5jbHVzaXZlQW1vdW50IGN1cnJlbmN5SUQ9IkVVUiI+NTcxMi4wMDwvY2JjOlRheEluY2x1c2l2ZUFtb3VudD4KICAgIDxjYmM6UGF5YWJsZUFtb3VudCBjdXJyZW5jeUlEPSJFVVIiPjU3MTIuMDA8L2NiYzpQYXlhYmxlQW1vdW50PgogIDwvY2FjOkxlZ2FsTW9uZXRhcnlUb3RhbD4KICA8Y2FjOkludm9pY2VMaW5lPgogICAgPGNiYzpJRD4xPC9jYmM6SUQ+CiAgICA8Y2JjOkludm9pY2VkUXVhbnRpdHkgdW5pdENvZGU9IkhVUiI+NDA8L2NiYzpJbnZvaWNlZFF1YW50aXR5PgogICAgPGNiYzpMaW5lRXh0ZW5zaW9uQW1vdW50IGN1cnJlbmN5SUQ9IkVVUiI+NDgwMC4wMDwvY2JjOkxpbmVFeHRlbnNpb25BbW91bnQ+CiAgICA8Y2FjOkl0ZW0+CiAgICAgIDxjYmM6RGVzY3JpcHRpb24+U29mdHdhcmUgRGV2ZWxvcG1lbnQgU2VydmljZXMg4oCUIE1hcmNoIDIwMjY8L2NiYzpEZXNjcmlwdGlvbj4KICAgICAgPGNiYzpOYW1lPlNvZnR3YXJlIERldmVsb3BtZW50IFNlcnZpY2VzIOKAlCBNYXJjaCAyMDI2PC9jYmM6TmFtZT4KICAgICAgPGNhYzpTZWxsZXJzSXRlbUlkZW50aWZpY2F0aW9uPgogICAgICAgIDxjYmM6SUQ+U1ZDLURFVi0wMDE8L2NiYzpJRD4KICAgICAgPC9jYWM6U2VsbGVyc0l0ZW1JZGVudGlmaWNhdGlvbj4KICAgICAgPGNhYzpDbGFzc2lmaWVkVGF4Q2F0ZWdvcnk+CiAgICAgICAgPGNiYzpJRD5TPC9jYmM6SUQ+CiAgICAgICAgPGNiYzpQZXJjZW50PjE5LjAwPC9jYmM6UGVyY2VudD4KICAgICAgICA8Y2FjOlRheFNjaGVtZT4KICAgICAgICAgIDxjYmM6SUQ+VkFUPC9jYmM6SUQ+CiAgICAgICAgPC9jYWM6VGF4U2NoZW1lPgogICAgICA8L2NhYzpDbGFzc2lmaWVkVGF4Q2F0ZWdvcnk+CiAgICA8L2NhYzpJdGVtPgogICAgPGNhYzpQcmljZT4KICAgICAgPGNiYzpQcmljZUFtb3VudCBjdXJyZW5jeUlEPSJFVVIiPjEyMC4wMDwvY2JjOlByaWNlQW1vdW50PgogICAgPC9jYWM6UHJpY2U+CiAgPC9jYWM6SW52b2ljZUxpbmU+CjwvdWJsOkludm9pY2U+","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse DE — XRechnung (UBL XML)","description":"Parse a **DE — XRechnung (UBL XML)** document. The request body below contains a real, round-trippable sample generated from the default DE example invoice — click \"Send\" right away to see the parser turn it back into structured Invoice data. Requires `e-invoice:de:xrechnung:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/de/zugferd/parse":{"post":{"operationId":"postApiV1InvoiceDeZugferdParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"DE — ZUGFeRD (PDF with embedded CII XML)","x-country":"de","x-format":"zugferd","value":{"data":"JVBERi0xLjcKJYGBgYEKCjUgMCBvYmoKPDwKL0xlbmd0aCAyMDY5Ci9GaWx0ZXIgL0ZsYXRlRGVjb2RlCj4+CnN0cmVhbQp4nNVby24jxxXd8yvqB3znvusWYGhhJxnAiwCJZ2d4oZGoIEEUIBkg+f2guqvJlqZVImXWUBbQEFUiWOe+n6SECdN3lDCFEkRJd487Sv/b/fJrwnS/w/SPHaafdhwg6pakCORgScIQjCU8UUCmyJb+s999+MP+v3+/2//14w/p7ssOgXOokGQ2LUjFE0KOYDEuSpRdc0LA5TXa9D9JX+7+tfvw8Qulv33ZPWzBcQLyrOFHQGwZ6j0aV0EkFBCFi+gRkiuYW2S9DqIQUIvAOCKyAMLCka+CSJXAPLA85RFyDrarIDI0sGKFV4AIRLJ9Ay368PEL11fPPnyyyPrOU97x7x1tWfAPn9o5pcVyPQdQMLOlT4+7D3+iFOnTw+6X7xGREJERURBREdEQ0REx3yT8NX36affHT7u/XASNGSircx9PIGJBxFtE/DwERyBgFnTu4rgbc7cCe0ju86DSfd/ksm9yWeTjN4kKmBBb+r6976HJ7fJ4SRA0hKn0AFcdIhoDQAnUSg66grRIDdysOq0e9YxIgkjankGiyAhEpUi8Zs/kiJQRKRCpzLpB5wLqJAKUawjGkh535g5FZHX2z/Vn/vjzDiHS8vz845/rzVJv/vmyHk4VWATRF44QXsHFOQMVJfM+oCc+7uIgDjwRBiNl24LwflxMOBAZWh/w7GLG8YoRcjHbEtc3sm8LKJzN+mAuZt8vvOO3pDfnMNzcQBDNy0wjJ9JXDfYtjOeX/RiHA2LWtR87nH3tx97ImZOcHsizn3Ta0dlsZ4cIP6gWn+InJ7Y3t7WclfbwMDdG7CBOpPEV6ifWeYtInxHp7qam7eiu6KnlBDUpmUy3/r5vZ9Kekz3KaOEIZnD97bK5a756v5LR5eUixSGqknNfLi+xXteieU/sp6mxkG2L/Q8z+6sUJlbv3wX7nyH+XbNfi4FqwS3tr2ZKDo5kLmkdkpsdVxmQvgtqRIGyMEqXoklRhivIcwQnKQi21zWp2F8oqRjO9Dm6qRiEoGyZMNlNchDNblN4qElUNdvTEqfRFLgvTc0uDdGiQKwiwe1NKsA5i+oU9pqbmhLDs5Km4VLSDNmnLm2XyNtG5OJb+V2Aj1g6ql3wn1sA4MZ9niV0fQLUCMLR/BUC7poLqOZ/f5MyxFIGLj53/7LSYbwHUo0zUOSaB3ZJfVhZ0+KPn3q8ThNEiaESbelxNZI4nn5dP/izn3Ta0dP6oTsQWWNaDSWuAWrz+sf1YOIqqLauf1wPJ66BavP6x9WA4hqgtm5f1cnDIV0kFVryAspARL6ZB9nlu4DHYN67+GH2PkxzIGdubsif+dZB7WQMsCji1EXJNc14ljqxPv27ImSbqZmC36En1VKUAei9gGUMfJ3Hc6l8k74LyFHq2GciAZG9ZVTWsqnLw2QskJUy9nWQ85jbGQG55NIX8RS5NxTv0F4cgMywDljZc198T2qUy1dKnoEpLEsfBZ5aKp93+yqj7PqnN9RhJ6SDTpAtkMvrtzcpcByL7gE6oUWhTJD6tlIu33knA8Oc6RVeVGd9+7T5MJgnZg5CItHX0LN5chn9JcglF6UkWcEQY7MR9bl52BoItHqYGjbmkmIKf5fvgBjjIs8usivIs26YzPLsIRug42tpWY2ETC/FgpqITIGzxsgxKxg1eyRTqUtcHTSz70PkMeN94wAsVqfWXRT7ox/8hvrRQfRMPxBsq9Q5CFwjQy5FaqUjU+ANKcfT0yf2mxdtfeS6UDj/mkvruzKYyxk9gCF9WaMCrlGTqx6ipSSoVliT75qp1kSaW5J9Wpv7bK1jLQW9j8yvEGUOs1pHUOHYBJab8LQZ5rPJDC2DylVva/rf+n081zmD9gtY60ahblvz/Qy/wqwSnuap9+N2VBRcUfUVUMuOQT4OGyc+3q9AjqlKOQTrUm8PndbOpLDWxbRmNDSmiKpj6GzFwruISIcFBdK6g4ccpc+T/U1dsaRsdVmuzZj4YVWKj9lJY6s95S5vmn0OLCipKKgi95ValsZ2A0LN8Cf/+tC6AFvKfq7PvfJyTS6THuDWcg3HTVIHCc+z7azXCri0wdhtS3tOm6kOJqsctup6hE2hvDQ3etLI5U2ePAeD5rI5dJfWSTk0vq6zUZcLuCETdcEuKe0AAEVAMhbSLoBBS7slwOd9wlepl3n0PTU4BvUpuQAVJyx9xeGj45kSPX/DRt8JZRcGlEJZI+USdXVnczWgRhINEClxbEFPsGJIvb6GFbn2zjdXQOs2Ld4NqEUzqBSctPXl25cuKS8iGsCHuj7soV3hiLaO5H5MZR51FsVFqItiYLpTl1Y4xKXPh0NnsvFDbDZmObdKOUcuPf24XemGHRPomldIPm7tHXKPaAMTnyvOalsSbyhCOjPq7AxibXBncz1+OPuqHp8+c9yKvgagip7scBZGSXnKqBEBU8AyVSfdAfmNtvbFa13jv4v0ooN1Ns+B9TQ4WnnRMYyP7Md1/Q6WbxTX65hR3EqmngLL7bGvOyCOMmeIqWPVA1G3u6qbm8YCPqzBzEbgWEeMXb8jc1YxqYw2lbmfY6u03rP4kNnjSmQdK6pf06lGLiftwL0VQEeB1zv/y7x8qowv34WUgiBhql2RXS3MnkVAzzHezm5BPs9GMGzCkiGKcf0G+MtgDgbAS73fFH75fsT6uxLtb1mMZRnO2zEdnJ+RnH3F2U7cLQO5ipDVc+7iqEnL3VHKC5Plvj375RnJKGKIyLSZRywZVTnu6lT7kIdj87nalOITgP8HkmpPggplbmRzdHJlYW0KZW5kb2JqCgoxNyAwIG9iago8PAovTGVuZ3RoIDk0MDIKL0ZpbHRlciAvRmxhdGVEZWNvZGUKPj4Kc3RyZWFtCnicjXoHeFPnuf/7feccDUsesi0bEOYccZAMyFu2vLAtPGQb422DZDwkyxNsbMQwYcQGwojYeyR2Fvm3hIxjEsCmbQoNoaRp0ibdbdL23o7n35a2t+29vfeCJd3nO0cyo+OpOevb37t+7/t+YpNnczcoYQwoiOrrdnWB9Pc8AFj6+rpdwfKnALBoYMgdKv8VAPYNurYOS0W0AwA495ZNXLBMxvuHPd3BdnwBAH/cO/BUj1Rm+gAWfNw3uGmrVF5kAUCKnuHeQalsKASI3AcIACjqzCcZ3yzriFz2X6BTiK23/0OTQt6/ansj8v483/eU6YqNAKAELC0OIB/wqwGUK+7P869Qpivgib9iAMiAbnge/oJ4NIwuoovoL7gWv4y/gX9ClVBnqf+kWbqd/oiZx+xiLjBvMv9fliLrkW2TjctuyxfIR+TfV8xXVCmOKj5S/EUpVyYrC5UO5WXl+8pPwhrCRsPGVYxqhWqn6nN1uHqpekR9KnxZ+NHw70SgiJyIZyLeiPhJpDwyL7JXpK8YLoEWtoAcMERBKhBO/TpyM1CAZABaRoBYctN5EAsQuBe6/c7AfzECaAECvwOAr8BNGIdxuAFn4SwkiqV98GW4DDfgAnwH3obz6OdwRixdQirYDW/Ci3AITsM0XIJ4OAkXYDschJfgp2L9OFwLznIR9sHLcBmuwVfhBuyGI3ABXoYr8B04DufhDXgb3kUfIJ84dzmcg/Hg/OfhBbgEAuyCvXAQTsEluAo3IB7qwA1bYSfsgYNwDM7By/AmfBd+ioywHZ6FkzAOr8I79GGIsgaeztzZvKMwwG7PD7DbCgLsU/lWduuyADuyrIDdkiVnN+cF2E15vezG3FrWkxtgN1gC7HDOR+xQToBdn93ODmZ/xA5kB9h12cns2uw5bH9mgO3LCLC9GR+xPeYA250eYLvSAqw77TLbmdbLulICrDNljO1IDbDtqSfZtuQA25oUYNeYAmzL0o9Yx9IAa18azq5eEmBXLQ6wzYmL2KbEZLbR0M42GAJsveEyW2cMsLXGMbZmUYCt5k3sSv4yW8UH2BX8KraSN7EVCwNsORdgbZyHLdMH2FK9hy1hA2zxgpPs8gUB1poQYIvmB9iC/JPW37LL8jPZvKwINtfiYXMstWy2ZSFryTrJmjOsbHqah01NWcGallrZxLk0azQsZg1m3dzWRfOiWZ6ZN7d14dwAq+cKWC5nTlwrOyeZXRAfYBPiAuz8ODmrM8+dv2ZOZtz8NfPIVzz50s4tjPt/LTHp0c2a9KjmaEeUIzxT3cxk0s1qB+1g6Q4aR9Kj9B9pKrI9olmVGdYsz5Q1o3RojnCEOWSOURlKldXKhmRUkaxDNiqjwJEKKBWG4I9AKTMVzVQmblY4sIPFHRhH4lH8R0xRViuDptAxoclUNSUPNFQJyro1AjogGBrJ01rfIsgOCNDcssY+idARx97DhyGhuEo41mi/QgEkFDsmMS6pt0/S1BHHxk1gApPJRN4bN20mBVKUKsiX9ESP/CMViFykCYmdpcq//Qx9/U2TVBL/Hu8T+psDMugCoBYzAlAgBxVEQgzEAyzX6rPMGl6j1/CaGK0+CyEeaZAZUUrfFp0F37bE+7Zgr++tPFwvPhjBYrlfxwjivc9iYVrvH2I2STdQcAlA1sAIIAMVRIHOGo7lEYxK4VHTIMceMGVkZJgyMjS5aemNZoTMiEfmGA2PyA5+/SX0Ofrsyz7hhG/zq7qbDP3qTUZ40Ea/QpaaOeC7SxbFOQAYng3coz6n84AGHWitYUgj88yhKJWKLJCaYcpIS+/WmDV8THZsBOYXpuAsjVkTuwCbMywWir8xOa86uevlTbV72s3T+txy4xZvwX3K+uAO+ikeuL6vKsV5YQDf8JVWdmTHrXkOEHQE7lFfpmsgC+KtKh1EZCxReeIj5GQxU4YmNzctfXmm0ZiYQmVlFmJzRlycls80GvmFMpk2dgGOX4C14jaMxixzcA8Uv25dy/FuS27/qTW7pzqns7orqztMWkvnyr2vN+UPne84eqfnBl23KXdlrwWxi8tytTGZK7pKrB57Ruv5tuTmnNSKxQtSExdqFjRtW12+pTm15+WWlQ7DYhtgUAbu4dXMcqBACzFWZZhG5aExJRNZQzhDBB5j1sTGxZkzLNnxMpm4M9zgu35neqGFjTeHo7jyjFJPCZ135AiSP/gwOydaSZ2Vh1tGB4hvawvco/5C14AJWGtUbwySxURHw1yV3LMIVCGWpJo72tLSywjnJZ4swFqtPkuflYL5hRFYq5WEkR0fgXHNhut7bDX7Xluz6dJA5swP8RBtXt9RtHblUlPjyMrOA+ZhfmA8tvrQTc/SZ751bEXd0VuexrMRFQfsWX1nOpdW7+/JqytxZDmXAYbDAPgcXQM0xMFca7hMqWRi5R5K5sFhHmIVGRkac1r6cg2vMRvkREARWC6XRIZs0++g1Sh+yTxrZ2miLDOxYdQem0kdmxmm82SvM9TiCnf+gs7X91YpAcG2wD36c+Y2mIh+m5YuZeZqoyjPIkYpkv9Nc3RuqriOJHTCgmiLhehFPP84/ZZsjT6L/ly35Vuv7P3ZK47qMz8+/IV/G42+FV59ZLj7lDM1f/35tt6xihj/W/h7vt8tdle2vY3QKxteQfB228Zv7KrdXbvCe3v7xqfvHKzg0+OQ7XkACg4CyJ4SuaCDDNBbNUuiccrChfEqSuZRyUO80JjNGrPGHOIHlVhIiVLS8JpMiTUG+d9UobIbwvxVKGf9xYGVY+2Z07l9tob1xQn4KztQ7uCLvav3t6XdyO0tL2i36in3zDid51dTQ185VG1qPdbjS8V3m3tS83r2JBgdF8eqUjpO9fhy8QdrupcsrWwHCg4F7tF6GQAN8yAV5loj9HFyj0ml8tBhHgBJgER/G80aOY+0QctOzJJ2Kc/KlHgr1xLWFuJDN6Jeo07nDDzf3fvc2iK1umjthZ6eiXU5NxYUD9TaeiuSVVGV29dUrSvhZHD/00+xUbvlg1MN5fveHWnd+u7+8toTHx7X1h8dLEqr783+k21XQ8HAEZDwjVHMYqjOGq6UKSiMZXLskSnIJonyS3pG7CwIrLRz5t6CW3THTapwfBx7QvgJCIyYxRH4OlCgmKQwpAYH4gj/HHz93DnAMBi4R/2WrgEd5MESq9aUtCBxQV5eZGK6yjNnbphHyUSKSJRBuEM0TxNNEKlbE4IgPgRKmti4eC1vNMbEizooAQCxQUpEANKNUpl7qmz9+dPLNrzQueVqb0zMrYgoDn+pdkdTUkpbafPuaqpWXth72L7+1TWlY+8MTeNka0dmWk1ynqctu+6lp/wKy7akKG4dZnbPzajKMDelV/SlO5b2tBWsOt6yeq8jhcjZ76RZUT+fkDMx1IiHchb18p/IWSPJGdluvIZ/k7Pu+e7eifXL1eriwed7eiYGsm8sLF+/UpRzbMXWNVWD5Quptff/yvzYd08UdOnua57hvxG032fbXlW0/ijBOaKPa2XRkEuwhNdZFDjMo0AenSpoPyEsCbE3lvB0AaWNlRA1MVvib1am5BeygvJApVO5fcfsg5c6EzMSbX39Nvebw5at7nlL+b22GlcSqVlqWZqxKrusM5O2P/gibV//6lBOxelNdevqa8zZq+taPNWeM5VaffRzcZa0uvTc1fUtW+qXtdY7ckscKYW7AEMWAF3PCKKGJlgjKLlchjGjVHtUDC1CVHRuaq45OldSNWSmECI6Wv/gl/jQ2Zf99Xh0Gv323CD1J/9nvnbqTlBT2wFoM3MbWJhrVUdFqbWMh2JZrCYzasymjIzUtPRuMt9DWrV8pgR8hDlyRJtnytHndldivqfetcs6PfDd57y3+01V7hz/tnPn9uKYzmcHcys226r2rd7+zadcb2227tn9dIHfQTBhQ+AeHcnchijgIA2soLdGhRcUGJK1WjormfEk0OGS74nOTY0O0hYURMgpy2d9siSYmNl2aY9PttOR2z/Zs+fTbSXbL/Xs+/SpG7anG5u3l5bsXLVqR8m54a9t3/ne+qGv7dj5taHpwvWVlYMFBeRZiLx7p53O6b2rjw/k974zXL/TZttZ3zRSVDSCH6x9rbPztbWjV9rbr+yuHF5eMFxdNVxYOAwYNgbu0SrmNsRDKvHZJhkbzXhkhCRTEEskM6BC7pSiNJkplGjHmtgFFDEEWmXdemlt05ENdUuXb73U33x0uHbpjfikktWW4p6yRfEpxauzSnvKFlIrf/r2X8+ULG078/2jP337zyetSxwnv+vfjHSdp9cWs+lrX9/u/1XnmUGbPnPoLcBi7HOfuQ3zIR+WWuN08xewNEBCQrQ5NXVJuCc8XBnNiPCTSiIvAn7R8YT5kur/HTXgeW2W6FZCoZk5NmQoRiOP9j/jGi3KGV5VM1IyPfzhvmfurDeve21kYuLgtX5T2c4vuju+MFYxXbKzuXl7ycqD7ZR5+YbyJk9ewfDKoWsDbdcPZO8cKFs8VLx+z/KeifU5lt6zrpWeovyta9ZsziU2fRkA/4iZAhmor8poDyLKa5LMmMky4B9N+w9iDTN1v4L+5MAX7kIgIEWazB2ZkeT2SA7L4RgAhF+ncLoGoeurwJSZCVLsQf086HXnWsOj8d/4W80/8bXINv3Wwmpk3fRSZ93YmrQbGU5b2Yb6ZKpx5o2HTrT99DpfPv56cy9xoqFI7Pd0DSQSi0yYOzdW7qFpUKoeyiMtvZtAvDnI6pApPBaH4MLi4QpGYEZubtx2dSQ/f+TqttF3BxmBWT60onljScL8ko3PWDoKnK92rzrz3uDSwffOrOqdHC4ZWF6y4dnypeXe4ZJZ+mXEQ86DeKtag+PC5B4KZkOvEPUxf5f4w39LuwzugwxmbP+A9usAaKvoh9VXAXuQ4qEk0dZbQfcKSPTXSkYAJYndKQWjlGMPZhQhsMgVhyDR1WgY5dd8/K1b+OdkOO1+MM4IDy7QPYAhAYD2MQLQ0jwgUyAl9lCKR+fpFrMZFM8jPIre+MT3q9P+l9ClrNO+X39Of4ds50Hy59Ke9gbu0QnMFbCQ+CEiac7ChUkU0J6koL0TH064ZdY+EisSUCVCk8nkIQ7Gzko12rKIKoqKOnlnkzmlrjvb2lW2iCt2l1bvbZZ1RlRvPFo3ONGTnrfxi0NbhE15hedRFHNlvOOFOz3fd53uyUx3bKtc/lRHdtVT5Wj4he7Uhmcvt/S+c2Cl6+U7PasvoMX/cYTsuSvgp/6HuQ05ZM+QE6fX56hNjCdH/dieu8WNhlx0aOfZ5tBWZ3OB2AiK51F6zIt3BxYn13blWLvFLZcUDjabafvyTc+3Dkx0p+d5Lg3tFIYyE+ov/PfVmOdazn21+2fuC30Wc+uOyuXbOnPTmwfyG196prbp0BuOvmsHa7q++OlQyYbffPcLLkBQH7hHb2RuQy6w1sgwY6QlPd2k9MyJjY2kQmliaih7S8H/OHujHkGqYPo2yVbv7x14c0exbc+14Yu/2nrTdmSwd9/yxMZdLTve2Zxbse9LG7vfe6HjZl73Llv3oUo0bK615i3ganueaW4+tm7Zzg88DaOVhWtLU6qslrn8qnX7mx3HerJzhl8drFpn0+f0AYbWwD06i64BLZgg6vp8jcqTKAtmnGnpjY8yUtxb9qyWhJjfWjp2bYPn+q7S0l1XPZ5ru0qnjdWbqlduXJmYWL2xeuXGaiPWxG/+4HRj4+kPNsdvvks+7h6Krz+6vqho/dH6+LqjQ1br0FFi2wUA+EOZFjSgBa1VFauVecJlyINE0xY35OI1EsTHy4OsiyeRwEvTzS+u55azYdqsefnNSb/2XaNf3/xSo0JxlqFTW4o9R44ADSYA5jt0HjAQBpGghUXWWLkKNFSsTBmlRmEyT3QErQybPTrIEP1LNzLLEU/FxPMIxZgRTxG7S0QvoLhtc/y/Gnnp95qd/jt0xL9P+e/s+A6KYrf4P59zk9o2OTNC583suEbnzeyhdj64Q+fNnP4WdfAtQuUlAPrrjADzYIF4boFQQkRk5ALsSVAE/bCE4S59tp64K5HR+ix9SAwERLDZ/22MUp7/dv+yTV8Y8E+hiqP3Lre2vvEX/wu3xvf8/gXHzvf22yY63vZNrJ7wXekIwhQGPQD1JfE84yG+yDyUIuxJfBHpRN9Hi7/i377jJyhdu8O/9QvUSZGSvpfpPEDk5BytEpFYfXUWgIPIuOqGBKuEXmLW/cxtoCASoq7Lw2fz5I+DwTeVSSSqjSVRElp1IyLbkpWbm2XJpvPIcohNLixMNhUUEHQ4hg8ydyn+ySyGuXv/LsWfO0d6BP4TbYFPQQVhb1OSi0pLH3lkhWP5OTn55O5MXb48NcVqJRR0iEh5G3hIBBOJZZeaEo1G+VwSc8gfRnzmjyVPJ51mkOMeyZTjg1k+iZGweLil1WdRqXnrM2JzthWO3DlWW3Ps/a1Fmwti04fz6natSUtv3eXxheO/+MIPREe9GBFVefxHx1H1iR+fqNREvBQVk9n34oB/cuDFvkwqfudO/4MdOwBBgv9zlAWfQRgoJmmA1I9IGBxLYBpnZaGs1sZ+Lin+s9NrPiytTFrjspwjUcXewH+iAbqMNsLi/wKQw+LAX6mNwEB/4HfMHuZ90AAPWVAOVcBbNZUZVUx+6ZKM+AiOYTwZkpe4nRF1OyOokY2hEFYbSj6yQ0Fs1mza8S/0iUGJqL9iX2v73oryvW1t+ysO8hUWi20hX27JKudx3sOmfZViU/lCvjw7q5z/yJfbh79OV1U3HmhoONBYXU9eE9UpDWZzQ0p1aqPZ3DhTV9NAahuk14s1KY1mc0NqTSrpQ1U/OFJMe4jEVwPQ20S/roRwgty0Wq0Mxx45RbJshZRsiOmG6G+kA8ssZOa1+ix624yRujGzaYQ6uLVhpnV8fJzef/+zYww3MQEYMgDos8HMXWsNA4oiSbsUODw8GdKT5Pu9d/GJB89J1jkxARS4/M3Un+kaiIElUAg6a2SaQeXJmyf3RMgiPSAL4qCYtZo1TyaAGhSC63gtybVn0dpiyc6SgnhqxRc3fWt/ztnj6a7S05X2sXLf4vyhCXfP+XWFalXRugu9rvHh/Gl92UBV69byWFVyeZ9t5WCZns578PnRb/Tzjbb1DdbiXe1Uof997Y4PT9SW7393a+vIu/vKG059cFBbf2SgoGas6k/ZvfVpRYNHg1j3DUaAOZAAvDVaN09JqdUqFcyfO0fhiQMsWZZoWiLcNurF6F0mk8v1ifpQsK7X8HqUjbSX0L9f/MVI/dl+iz8fo1V9Xlvx4SH/z25Rjf6JD1AvI3S9d6Tr1Y3zteOVO6qani67/wd8CvlG1KHzFGZW3vOtUTK5ilErZJimsCcMhwKs+NygeBBKRCgGZSO09had5nvF/zqHAP0mxferjfiIJDGfw//Cx2ge5u7X4TvnZ14K0nuAEWAupMESa+zcJUacmIiMxgh1JPbM1+kiFKEslkQyZo1Zigwfp1UjQj1hAhV0AWJDtj5eqsaC/yhGtY07ygp2Ov2/vIU+Hxa2W1tfGazxrxxE5a27SvN2dPp/j9HWJf0nqkd+iC89l9NfWdedev8PjJDccaKn5XhruG/xuHVzXf0W63M5yu7n2w98yUWyX7J/2yMn9wnWCFVYmCwyQo49VNAspHP11KBVkJMnFEQ82jbjS7xFZfvc+H998vHxcSZG5NMRchYl2kYNnKAz6Wvi/FFX5XKKkmFIvWOOupMaPCQgBwSZM/Nw3TQV/uab6NKDz+hFBPkvBO7RKYwAS8ieEpVKnDB3bky4h8HSSUMwJ0xLX54Yo9fqKYJBD0PXRPNjoS1yn6rEv/NdSVq8va77xQ3Lcj1vbLaPb68OE9QVm2uKe2wGY9WAra0DXzXi7132b4pfXDb2zlC/sKcivftsT8NwbsqqbSvLttjTM8jOagBoo/hLRIxViRhGRnso9SMZNeKRPos2+l59D7fM3GOEvvtTzJxzxDMO+vNl32LOwnLog0RrdDTDlDfEeFxdXaq2toSEZUvSINVM4l1RU0LYEbTsGDMlC0a9FtG2KbmM5OezvglnW6ItlkWEDdFMqGt8cHQh/YjXkt2l05znB8p6l89VmE+aZTGLzXOWtS9fRMuXuJ7/4cGnv3fpqTKZPKV34ttj9qsFRtsnbece3BpbJpc3n/oIobMX7n9lR+6Dv8ojFi9PSrAWWqKL4ytbujMr15fqlMqcxv4thQM7cpoT2q3ZzupM9N+t0xfa0lt31+Glvu9XtqZHFw2dbDp9/2v7bNXHvuE7cebB+8+WL13kSU5qfOEXaOHrF9HCe5dbmyZ+6f95wLZ+ZWJCYZetomFHk6lo00vu/iuHOs1FJvf8tJzhVyUvTv3pkZPdcD1Nx6k8JpXcgyCInamh32z+BbDMvvGab07BhnHXQ3zsGN9QcENvG6hqHamIVSeX99pWDtr0nzIp9wFr/gVIBARbA/foHzK3IZF4B+lEH8Qj/W+aTd8U87F/lkWLJ0ZzbkaO/fatsU/O1Nef/+H+V385GnkzYuWhDa6T7ozk1iOu7Seq0Le8Px51Tv7v+ePn//eKc8dPjvWcrFtx4N1NJ9d9+Uh9zYnQueNr4i/rRG81MhX2yJTiybL5Mf8i/qYVdDHUb2+e+NPhU388+NWms13dZ5sYYSbx4o8HB398kfrRTKLnVEXFKdG7JgAwC4J5bDhBQlouDwsPl4FKrcYKCnuYEOISq83NNWuCZ9nkdzqEEs2IIv7xtn/B+9g0io77E6hRnPyzmY+Z1PufiOibuut+HdZNTBA7GgncY8KY22IOE2NVJsrma6ggLaFTLSzR8shvJNHUbPoYymmYsIYLP9i76wfjq5qf/8GuvT94rvGrWT0n21qO9+bk9B9vaT/RnUnJWi/6Z645ndcQfbH1IqKuO53X/b4AtO++e8BmO3B3d/ueD5612Z79QPI5dOqjZ/hymQyHqVQU9uDZWD/4G85DFEVrb1G8bxP+o08T9DMbJibw0YkJQJAHQH/MCKCCedYIOR2GaCUlyu0x/0V+7yRHBDxCyIjaUfu/+TPRD37hP+8//wv0A38mI/g+xSm+VJ8e5/q+jn+GPyEycwBQb9N5sx4yXIyIZB4RpKOhyPyPwiHq7Znf47/6Mjfgr29p8CWcO3eOYmcqD1BXzp8n8x4GoMPFPIHMm2DVhDyvUkaBJwxLuUfRrOtV4sRsyfOW36Bq/Yv9/xP5FVSX63/aiWakrMKf55f7//D+v6OuB3cw/apvNWDopv+E/8jcARXEQ8Q7lFIZqYVUs5kwt/GR6N/wyHd3TpYlJ8eSlYPeCqUczJpgsrEk+KYOQZdsBi7R/fAsrYcOPAFKuhDa8DU4jGYAmI2wTU7DQfppOMRchUvYAka6BQZJmf4aHKJHIYsehXZ6FDbQo7CRHoUOehQui/Otg8N0GrTRfXAYJ8N1Mp6ZAwn0KOylR6GLvgn19DFoxXehQEaBibHCJernoEd/hufRn+GIrAiO4flwjMyJTkIC+g/Yy3wG/fSHsJq+Axn00+Ci/wCXGAYu0YSGQ3CJ9kINPQoX6FGokafCIL0HOpgs2MqkwSEmBxKYXTBCD8AlhoY86n/AQUfAYcoB3dYV58+dPbN/395n9uzeNTb69M4d27c9tXVky+ZNGz0bhofWDw6sW9vf19vT3eXudDk72tta17Q47KtXNTc11tfV1lSvrFpRWVFuW8xGhSmT0KQqrIQv6Q5LToLJMFUJX6JKTkKCrESQi5VCrYkTrPV2fVWDvaxUp9c7dLxesAq0oYzcri6vO9TgSE4CQV4iyMgUVY18VX2LnSvzOsXG5KSqpsdKUnvObFvwS8AlTXbBZtLp9Y+Uy8XybLHiiebKUDPPCVDn9XZNAmVosgtW3SQSP5iSgw6h1uTghU4Tr+ft3Y7kpEkFqPVNzpLkpEl16Atx5QIu4aaioHMqCtyr+SkU/GqxC5yzx1GRnDQJ2CCIV+MUZPFbpW+nwLk5TpAZ+M46u1cvICevC5Yb7LxeQC6dV8/rOYdjKnBrPunN65OTJjEUT/LoQP2kFR1obLFPRYHAHWiyX8EIlziLHZOL0IF6+xQHglWsxaSWVJICRwpQhaoa7FewQuyvm7KCMCa20mKFWHZPIRDrpE7TVkDgnsJSXZS0kJEsNG0FDO4pWmqxhnrT4J5SSHVjUu/Fwd4KcE9FkZZpwAgEsVH6mwQiGWsYY1VYlVY1Dse6SUSqrjBWxQ0EoETwthqFI93kGC5pEKun0Nik0qqbEmdqCPYcAyUidWOzdVMYSLdHJnI4JEIPND+koLnF/rYawpFOfDocjmLyl5xUNolrTPxDta63C9hQNolqTE6HjidFylDGdXndgrXRTvo6dXqHTu9wlCYnEe3i7Hy3jndMxsZ6h8uEWhM/6ZIZnSavpGREtfiovOQkgTJUunmbk/QQaINAGyoFyuBexTmFTqdJoAxclM1rI3rgIr0hbhJThklEG1AhFE4iLFMLYXx3saDii2dbiqBIapGRFjlfLKA4ic9lfBk3p9/r5js5TrDW2Xt1PQ6XwLkFK+8SaL5YN0lDsV7vmIOSk7iySagxlSYnVdVPWmtNdWvsnEg+5/WWcpNW2uhyu0i5VK/j9d5gE19a6nhkRBnnFawut1PH68scYufkJL6M85bxLq5LsNYLtIEToJEn/5GqhYxparF71V18F99on7RavS7O7dJxbofO63CLPC5NTkLJSZCcxDzEoyAcYWLlBnePgA1THHQ6+U6pgtjjk3W9T1b0CJzz0Tp+BVlOfCPx7V3Bl3UJ2EBuV5dAlTTY9VyXQ1ISqBOR4h92Qo904gTKIE7ujcoPlVCwJFAGgTJ4hd7Hi32zRRu5nQJtSJF0RaCNRNfsemGtThhwmGa7uISxTs7LRfF5PHmIg8vJ7RQYQ7kw5nYROJIR3RMYwwphzM3ZO3V6h0AbbU5vSOOSkwTaOLuSsN702JQ8J6Amu17ABkKOMFbHOR2c08kJqN6u1+s4gam367keF1EuArR1Ej11LXZCtcvbaNcLQExGJ8ib7FyPq5vX6/SkzuGQuE/2SBtWCNBoF0Dn9fJeATkE2mDjelycwBgFmbGSvBijMGziXd0C5yTrca5ucayN80rcIbPpyni9w9UtYIPIS9rITWHoJA+3l3dxQpvTJDAGjTfay+V67dPQFgUCbXSvcpp4PRfF2ThR1C4drydMqCQlR35yktRRaSAdBcYgXkZh0DTZJjc8rBGvIZPUWSHOygnQYBfqQl3k4sUYhA0mAcfnCNBAiEcNLXbCfJmICgJjqHRygrXBrteR0ZyAm+xB8YjjK8lQXUhg0jAcnyMCLXGE+tB+VdJ+pUVl4qUWL6VBUBiE9SaBjs8JNssJOQ+VYNBENi2NocTtSgRQBrIUF2wRCXEGC7ShW6RJcoAcAUy9YHXx5NZNBW7W2QWrkye3w0GWV4gLkRHi1F5pYsIuGWn8e6wIriRdKnJViiQ8Wh0mXnJxz6RNIol5nPFB7k0FbgY5pw/+EZ0hVO4PWmXQ7rp1Qp/D1CWNkgURnOPcBLnd9WJ8scau1/N6uY5zC9jAuV2c0GjyuiXa9ktcXSGhA9FKZOPBJjChD4gDAfgKRB7ACYivEDBfgWa/+CsYkILPIS8lnzOJkVxAcQSMosLVXjfvdTu7JNdcZxcgR7eMBEMyUdBKUbZbCDQ12Rkd7RBVxiiMmIJaLD23mGbbR4hNykOcVJA272wjI043IumGMfjcYlL83VFexb+2mCIoTUEpthE0Mir++VKUJKAVkrhWYGnmFRJOrCA27fUSaJtsiyAWqjZqBMYYLYQZcgW5ITe4S6VB2GESoI4srRBrxGKTnRCiCorNoBLCDFGC0nBLUm2VIDdECTLDLZ3US1AZpgIBcd9Sb4kJIyaRD+QKNgdHS9o5YnIIYQYbuZ2CwmAjd9CSVEErVT+B+sHpJZkqH2/kZycjjp6fnZGUJpHa0GSndYxDCDNyUQJlyBP5aVQJciMX5c2bRHJjsANDOmBDnterCuE/gf9pACuI4SQ4vE9WCDtNyUleryL877conqwNF6uDUg6ffZPKoDmElQiqEhK/EN+kJAqQIjCGne8HMUcMJx5hjFhFTPHR2jmE9/IQJAyZQmNDfOsRTTo49onaJvtOgTYQTr1PPImADO8LjFFPbh1hnbga0fEhUzC03Umku1ucbreJ4/pdAl2CeJfgdJJvzsWR3gqjCHJer4vrd7lEHBITlznJSVUNJB5ubLHzURxaBsuk9IcPZhZ2TqAN9mW6XIeAnFOB38x3SFCFDeXkbvJyXJRGQE4vFy0gl7BXZG+wjRfreE6QGYO9CAV7TV6v1I/sXo29VY0CbSQ5WFiOLozkdaGU6pzpnzVzZLyA+Cno47fqCS+moJ1/Si/gEl7guFa7nrj6Kaie7/B6OS/n5Un+tMouPUkjmoK0+SQ+ILHMbP+E+Q7+sQr1fKJ4rqnA5fkkVXq47q7ZdUf4p8Qvb2jhKej9u8sSlUNrJMUTaKNIyxTkCMBLG6GNwbW9rd4WXs/rp2ABWT64H1KOmO8QZ3FNBU6SDf0fD6oBSwplbmRzdHJlYW0KZW5kb2JqCgoyMCAwIG9iago8PAovTGVuZ3RoIDM3NQovRmlsdGVyIC9GbGF0ZURlY29kZQo+PgpzdHJlYW0KeJxdUj1vgzAQ3fkVHtshwmADrYSQKrIw9EOlmaoOgM8IqRhknCH/vsLPTaMO4endu3d3OV9cN8fGTI7Fb3YZWnJMT0ZZ2pazHYj1NE4mSlKmpsEF5r/D3K1RXDfH9rI5mhujF1aWEWPxO43T5uyF3T2ppaf7PfZqFdnJjOzuVLc+0p7X9ZtmMo7xqKqYIh3F9XO3vnQzsdhbD40i4yZ3OZzq9i/j47ISSz1PMNKwKNrWbiDbmZGiknPOq1JrrauIjPonB1Ovb7NZybnkFfu8ocpDkQEEQHrIQzD1kAZDAQ2+HJp8QEoIJvDBoLQHgZoCBgGDQIpAWwGfHlCFANByGOQjAFqWwxcAWhYMaJtDKzC1xBAFgnlotPtSnkBLybMOWgoQHRgWkoFlYUsonYVN9IDAYEgRFGCiuD7EbkcViakzpEhsQuI/SIybYQUFuud99bW/++8L7yewn+v1vIaztWScv2l/UvsxTYauZ78u6+7yvx/FPc//CmVuZHN0cmVhbQplbmRvYmoKCjIxIDAgb2JqCjw8Ci9MZW5ndGggNzE5MgovRmlsdGVyIC9GbGF0ZURlY29kZQo+PgpzdHJlYW0KeJyNeQl4FMeV8KvqYzQaXaMTeQTdQzMjcOsenaODlkYS6EC3xIyQxIxGI4kbBpDEKYENhjFgm8OOD3xt8K7j2C4ZE8tXFjs4YMd2NrGzX9bO7/W3ca41SSz+JP8GkOb/qntGyEeyGbq6671XVe/Vq3eV2OHf6QM9TAADccM+zwBov0cAoHB42OcJwT8FgCUbt3jD8F8AoHuTZ2yrBqIWABC9IzvEEEzxs1v9vhAdbwbA7w9t3DWowVwZQMKdw5t2jGnwgosAQAa3Dm3S4NStALGHAQEAw9y/9r4Pp9fGlv0ZTBEq9dIXxiz6/VXvs7HXrTM/03sitgOAHrDGHEC3cTYKQL/5unW2Qu+JgK/8MgAgD0bhEopEVWgvOo9N2I/fZzATw3iYt5m/silsOTvI7mKPs8fZixzPmbkJ7gOe5338Gf4NXaLOqyO6d3S/iYCI5RHHIj7RG/TL9Jv0Z/RvqjJnwNOQBCOgAwxxkA0PAeBfx+4EBhAPkMQRSKSNtUMiQPBquM26g3/mCCQBBD8HgNfhIpyFs/AKPAAPQLoKHYbX4Bl4BR6CD+A8PIg+hftV6GlkgIPwHDwOx+AMvAxPQwqcgodgD9wNT8AnKv4sfC+0yrfhMDwJz8D34F/hFTgIJ+AheBJegA/gPngQnoXz8H30NppR114B34KzofUfhMfgaSBwAA7B3XAanoYL8AqkQAt4YQz2wR1wN9wL34In4Tn4ED5BVtgDR+EUnIVz8CJ7HOKU4P78fZ17K4LCntKgsLs8KOwqVYSxsqAwWlYujBTohJ32oLDDPiRsL2kW/CVBYVthUNha/J6wpTgobC7qEzYVvSdsLAoKG4oyhfVFC4R1+UFhOC8oDOW9JwzagoIvNygM5AQFb84zQn/OkODJCgrurAlhbXZQ6Ms+JfRmBoWejKCwRg4K3be/J7huDwrO26OF1cuCQtfSoNCZvkToSM8U2i19QpslKLRanhFarEGh2TohNC0JCqskWWiUnhEapKBQL3UJdZIsrFwcFFaIQaFW9As15qBQbfYLDiEoVC06JVQuCgrKwqCwPC0olJeeUv5bKCvNF+wFMUJJoV8oLmwWigoXC4UFpwRbniLk5viF7Kx6Qb5dEdJTWcFqWSpYbKbUniW3xQsSd1tqz+LUoGAWywWxeEFyj7AgU1iUEhQWJgeFtGSdYLKlpq1ZkJ+ctuY22kuhvaTUiuSnuhNy4zuNuXGd8a44V3R+VCeXz3ZGuViXwK5lcSw7zv6RZWL7YjoN+ZGduny+E+VCZ4wr0sW7xnmUzTfzW3hmOb+WH+cZcGUDyoYt8Edg9PkRnUw+7oxwYZeA12Ici8fxHzHDKAqHptC9pENumNIF2xqIvmUNQUeIpZ2+ldZuwh8h0Nm9xjmJ0AnXoePHYWFVA7m33fkCA7CwyjWJsaPVOckyJ1zbd4AMsizT7/YdOylAQQ1Be9obzftHEYg+lITUwRry691w72skDVJ/Xx4T/i0AHgYAmKUcAQZ0YIBYSIAUgMokc4HNKBnNRsmYkGQuQEhCRmRDjH5mxFSILxWmzIzgwMzzdtyqvjhSWHi9hSNqO1xYyPVcP8bt0BpgOA3A/idHYAEsBEmJN92mZ6KiDAZIS10Q4U8G7Ac5T87Liy/JtsWnlOTktpvzkpOTEnlepzOnm/MKCwvyrVbJbJTMyIKSTmPmqf/e13LS1zibi9Ga7rHy0t19s/9zg1k++x2kQ2s4MvCDezY9tU2wXFa21DZuK7+xAJ9AM/ujAUFr8CobyTaBDIISN5SA+IT4eEg16PxLwKBJYSzJtq3tzcmtWZyFCwryK7AtbxFOSjIXmAuysLQ4BiclJS7CtrzCopQYjF1jb9y1sv7OF9fteG57yc3XcBfOdreU9VaY0xs31qw+kjcubX0isfnExS1Lx98/1dR0/M2dQ88mVPprbe67Opau2NVtq1X22HrtgKApeJWZZpsgHVKVqIWpqYk6P8uCXpUqL1vOy87LyfXlFRYW2WKwdEu25OQUaZ5cuLB0bSnzSzz2w7G9U7vLy3dP7Tl4aRv+JVOwtqrOXZiSXOT+bnZH0brv+jrvv7RV2vrW/Z1DL+0q89hLffsckmO/txQAw24A5joPwMBtkKJEGXFypM7PgB9H+qkh5RltObmV1DTSKxhVPUbJSE9ocQxG67/4YRMq3/LI2pYDfbnXMrsqKr1VZh6uAw83a9DW7x9fleF5eMtMHX65qWdZfvfIHD+2CVgwQaoSHY9TDAzvN+jCDI22MEcb8w0sN0z/cmETWr7tUU/T+Jqca5mdyyv6HUuY9pvPsvZZA9p+MdAgux/cMlODX2takx7iORq8yvyVtas8k5RIZOT9CxjGoOo7O0+m2jbajFJCUWJI30abUTv4QkZ37bPE1pyBRzY137k2fzotR1kyNGoLMqU3fog+xZteuqshy/3QBvzqjKO0OSexNQAMtM12slFsEyTAMqgAkxKbYzH47bfp/DF8rB94uss8WeVaaTMm8ry02GpNL0pOpuwKjChshylJMQwVpihkg4VFBVkM1QGT+/HeT05WPHA8e5v92Kr2ncpMUdnWx33rzgyUxERXDJ7xeR/bVja9sHxtZeem0ijeUtGnVLrLF7H2G5+dfHfDkmblRI1SPtLJZMy+m7TnR6eaG4//YNSx4+KxxrbTb9+dVD/hKVq5p/FC6eAqubj/ICCoC15lLrNNUAApisEEMXnLDP6UGF3YhUpycivzrdb0LCZspUmSelo8TyVPWYSTVLVarQU2bSP44yW+/q57BovtGx92H/nB8LTcVVnRmp6Ut7pq73l3+Y4nBk69u+53rMNXWOnMQpYlpTmJCQWNw9VVI935ax72yA3Z6RUWkywtirmtddyzcnR1zrpzLkezJJUDA3sB+L0h+8oDs2JcFo+zFi/+mpXZqKHdsrSw898yNU73dRzaNP3L1LbijU+sr9+zJnc6e3VZ9dqyNPzYtqINjw6239GTcy27q6y4076Q6bv5pGqQ1AnknnsHZ7Lxa83d1CCZ1P7nDzVmuh/cOFONX2/rlpbV9QGGfQD4ZVXuZOoXvF7PJer8DD/niHOeaLPoNGl0moTJaPP0r1EXTralVvQtX8wULW3d05psYzbePM3adZ+yrFTZU8IOPndnfUQwCOPBP6GH2FbWCil/BdBBSvA60wEMtASvspgHYOE2yKYSmFk22eCXDTo/gpDNZoc95R8w0rhrH88ss29+1Nt/ergiOrpi+Iy3/+xm+7TJ3lvZtr7cwFsq1lRU9ZSmfcqJ1wEb/wFTBAxdqic3gQnssExJkjMWpS+y22PTcw3+BamRfj0Xq9ql6l80xRjjqX36jGGDlMImakxMTkmSrNaEFDWeJmruV5RCt2O1qtvDn9zeqZR25XxRMfLtwd2vb0pK/H/GBAk/6xisXrx0VVH9FgU3Rdl7D3Ssf6qvcnxq5D8wa+/IWlotK2N9hW3n9s4K9TvluPRd6NqZ1JxqWV6xtNy1dMOyvs7Czvt6ug51ZwOGyOBVvJNzAANJkKDoI40GP4sZXg1MaoRIMhck2IyaeEUpWrAowBtnHiXTC/Ol1KwYtKjZ1j6xkrUTgvQ3fptXEM8zU/qY0sNbIJSNl4QyfpISyWDM67Cfj6AHqkVaH+VglIzskhlL7Y3Lly+zv6OZHTD1JHQv9+/AQCzEvaSLnrPF9/M0Q2TyC215NHdLi61o/7W4ukqlvl6prGPtN37I2lFaUV1dUeHKlTS3UDny5yoPkxKt43kcaTAw2I9VYfKMNpqNtYURLUNou+cGs2pmM/7VjEmrN2buuHwZ77tyJRjULIF7j7dCNNCLirwFIPolBrfEIvRPXSDn59O71TEAtF/NblEX5pJaiMn+a1qqouOofD/mCKTQGIcRiomKxf6YkGSaXOaC+dWJMVy24NdnD6E93t0lJbu9sz+9gZc9/fu9e3+PhcvKtrqaXfU3FnBk9CeHj7+zETDN+2wZ2wRJIEPcS2lGgz+dD8XRnNz2WwVIKA2FnKqC5n8t7zdVH3h1ZPTVg9XVB19Rv9OLlIEah1cRhEpvdbVXWYSNKTvfPtPefubtnSk7r9DOlWMpdQf7i4v7D9alrDwwUFIycIDu+HDwT+hxmAEDRJ5ntNIjJ3d03okebqysamioqmwcK161qri4sTFsT+c4AqmQA8uUxNRlVpyejqxWVV9pJpOqsjyjTdOazWhT/a9yXmUnqbqjSYHndYy56JZSi8wpGhp/b/Y4RtVt28uKt7v+7w30h7HXD9V0/cu+NbN121Btp78kb+Pq2V9jtKVk7OHGXf+FT76U21tV13M71XWW5/Rg95k+/Uz25RJf9Yp1JS/VsP2PdN/9mgcY2Be8yubMi3Ex5mSdXzYY/GykH0ALs+pR2Iw6CYWPIb1AK0N04VPQJWnHsm865SPmfMGGs0O++300xvnODAw/tr5gekFRb43SUyHx+tKNnY6eolQerv/mNzg9aezt062Nx97c6Rh543hjy6l37kmqO9BfktE4YL/QsK+h0HMw5Cv8eo4ADwaIo76CdTGcIcIfxYJOLZ9peMsz0trZhpANSciWYJQQreGvf4rOoW9/OvPhCzNbfma5zsG/3+DIjbOslzrPzfzZNOpG6DN6/g3Bq+wJ7hKUgKDERlpjC3NzZb1/QWJiLBMui7LD2T0L/+3szoTVVGALl0wnTdV71g4/f3Blw93f3/7k5+N/Ld/T5xqxW5tGWna9OFZWf/Rfd6770VP9N3KdOx3O0TI0mllrL1ooNq872u06uaF07J3dK7cohT32ZY6SvJQlqzff7ew5NVRUvP3ZHSsGli/K6wZWtcNV824yC5UYQ2QkHxujw34Gq/EtpKXseTEuHFfYVTdvrLjBdMy4GZiBuZg38/ilS9h95Qow0ArAvMHagQE9REOaEs1GRemjeb+OYXgcD8upaYdSsk+7MxUgm5RkLmDeuPkREzdT9Qh+5fHemdiLFy/iz272PMw8dvEiPdt9s242W83yX7FAGlxjblmgmuf/dwtEm6c/wR8WbXhk0PfA8PLo6OXD9w8MPrqxcDqtrLdS6alYrIuyb+io7ClNY9Zf/wv30czvk0bePtPWEHh1a+vom8cam+/70X1JDQf6i+RGX+mbK8dWFHtpxbcheJW9xl0CmVqffPvtXGpSHONfwunVWPWuLT4UqbWyjoan+MLCr91P1IRqNBew14Q7fv7E0c/Odbc/8n+Onf98wviXqJpx3+o7V2fYPMecXZsr42d/gn878+EyT23vi4h5yncOMS/2jv70rsaxmqqJqZGhsVcmKhcuS0DmV6nljgevsiUcgWX01NP1erwwNTUh2s9hVgul2eGInZ5gTjIzVLJwDZqF022hkKpqkkcbLjYzxpmXli4eWzX0T/6y0pHzu9f8850t/FV9+aCj3Fm60FzZr3Stweey8S/enX04Md0xfmGbjxxuKFj3sG+FN19u3exQ1jfJeVSyxbNTqA9+C5EQMckCZL+Xk+vTJfK6dBrCUR8a7DiQlpX22+8O/ry2IbNnePkFQFANwBao3p6g6BHH8ayfiQplRJr/kYTMBWzBzCuzuGYmhiN3Xv+Q/eIi5fYdalDcBeAh6gLP+lHUrdzGFVgYmJ59GJdwF643sA/suvxvdEYbAFvBXQKB3jvj4qKSOD8jCDgqHLPzskPmTPUzVzFpR0sVqENsxc0c9FFTt8XWX9u6uXh6xy8ePvnuhozWzVWzb128eA5zzomh3Jp15bV7msc/2Nf/4p7qw4cOVc+eo7ljOHiVlbhLkALZdK8yL8Rzfj563l61M2LCV3GGMeZr1WSSMXERQ4+NlRz7n9/YdWqkPbN6//MbV5/a2Z4xnZhur88qdpYJiUtLGjJLnGWLmLY/PDN9f21G35l/O/qH7/7+TLXcc+rHs0Mof/Wh3lKT3Pfgptl3nYfXlqdleB4BBnqCV1kbdwkkSAeZWtXtcrrVqkuN5/ygi9asitr8+9q9XKvD6DVRC4kpoXqcSokTQjGGaSwczFpo31+5573729sf/Ml4xc7ShRlD+av2dGVmd+0avnmNibl57YW4uCsxcSvv+dkJ1H7y49P1xpi3Y+Ozek/6Zp8ZOO66Hf/56NHZPx09SutzAPaEGvFoRBKUWDUiYRqRcCjgGf9WUGJP3IxmfnHzwL8wB8/13iyjAa/p+uePccYrVwBDJgD74q0aERiG1ohIK37mbh3mJHMB/vyv+M0bu7Ra7MoVQDAYvMp+zl2CdDpTixKghol3bfK7dObf/QuGmi2+uB515C/krp8/1Nr+yMdHn/viUOz1SMfBdV0TXXJ6637nhkM16KN7/nPCc3727K6zsxfcE/91su/wCmXvhR17Np+fqK2+I5QzuZT59aWej/hysVuSbQtZmZYLaA3Hdt28UXGDveM603L5MnaH/6oFGLzsr5gM7j0wQArEvMjo9bFJkG2z0bDSPq9Gsszre6uLS6qrS4qr0Y+rS4praopLqjlXrsORm+NwZIe+zDEY4PRwmq2DVjYTmlg/7GZ3wG52O4yyR6GNXQR1/P/AXvwh7MNpMM4ehBa2BbrwdyCSbYPTOBL2ssNwWsVFwjE0A8CZ4DQbgCZcAoe5aDjNjsM+Pgin2Z9DA3sITrM8tFIctx02sMdgHL0Di9ljUM0eg++wx6CNPQbD7DHoYT+AFvZTyORKYJB7Fk4zJ8Gr1D/4rQfuv+vwoTvvOHhgYnz/vr17du8aGx3ZuWO7f9vWLZs3bdywft3w0KBvwNvvca/t6+1Z0+1yru7q7GhvbWluWtXYUF+3ckXtUiEuUp+BJg2RDsnhi8zMgMlIg0NyGDIzEOEdRKciSbMsEqXVaW5oc9ZUm8xml0kyE4WwlhraPAMBb5jgyswAonMQni7R0C41tHY7xZqAWyVmZjR0fAnS6MVztFCPYEeHk9TKJrN5HrxChefAlV8h14XJkkigJRAYmATG0uEkimkSqR3OcbeLNMsuifTLklly+lyZGZMREGXucDsyMyajwj0kriDYIU7FQf9UHHhXS1Mo1Ot2EtE96FqZmTEJ2ELUp30KCqQxre8molcUCW+R+lucATNBbskUgtuckpkgjylglsyiyzUVfCONjpbMmRmTGKomJXSkdVJBR9q7nVNxQMQjHc4XMMIOd5Vrcgk60uqcEoEoKhZTLEVSQKQANKCGNucLOEIdb5pSgEyoVFZFqLB3CoGK0wa9rAAC7xTWcHEaIytl9LJCvWyK1ShKeDQL3qkIDTehjV4aGh0B3qk4SnkZMAKiErXfJNCTUSI5JULRK1E4GpsmEUW9wCkRryAAPYLzUSgamSYnsKNNRU+hiUm9YppSV2oLjZwAPaK4iTncFAY6bN5CLpe20SOdt3bQ2e08HwXRyKS+XS5XFf1lZtRM4iZZumXWrU6CLTWTqEl2u0wSBRlLjTgQ8BKl3UnHuk1ml8nsclVnZlDrEp2SzyS5JhMTA1trSLMsTXp4q1sOaEZGTUuKs2dmEMZS55Vq3XQEYS2EtdQRxuLtEt2k3y0TxiLG1QZqqR146GhInsSMZRKxFlQBFZMI81EkUvJVEYNUNUdZDss1Ck8pOqmKoGRNzzVSjbhgXcAr9YsiUVqcQ6ZBl4eIXqJIHsJKVaZJFqrMZtcClJkh1kxCk1ydmdHQOqk0yy1rnKK6fTEQqBYnFdbq8XooXG02SeZAiCRVV7vmzagRA0TxeN0myVzjUgdnZkg1YqBG8ogDRGklrEUk0C7R/6bppnM6up2BqAFpQGp3TipKwCN6PSbR6zIFXF5Vx9WZGSgzAzIzuFvxKBSOMPVyi3eQYMuUCP1uqV9DUH/8Km7oq4hBIrrn46R6yk79IvUbqJdqBgi20OYZIIyjzWkWB1yakUCLGin+5iA0b5BIGIu6eCCuNAyhEEQYC2EsATL0ZXB4DqylzU1YS5ZmK4S1Ultzmsl6E9nokueGeMhEvxgQ4yS7RF/q5BW0uQlnWUEmvB4ajnhqe4Sz1JMJr+jsN5ldhLXWugNhi8vMIKx1jhPZLH9pSUkkqMNpJthCt0MmWkS3S3S7RYJanWazSSRcq9MsDnqocdFA26Ltp6XbSXftCbQ7zQSoy5iIrsMpDnp8ktlkpjiXS9M+lZG11BNodxIwBQJSgCAXYS214qBHJJyV8NY6+uGsZKsseXxEdFN+osenzq0VA5p26GqmGsns8vgItqi6ZK3iFIZ++vIGJI9Iet0y4SzGQHxALAk4X4beOCCs1dvlliWzGCfWiupRe0ySmSqhjkKu0swMbaDeQgcSzqI+VrJJnuzVWW5h1GeLrA2OUFcVCbQ5SUt4iE59OAvZJhOcUkygjW4etXU7qfJ5NSoQzlLnFonS5jSb6GyR4A5n6HjU+XV0qil8YNo0nFKsBlqaCM1heQ2avBpTXn2i1EdvIREWslkmbEpxiKyj27llBJtkKrQ2h1HF1TbAWCgrMURRN+IOAazFp+5JS4AiDZhmongk2kxTwYstTqK4JdpcLso+QmVEZ6hLB7SFqbp4SvwmVYQ4aY+BPnXqFuajI9VHp8pMadqWuC8rPqS9qeDFkObMoR+1GbrLu0JeGfI7n4kMu+QBbRYfiuCi6KWR29uq1hdrnGazZNaZRC/BFtHrEUm7HPBqe7tL02q9Fh2oVaJaCWoJF+5AMhCQViL6ApEgaSXB0ko015NewIAipGL60UvFkxjpCEqmwSguOirglQJe94CWmlucBIpNZbQY4tWD1qtnO0JDU4eTM7Eu1WSsZFQOWbH2HpHn6KPUJ3VhTUZQWmCOyKnLjWq2YQ29R+SIb5wViPjHmEWETpPoVRqNRtaIv8+K0Q6oXjuueqytXK/FiXrq04EADW2TvTHUQ6OsRsJZ40mkpYToLCUhKfUWslcm0EJZR6gYFexw0o0YQsdmMZBISxzRW97QTNtAdJY4wlveMGmjiMEyFQyqcmujNSWMyqoe6BMih2Zr1jkqu0ikpZY2N4mw1NIW8iRDyEujvhL1Q8trZ6r/MlGaW4wmemluRQpNoihLh5M1cS4SaRXjCGOxq/q0GojOKsYF7JNIZw0N4OgAbLEHAoZw/Kfh/2UABdRyElyBryLIPjkzIxCIiP5mSsRXsdEqOnTK0XNfigy5Q6SDGBy0fqG5SU8NIItwln1vhWKOWk7MU4yKoq44H7uA6l4XDglb5PDcsN4GVZcOzf0KtsO5j7AWqqm3aCYhyPIW4axm2kxUdSo3auNb5FBpu4+e7kF1uYOyKK7zENaBJA9xu2lf9Ih0dIRVDXKBgEdc5/GocUi9uCzIzGhoo/Vwe7dTihNRGZRp1x8pdLNwioS1OMtMJS6C3FPB36W5tFCFLSto6wiIYpyRIHdAjCfIQw6p6g3RJBUniYS3hkbRHRySAwFtHJU+Cgca2glrpXewyGJTJL3Xha9U35L/Hlmk8wmSpmBYGjNTXUxBn7TLTLBDIqLY4zTTVD8Fq9JcgYAYEAMSvT91ObU3JaIpyEmj9QGtZebGL0xzSV9CRKVRw/NMBZ9Jo1elW3wPzPEdlXapvUCY8RQMfSNbanJojWZ4hLWqe5mCYgKSJghrDfEO9AS6JbNknoJFlH1IHgrHpLnUVTxTwVNUoP8PmgrjTgplbmRzdHJlYW0KZW5kb2JqCgoyNCAwIG9iago8PAovTGVuZ3RoIDMyOAovRmlsdGVyIC9GbGF0ZURlY29kZQo+PgpzdHJlYW0KeJxdUrtuwzAM3P0VHNMhsPyKU8AwUDiLhz5QN1PRQZEoQ0AtC7Iy+O8Li2pSdLAPR/LEA8m060+90R7SNzeLAT0obaTDZb46gXDBUZsky0Fq4SMLfzFxm6RdfxrWxePUGzVD0yQA6TuOevFuhd2TnC/4sMVenUSnzQi7czeEyHC19hsnNB5Y0rYgUSVp98ztC58Q0iDd9xKN137dn7vhXvGxWoQ88IwsiVniYrlAx82IScMYY22jlFJtgkb+S0fRRf2thoaxnLfweadVHuBQERQERwIMUMdcTSyWSGIkLzgFS4KMcsRKQcFHYocAGCspl0cvBAdFQepeRoMEJbWtyERJzmrqXpO8JJ8F5XLqUMQgOSui602QM04lFb1SRdexw7H92qb7O8dt0NtR3JYors6h8eFywuK2lWmDt+Oys91U4fsBJvSwJwplbmRzdHJlYW0KZW5kb2JqCgoyNSAwIG9iago8PAovTiAzCi9MZW5ndGggNDgwCj4+CnN0cmVhbQoAAAHgbGNtcwQgAABtbnRyUkdCIFhZWiAH4gADABQACQAOAB1hY3NwTVNGVAAAAABzYXdzY3RybAAAAAAAAAAAAAAAAAAA9tYAAQAAAADTLWhhbmR56b9WWj4BtoMjhVVG90+qAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAApkZXNjAAAA/AAAACRjcHJ0AAABIAAAACJ3dHB0AAABRAAAABRjaGFkAAABWAAAACxyWFlaAAABhAAAABRnWFlaAAABmAAAABRiWFlaAAABrAAAABRyVFJDAAABwAAAACBnVFJDAAABwAAAACBiVFJDAAABwAAAACBtbHVjAAAAAAAAAAEAAAAMZW5VUwAAAAgAAAAcAHMAUgBHAEJtbHVjAAAAAAAAAAEAAAAMZW5VUwAAAAYAAAAcAEMAQwAwAABYWVogAAAAAAAA9tYAAQAAAADTLXNmMzIAAAAAAAEMPwAABd3///MmAAAHkAAA/ZL///uh///9ogAAA9wAAMBxWFlaIAAAAAAAAG+gAAA48gAAA49YWVogAAAAAAAAYpYAALeJAAAY2lhZWiAAAAAAAAAkoAAAD4UAALbEcGFyYQAAAAAAAwAAAAJmaQAA8qcAAA1ZAAAT0AAAClsKZW5kc3RyZWFtCmVuZG9iagoKMjcgMCBvYmoKPDwKL1R5cGUgL01ldGFkYXRhCi9TdWJ0eXBlIC9YTUwKL0xlbmd0aCA3MDIKPj4Kc3RyZWFtCjw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+PHg6eG1wbWV0YSB4bWxuczp4PSJhZG9iZTpuczptZXRhLyI+PHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj48cmRmOkRlc2NyaXB0aW9uIHJkZjphYm91dD0iIiB4bWxuczpwZGZhaWQ9Imh0dHA6Ly93d3cuYWlpbS5vcmcvcGRmYS9ucy9pZC8iIHhtbG5zOmRjPSJodHRwOi8vcHVybC5vcmcvZGMvZWxlbWVudHMvMS4xLyIgeG1sbnM6eG1wPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvIiB4bWxuczpwZGY9Imh0dHA6Ly9ucy5hZG9iZS5jb20vcGRmLzEuMy8iPjxwZGZhaWQ6cGFydD4zPC9wZGZhaWQ6cGFydD48cGRmYWlkOmNvbmZvcm1hbmNlPkI8L3BkZmFpZDpjb25mb3JtYW5jZT48eG1wOkNyZWF0b3JUb29sPnhodWJpby1zYWFzIHBkZi1iYWNrZW5kPC94bXA6Q3JlYXRvclRvb2w+PHhtcDpDcmVhdGVEYXRlPjIwMjYtMDgtMjNUMTg6NDE6MDlaPC94bXA6Q3JlYXRlRGF0ZT48eG1wOk1vZGlmeURhdGU+MjAyNi0wOC0yM1QxODo0MTowOVo8L3htcDpNb2RpZnlEYXRlPjxwZGY6UHJvZHVjZXI+eGh1YmlvLXNhYXMgcGRmLWJhY2tlbmQ8L3BkZjpQcm9kdWNlcj48L3JkZjpEZXNjcmlwdGlvbj48L3JkZjpSREY+PC94OnhtcG1ldGE+PD94cGFja2V0IGVuZD0idyI/PgplbmRzdHJlYW0KZW5kb2JqCgoyOCAwIG9iago8PAovVHlwZSAvRW1iZWRkZWRGaWxlCi9TdWJ0eXBlIC90ZXh0IzJGeG1sCi9QYXJhbXMgPDwKL1NpemUgNjUzOAovQ3JlYXRpb25EYXRlIChEOjIwMjYwODIzMTg0MTExWikKL01vZERhdGUgKEQ6MjAyNjA4MjMxODQxMTFaKQo+PgovTGVuZ3RoIDY1MzgKPj4Kc3RyZWFtCjw/eG1sIHZlcnNpb249IjEuMCIgZW5jb2Rpbmc9IlVURi04Ij8+Cjxyc206Q3Jvc3NJbmR1c3RyeUludm9pY2UgeG1sbnM6cnNtPSJ1cm46dW46dW5lY2U6dW5jZWZhY3Q6ZGF0YTpzdGFuZGFyZDpDcm9zc0luZHVzdHJ5SW52b2ljZToxMDAiIHhtbG5zOnFkdD0idXJuOnVuOnVuZWNlOnVuY2VmYWN0OmRhdGE6c3RhbmRhcmQ6UXVhbGlmaWVkRGF0YVR5cGU6MTAwIiB4bWxuczpyYW09InVybjp1bjp1bmVjZTp1bmNlZmFjdDpkYXRhOnN0YW5kYXJkOlJldXNhYmxlQWdncmVnYXRlQnVzaW5lc3NJbmZvcm1hdGlvbkVudGl0eToxMDAiIHhtbG5zOnVkdD0idXJuOnVuOnVuZWNlOnVuY2VmYWN0OmRhdGE6c3RhbmRhcmQ6VW5xdWFsaWZpZWREYXRhVHlwZToxMDAiPgogIDxyc206RXhjaGFuZ2VkRG9jdW1lbnRDb250ZXh0PgogICAgPHJhbTpHdWlkZWxpbmVTcGVjaWZpZWREb2N1bWVudENvbnRleHRQYXJhbWV0ZXI+CiAgICAgIDxyYW06SUQ+dXJuOmNlbi5ldTplbjE2OTMxOjIwMTc8L3JhbTpJRD4KICAgIDwvcmFtOkd1aWRlbGluZVNwZWNpZmllZERvY3VtZW50Q29udGV4dFBhcmFtZXRlcj4KICA8L3JzbTpFeGNoYW5nZWREb2N1bWVudENvbnRleHQ+CiAgPHJzbTpFeGNoYW5nZWREb2N1bWVudD4KICAgIDxyYW06SUQ+SU5WLTIwMjYtMDA0MjwvcmFtOklEPgogICAgPHJhbTpUeXBlQ29kZT4zODA8L3JhbTpUeXBlQ29kZT4KICAgIDxyYW06SXNzdWVEYXRlVGltZT4KICAgICAgPHVkdDpEYXRlVGltZVN0cmluZyBmb3JtYXQ9IjEwMiI+MjAyNjAzMjA8L3VkdDpEYXRlVGltZVN0cmluZz4KICAgIDwvcmFtOklzc3VlRGF0ZVRpbWU+CiAgICA8cmFtOkluY2x1ZGVkTm90ZT4KICAgICAgPHJhbTpDb250ZW50PlZpZWxlbiBEYW5rIGbDvHIgSWhyZW4gQXVmdHJhZyE8L3JhbTpDb250ZW50PgogICAgPC9yYW06SW5jbHVkZWROb3RlPgogIDwvcnNtOkV4Y2hhbmdlZERvY3VtZW50PgogIDxyc206U3VwcGx5Q2hhaW5UcmFkZVRyYW5zYWN0aW9uPgogICAgPHJhbTpJbmNsdWRlZFN1cHBseUNoYWluVHJhZGVMaW5lSXRlbT4KICAgICAgPHJhbTpBc3NvY2lhdGVkRG9jdW1lbnRMaW5lRG9jdW1lbnQ+CiAgICAgICAgPHJhbTpMaW5lSUQ+MTwvcmFtOkxpbmVJRD4KICAgICAgPC9yYW06QXNzb2NpYXRlZERvY3VtZW50TGluZURvY3VtZW50PgogICAgICA8cmFtOlNwZWNpZmllZFRyYWRlUHJvZHVjdD4KICAgICAgICA8cmFtOlNlbGxlckFzc2lnbmVkSUQ+U1ZDLURFVi0wMDE8L3JhbTpTZWxsZXJBc3NpZ25lZElEPgogICAgICAgIDxyYW06TmFtZT5Tb2Z0d2FyZSBEZXZlbG9wbWVudCBTZXJ2aWNlcyDigJQgTWFyY2ggMjAyNjwvcmFtOk5hbWU+CiAgICAgIDwvcmFtOlNwZWNpZmllZFRyYWRlUHJvZHVjdD4KICAgICAgPHJhbTpTcGVjaWZpZWRMaW5lVHJhZGVBZ3JlZW1lbnQ+CiAgICAgICAgPHJhbTpOZXRQcmljZVByb2R1Y3RUcmFkZVByaWNlPgogICAgICAgICAgPHJhbTpDaGFyZ2VBbW91bnQ+MTIwLjAwPC9yYW06Q2hhcmdlQW1vdW50PgogICAgICAgIDwvcmFtOk5ldFByaWNlUHJvZHVjdFRyYWRlUHJpY2U+CiAgICAgIDwvcmFtOlNwZWNpZmllZExpbmVUcmFkZUFncmVlbWVudD4KICAgICAgPHJhbTpTcGVjaWZpZWRMaW5lVHJhZGVEZWxpdmVyeT4KICAgICAgICA8cmFtOkJpbGxlZFF1YW50aXR5IHVuaXRDb2RlPSJIVVIiPjQwLjAwPC9yYW06QmlsbGVkUXVhbnRpdHk+CiAgICAgIDwvcmFtOlNwZWNpZmllZExpbmVUcmFkZURlbGl2ZXJ5PgogICAgICA8cmFtOlNwZWNpZmllZExpbmVUcmFkZVNldHRsZW1lbnQ+CiAgICAgICAgPHJhbTpBcHBsaWNhYmxlVHJhZGVUYXg+CiAgICAgICAgICA8cmFtOlR5cGVDb2RlPlZBVDwvcmFtOlR5cGVDb2RlPgogICAgICAgICAgPHJhbTpDYXRlZ29yeUNvZGU+UzwvcmFtOkNhdGVnb3J5Q29kZT4KICAgICAgICAgIDxyYW06UmF0ZUFwcGxpY2FibGVQZXJjZW50PjE5LjAwPC9yYW06UmF0ZUFwcGxpY2FibGVQZXJjZW50PgogICAgICAgIDwvcmFtOkFwcGxpY2FibGVUcmFkZVRheD4KICAgICAgICA8cmFtOlNwZWNpZmllZFRyYWRlU2V0dGxlbWVudExpbmVNb25ldGFyeVN1bW1hdGlvbj4KICAgICAgICAgIDxyYW06TGluZVRvdGFsQW1vdW50PjQ4MDAuMDA8L3JhbTpMaW5lVG90YWxBbW91bnQ+CiAgICAgICAgPC9yYW06U3BlY2lmaWVkVHJhZGVTZXR0bGVtZW50TGluZU1vbmV0YXJ5U3VtbWF0aW9uPgogICAgICA8L3JhbTpTcGVjaWZpZWRMaW5lVHJhZGVTZXR0bGVtZW50PgogICAgPC9yYW06SW5jbHVkZWRTdXBwbHlDaGFpblRyYWRlTGluZUl0ZW0+CiAgICA8cmFtOkFwcGxpY2FibGVIZWFkZXJUcmFkZUFncmVlbWVudD4KICAgICAgPHJhbTpCdXllclJlZmVyZW5jZT4wNDAxMTAwMC0xMjM0NS0zNDwvcmFtOkJ1eWVyUmVmZXJlbmNlPgogICAgICA8cmFtOlNlbGxlclRyYWRlUGFydHk+CiAgICAgICAgPHJhbTpHbG9iYWxJRCBzY2hlbWVJRD0iMDIwNCI+REUxMzY2OTU5NzY8L3JhbTpHbG9iYWxJRD4KICAgICAgICA8cmFtOk5hbWU+VGVjaENvcnAgR21iSDwvcmFtOk5hbWU+CiAgICAgICAgPHJhbTpEZWZpbmVkVHJhZGVDb250YWN0PgogICAgICAgICAgPHJhbTpUZWxlcGhvbmVVbml2ZXJzYWxDb21tdW5pY2F0aW9uPgogICAgICAgICAgICA8cmFtOkNvbXBsZXRlTnVtYmVyPis0OSAzMCAxMjM0NTY3PC9yYW06Q29tcGxldGVOdW1iZXI+CiAgICAgICAgICA8L3JhbTpUZWxlcGhvbmVVbml2ZXJzYWxDb21tdW5pY2F0aW9uPgogICAgICAgICAgPHJhbTpFbWFpbFVSSVVuaXZlcnNhbENvbW11bmljYXRpb24+CiAgICAgICAgICAgIDxyYW06VVJJSUQ+YmlsbGluZ0B0ZWNoY29ycC5kZTwvcmFtOlVSSUlEPgogICAgICAgICAgPC9yYW06RW1haWxVUklVbml2ZXJzYWxDb21tdW5pY2F0aW9uPgogICAgICAgIDwvcmFtOkRlZmluZWRUcmFkZUNvbnRhY3Q+CiAgICAgICAgPHJhbTpQb3N0YWxUcmFkZUFkZHJlc3M+CiAgICAgICAgICA8cmFtOlBvc3Rjb2RlQ29kZT4xMDYyMzwvcmFtOlBvc3Rjb2RlQ29kZT4KICAgICAgICAgIDxyYW06TGluZU9uZT5LYW50c3RyYcOfZSAxMjwvcmFtOkxpbmVPbmU+CiAgICAgICAgICA8cmFtOkNpdHlOYW1lPkJlcmxpbjwvcmFtOkNpdHlOYW1lPgogICAgICAgICAgPHJhbTpDb3VudHJ5SUQ+REU8L3JhbTpDb3VudHJ5SUQ+CiAgICAgICAgPC9yYW06UG9zdGFsVHJhZGVBZGRyZXNzPgogICAgICAgIDxyYW06VVJJVW5pdmVyc2FsQ29tbXVuaWNhdGlvbj4KICAgICAgICAgIDxyYW06VVJJSUQgc2NoZW1lSUQ9IkVNIj5iaWxsaW5nQHRlY2hjb3JwLmRlPC9yYW06VVJJSUQ+CiAgICAgICAgPC9yYW06VVJJVW5pdmVyc2FsQ29tbXVuaWNhdGlvbj4KICAgICAgICA8cmFtOlNwZWNpZmllZFRheFJlZ2lzdHJhdGlvbj4KICAgICAgICAgIDxyYW06SUQgc2NoZW1lSUQ9IlZBIj5ERTEzNjY5NTk3NjwvcmFtOklEPgogICAgICAgIDwvcmFtOlNwZWNpZmllZFRheFJlZ2lzdHJhdGlvbj4KICAgICAgICA8cmFtOlNwZWNpZmllZFRheFJlZ2lzdHJhdGlvbj4KICAgICAgICAgIDxyYW06SUQgc2NoZW1lSUQ9IkZDIj4yNy8xMjMvNDU2Nzg8L3JhbTpJRD4KICAgICAgICA8L3JhbTpTcGVjaWZpZWRUYXhSZWdpc3RyYXRpb24+CiAgICAgIDwvcmFtOlNlbGxlclRyYWRlUGFydHk+CiAgICAgIDxyYW06QnV5ZXJUcmFkZVBhcnR5PgogICAgICAgIDxyYW06TmFtZT5NdXN0ZXIgR21iSDwvcmFtOk5hbWU+CiAgICAgICAgPHJhbTpQb3N0YWxUcmFkZUFkZHJlc3M+CiAgICAgICAgICA8cmFtOlBvc3Rjb2RlQ29kZT44MDMzMTwvcmFtOlBvc3Rjb2RlQ29kZT4KICAgICAgICAgIDxyYW06TGluZU9uZT5IYXVwdHN0cmHDn2UgNDI8L3JhbTpMaW5lT25lPgogICAgICAgICAgPHJhbTpDaXR5TmFtZT5Nw7xuY2hlbjwvcmFtOkNpdHlOYW1lPgogICAgICAgICAgPHJhbTpDb3VudHJ5SUQ+REU8L3JhbTpDb3VudHJ5SUQ+CiAgICAgICAgPC9yYW06UG9zdGFsVHJhZGVBZGRyZXNzPgogICAgICAgIDxyYW06VVJJVW5pdmVyc2FsQ29tbXVuaWNhdGlvbj4KICAgICAgICAgIDxyYW06VVJJSUQgc2NoZW1lSUQ9IkVNIj5pbnZvaWNlQG11c3Rlci5kZTwvcmFtOlVSSUlEPgogICAgICAgIDwvcmFtOlVSSVVuaXZlcnNhbENvbW11bmljYXRpb24+CiAgICAgICAgPHJhbTpTcGVjaWZpZWRUYXhSZWdpc3RyYXRpb24+CiAgICAgICAgICA8cmFtOklEIHNjaGVtZUlEPSJWQSI+REU4MTE1Njk4Njk8L3JhbTpJRD4KICAgICAgICA8L3JhbTpTcGVjaWZpZWRUYXhSZWdpc3RyYXRpb24+CiAgICAgIDwvcmFtOkJ1eWVyVHJhZGVQYXJ0eT4KICAgICAgPHJhbTpCdXllck9yZGVyUmVmZXJlbmNlZERvY3VtZW50PgogICAgICAgIDxyYW06SXNzdWVyQXNzaWduZWRJRD4wNDAxMTAwMC0xMjM0NS0zNDwvcmFtOklzc3VlckFzc2lnbmVkSUQ+CiAgICAgIDwvcmFtOkJ1eWVyT3JkZXJSZWZlcmVuY2VkRG9jdW1lbnQ+CiAgICA8L3JhbTpBcHBsaWNhYmxlSGVhZGVyVHJhZGVBZ3JlZW1lbnQ+CiAgICA8cmFtOkFwcGxpY2FibGVIZWFkZXJUcmFkZURlbGl2ZXJ5PgogICAgICA8cmFtOkFjdHVhbERlbGl2ZXJ5U3VwcGx5Q2hhaW5FdmVudD4KICAgICAgICA8cmFtOk9jY3VycmVuY2VEYXRlVGltZT4KICAgICAgICAgIDx1ZHQ6RGF0ZVRpbWVTdHJpbmcgZm9ybWF0PSIxMDIiPjIwMjYwMzIwPC91ZHQ6RGF0ZVRpbWVTdHJpbmc+CiAgICAgICAgPC9yYW06T2NjdXJyZW5jZURhdGVUaW1lPgogICAgICA8L3JhbTpBY3R1YWxEZWxpdmVyeVN1cHBseUNoYWluRXZlbnQ+CiAgICA8L3JhbTpBcHBsaWNhYmxlSGVhZGVyVHJhZGVEZWxpdmVyeT4KICAgIDxyYW06QXBwbGljYWJsZUhlYWRlclRyYWRlU2V0dGxlbWVudD4KICAgICAgPHJhbTpJbnZvaWNlQ3VycmVuY3lDb2RlPkVVUjwvcmFtOkludm9pY2VDdXJyZW5jeUNvZGU+CiAgICAgIDxyYW06U3BlY2lmaWVkVHJhZGVTZXR0bGVtZW50UGF5bWVudE1lYW5zPgogICAgICAgIDxyYW06VHlwZUNvZGU+NTg8L3JhbTpUeXBlQ29kZT4KICAgICAgICA8cmFtOlBheWVlUGFydHlDcmVkaXRvckZpbmFuY2lhbEFjY291bnQ+CiAgICAgICAgICA8cmFtOklCQU5JRD5ERTg5MzcwNDAwNDQwNTMyMDEzMDAwPC9yYW06SUJBTklEPgogICAgICAgICAgPHJhbTpBY2NvdW50TmFtZT5UZWNoQ29ycCBHbWJIPC9yYW06QWNjb3VudE5hbWU+CiAgICAgICAgPC9yYW06UGF5ZWVQYXJ0eUNyZWRpdG9yRmluYW5jaWFsQWNjb3VudD4KICAgICAgICA8cmFtOlBheWVlU3BlY2lmaWVkQ3JlZGl0b3JGaW5hbmNpYWxJbnN0aXR1dGlvbj4KICAgICAgICAgIDxyYW06QklDSUQ+Q09CQURFRkZYWFg8L3JhbTpCSUNJRD4KICAgICAgICA8L3JhbTpQYXllZVNwZWNpZmllZENyZWRpdG9yRmluYW5jaWFsSW5zdGl0dXRpb24+CiAgICAgIDwvcmFtOlNwZWNpZmllZFRyYWRlU2V0dGxlbWVudFBheW1lbnRNZWFucz4KICAgICAgPHJhbTpBcHBsaWNhYmxlVHJhZGVUYXg+CiAgICAgICAgPHJhbTpDYWxjdWxhdGVkQW1vdW50PjkxMi4wMDwvcmFtOkNhbGN1bGF0ZWRBbW91bnQ+CiAgICAgICAgPHJhbTpUeXBlQ29kZT5WQVQ8L3JhbTpUeXBlQ29kZT4KICAgICAgICA8cmFtOkJhc2lzQW1vdW50PjQ4MDAuMDA8L3JhbTpCYXNpc0Ftb3VudD4KICAgICAgICA8cmFtOkNhdGVnb3J5Q29kZT5TPC9yYW06Q2F0ZWdvcnlDb2RlPgogICAgICAgIDxyYW06UmF0ZUFwcGxpY2FibGVQZXJjZW50PjE5LjAwPC9yYW06UmF0ZUFwcGxpY2FibGVQZXJjZW50PgogICAgICA8L3JhbTpBcHBsaWNhYmxlVHJhZGVUYXg+CiAgICAgIDxyYW06U3BlY2lmaWVkVHJhZGVQYXltZW50VGVybXM+CiAgICAgICAgPHJhbTpEZXNjcmlwdGlvbj5aYWhsYmFyIGlubmVyaGFsYiB2b24gMzAgVGFnZW4gb2huZSBBYnp1ZzwvcmFtOkRlc2NyaXB0aW9uPgogICAgICAgIDxyYW06RHVlRGF0ZURhdGVUaW1lPgogICAgICAgICAgPHVkdDpEYXRlVGltZVN0cmluZyBmb3JtYXQ9IjEwMiI+MjAyNjA0MTk8L3VkdDpEYXRlVGltZVN0cmluZz4KICAgICAgICA8L3JhbTpEdWVEYXRlRGF0ZVRpbWU+CiAgICAgIDwvcmFtOlNwZWNpZmllZFRyYWRlUGF5bWVudFRlcm1zPgogICAgICA8cmFtOlNwZWNpZmllZFRyYWRlU2V0dGxlbWVudEhlYWRlck1vbmV0YXJ5U3VtbWF0aW9uPgogICAgICAgIDxyYW06TGluZVRvdGFsQW1vdW50PjQ4MDAuMDA8L3JhbTpMaW5lVG90YWxBbW91bnQ+CiAgICAgICAgPHJhbTpUYXhCYXNpc1RvdGFsQW1vdW50PjQ4MDAuMDA8L3JhbTpUYXhCYXNpc1RvdGFsQW1vdW50PgogICAgICAgIDxyYW06VGF4VG90YWxBbW91bnQgY3VycmVuY3lJRD0iRVVSIj45MTIuMDA8L3JhbTpUYXhUb3RhbEFtb3VudD4KICAgICAgICA8cmFtOkdyYW5kVG90YWxBbW91bnQ+NTcxMi4wMDwvcmFtOkdyYW5kVG90YWxBbW91bnQ+CiAgICAgICAgPHJhbTpEdWVQYXlhYmxlQW1vdW50PjU3MTIuMDA8L3JhbTpEdWVQYXlhYmxlQW1vdW50PgogICAgICA8L3JhbTpTcGVjaWZpZWRUcmFkZVNldHRsZW1lbnRIZWFkZXJNb25ldGFyeVN1bW1hdGlvbj4KICAgIDwvcmFtOkFwcGxpY2FibGVIZWFkZXJUcmFkZVNldHRsZW1lbnQ+CiAgPC9yc206U3VwcGx5Q2hhaW5UcmFkZVRyYW5zYWN0aW9uPgo8L3JzbTpDcm9zc0luZHVzdHJ5SW52b2ljZT4KZW5kc3RyZWFtCmVuZG9iagoKMzEgMCBvYmoKPDwKL1R5cGUgL01ldGFkYXRhCi9TdWJ0eXBlIC9YTUwKL0xlbmd0aCAzMzk3Cj4+CnN0cmVhbQo8P3hwYWNrZXQgYmVnaW49Iu+7vyIgaWQ9Ilc1TTBNcENlaGlIenJlU3pOVGN6a2M5ZCI/Pgo8eDp4bXBtZXRhIHhtbG5zOng9ImFkb2JlOm5zOm1ldGEvIj4KICA8cmRmOlJERiB4bWxuczpyZGY9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkvMDIvMjItcmRmLXN5bnRheC1ucyMiPgogICAgPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIKICAgICAgeG1sbnM6eG1wPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvIgogICAgICB4bWxuczpkYz0iaHR0cDovL3B1cmwub3JnL2RjL2VsZW1lbnRzLzEuMS8iCiAgICAgIHhtbG5zOnBkZj0iaHR0cDovL25zLmFkb2JlLmNvbS9wZGYvMS4zLyIKICAgICAgeG1sbnM6cGRmYWlkPSJodHRwOi8vd3d3LmFpaW0ub3JnL3BkZmEvbnMvaWQvIgogICAgICB4bWxuczpwZGZhRXh0ZW5zaW9uPSJodHRwOi8vd3d3LmFpaW0ub3JnL3BkZmEvbnMvZXh0ZW5zaW9uLyIKICAgICAgeG1sbnM6cGRmYVNjaGVtYT0iaHR0cDovL3d3dy5haWltLm9yZy9wZGZhL25zL3NjaGVtYSMiCiAgICAgIHhtbG5zOnBkZmFQcm9wZXJ0eT0iaHR0cDovL3d3dy5haWltLm9yZy9wZGZhL25zL3Byb3BlcnR5IyIKICAgICAgeG1sbnM6Zng9InVybjpmYWN0dXIteDpwZGZhOkNyb3NzSW5kdXN0cnlEb2N1bWVudDppbnZvaWNlOjFwMCMiPgogICAgICA8eG1wOkNyZWF0ZURhdGU+MjAyNi0wOC0yM1QxODo0MToxMS4xMjZaPC94bXA6Q3JlYXRlRGF0ZT4KICAgICAgPHhtcDpNb2RpZnlEYXRlPjIwMjYtMDgtMjNUMTg6NDE6MTEuMTI2WjwveG1wOk1vZGlmeURhdGU+CiAgICAgIDx4bXA6Q3JlYXRvclRvb2w+bGliLWludm9pY2UtZmFjdHVyeC1lbWJlZGRpbmc8L3htcDpDcmVhdG9yVG9vbD4KICAgICAgPGRjOmZvcm1hdD5hcHBsaWNhdGlvbi9wZGY8L2RjOmZvcm1hdD4KICAgICAgPHBkZjpQcm9kdWNlcj5wZGYtbGliPC9wZGY6UHJvZHVjZXI+CiAgICAgIDxwZGZhaWQ6cGFydD4zPC9wZGZhaWQ6cGFydD4KICAgICAgPHBkZmFpZDpjb25mb3JtYW5jZT5CPC9wZGZhaWQ6Y29uZm9ybWFuY2U+CgogICAgICA8cGRmYUV4dGVuc2lvbjpzY2hlbWFzPgogICAgICAgIDxyZGY6QmFnPgogICAgICAgICAgPHJkZjpsaSByZGY6cGFyc2VUeXBlPSJSZXNvdXJjZSI+CiAgICAgICAgICAgIDxwZGZhU2NoZW1hOnNjaGVtYT5GYWN0dXItWCBQREZBIEV4dGVuc2lvbiBTY2hlbWE8L3BkZmFTY2hlbWE6c2NoZW1hPgogICAgICAgICAgICA8cGRmYVNjaGVtYTpuYW1lc3BhY2VVUkk+dXJuOmZhY3R1ci14OnBkZmE6Q3Jvc3NJbmR1c3RyeURvY3VtZW50Omludm9pY2U6MXAwIzwvcGRmYVNjaGVtYTpuYW1lc3BhY2VVUkk+CiAgICAgICAgICAgIDxwZGZhU2NoZW1hOnByZWZpeD5meDwvcGRmYVNjaGVtYTpwcmVmaXg+CiAgICAgICAgICAgIDxwZGZhU2NoZW1hOnByb3BlcnR5PgogICAgICAgICAgICAgIDxyZGY6U2VxPgogICAgICAgICAgICAgICAgPHJkZjpsaSByZGY6cGFyc2VUeXBlPSJSZXNvdXJjZSI+CiAgICAgICAgICAgICAgICAgIDxwZGZhUHJvcGVydHk6bmFtZT5Eb2N1bWVudEZpbGVOYW1lPC9wZGZhUHJvcGVydHk6bmFtZT4KICAgICAgICAgICAgICAgICAgPHBkZmFQcm9wZXJ0eTp2YWx1ZVR5cGU+VGV4dDwvcGRmYVByb3BlcnR5OnZhbHVlVHlwZT4KICAgICAgICAgICAgICAgICAgPHBkZmFQcm9wZXJ0eTpjYXRlZ29yeT5leHRlcm5hbDwvcGRmYVByb3BlcnR5OmNhdGVnb3J5PgogICAgICAgICAgICAgICAgICA8cGRmYVByb3BlcnR5OmRlc2NyaXB0aW9uPk5hbWUgb2YgdGhlIGVtYmVkZGVkIFhNTCBpbnZvaWNlIGZpbGU8L3BkZmFQcm9wZXJ0eTpkZXNjcmlwdGlvbj4KICAgICAgICAgICAgICAgIDwvcmRmOmxpPgogICAgICAgICAgICAgICAgPHJkZjpsaSByZGY6cGFyc2VUeXBlPSJSZXNvdXJjZSI+CiAgICAgICAgICAgICAgICAgIDxwZGZhUHJvcGVydHk6bmFtZT5Eb2N1bWVudFR5cGU8L3BkZmFQcm9wZXJ0eTpuYW1lPgogICAgICAgICAgICAgICAgICA8cGRmYVByb3BlcnR5OnZhbHVlVHlwZT5UZXh0PC9wZGZhUHJvcGVydHk6dmFsdWVUeXBlPgogICAgICAgICAgICAgICAgICA8cGRmYVByb3BlcnR5OmNhdGVnb3J5PmV4dGVybmFsPC9wZGZhUHJvcGVydHk6Y2F0ZWdvcnk+CiAgICAgICAgICAgICAgICAgIDxwZGZhUHJvcGVydHk6ZGVzY3JpcHRpb24+VHlwZSBvZiB0aGUgZW1iZWRkZWQgZG9jdW1lbnQ8L3BkZmFQcm9wZXJ0eTpkZXNjcmlwdGlvbj4KICAgICAgICAgICAgICAgIDwvcmRmOmxpPgogICAgICAgICAgICAgICAgPHJkZjpsaSByZGY6cGFyc2VUeXBlPSJSZXNvdXJjZSI+CiAgICAgICAgICAgICAgICAgIDxwZGZhUHJvcGVydHk6bmFtZT5Db25mb3JtYW5jZUxldmVsPC9wZGZhUHJvcGVydHk6bmFtZT4KICAgICAgICAgICAgICAgICAgPHBkZmFQcm9wZXJ0eTp2YWx1ZVR5cGU+VGV4dDwvcGRmYVByb3BlcnR5OnZhbHVlVHlwZT4KICAgICAgICAgICAgICAgICAgPHBkZmFQcm9wZXJ0eTpjYXRlZ29yeT5leHRlcm5hbDwvcGRmYVByb3BlcnR5OmNhdGVnb3J5PgogICAgICAgICAgICAgICAgICA8cGRmYVByb3BlcnR5OmRlc2NyaXB0aW9uPkZhY3R1ci1YIGNvbmZvcm1hbmNlIGxldmVsPC9wZGZhUHJvcGVydHk6ZGVzY3JpcHRpb24+CiAgICAgICAgICAgICAgICA8L3JkZjpsaT4KICAgICAgICAgICAgICAgIDxyZGY6bGkgcmRmOnBhcnNlVHlwZT0iUmVzb3VyY2UiPgogICAgICAgICAgICAgICAgICA8cGRmYVByb3BlcnR5Om5hbWU+VmVyc2lvbjwvcGRmYVByb3BlcnR5Om5hbWU+CiAgICAgICAgICAgICAgICAgIDxwZGZhUHJvcGVydHk6dmFsdWVUeXBlPlRleHQ8L3BkZmFQcm9wZXJ0eTp2YWx1ZVR5cGU+CiAgICAgICAgICAgICAgICAgIDxwZGZhUHJvcGVydHk6Y2F0ZWdvcnk+ZXh0ZXJuYWw8L3BkZmFQcm9wZXJ0eTpjYXRlZ29yeT4KICAgICAgICAgICAgICAgICAgPHBkZmFQcm9wZXJ0eTpkZXNjcmlwdGlvbj5GYWN0dXItWCB2ZXJzaW9uPC9wZGZhUHJvcGVydHk6ZGVzY3JpcHRpb24+CiAgICAgICAgICAgICAgICA8L3JkZjpsaT4KICAgICAgICAgICAgICA8L3JkZjpTZXE+CiAgICAgICAgICAgIDwvcGRmYVNjaGVtYTpwcm9wZXJ0eT4KICAgICAgICAgIDwvcmRmOmxpPgogICAgICAgIDwvcmRmOkJhZz4KICAgICAgPC9wZGZhRXh0ZW5zaW9uOnNjaGVtYXM+CiAgICAgIDxmeDpEb2N1bWVudEZpbGVOYW1lPmZhY3R1ci14LnhtbDwvZng6RG9jdW1lbnRGaWxlTmFtZT4KICAgICAgPGZ4OkRvY3VtZW50VHlwZT5JTlZPSUNFPC9meDpEb2N1bWVudFR5cGU+CiAgICAgIDxmeDpDb25mb3JtYW5jZUxldmVsPkVOIDE2OTMxPC9meDpDb25mb3JtYW5jZUxldmVsPgogICAgICA8Zng6VmVyc2lvbj4xLjA8L2Z4OlZlcnNpb24+CiAgICA8L3JkZjpEZXNjcmlwdGlvbj4KICA8L3JkZjpSREY+CjwveDp4bXBtZXRhPgo8P3hwYWNrZXQgZW5kPSJ3Ij8+CmVuZHN0cmVhbQplbmRvYmoKCjMyIDAgb2JqCjw8Ci9GaWx0ZXIgL0ZsYXRlRGVjb2RlCi9UeXBlIC9PYmpTdG0KL04gMjIKL0ZpcnN0IDE0OQovTGVuZ3RoIDE0NjgKPj4Kc3RyZWFtCnicxVdtb9s2EP7uX8GPCQZTfH8ZigKJHbvGljXIy1a0KAbFYlyhtmVYcpH8+z2kZMduEjQrMCyAQ+p4vDvePc+J4oQRQZQiknhDFBGME4P/llgijSKOKIslopkgnBEtLeHQsHgSxEKZS+KkJlwRbzFo4h0GQ7zH4LAHIu6hbTwRgghu4FASobBRGCIZdglPZHQsGZHSOfLmTS+7flgFkl3ks1D3skG1WTaE97LfyqImnxAbI5fkc+/t217UHYa6qdOuP/JFiAppKTtb3IaiCMWonEMK69i13dPaH+RNPq9mvdYR4UmjsyLah/ebZrVpJssmLJtoGkG3zrPz0OQFDBDZ7TsZxXV/EFzn7mJdTa9Cg/XsYjgi2XW4b0g2WcDtaTcOunESbZ/dN+OrJm9COta45qhE8jGuBfHbqYzF6A6VjSrkKGqPeCxVUhmlOm01BtW8Wl+t8mmyCslBLmIKYiLWIea63X8eijI/re4Rd7SovabCEac4dT6GOai6vOhW/zLU1WY9RfZMK7ipw/pmWcbiHTjbna+XTfMfLWaDk+9V4mF72dXmtkmPUch62Wleh5SG7PRj/Pvlsrqtmqp/GWabeb5GWpfTqiiXM6S6QNxl89B/l/AzDcsiXzZxcywy3xYxu64QPjYFkOIpfvYi/fcxDg5ijKneLF4fIkj0NES1HyIwV2ymYU2O7r9sbsuqX+d5TVbFXf82n36FtWNEvQ55U/1YpayWw4jGo+GvggnDnJAcMGD+IzTOq+LFRcRyBHuL/Gs43p89o3qYuXjidblCcC20IylfrOtons9qolrN0xawfSstlUwZZ0lfWEa9N8wrUEY56oW2LvJEG8q1kOiAyOQE3aCcnixn80BQqpOY84Z4YamVSlq9rUMDg0pRrpgREA7y1btQzr40xHK4SYofOokWjqK5SS4BhSYs/oyGY5SxKYGd9imovsPNYDKMkrgmXgFxqF891PA0Wd5VqR9gqayb9QM5OimqWyQ/e78uwjpi7GiLsePocLWah0U8Hds1lMcqxG6eKP1XagafiGfoBFbSlGFNtOYUTV6jGWqOpHIpkGCJ3CHfSjq8OxgVMY8udnnqjOXo9QLF6CwYx7e1cNbQaErAruE0CrHNckmldZ7hDQUF2VrQSlKvoCz3dbVX1AqjTZQKyji3IPXPTvfOpgUVKgEJnmhEBWSMAk0IVlhOfXK7H6yRhiLUqPm8eS9pXARG05GlshQmMLNwrAzypwgEFBLMafQpcGpuAEC5P7UOkZhkVBhJzROv3CMUa2OOhRI0LVspqBKtpveUC55OB01jvYkZfkyrQWnjepyitEpFDmD6CAMDvGuf0mLAPwcUvFQC5y0q50WSoojbgzLqusQBHCnDBlmX7cxhj4tWUylsJxU7vCjEzVr/zFAXY3Hkc3pZTYbX1XgyPM9Xj831KfWebzzPN+sX+g6KFgEpvus7FocwiRb/e98R/Kf7zvOZ+M/ajhBP244RnsrEeXQVTY1qp2JHPq0hbSmhkWmTEpamXdK1ATY6C1xR07YoB/q22JFaUs0TBw+IBMbbtqlIT5NRKYF9ZhPKFaNM+sRJrajrsL/rDrs9e6ux/+EMcIU24UBIAFbtU0dYCxTHSkKBgwU2HXCPRVYh1DQ1TNMtDRWolciJqztedx2Rd7v2mu0eZQWInBAqD4n8+qlhSIdIDQaop1vydiewEKm2RK+l5P79G2gh2fj66m/coU/49m6OS2hRxhtKa+CujFee+nJ8CnQlNKYHMjkbGLQ/00fbO24/Gtr9uCfdgRSoyjOciJ8OqzAFLMnRXT5tNuv+Pb1fzGHhZkTejM5GI8aMwY/jJ4EEhZ/GTzAmhhEZGM/a0eDZDN62dCZHH2/Go3A5JJPlt6rEpfzD+e/H8SviMszTjav+UiItJ/MmrJcQfMMt82zUXvGJ6N7GN7vp431++xX0c9EdfMH8A8WsiHoKZW5kc3RyZWFtCmVuZG9iagoKMzMgMCBvYmoKPDwKL1NpemUgMzQKL1Jvb3QgMyAwIFIKL0luZm8gMTMgMCBSCi9JRCBbIDw5NTY4MjdjN2Y0OGU1NmIxMDIxNDNiOTFiNmQxYjQxMz4gPDk1NjgyN2M3ZjQ4ZTU2YjEwMjE0M2I5MWI2ZDFiNDEzPiBdCi9GaWx0ZXIgL0ZsYXRlRGVjb2RlCi9UeXBlIC9YUmVmCi9MZW5ndGggMTEwCi9XIFsgMSAyIDIgXQovSW5kZXggWyAwIDM0IF0KPj4Kc3RyZWFtCnicJcs7CoMAEIThWd/xHaO9dUCsvIGdiBDwFgEbK6ucInhb3WGbD+ZfFsB1OWgBIsQhrqC05hGfBCQkEXmQmCQkJRnJJdrstyCldDsg/WDtSSqZTm3z29pLllHnZ7VZk0a+f21Hr/z0cAOkrwx9CmVuZHN0cmVhbQplbmRvYmoKCnN0YXJ0eHJlZgozMjg1MwolJUVPRg==","filename":"invoice-sample.pdf"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse DE — ZUGFeRD (PDF with embedded CII XML)","description":"Parse a **DE — ZUGFeRD (PDF with embedded CII XML)** document. The request body below contains a real, round-trippable sample generated from the default DE example invoice — click \"Send\" right away to see the parser turn it back into structured Invoice data. Requires `e-invoice:de:zugferd:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/at/ebinterface/parse":{"post":{"operationId":"postApiV1InvoiceAtEbinterfaceParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"AT — ebInterface","x-country":"at","x-format":"ebinterface","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse AT — ebInterface","description":"Parse a **AT — ebInterface** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:at:ebinterface:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/at/zugferd/parse":{"post":{"operationId":"postApiV1InvoiceAtZugferdParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"AT — ZUGFeRD","x-country":"at","x-format":"zugferd","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.pdf"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse AT — ZUGFeRD","description":"Parse a **AT — ZUGFeRD** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:at:zugferd:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/at/ubl/parse":{"post":{"operationId":"postApiV1InvoiceAtUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"AT — UBL (Peppol BIS 3.0)","x-country":"at","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse AT — UBL (Peppol BIS 3.0)","description":"Parse a **AT — UBL (Peppol BIS 3.0)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:at:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/at/cii/parse":{"post":{"operationId":"postApiV1InvoiceAtCiiParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"AT — UN/CEFACT CII","x-country":"at","x-format":"cii","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse AT — UN/CEFACT CII","description":"Parse a **AT — UN/CEFACT CII** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:at:cii:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/fr/facturx/parse":{"post":{"operationId":"postApiV1InvoiceFrFacturxParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"FR — Factur-X","x-country":"fr","x-format":"facturx","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.pdf"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse FR — Factur-X","description":"Parse a **FR — Factur-X** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:fr:facturx:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/fr/ubl/parse":{"post":{"operationId":"postApiV1InvoiceFrUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"FR — UBL","x-country":"fr","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse FR — UBL","description":"Parse a **FR — UBL** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:fr:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/fr/cii/parse":{"post":{"operationId":"postApiV1InvoiceFrCiiParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"FR — UN/CEFACT CII","x-country":"fr","x-format":"cii","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse FR — UN/CEFACT CII","description":"Parse a **FR — UN/CEFACT CII** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:fr:cii:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/it/fatturapa/parse":{"post":{"operationId":"postApiV1InvoiceItFatturapaParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"IT — FatturaPA","x-country":"it","x-format":"fatturapa","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse IT — FatturaPA","description":"Parse a **IT — FatturaPA** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:it:fatturapa:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/it/ubl/parse":{"post":{"operationId":"postApiV1InvoiceItUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"IT — UBL (Peppol BIS 3.0)","x-country":"it","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse IT — UBL (Peppol BIS 3.0)","description":"Parse a **IT — UBL (Peppol BIS 3.0)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:it:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/it/cii/parse":{"post":{"operationId":"postApiV1InvoiceItCiiParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"IT — UN/CEFACT CII","x-country":"it","x-format":"cii","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse IT — UN/CEFACT CII","description":"Parse a **IT — UN/CEFACT CII** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:it:cii:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/es/facturae/parse":{"post":{"operationId":"postApiV1InvoiceEsFacturaeParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"ES — Facturae","x-country":"es","x-format":"facturae","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse ES — Facturae","description":"Parse a **ES — Facturae** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:es:facturae:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/es/ubl/parse":{"post":{"operationId":"postApiV1InvoiceEsUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"ES — UBL (Peppol BIS 3.0)","x-country":"es","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse ES — UBL (Peppol BIS 3.0)","description":"Parse a **ES — UBL (Peppol BIS 3.0)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:es:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/es/cii/parse":{"post":{"operationId":"postApiV1InvoiceEsCiiParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"ES — UN/CEFACT CII","x-country":"es","x-format":"cii","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse ES — UN/CEFACT CII","description":"Parse a **ES — UN/CEFACT CII** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:es:cii:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/nl/ubl/parse":{"post":{"operationId":"postApiV1InvoiceNlUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"NL — UBL (Peppol BIS 3.0)","x-country":"nl","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse NL — UBL (Peppol BIS 3.0)","description":"Parse a **NL — UBL (Peppol BIS 3.0)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:nl:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/nl/cii/parse":{"post":{"operationId":"postApiV1InvoiceNlCiiParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"NL — UN/CEFACT CII","x-country":"nl","x-format":"cii","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse NL — UN/CEFACT CII","description":"Parse a **NL — UN/CEFACT CII** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:nl:cii:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/be/ubl/parse":{"post":{"operationId":"postApiV1InvoiceBeUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"BE — UBL (Peppol BIS 3.0)","x-country":"be","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse BE — UBL (Peppol BIS 3.0)","description":"Parse a **BE — UBL (Peppol BIS 3.0)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:be:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/be/cii/parse":{"post":{"operationId":"postApiV1InvoiceBeCiiParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"BE — UN/CEFACT CII","x-country":"be","x-format":"cii","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse BE — UN/CEFACT CII","description":"Parse a **BE — UN/CEFACT CII** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:be:cii:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/be/facturx/parse":{"post":{"operationId":"postApiV1InvoiceBeFacturxParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"BE — Factur-X (CII)","x-country":"be","x-format":"facturx","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.pdf"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse BE — Factur-X (CII)","description":"Parse a **BE — Factur-X (CII)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:be:facturx:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/ch/cii/parse":{"post":{"operationId":"postApiV1InvoiceChCiiParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"CH — UN/CEFACT CII (ZUGFeRD CH)","x-country":"ch","x-format":"cii","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse CH — UN/CEFACT CII (ZUGFeRD CH)","description":"Parse a **CH — UN/CEFACT CII (ZUGFeRD CH)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:ch:cii:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/ch/zugferd/parse":{"post":{"operationId":"postApiV1InvoiceChZugferdParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"CH — ZUGFeRD (CII)","x-country":"ch","x-format":"zugferd","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse CH — ZUGFeRD (CII)","description":"Parse a **CH — ZUGFeRD (CII)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:ch:zugferd:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/ch/ubl/parse":{"post":{"operationId":"postApiV1InvoiceChUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"CH — UBL","x-country":"ch","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse CH — UBL","description":"Parse a **CH — UBL** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:ch:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/ch/qr-bill/parse":{"post":{"operationId":"postApiV1InvoiceChQrBillParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"CH — Swiss QR-Bill (text/plain)","x-country":"ch","x-format":"qr-bill","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.txt"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse CH — Swiss QR-Bill (text/plain)","description":"Parse a **CH — Swiss QR-Bill (text/plain)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:ch:qr-bill:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/pt/saft/parse":{"post":{"operationId":"postApiV1InvoicePtSaftParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"PT — SAF-T","x-country":"pt","x-format":"saft","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse PT — SAF-T","description":"Parse a **PT — SAF-T** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:pt:saft:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/pt/ubl/parse":{"post":{"operationId":"postApiV1InvoicePtUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"PT — UBL (CIUS-PT)","x-country":"pt","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse PT — UBL (CIUS-PT)","description":"Parse a **PT — UBL (CIUS-PT)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:pt:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/pt/peppol-ubl/parse":{"post":{"operationId":"postApiV1InvoicePtPeppolUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"PT — Peppol BIS 3.0 UBL (cross-border)","x-country":"pt","x-format":"peppol-ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse PT — Peppol BIS 3.0 UBL (cross-border)","description":"Parse a **PT — Peppol BIS 3.0 UBL (cross-border)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:pt:peppol-ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/pl/ksef/parse":{"post":{"operationId":"postApiV1InvoicePlKsefParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"PL — KSeF","x-country":"pl","x-format":"ksef","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse PL — KSeF","description":"Parse a **PL — KSeF** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:pl:ksef:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/pl/ubl/parse":{"post":{"operationId":"postApiV1InvoicePlUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"PL — UBL (KSeF FA(3))","x-country":"pl","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse PL — UBL (KSeF FA(3))","description":"Parse a **PL — UBL (KSeF FA(3))** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:pl:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/pl/peppol-ubl/parse":{"post":{"operationId":"postApiV1InvoicePlPeppolUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"PL — Peppol BIS 3.0 UBL (cross-border)","x-country":"pl","x-format":"peppol-ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse PL — Peppol BIS 3.0 UBL (cross-border)","description":"Parse a **PL — Peppol BIS 3.0 UBL (cross-border)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:pl:peppol-ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/cz/isdoc/parse":{"post":{"operationId":"postApiV1InvoiceCzIsdocParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"CZ — ISDOC","x-country":"cz","x-format":"isdoc","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse CZ — ISDOC","description":"Parse a **CZ — ISDOC** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:cz:isdoc:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/cz/ubl/parse":{"post":{"operationId":"postApiV1InvoiceCzUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"CZ — UBL (Peppol BIS 3.0)","x-country":"cz","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse CZ — UBL (Peppol BIS 3.0)","description":"Parse a **CZ — UBL (Peppol BIS 3.0)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:cz:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/hu/nav/parse":{"post":{"operationId":"postApiV1InvoiceHuNavParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"HU — NAV Online Számla","x-country":"hu","x-format":"nav","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse HU — NAV Online Számla","description":"Parse a **HU — NAV Online Számla** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:hu:nav:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/hu/ubl/parse":{"post":{"operationId":"postApiV1InvoiceHuUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"HU — UBL (Peppol BIS 3.0)","x-country":"hu","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse HU — UBL (Peppol BIS 3.0)","description":"Parse a **HU — UBL (Peppol BIS 3.0)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:hu:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/ro/efactura/parse":{"post":{"operationId":"postApiV1InvoiceRoEfacturaParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"RO — eFactura","x-country":"ro","x-format":"efactura","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse RO — eFactura","description":"Parse a **RO — eFactura** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:ro:efactura:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/ro/ubl/parse":{"post":{"operationId":"postApiV1InvoiceRoUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"RO — UBL (eFactura/CIUS-RO)","x-country":"ro","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse RO — UBL (eFactura/CIUS-RO)","description":"Parse a **RO — UBL (eFactura/CIUS-RO)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:ro:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/ro/cii/parse":{"post":{"operationId":"postApiV1InvoiceRoCiiParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"RO — UN/CEFACT CII","x-country":"ro","x-format":"cii","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse RO — UN/CEFACT CII","description":"Parse a **RO — UN/CEFACT CII** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:ro:cii:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/ro/peppol-ubl/parse":{"post":{"operationId":"postApiV1InvoiceRoPeppolUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"RO — Peppol BIS 3.0 UBL (cross-border)","x-country":"ro","x-format":"peppol-ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse RO — Peppol BIS 3.0 UBL (cross-border)","description":"Parse a **RO — Peppol BIS 3.0 UBL (cross-border)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:ro:peppol-ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/bg/ubl/parse":{"post":{"operationId":"postApiV1InvoiceBgUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"BG — UBL","x-country":"bg","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse BG — UBL","description":"Parse a **BG — UBL** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:bg:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/bg/cii/parse":{"post":{"operationId":"postApiV1InvoiceBgCiiParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"BG — UN/CEFACT CII","x-country":"bg","x-format":"cii","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse BG — UN/CEFACT CII","description":"Parse a **BG — UN/CEFACT CII** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:bg:cii:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/gr/mydata/parse":{"post":{"operationId":"postApiV1InvoiceGrMydataParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"GR — myDATA (AADE)","x-country":"gr","x-format":"mydata","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse GR — myDATA (AADE)","description":"Parse a **GR — myDATA (AADE)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:gr:mydata:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/gr/ubl/parse":{"post":{"operationId":"postApiV1InvoiceGrUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"GR — UBL (Peppol BIS 3.0)","x-country":"gr","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse GR — UBL (Peppol BIS 3.0)","description":"Parse a **GR — UBL (Peppol BIS 3.0)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:gr:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/cy/ubl/parse":{"post":{"operationId":"postApiV1InvoiceCyUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"CY — UBL (Peppol BIS 3.0)","x-country":"cy","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse CY — UBL (Peppol BIS 3.0)","description":"Parse a **CY — UBL (Peppol BIS 3.0)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:cy:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/dk/ubl/parse":{"post":{"operationId":"postApiV1InvoiceDkUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"DK — UBL (Peppol BIS 3.0)","x-country":"dk","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse DK — UBL (Peppol BIS 3.0)","description":"Parse a **DK — UBL (Peppol BIS 3.0)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:dk:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/ee/ubl/parse":{"post":{"operationId":"postApiV1InvoiceEeUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"EE — UBL (Peppol BIS 3.0)","x-country":"ee","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse EE — UBL (Peppol BIS 3.0)","description":"Parse a **EE — UBL (Peppol BIS 3.0)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:ee:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/fi/ubl/parse":{"post":{"operationId":"postApiV1InvoiceFiUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"FI — UBL (Peppol BIS 3.0)","x-country":"fi","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse FI — UBL (Peppol BIS 3.0)","description":"Parse a **FI — UBL (Peppol BIS 3.0)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:fi:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/gb/ubl/parse":{"post":{"operationId":"postApiV1InvoiceGbUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"GB — UBL (Peppol BIS 3.0)","x-country":"gb","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse GB — UBL (Peppol BIS 3.0)","description":"Parse a **GB — UBL (Peppol BIS 3.0)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:gb:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/ie/ubl/parse":{"post":{"operationId":"postApiV1InvoiceIeUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"IE — UBL (Peppol BIS 3.0)","x-country":"ie","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse IE — UBL (Peppol BIS 3.0)","description":"Parse a **IE — UBL (Peppol BIS 3.0)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:ie:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/lt/ubl/parse":{"post":{"operationId":"postApiV1InvoiceLtUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"LT — UBL (Peppol BIS 3.0)","x-country":"lt","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse LT — UBL (Peppol BIS 3.0)","description":"Parse a **LT — UBL (Peppol BIS 3.0)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:lt:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/lu/ubl/parse":{"post":{"operationId":"postApiV1InvoiceLuUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"LU — UBL (Peppol BIS 3.0)","x-country":"lu","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse LU — UBL (Peppol BIS 3.0)","description":"Parse a **LU — UBL (Peppol BIS 3.0)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:lu:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/lv/ubl/parse":{"post":{"operationId":"postApiV1InvoiceLvUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"LV — UBL (Peppol BIS 3.0)","x-country":"lv","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse LV — UBL (Peppol BIS 3.0)","description":"Parse a **LV — UBL (Peppol BIS 3.0)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:lv:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/mt/ubl/parse":{"post":{"operationId":"postApiV1InvoiceMtUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"MT — UBL (Peppol BIS 3.0)","x-country":"mt","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse MT — UBL (Peppol BIS 3.0)","description":"Parse a **MT — UBL (Peppol BIS 3.0)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:mt:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/no/ubl/parse":{"post":{"operationId":"postApiV1InvoiceNoUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"NO — UBL (Peppol BIS 3.0)","x-country":"no","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse NO — UBL (Peppol BIS 3.0)","description":"Parse a **NO — UBL (Peppol BIS 3.0)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:no:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/se/ubl/parse":{"post":{"operationId":"postApiV1InvoiceSeUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"SE — UBL (Peppol BIS 3.0)","x-country":"se","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse SE — UBL (Peppol BIS 3.0)","description":"Parse a **SE — UBL (Peppol BIS 3.0)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:se:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/si/ubl/parse":{"post":{"operationId":"postApiV1InvoiceSiUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"SI — UBL (SI-UBL 2.0)","x-country":"si","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse SI — UBL (SI-UBL 2.0)","description":"Parse a **SI — UBL (SI-UBL 2.0)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:si:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/li/ubl/parse":{"post":{"operationId":"postApiV1InvoiceLiUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"LI — UBL (Peppol BIS 3.0)","x-country":"li","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse LI — UBL (Peppol BIS 3.0)","description":"Parse a **LI — UBL (Peppol BIS 3.0)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:li:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/is/ubl/parse":{"post":{"operationId":"postApiV1InvoiceIsUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"IS — UBL (Peppol BIS 3.0)","x-country":"is","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse IS — UBL (Peppol BIS 3.0)","description":"Parse a **IS — UBL (Peppol BIS 3.0)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:is:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/hr/ubl/parse":{"post":{"operationId":"postApiV1InvoiceHrUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"HR — UBL (Peppol BIS 3.0)","x-country":"hr","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse HR — UBL (Peppol BIS 3.0)","description":"Parse a **HR — UBL (Peppol BIS 3.0)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:hr:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/hr/peppol-ubl/parse":{"post":{"operationId":"postApiV1InvoiceHrPeppolUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"HR — Peppol BIS 3.0 UBL (cross-border)","x-country":"hr","x-format":"peppol-ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse HR — Peppol BIS 3.0 UBL (cross-border)","description":"Parse a **HR — Peppol BIS 3.0 UBL (cross-border)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:hr:peppol-ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/sk/ubl/parse":{"post":{"operationId":"postApiV1InvoiceSkUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"SK — UBL (CIUS-SK)","x-country":"sk","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse SK — UBL (CIUS-SK)","description":"Parse a **SK — UBL (CIUS-SK)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:sk:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/sk/peppol-ubl/parse":{"post":{"operationId":"postApiV1InvoiceSkPeppolUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"SK — Peppol BIS 3.0 UBL (cross-border)","x-country":"sk","x-format":"peppol-ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse SK — Peppol BIS 3.0 UBL (cross-border)","description":"Parse a **SK — Peppol BIS 3.0 UBL (cross-border)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:sk:peppol-ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/ae/ubl/parse":{"post":{"operationId":"postApiV1InvoiceAeUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"AE — UBL (PINT-AE)","x-country":"ae","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse AE — UBL (PINT-AE)","description":"Parse a **AE — UBL (PINT-AE)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:ae:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/om/ubl/parse":{"post":{"operationId":"postApiV1InvoiceOmUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"OM — UBL (PINT-OM)","x-country":"om","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse OM — UBL (PINT-OM)","description":"Parse a **OM — UBL (PINT-OM)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:om:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/jp/ubl/parse":{"post":{"operationId":"postApiV1InvoiceJpUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"JP — UBL (PINT-JP)","x-country":"jp","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse JP — UBL (PINT-JP)","description":"Parse a **JP — UBL (PINT-JP)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:jp:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/au/ubl/parse":{"post":{"operationId":"postApiV1InvoiceAuUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"AU — UBL (PINT AU-NZ)","x-country":"au","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse AU — UBL (PINT AU-NZ)","description":"Parse a **AU — UBL (PINT AU-NZ)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:au:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/nz/ubl/parse":{"post":{"operationId":"postApiV1InvoiceNzUblParse","requestBody":{"required":true,"content":{"application/json":{"schema":{"vendor":"zod"},"examples":{"sample":{"summary":"NZ — UBL (PINT AU-NZ)","x-country":"nz","x-format":"ubl","value":{"data":"<DATA REQUIRED Base64>","filename":"invoice-sample.xml"}}}}}},"tags":["Invoice Parsing"],"summary":"Parse NZ — UBL (PINT AU-NZ)","description":"Parse a **NZ — UBL (PINT AU-NZ)** document. No pre-generated sample is shipped for this country/format yet — replace the `data` field with your own base64-encoded document before sending. Requires `e-invoice:nz:ubl:parse` entitlement.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful","example":true},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"format":{"description":"Detected format (e.g., ZUGFERD_EN16931)","example":"ZUGFERD_EN16931","type":"string"},"hash":{"description":"SHA-256 hash of the input document","example":"a1b2c3d4e5f6...","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","dueDate":"2026-04-19","currency":"EUR","seller":{"name":"TechCorp GmbH","street":"Kantstraße 12","city":"Berlin","postalCode":"10623","countryCode":"DE"},"buyer":{"name":"Muster GmbH","street":"Hauptstraße 42","city":"München","postalCode":"80331","countryCode":"DE"},"items":[{"position":1,"description":"Consulting","quantity":10,"unit":"HUR","unitPrice":150,"taxRate":19,"netAmount":1500,"taxAmount":285,"grossAmount":1785}],"subtotal":1500,"total":1785,"taxSummary":[{"taxRate":19,"netAmount":1500,"taxAmount":285}],"paymentTerms":{"dueDays":30}},"format":"ZUGFERD_EN16931","hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or unsupported format","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Document data is required (base64 encoded)"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/convert":{"post":{"operationId":"postApiV1InvoiceConvert","tags":["Invoice Conversion"],"summary":"Convert an e-invoice between formats","description":"Auto-detects and parses the source e-invoice, then regenerates it in the requested target format (`zugferd`, `facturx`, `xrechnung`). XRechnung → ZUGFeRD is loss-free (CIUS → EN 16931); the reverse only succeeds when the XRechnung obligations (BT-10, BR-DE-*) are met — otherwise a 422 with the offending rule codes is returned. `zugferd` and `facturx` are the same hybrid PDF/A-3 standard — the seller country picks the flavour (FR/BE → Factur-X, otherwise ZUGFeRD), so both requests yield a PDF with the embedded CII XML. Any fields not carried across are listed in `conversionWarnings`. Requires BOTH the source `:parse` and the target `:create` entitlement; usage is billed once against the target `:create` key (like generate).","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Converted document (base64) + conversionWarnings"},"400":{"description":"Bad request / source format not detectable"},"403":{"description":"Missing parse or create entitlement"},"422":{"description":"Source could not be converted to a conformant target document"},"429":{"description":"Quota exceeded"}}}},"/api/v1/invoice/parse":{"post":{"operationId":"postApiV1InvoiceParse","tags":["Invoice Parsing"],"summary":"Auto-detect and parse e-invoice","description":"Automatically detect the e-invoice format and country, then parse the document. The country is primarily extracted from the document content (seller country), with fallback to format-based inference. Requires e-invoice:*:*:parse entitlement.\n\n### Sample documents\nThe \"Examples\" dropdown below offers the same set of real / placeholder documents as the explicit `/:countryCode/:format/parse` endpoint. Pick any one — the server will inspect the bytes and figure out format and country on its own.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string","description":"Base64 encoded document (XML or PDF with embedded XML)"},"filename":{"description":"Original filename (helps detect format)","type":"string"}},"required":["data"]}}}},"x-codeSamples":[{"lang":"bash","label":"cURL","source":"curl -X POST https://service.invoice-api.xhub.io/api/invoice/parse \\\n  -H \"Authorization: Bearer sk_live_xxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"data\": \"<base64-encoded-XML-or-PDF>\",\n    \"filename\": \"invoice.xml\"\n  }'"},{"lang":"javascript","label":"JavaScript","source":"const fileBuffer = await fs.readFile('invoice.xml')\nconst base64 = fileBuffer.toString('base64')\n\nconst response = await fetch('https://service.invoice-api.xhub.io/api/invoice/parse', {\n  method: 'POST',\n  headers: {\n    'Authorization': 'Bearer sk_live_xxx',\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({ data: base64, filename: 'invoice.xml' }),\n})\n\nconst { success, invoice, detection } = await response.json()\n// detection.format = 'ZUGFERD_EN16931', detection.countryCode = 'DE'"}],"responses":{"200":{"description":"Invoice parsed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether parsing was successful"},"invoice":{"description":"Extracted invoice data","type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{}},"detection":{"type":"object","properties":{"format":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Detected format (e.g., ZUGFERD_EN16931, XRECHNUNG_UBL)","example":"ZUGFERD_EN16931"},"formatVersion":{"description":"Detected format version","example":"2.3.0","type":"string"},"countryCode":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Detected country code (ISO 3166-1 alpha-2)","example":"DE"},"confidence":{"type":"number","minimum":0,"maximum":100,"description":"Detection confidence (0-100)","example":95},"formatMethod":{"type":"string","enum":["NAMESPACE","ROOT_ELEMENT","CUSTOMIZATION_ID","PROFILE_ID","HEURISTIC"],"description":"Method used for format detection","example":"CUSTOMIZATION_ID"},"countrySource":{"type":"string","enum":["DOCUMENT","FORMAT_MAPPING","UNKNOWN"],"description":"Source of country code detection","example":"DOCUMENT"},"isAmbiguous":{"type":"boolean","description":"Whether the format is used by multiple countries","example":false},"alternativeCountries":{"description":"Alternative countries for ambiguous formats","type":"array","items":{"type":"string"}}},"required":["format","countryCode","confidence","formatMethod","countrySource","isAmbiguous"],"description":"Format and country detection result"},"hash":{"description":"SHA-256 hash of the input document","type":"string"},"errors":{"description":"Parsing errors (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Parsing warnings (if any)","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"infos":{"description":"Informational messages (e.g., XML extracted from PDF)","type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Info code (e.g., EXTRACTED_FROM_PDF)"},"message":{"type":"string","description":"Informational message"}},"required":["code","message"]}}},"required":["success","detection"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}},"example":{"success":true,"invoice":{"invoiceNumber":"INV-2026-0042","type":"invoice","issueDate":"2026-03-20","currency":"EUR","subtotal":1500,"total":1785},"detection":{"format":"ZUGFERD_EN16931","formatVersion":"2.3.0","countryCode":"DE","confidence":95,"formatMethod":"CUSTOMIZATION_ID","countrySource":"DOCUMENT","isAmbiguous":false},"hash":"a1b2c3d4e5f6..."}}}},"400":{"description":"Bad Request - Invalid document or format not detected","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false,"description":"Indicates failure"},"detection":{"type":"object","properties":{"format":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Detected format (e.g., ZUGFERD_EN16931, XRECHNUNG_UBL)","example":"ZUGFERD_EN16931"},"formatVersion":{"description":"Detected format version","example":"2.3.0","type":"string"},"countryCode":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Detected country code (ISO 3166-1 alpha-2)","example":"DE"},"confidence":{"type":"number","minimum":0,"maximum":100,"description":"Detection confidence (0-100)","example":95},"formatMethod":{"type":"string","enum":["NAMESPACE","ROOT_ELEMENT","CUSTOMIZATION_ID","PROFILE_ID","HEURISTIC"],"description":"Method used for format detection","example":"CUSTOMIZATION_ID"},"countrySource":{"type":"string","enum":["DOCUMENT","FORMAT_MAPPING","UNKNOWN"],"description":"Source of country code detection","example":"DOCUMENT"},"isAmbiguous":{"type":"boolean","description":"Whether the format is used by multiple countries","example":false},"alternativeCountries":{"description":"Alternative countries for ambiguous formats","type":"array","items":{"type":"string"}}},"required":["format","countryCode","confidence","formatMethod","countrySource","isAmbiguous"],"description":"Detection result (may be partial)"},"error":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Error message"}},"required":["success","detection","error","message"]},"example":{"success":false,"detection":{"format":null,"countryCode":null,"confidence":0,"formatMethod":"HEURISTIC","countrySource":"UNKNOWN","isAmbiguous":false},"error":"FORMAT_NOT_DETECTED","message":"Could not reliably detect the document format. Please use the explicit parse endpoint with country and format parameters."}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"FORBIDDEN","message":"Missing entitlement: e-invoice:de:zugferd:parse"}}}},"429":{"description":"Quota Exceeded - Usage limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100,"period":"2026-03"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to parse invoice document"}}}}}}},"/api/v1/invoice/{countryCode}/validate":{"post":{"operationId":"postApiV1InvoiceByCountryCodeValidate","tags":["Invoice Validation"],"summary":"Validate invoice data","description":"Validate invoice data against country-specific rules and e-invoice format requirements. Returns validation errors and warnings without consuming billing quota.","security":[{"bearerAuth":[]}],"parameters":[{"name":"countryCode","in":"path","required":true,"description":"ISO 3166-1 alpha-2 country code (lowercase). Determines country-specific validation and available e-invoice formats. Supported countries (37): ae, at, au, be, bg, ch, cy, cz, de, dk, ee, es, fi, fr, gb, gr, hr, hu, ie, is, it, jp, li, lt, lu, lv, mt, nl, no, nz, om, pl, pt, ro, se, si, sk.","schema":{"type":"string","enum":["ae","at","au","be","bg","ch","cy","cz","de","dk","ee","es","fi","fr","gb","gr","hr","hu","ie","is","it","jp","li","lt","lu","lv","mt","nl","no","nz","om","pl","pt","ro","se","si","sk"],"example":"de"}}],"responses":{"200":{"description":"Validation result","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean","description":"Overall: true only if every validated format is valid","example":true},"errors":{"description":"Validation errors","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Validation warnings","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"results":{"description":"Per-format validation results — the generated XML validated against its XSD + Schematron. For ZUGFeRD/Factur-X this includes every profile.","type":"array","items":{"type":"object","properties":{"format":{"type":"string","description":"Spec format-id that was validated (e.g. zugferd-2.4-en16931)","example":"zugferd-2.4-en16931"},"valid":{"type":"boolean","description":"Whether the generated XML passed XSD + Schematron"},"errors":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"message":{"type":"string"}},"required":["message"]},"description":"XSD structural + Schematron business-rule findings"}},"required":["format","valid","errors"]}}},"required":["valid"]},"examples":{"valid":{"summary":"Invoice is valid","value":{"valid":true}},"invalid":{"summary":"Invoice has validation errors","value":{"valid":false,"errors":[{"code":"MISSING_FIELD","message":"Seller VAT ID is required for B2B invoices","field":"seller.vatId"}],"warnings":[{"code":"MISSING_OPTIONAL","message":"Delivery date is recommended","field":"deliveryDate"}]}}}}}},"400":{"description":"Bad Request - Invalid invoice data or unsupported country","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Invoice data is required"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"UNAUTHORIZED","message":"API key authentication failed"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Internal Server Error","message":"Failed to validate invoice"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"invoice":{"type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{},"description":"Invoice data to validate"}},"required":["invoice"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}}}}}}},"/api/v1/invoice/{countryCode}/{format}/validate":{"post":{"operationId":"postApiV1InvoiceByCountryCodeByFormatValidate","tags":["Invoice Validation"],"summary":"Validate invoice for a specific format","description":"Generate the invoice in the given format and validate the resulting XML against its official XSD and Schematron rules. For ZUGFeRD/Factur-X every profile is validated. Returns per-format results and does not consume quota.","security":[{"bearerAuth":[]}],"parameters":[{"name":"countryCode","in":"path","required":true,"description":"ISO 3166-1 alpha-2 country code (lowercase). Determines country-specific validation and available e-invoice formats. Supported countries (37): ae, at, au, be, bg, ch, cy, cz, de, dk, ee, es, fi, fr, gb, gr, hr, hu, ie, is, it, jp, li, lt, lu, lv, mt, nl, no, nz, om, pl, pt, ro, se, si, sk.","schema":{"type":"string","enum":["ae","at","au","be","bg","ch","cy","cz","de","dk","ee","es","fi","fr","gb","gr","hr","hu","ie","is","it","jp","li","lt","lu","lv","mt","nl","no","nz","om","pl","pt","ro","se","si","sk"],"example":"de"}},{"name":"format","in":"path","required":true,"description":"Output/input format identifier (lowercase). Valid format values depend on the country — call `GET /api/v1/invoice/{countryCode}/formats` to discover the exact set for a country. Overview:\n\n- **pdf** — all 37 countries.\n- **ubl** — generic Peppol BIS 3.0 UBL on most countries (incl. PINT flavours for AE/AU/NZ); on **PL** it emits the national KSeF FA(3), on **PT** CIUS-PT, on **RO** eFactura (CIUS-RO), on **SK** CIUS-SK.\n- **xrechnung** (DE), **zugferd** (DE — `formatOptions.profile` selects `EN16931`/`BASIC`/`EXTENDED`; CH — Swiss CII flavour for cross-border DE/AT customers).\n- **ebinterface** (AT).\n- **facturx** (FR/BE — `formatOptions.profile` selects `EN16931`/`BASIC`).\n- **fatturapa** (IT — 6-char SDI codes for PA accepted).\n- **facturae** (ES).\n- **isdoc** (CZ), **nav** (HU), **mydata** (GR), **ksef** (PL).\n- **peppol-ubl** — generic Peppol BIS 3.0 UBL for HR/PL/PT/RO/SK whose `ubl` slot is (or can be) occupied by the national CIUS.\n- **hr-fisk** (HR — HR-FISK 2.0 CIUS, validate only).\n- **qr-bill** (CH/LI — structured 32-line QR-Bill payload as text/plain).\n\nExact spelling matters — values must be lowercase. The `peppol-ubl`, `qr-bill` and `hr-fisk` slots are dash-separated.","schema":{"type":"string","enum":["ebinterface","facturae","facturx","fatturapa","hr-fisk","isdoc","ksef","mydata","nav","pdf","peppol-ubl","qr-bill","ubl","xrechnung","zugferd"],"example":"pdf"}}],"responses":{"200":{"description":"Validation result","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean","description":"Overall: true only if every validated format is valid","example":true},"errors":{"description":"Validation errors","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"warnings":{"description":"Validation warnings","type":"array","items":{"type":"object","properties":{"code":{"anyOf":[{"type":"string","enum":["DE_AC_001","DE_AC_002","DE_BIC_INVALID","DE_BR_AE_02","DE_BR_AE_03","DE_BR_DE_16","DE_BR_DEX_04","DE_BR_DEX_05","DE_BR_DEX_06","DE_BR_DEX_07","DE_BR_DEX_08","DE_BR_K_02","DE_BR_K_04","DE_BR_K_05","DE_BR_O_01","DE_BR_O_02","DE_BR_O_05","DE_BUYER_IBAN_001","DE_BUYER_IBAN_REQUIRED","DE_CREDITOR_ID_INVALID","DE_CREDITOR_ID_REQUIRED","DE_DLV_001","DE_INV_NUM_NOT_SEQUENTIAL","DE_INV_NUM_REQUIRED","DE_INV_NUM_SPECIAL_CHARS","DE_INV_NUM_TOO_LONG","DE_KU_001","DE_KU_002","DE_LW_002","DE_MANDATE_ID_REQUIRED","DE_MANDATE_ID_TOO_LONG","DE_REF_001","DE_REF_002","DE_SELLER_CONTACT_001","DE_SELLER_IBAN_FORMAT","DE_SELLER_IBAN_INVALID","DE_SEPA_003","DE_VAT_001","GR_AFM_001","GR_AFM_002","GR_CREDIT_NOTE_MISSING_MARK","GR_GEN_001","GR_INV_001","GR_INV_002","GR_INV_NUM_REQUIRED","GR_PDF_001","GR_PDF_002"]},{"type":"string","description":"Schematron rule ID (e.g. BR-CO-15, BR-S-08) or any other dynamic code emitted by the invoice lib. Falls back to a free-form string so unknown codes never fail response validation."}],"description":"Error code. Either one of the documented hand-rolled codes (DE_*, GR_*) or a free-form string for Schematron rule IDs and forward-compatibility with new lib codes."},"message":{"type":"string","description":"Error message"},"field":{"description":"Field path (if applicable)","type":"string"}},"required":["code","message"]}},"results":{"description":"Per-format validation results — the generated XML validated against its XSD + Schematron. For ZUGFeRD/Factur-X this includes every profile.","type":"array","items":{"type":"object","properties":{"format":{"type":"string","description":"Spec format-id that was validated (e.g. zugferd-2.4-en16931)","example":"zugferd-2.4-en16931"},"valid":{"type":"boolean","description":"Whether the generated XML passed XSD + Schematron"},"errors":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"message":{"type":"string"}},"required":["message"]},"description":"XSD structural + Schematron business-rule findings"}},"required":["format","valid","errors"]}}},"required":["valid"]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"invoice":{"type":"object","properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2026-0042"},"type":{"type":"string","enum":["invoice","credit_note","proforma","correction"],"description":"Invoice type","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"type":"string","description":"Due date (ISO 8601: YYYY-MM-DD)","example":"2026-04-19"},"deliveryDate":{"description":"Delivery/service date (ISO 8601)","example":"2026-03-20","type":"string"},"servicePeriod":{"description":"Service period (Leistungszeitraum). Required in DE if different from issueDate.","type":"object","properties":{"start":{"type":"string","description":"Period start (ISO 8601: YYYY-MM-DD)","example":"2026-03-01"},"end":{"type":"string","description":"Period end (ISO 8601: YYYY-MM-DD)","example":"2026-03-31"}},"required":["start","end"]},"seller":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Seller party information"},"buyer":{"type":"object","properties":{"name":{"type":"string","description":"Legal name of the party","example":"Muster GmbH"},"tradingName":{"description":"Trading name (if different from legal name)","example":"Muster Shop","type":"string"},"street":{"description":"Street address","example":"Hauptstraße 42","type":"string"},"additionalStreet":{"description":"Additional address line","example":"2. OG, Raum 5","type":"string"},"city":{"description":"City","example":"Berlin","type":"string"},"postalCode":{"description":"Postal code","example":"10115","type":"string"},"countryCode":{"type":"string","description":"Country code (ISO 3166-1 alpha-2)","example":"DE"},"state":{"description":"State/region (ISO 3166-2)","example":"BE","type":"string"},"taxId":{"description":"National tax identification number","example":"27/123/45678","type":"string"},"vatId":{"description":"EU VAT identification number","example":"DE136695976","type":"string"},"email":{"description":"Email address","example":"billing@muster.de","type":"string"},"phone":{"description":"Phone number","example":"+49 30 12345678","type":"string"},"website":{"description":"Website URL","example":"https://muster.de","type":"string"},"contact":{"description":"Structured contact person (BG-6 for seller, BG-9 for buyer)","type":"object","properties":{"name":{"description":"Contact person name","example":"Max Mustermann","type":"string"},"phone":{"description":"Contact phone number","example":"+49 30 12345678","type":"string"},"email":{"description":"Contact email address","example":"max@muster.de","type":"string"}}},"bankAccount":{"description":"Bank account (required on seller for SEPA bank transfers in ZUGFeRD/XRechnung). For direct debit (SEPA Lastschrift), buyer bankAccount is also required.","type":"object","properties":{"iban":{"type":"string","description":"IBAN (International Bank Account Number)","example":"DE89370400440532013000"},"bic":{"description":"BIC/SWIFT code (8 or 11 characters)","example":"COBADEFFXXX","type":"string"},"bankName":{"description":"Name of the bank","example":"Commerzbank","type":"string"},"accountHolder":{"description":"Account holder name (if different from party name)","example":"TechCorp GmbH","type":"string"}},"required":["iban"]}},"required":["name","countryCode"],"additionalProperties":{},"description":"Buyer party information"},"items":{"type":"array","items":{"$ref":"#/components/schemas/__schema0"},"description":"Invoice line items"},"currency":{"type":"string","description":"Currency code (ISO 4217)","example":"EUR"},"subtotal":{"type":"number","description":"Total net amount","example":4800},"total":{"type":"number","description":"Total gross amount","example":5712},"taxSummary":{"type":"array","items":{"type":"object","properties":{"taxRate":{"type":"number","description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code","example":"S","type":"string"},"netAmount":{"type":"number","description":"Net amount for this tax rate","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"exemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge","type":"string"},"exemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"}},"required":["taxRate","netAmount","taxAmount"],"additionalProperties":{}},"description":"Tax summary per tax rate"},"paymentTerms":{"description":"Payment terms","type":"object","properties":{"dueDays":{"description":"Payment due in days","example":30,"type":"number"},"description":{"description":"Payment terms description","example":"Zahlbar innerhalb von 30 Tagen ohne Abzug","type":"string"},"earlyPaymentDiscount":{"description":"Early payment discount (Skonto). E.g., 2% discount if paid within 10 days.","type":"object","properties":{"days":{"type":"number","description":"Discount valid within this many days","example":10},"discountPercent":{"type":"number","description":"Discount percentage (Skonto)","example":2}},"required":["days","discountPercent"]}},"additionalProperties":{}},"paymentMethods":{"description":"Payment methods accepted for this invoice. Used in ZUGFeRD/XRechnung to generate SpecifiedTradeSettlementPaymentMeans. For bank_transfer, seller.bankAccount must also be set.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bank_transfer","credit_transfer","direct_debit","credit_card","paypal","cash","danish_fik","giro","other"],"description":"Payment method type. Maps to UNTDID 4461 codes in e-invoices: bank_transfer / credit_transfer = 30 (Credit transfer), direct_debit=49 (SEPA Direct Debit), credit_card=48 (Card payment), cash=10, danish_fik=93 (DK Indbetalingskort FIK), giro=50 (DK postal giro), other=1.","example":"bank_transfer"},"details":{"description":"Additional details (e.g., \"PayPal: invoice@example.com\")","example":"SEPA-Überweisung","type":"string"}},"required":["type"],"description":"Payment method"}},"orderNumber":{"description":"Purchase order number (Bestellnummer)","example":"PO-2026-0815","type":"string"},"customerNumber":{"description":"Customer number at the seller","example":"KD-42","type":"string"},"contractNumber":{"description":"Contract number (BT-12)","example":"V-2025-1234","type":"string"},"projectNumber":{"description":"Project reference (BT-11)","example":"PROJ-2026-42","type":"string"},"roundingAmount":{"description":"Rounding amount (BT-114)","example":0.01,"type":"number"},"allowancesCharges":{"description":"Invoice-level allowances (discounts) and charges (surcharges) (BG-20 / BG-21). For line-level discounts, use items[].discount instead.","type":"array","items":{"type":"object","properties":{"isCharge":{"type":"boolean","description":"true = surcharge (BG-21), false = discount/allowance (BG-20)","example":false},"amount":{"type":"number","description":"Allowance/charge amount (BT-92 / BT-99)","example":100},"percentage":{"description":"Percentage (BT-94 / BT-101) — alternative to fixed amount","example":5,"type":"number"},"baseAmount":{"description":"Base amount for percentage calculation (BT-93 / BT-100)","example":2000,"type":"number"},"reason":{"description":"Reason text (BT-97 / BT-104)","example":"Gesamtrabatt","type":"string"},"reasonCode":{"description":"Reason code per UNTDID 5189 (allowance) / 7161 (charge) (BT-98 / BT-105)","example":"95","type":"string"},"taxCategoryCode":{"description":"Tax category code (BT-95 / BT-102)","example":"S","type":"string"},"taxRate":{"description":"Tax rate in percent (BT-96 / BT-103)","example":19,"type":"number"}},"required":["isCharge","amount"],"description":"Invoice-level allowance (discount) or charge (surcharge)"}},"delivery":{"description":"Delivery information (BG-13). Includes delivery date (BT-72), deliver-to name (BT-70), location identifier (BT-71), and delivery address (BG-15).","type":"object","properties":{"date":{"description":"Delivery date (BT-72, ISO 8601)","example":"2026-03-20","type":"string"},"name":{"description":"Deliver-to party name (BT-70)","example":"Lager Nord","type":"string"},"locationId":{"description":"Delivery location identifier (BT-71)","type":"string"},"address":{"description":"Delivery address (BG-15)","type":"object","properties":{"street":{"description":"Delivery street (BT-75)","example":"Lagerstraße 10","type":"string"},"additionalStreet":{"description":"Additional delivery address line (BT-76)","type":"string"},"city":{"description":"Delivery city (BT-77)","example":"Hamburg","type":"string"},"postalCode":{"description":"Delivery postal code (BT-78)","example":"20457","type":"string"},"state":{"description":"Delivery state/region (BT-79)","type":"string"},"countryCode":{"description":"Delivery country code (BT-80)","example":"DE","type":"string"}}}}},"directDebitMandate":{"description":"SEPA direct debit mandate (BG-19). Required when paymentMethods includes direct_debit.","type":"object","properties":{"mandateId":{"type":"string","description":"SEPA mandate reference (BT-89)","example":"MANDATE-2026-001"},"creditorId":{"type":"string","description":"SEPA creditor identifier (BT-90)","example":"DE98ZZZ09999999999"},"debitAccountId":{"description":"Debited account IBAN (BT-91)","example":"DE89370400440532013000","type":"string"}},"required":["mandateId","creditorId"]},"notes":{"description":"Additional notes displayed on the invoice","example":"Vielen Dank für Ihren Auftrag!","type":"string"},"profile":{"description":"XRechnung CIUS profile. `xrechnung` produces the standard CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0`. `xrechnung-extension` produces the EXTENSION CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0#conformant#urn:xoev-de:kosit:extension:xrechnung_3.0` which unlocks the additional XRechnung-EXTENSION business terms (subItems, third-party payments, ...). Defaults to `xrechnung` when omitted.","example":"xrechnung","type":"string","enum":["xrechnung","xrechnung-extension"]},"referencedInvoiceNumber":{"description":"Number of the previously issued invoice this document references (BT-25, BG-3). Used for credit notes, corrections, and partial-invoice chains. Renders as `<cac:BillingReference>` in UBL / `IncludedNote` reference in CII.","example":"INV-2026-0040","type":"string"},"referencedInvoiceDate":{"description":"Issue date of the referenced invoice (BT-26, ISO 8601 YYYY-MM-DD). Pairs with `referencedInvoiceNumber`.","example":"2026-03-15","type":"string"},"deliveryNote":{"description":"Despatch advice / delivery note reference (BT-16 / BT-17). Renders as `<cac:DespatchDocumentReference>` in UBL.","type":"object","properties":{"number":{"type":"string","description":"Despatch advice / delivery note number (BT-16).","example":"LS-2026-4711"},"date":{"description":"Despatch advice / delivery note date (BT-17, ISO 8601).","example":"2026-03-19","type":"string"}},"required":["number"]},"thirdPartyPayments":{"description":"Third-party prepaid payments (BG-DEX-09, ZUGFeRD EXTENDED). Each entry is rendered as `<cac:PrepaidPayment>` in UBL.","type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Third-party payment type identifier (BT-DEX-001). Free-form code chosen by the issuer (e.g., \"voucher\", \"loyalty\", \"partial\").","example":"voucher"},"paidAmount":{"type":"number","description":"Amount already paid by the third party (BT-DEX-002).","example":25},"description":{"type":"string","description":"Human-readable description of the third-party payment (BT-DEX-003).","example":"Geschenkgutschein eingelöst"}},"required":["type","paidAmount","description"],"description":"Third-party prepaid payment (BG-DEX-09 / BT-DEX-001..003, ZUGFeRD EXTENDED)"}},"attachments":{"description":"Embedded supporting documents (BG-24 / BT-122..125). Rendered as `<cbc:EmbeddedDocumentBinaryObject>` in UBL.","type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename (BT-125).","example":"leistungsnachweis.pdf"},"mimeType":{"type":"string","description":"IANA media type of the attachment (BT-125-1).","example":"application/pdf"},"content":{"type":"string","description":"Base64-encoded binary content of the attachment (BT-125). Decoded payload should not exceed roughly 200 MiB (KoSIT alignment).","example":"JVBERi0xLjcKJeLjz9MK..."},"description":{"description":"Optional human-readable description of the attachment (BT-123).","example":"Stundennachweis März 2026","type":"string"}},"required":["filename","mimeType","content"],"description":"Embedded attachment (BG-24 / BT-122..125)"}},"serviceCategory":{"description":"Service category hint for the German construction-tax flow. When set to `construction` and a line uses `taxCategoryCode: \"AE\"`, the generator emits the §13b UStG reverse-charge note automatically.","example":"construction","type":"string","enum":["construction","general"]},"constructionTax":{"description":"German construction-tax block (§13b UStG / §48 EStG). Setting `exemptionCertificateNumber` triggers the `#FREISTELLUNG#` note in the generated invoice. `withholdingPercent` documents the Bauabzugsteuer rate.","type":"object","properties":{"exemptionCertificateNumber":{"description":"Freistellungsbescheinigung number per §48b EStG. When set, the generator emits a \"#FREISTELLUNG#\" note documenting the construction-withholding exemption.","example":"FB-2026-0042","type":"string"},"withholdingPercent":{"description":"Construction withholding tax rate in percent (Bauabzugsteuer). Typically 15 in Germany when no Freistellungsbescheinigung is presented.","example":15,"type":"number"},"recipientTaxOffice":{"description":"Tax office responsible for the recipient of the construction service.","example":"Finanzamt München","type":"string"}}},"countrySpecific":{"description":"Country-specific invoice data. Must include countryCode matching the invoice country. For DE: buyerReference (BT-10, required), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer (§19 UStG). Other countries have their own fields — see country-specific documentation.","type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code identifying this country-specific block.","example":"DE"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","dueDate","seller","buyer","items","currency","subtotal","total","taxSummary"],"additionalProperties":{},"description":"Invoice data to validate"}},"required":["invoice"],"$defs":{"__schema0":{"type":"object","properties":{"position":{"description":"Line item position number (BT-126 — zero-indexed line IDs are valid)","example":1,"type":"integer","minimum":0,"maximum":9007199254740991},"description":{"type":"string","description":"Item description","example":"Software Development Services — March 2026"},"articleNumber":{"description":"Article/SKU number","example":"SVC-DEV-001","type":"string"},"quantity":{"type":"number","description":"Quantity (negative values allowed for return/credit lines, EN 16931 BG-25)","example":40},"unit":{"type":"string","description":"Unit code (UN/ECE Rec 20)","example":"HUR"},"unitPrice":{"type":"number","description":"Unit price (net)","example":120},"discount":{"description":"Line item discount (BT-136 to BT-138)","type":"object","properties":{"type":{"description":"Discount type: percentage or absolute amount","example":"absolute","type":"string","enum":["percentage","absolute"]},"value":{"description":"Discount value","example":50,"type":"number"},"reason":{"description":"Discount reason (BT-139)","example":"Mengenrabatt","type":"string"}},"additionalProperties":{}},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate in percent","example":19},"taxCategoryCode":{"description":"Tax category code (EN 16931: S, Z, E, AE, K, G, O, ...)","example":"S","type":"string"},"taxExemptionReason":{"description":"Tax exemption reason free text (BT-120)","example":"Reverse charge — Steuerschuldnerschaft des Leistungsempfängers","type":"string"},"taxExemptionReasonCode":{"description":"Tax exemption reason code (BT-121, VATEX code)","example":"VATEX-EU-AE","type":"string"},"netAmount":{"type":"number","description":"Net amount (quantity * unitPrice)","example":4800},"taxAmount":{"type":"number","description":"Tax amount","example":912},"grossAmount":{"description":"Gross amount (net + tax)","example":5712,"type":"number"},"lineSubtype":{"description":"Sub-line-item type (BT-X-8, ZUGFeRD 2.4 EXTENDED). DETAIL = included in totals, INFORMATION = info only, GROUP = sum of sub-items.","type":"string","enum":["DETAIL","INFORMATION","GROUP"]},"parentLineId":{"description":"Parent line item position reference (BT-X-304, for hierarchical line items)","type":"string"},"perPackageQuantity":{"description":"Quantity per package unit (BT-X-561)","type":"number"},"subItems":{"description":"Nested sub-line-items (BG-DEX-01, ZUGFeRD 2.4 EXTENDED hierarchy). Each entry has the same shape as a top-level item and may itself have subItems. Use `lineSubtype` (DETAIL/INFORMATION/GROUP) on each sub-item to control how it contributes to totals.","type":"array","items":{"$ref":"#/components/schemas/__schema0"}}},"required":["description","quantity","unit","unitPrice","taxRate","netAmount","taxAmount"],"additionalProperties":{}}}}}}}}},"/api/v1/invoice/{countryCode}/formats":{"get":{"operationId":"getApiV1InvoiceByCountryCodeFormats","tags":["Formats"],"summary":"Get formats for country","description":"Get all supported invoice formats for a specific country. Returns format identifiers, names, and MIME types.","security":[{"bearerAuth":[]}],"parameters":[{"name":"countryCode","in":"path","required":true,"description":"ISO 3166-1 alpha-2 country code (lowercase). Determines country-specific validation and available e-invoice formats. Supported countries (37): ae, at, au, be, bg, ch, cy, cz, de, dk, ee, es, fi, fr, gb, gr, hr, hu, ie, is, it, jp, li, lt, lu, lv, mt, nl, no, nz, om, pl, pt, ro, se, si, sk.","schema":{"type":"string","enum":["ae","at","au","be","bg","ch","cy","cz","de","dk","ee","es","fi","fr","gb","gr","hr","hu","ie","is","it","jp","li","lt","lu","lv","mt","nl","no","nz","om","pl","pt","ro","se","si","sk"],"example":"de"}}],"responses":{"200":{"description":"Country formats retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Country code"},"name":{"type":"string","description":"Country name"},"label":{"type":"string","description":"Display label, e.g. 'Germany (DE)'"},"formats":{"type":"array","items":{"type":"string"},"description":"Supported output format tokens, e.g. ['pdf', 'zugferd', 'xrechnung']"},"formatDetails":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"URL format token, e.g. 'zugferd', 'ubl'"},"label":{"type":"string","description":"Display label, e.g. 'ZUGFeRD 2.3/2.4/2.5'"},"kind":{"type":"string","enum":["pdf","einvoice"],"description":"Whether the format is PDF-based or an e-invoice"}},"required":["code","label","kind"]},"description":"Per-format display metadata (label + kind) for the format tokens"}},"required":["code","name","label","formats","formatDetails"]}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]}}}},"404":{"description":"Not Found - Country not supported","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]}}}}}}},"/api/v1/invoice/formats":{"get":{"operationId":"getApiV1InvoiceFormats","tags":["Formats"],"summary":"Get all supported formats","description":"Get all supported countries and their invoice formats. Useful for discovering available options before generating invoices.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"All formats retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"countries":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Country code"},"name":{"type":"string","description":"Country name"},"label":{"type":"string","description":"Display label, e.g. 'Germany (DE)'"},"formats":{"type":"array","items":{"type":"string"},"description":"Supported output format tokens, e.g. ['pdf', 'zugferd', 'xrechnung']"},"formatDetails":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"URL format token, e.g. 'zugferd', 'ubl'"},"label":{"type":"string","description":"Display label, e.g. 'ZUGFeRD 2.3/2.4/2.5'"},"kind":{"type":"string","enum":["pdf","einvoice"],"description":"Whether the format is PDF-based or an e-invoice"}},"required":["code","label","kind"]},"description":"Per-format display metadata (label + kind) for the format tokens"}},"required":["code","name","label","formats","formatDetails"]},"description":"All supported countries and formats"}},"required":["countries"]}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]}}}}}}},"/api/v1/invoice/es/verifactu-qr":{"post":{"operationId":"postApiV1InvoiceEsVerifactuQr","tags":["Invoice Generation"],"summary":"Generate VeriFactu QR (ES)","description":"Generate the AEAT VeriFactu QR for a Spanish invoice. Returns the verification URL plus PNG (base64) and SVG renderings of the QR code.\n\nNote: PNG is base64-encoded (no `data:` prefix) so clients can embed it directly or decode it to bytes — JSON keeps the response easy to consume without multipart.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sellerNif":{"type":"string","description":"Seller NIF/CIF (Spanish tax ID), e.g., \"B12345678\".","example":"B12345678"},"invoiceSeries":{"type":"string","description":"Invoice series prefix that is concatenated with `invoiceNumber` to form the AEAT `numserie` parameter. Use whatever series your numbering scheme prescribes; characters are URL-encoded by the QR builder.","example":"A"},"invoiceNumber":{"type":"string","description":"Invoice number within the series (forms the second half of `numserie`).","example":"2026-0042"},"invoiceDate":{"type":"string","description":"Invoice issue date in AEAT QR format `DD-MM-YYYY`.","example":"20-03-2026"},"total":{"type":"number","description":"Invoice total amount used as the `importe` query parameter. Negative totals are accepted for credit notes.","example":5712},"verifactuMode":{"description":"Deprecated and ignored. The platform is VERI*FACTU-only (`TipoUsoPosibleSoloVerifactu='S'`), so the QR always points at the `ValidarQR` cotejo service. Whether that is the AEAT test or production host follows the deployment configuration (`GOV_API_ES_AEAT_URL`), not this flag. Accepted for backwards compatibility; will be removed.","example":false,"deprecated":true,"type":"boolean"}},"required":["sellerNif","invoiceSeries","invoiceNumber","invoiceDate","total"],"description":"Inputs to the AEAT VeriFactu QR builder."}}}},"responses":{"200":{"description":"QR generated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"AEAT verification URL embedded in the QR code.","example":"https://prewww2.aeat.es/wlpl/TIKE-CONT/ValidarQR?nif=B12345678&numserie=A2026-0042&fecha=20-03-2026&importe=5712.00"},"png":{"type":"string","description":"Base64-encoded PNG image of the QR code (no data URL prefix).","example":"iVBORw0KGgoAAAANSUhEUgAA..."},"svg":{"type":"string","description":"SVG markup string for the QR code.","example":"<svg ...>...</svg>"}},"required":["url","png","svg"],"description":"VeriFactu QR generation result."}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]},"example":{"error":"Bad Request","message":"Invalid VeriFactu QR input"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]}}}},"403":{"description":"Forbidden - Missing required entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]}}}}}}},"/api/v1/invoice/attachments":{"post":{"operationId":"postApiV1InvoiceAttachments","tags":["Invoice Generation"],"summary":"Attach documents to an invoice PDF","description":"Embeds one or more files as attachments into an invoice PDF (visible in the Acrobat Attachments pane). For PDF/A-3 carriers (ZUGFeRD/Factur-X) the result stays PDF/A-3 conformant; the `relationship` defaults to `Supplement`.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pdf":{"type":"string","minLength":1,"description":"Base64-encoded carrier PDF to embed the attachments into"},"attachments":{"minItems":1,"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":255,"description":"Filename shown in the PDF Attachments pane","example":"leistungsnachweis.pdf"},"mimeType":{"description":"MIME type of the attachment","example":"application/pdf","type":"string","maxLength":127},"contentBase64":{"type":"string","minLength":1,"description":"Base64-encoded file content"},"description":{"description":"Human-readable description","type":"string","maxLength":255},"relationship":{"description":"PDF/A-3 AFRelationship. Defaults to \"Supplement\" for supporting documents.","type":"string","enum":["Data","Source","Alternative","Supplement","Unspecified"]}},"required":["filename","contentBase64"],"description":"A single embedded file attachment"},"description":"Files to embed into the PDF"}},"required":["pdf","attachments"],"description":"Request body for embedding attachments into a PDF"}}}},"responses":{"200":{"description":"PDF with embedded attachments","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"string","description":"Base64-encoded result PDF with the attachments embedded"},"pdfA3Conformant":{"type":"boolean","description":"True if the carrier was PDF/A-3 and conformance was preserved","example":true},"attachmentCount":{"type":"number","description":"Number of attachments embedded","example":1}},"required":["success","data","pdfA3Conformant","attachmentCount"]}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]}}}},"403":{"description":"Forbidden — missing entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]}}}},"413":{"description":"Attachment(s) exceed the configured size limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]}}}},"429":{"description":"Quota exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]}}}}}}},"/api/v1/pdf/generate":{"post":{"operationId":"postApiV1PdfGenerate","tags":["PDF"],"summary":"Render a PDF from a template and data","description":"Renders a PDF document by merging `data` into a template. Provide either `templateId` (referring to a stored template owned by the calling organization or a system template) or `template` (an inline BlockTemplate). Returns the binary PDF as `application/pdf`. Optional `attachments` are embedded after the render (visible in the Acrobat Attachments pane).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"templateId":{"description":"UUID of a stored template (system or organization-owned). Mutually exclusive with `template`.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"template":{"description":"Inline template definition. Mutually exclusive with `templateId`.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Data object that is merged into the template placeholders. Shape is template-specific — keys must match the placeholders the template expects."},"attachments":{"description":"Optional file attachments to embed into the rendered PDF (visible in the Acrobat Attachments pane; same mechanism as ZUGFeRD/Factur-X embedding).","maxItems":20,"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":255,"description":"Filename shown to the user in the PDF Attachments pane."},"mimeType":{"description":"MIME type, e.g. \"application/xml\" for ZUGFeRD XML attachments.","type":"string","maxLength":127},"contentBase64":{"type":"string","minLength":1,"description":"Base64-encoded file content. Decoded size must be <= MAX_ATTACHMENT_BYTES (25 MB by default)."},"description":{"type":"string","maxLength":255}},"required":["filename","contentBase64"],"description":"A single embedded file attachment."}}},"required":["data"],"description":"Request body for generic PDF generation."}}}},"responses":{"200":{"description":"PDF document","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]}}}},"403":{"description":"Forbidden — missing entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]}}}},"404":{"description":"Template not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]}}}},"429":{"description":"Quota exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]}}}}}}},"/api/v1/pdf/attachments":{"post":{"operationId":"postApiV1PdfAttachments","tags":["PDF"],"summary":"Attach files to a PDF","description":"Embeds one or more files as attachments into any PDF (visible in the Acrobat Attachments pane). If the carrier is already PDF/A-3 its conformance is preserved (`pdfA3Conformant: true`); otherwise the files are embedded without claiming PDF/A-3.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pdf":{"type":"string","minLength":1,"description":"Base64-encoded carrier PDF to embed the attachments into"},"attachments":{"minItems":1,"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":255,"description":"Filename shown in the PDF Attachments pane","example":"leistungsnachweis.pdf"},"mimeType":{"description":"MIME type of the attachment","example":"application/pdf","type":"string","maxLength":127},"contentBase64":{"type":"string","minLength":1,"description":"Base64-encoded file content"},"description":{"description":"Human-readable description","type":"string","maxLength":255},"relationship":{"description":"PDF/A-3 AFRelationship. Defaults to \"Supplement\" for supporting documents.","type":"string","enum":["Data","Source","Alternative","Supplement","Unspecified"]}},"required":["filename","contentBase64"],"description":"A single embedded file attachment"},"description":"Files to embed into the PDF"}},"required":["pdf","attachments"],"description":"Request body for embedding attachments into a PDF"}}}},"responses":{"200":{"description":"PDF with embedded attachments","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"string","description":"Base64-encoded result PDF with the attachments embedded"},"pdfA3Conformant":{"type":"boolean","description":"True if the carrier was PDF/A-3 and conformance was preserved","example":true},"attachmentCount":{"type":"number","description":"Number of attachments embedded","example":1}},"required":["success","data","pdfA3Conformant","attachmentCount"]}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]}}}},"403":{"description":"Forbidden — missing entitlement","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]}}}},"413":{"description":"Attachment(s) exceed the configured size limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]}}}},"429":{"description":"Quota exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","const":"QUOTA_EXCEEDED","description":"Error code"},"message":{"type":"string","description":"Error message","example":"Usage limit reached for pdf:de:generate"},"quota":{"type":"object","properties":{"current":{"type":"number","description":"Current usage count","example":100},"limit":{"type":"number","description":"Usage limit","example":100},"period":{"type":"string","description":"Billing period","example":"2026-03"}},"required":["current","limit","period"]}},"required":["error","message","quota"]}}}}}}},"/api/v1/peppol/registration":{"post":{"operationId":"postApiV1PeppolRegistration","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"environment":{"default":"production","type":"string","enum":["sandbox","production"],"description":"Peppol settings scope to use (which provider config + API key)"},"senderPeppolId":{"type":"string","pattern":"^\\d{4}:.+$","description":"The organization's own Peppol address","example":"9930:DE123456789"},"legalName":{"type":"string","minLength":1,"maxLength":255,"description":"Registered legal name — published in the Peppol directory"},"country":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2","example":"DE"},"address":{"description":"Postal address — some Access Points require it for KYC","type":"object","properties":{"line1":{"type":"string","maxLength":255},"city":{"type":"string","maxLength":128},"zip":{"type":"string","maxLength":32}}}},"required":["senderPeppolId","legalName","country"]}}}},"tags":["Peppol"],"summary":"Activate Peppol for the organization","description":"Registers the organization as a participant in the Peppol network via the platform's Access Point (legal entity + Peppol identifier are created under the platform account). Status may be `pending` when the Access Point requires an asynchronous verification (KYC). Provider and API key are platform configuration — they are never supplied by the customer.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Registration state after the activation attempt","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"settings":{"anyOf":[{"type":"object","properties":{"senderPeppolId":{"type":"string"},"registrationStatus":{"type":"string","enum":["unregistered","pending","active","deregistering","failed"]},"registrationError":{"anyOf":[{"type":"string"},{"type":"null"}]},"registeredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"enabled":{"type":"boolean"},"environment":{"type":"string","enum":["sandbox","production"],"description":"Peppol settings scope to use (which provider config + API key)"}},"additionalProperties":{}},{"type":"null"}],"description":"Registration lifecycle state (null when nothing is configured)"},"errorCode":{"type":"string"},"errorMessage":{"type":"string"}},"required":["success","settings"]}}}},"400":{"description":"Invalid input (Peppol id, legal name)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"settings":{"anyOf":[{"type":"object","properties":{"senderPeppolId":{"type":"string"},"registrationStatus":{"type":"string","enum":["unregistered","pending","active","deregistering","failed"]},"registrationError":{"anyOf":[{"type":"string"},{"type":"null"}]},"registeredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"enabled":{"type":"boolean"},"environment":{"type":"string","enum":["sandbox","production"],"description":"Peppol settings scope to use (which provider config + API key)"}},"additionalProperties":{}},{"type":"null"}],"description":"Registration lifecycle state (null when nothing is configured)"},"errorCode":{"type":"string"},"errorMessage":{"type":"string"}},"required":["success","settings"]}}}},"409":{"description":"Platform provider not configured","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"settings":{"anyOf":[{"type":"object","properties":{"senderPeppolId":{"type":"string"},"registrationStatus":{"type":"string","enum":["unregistered","pending","active","deregistering","failed"]},"registrationError":{"anyOf":[{"type":"string"},{"type":"null"}]},"registeredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"enabled":{"type":"boolean"},"environment":{"type":"string","enum":["sandbox","production"],"description":"Peppol settings scope to use (which provider config + API key)"}},"additionalProperties":{}},{"type":"null"}],"description":"Registration lifecycle state (null when nothing is configured)"},"errorCode":{"type":"string"},"errorMessage":{"type":"string"}},"required":["success","settings"]}}}},"501":{"description":"Registration layer not available in this deployment yet","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"missing":{"type":"string"}},"required":["error","missing"]}}}},"502":{"description":"Access Point rejected the registration","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"settings":{"anyOf":[{"type":"object","properties":{"senderPeppolId":{"type":"string"},"registrationStatus":{"type":"string","enum":["unregistered","pending","active","deregistering","failed"]},"registrationError":{"anyOf":[{"type":"string"},{"type":"null"}]},"registeredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"enabled":{"type":"boolean"},"environment":{"type":"string","enum":["sandbox","production"],"description":"Peppol settings scope to use (which provider config + API key)"}},"additionalProperties":{}},{"type":"null"}],"description":"Registration lifecycle state (null when nothing is configured)"},"errorCode":{"type":"string"},"errorMessage":{"type":"string"}},"required":["success","settings"]}}}}}},"get":{"operationId":"getApiV1PeppolRegistration","tags":["Peppol"],"summary":"Get the Peppol registration status","description":"Lifecycle state of the participant registration (unregistered/pending/active/deregistering/failed). Query param: `environment` (sandbox|production, default production).","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Registration state (settings null when nothing configured)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"settings":{"anyOf":[{"type":"object","properties":{"senderPeppolId":{"type":"string"},"registrationStatus":{"type":"string","enum":["unregistered","pending","active","deregistering","failed"]},"registrationError":{"anyOf":[{"type":"string"},{"type":"null"}]},"registeredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"enabled":{"type":"boolean"},"environment":{"type":"string","enum":["sandbox","production"],"description":"Peppol settings scope to use (which provider config + API key)"}},"additionalProperties":{}},{"type":"null"}],"description":"Registration lifecycle state (null when nothing is configured)"},"errorCode":{"type":"string"},"errorMessage":{"type":"string"}},"required":["success","settings"]}}}},"501":{"description":"Registration layer not available in this deployment yet","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"missing":{"type":"string"}},"required":["error","missing"]}}}}}},"delete":{"operationId":"deleteApiV1PeppolRegistration","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"environment":{"default":"production","type":"string","enum":["sandbox","production"],"description":"Peppol settings scope to use (which provider config + API key)"}}}}}},"tags":["Peppol"],"summary":"Deactivate Peppol for the organization","description":"Deregisters the participant at the Access Point and disables sending/receiving. The configuration row is kept, so re-activation re-registers without losing settings.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Registration state after deactivation","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"settings":{"anyOf":[{"type":"object","properties":{"senderPeppolId":{"type":"string"},"registrationStatus":{"type":"string","enum":["unregistered","pending","active","deregistering","failed"]},"registrationError":{"anyOf":[{"type":"string"},{"type":"null"}]},"registeredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"enabled":{"type":"boolean"},"environment":{"type":"string","enum":["sandbox","production"],"description":"Peppol settings scope to use (which provider config + API key)"}},"additionalProperties":{}},{"type":"null"}],"description":"Registration lifecycle state (null when nothing is configured)"},"errorCode":{"type":"string"},"errorMessage":{"type":"string"}},"required":["success","settings"]}}}},"404":{"description":"No Peppol configuration for this organization/environment","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]}}}},"501":{"description":"Registration layer not available in this deployment yet","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"missing":{"type":"string"}},"required":["error","missing"]}}}},"502":{"description":"Access Point rejected the deregistration","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"settings":{"anyOf":[{"type":"object","properties":{"senderPeppolId":{"type":"string"},"registrationStatus":{"type":"string","enum":["unregistered","pending","active","deregistering","failed"]},"registrationError":{"anyOf":[{"type":"string"},{"type":"null"}]},"registeredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"enabled":{"type":"boolean"},"environment":{"type":"string","enum":["sandbox","production"],"description":"Peppol settings scope to use (which provider config + API key)"}},"additionalProperties":{}},{"type":"null"}],"description":"Registration lifecycle state (null when nothing is configured)"},"errorCode":{"type":"string"},"errorMessage":{"type":"string"}},"required":["success","settings"]}}}}}}},"/api/v1/peppol/send":{"post":{"operationId":"postApiV1PeppolSend","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"environment":{"default":"production","type":"string","enum":["sandbox","production"],"description":"Peppol settings scope to use (which provider config + API key)"},"receiverPeppolId":{"type":"string","pattern":"^\\d{4}:.+$","description":"Receiver participant address","example":"9930:DE987654321"},"documentType":{"default":"invoice","type":"string","enum":["invoice","credit-note"],"description":"Document type of the UBL payload"},"document":{"type":"string","minLength":1,"description":"Base64-encoded UBL XML (Peppol BIS Billing 3.0) — e.g. from a /generate endpoint","example":"<BASE64 UBL XML>"},"invoiceNumber":{"description":"Invoice number for the transmissions log (UI only, not sent over the network)","type":"string","maxLength":255},"issueDate":{"description":"ISO 8601 issue date (log/UI only)","type":"string","maxLength":64},"verifyReceiver":{"description":"Run an SMP discovery check first and refuse with RECEIVER_NOT_REACHABLE when the receiver cannot accept the document type","type":"boolean"}},"required":["receiverPeppolId","document"]}}}},"tags":["Peppol"],"summary":"Send a UBL document over the Peppol network","description":"Dispatches a base64-encoded UBL (Peppol BIS Billing 3.0) document to the receiver via the organization's configured Access Point provider (Storecove, ecosio, or mock for testing). Every attempt — success or failure — is persisted to the transmissions log. Configure the provider first in the console under Settings → Peppol.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Document accepted by the Access Point","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"transmission":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"invoiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"direction":{"type":"string","enum":["outbound","inbound"]},"providerName":{"type":"string","example":"storecove"},"messageId":{"type":"string","description":"Provider-assigned message id (or local-* for failed sends)"},"senderPeppolId":{"type":"string","example":"9930:DE123456789"},"receiverPeppolId":{"type":"string","example":"9930:DE987654321"},"documentType":{"type":"string"},"status":{"type":"string","enum":["pending","sent","delivered","failed","rejected"]},"errorCode":{"anyOf":[{"type":"string"},{"type":"null"}]},"errorMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"contentHash":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"SHA-256 of the UBL payload"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"statusAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","organizationId","invoiceId","direction","providerName","messageId","senderPeppolId","receiverPeppolId","documentType","status","errorCode","errorMessage","contentHash","createdAt","updatedAt","statusAt"]},{"type":"null"}],"description":"Persisted log row — present for every attempt that reached the provider"},"errorCode":{"type":"string"},"errorMessage":{"type":"string"}},"required":["success","transmission"]}}}},"400":{"description":"Invalid input (receiver id, empty document)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"transmission":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"invoiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"direction":{"type":"string","enum":["outbound","inbound"]},"providerName":{"type":"string","example":"storecove"},"messageId":{"type":"string","description":"Provider-assigned message id (or local-* for failed sends)"},"senderPeppolId":{"type":"string","example":"9930:DE123456789"},"receiverPeppolId":{"type":"string","example":"9930:DE987654321"},"documentType":{"type":"string"},"status":{"type":"string","enum":["pending","sent","delivered","failed","rejected"]},"errorCode":{"anyOf":[{"type":"string"},{"type":"null"}]},"errorMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"contentHash":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"SHA-256 of the UBL payload"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"statusAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","organizationId","invoiceId","direction","providerName","messageId","senderPeppolId","receiverPeppolId","documentType","status","errorCode","errorMessage","contentHash","createdAt","updatedAt","statusAt"]},{"type":"null"}],"description":"Persisted log row — present for every attempt that reached the provider"},"errorCode":{"type":"string"},"errorMessage":{"type":"string"}},"required":["success","transmission"]}}}},"409":{"description":"Peppol not configured or disabled for this organization/environment","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"transmission":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"invoiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"direction":{"type":"string","enum":["outbound","inbound"]},"providerName":{"type":"string","example":"storecove"},"messageId":{"type":"string","description":"Provider-assigned message id (or local-* for failed sends)"},"senderPeppolId":{"type":"string","example":"9930:DE123456789"},"receiverPeppolId":{"type":"string","example":"9930:DE987654321"},"documentType":{"type":"string"},"status":{"type":"string","enum":["pending","sent","delivered","failed","rejected"]},"errorCode":{"anyOf":[{"type":"string"},{"type":"null"}]},"errorMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"contentHash":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"SHA-256 of the UBL payload"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"statusAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","organizationId","invoiceId","direction","providerName","messageId","senderPeppolId","receiverPeppolId","documentType","status","errorCode","errorMessage","contentHash","createdAt","updatedAt","statusAt"]},{"type":"null"}],"description":"Persisted log row — present for every attempt that reached the provider"},"errorCode":{"type":"string"},"errorMessage":{"type":"string"}},"required":["success","transmission"]}}}},"422":{"description":"Receiver not reachable in the Peppol network (verifyReceiver=true)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"transmission":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"invoiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"direction":{"type":"string","enum":["outbound","inbound"]},"providerName":{"type":"string","example":"storecove"},"messageId":{"type":"string","description":"Provider-assigned message id (or local-* for failed sends)"},"senderPeppolId":{"type":"string","example":"9930:DE123456789"},"receiverPeppolId":{"type":"string","example":"9930:DE987654321"},"documentType":{"type":"string"},"status":{"type":"string","enum":["pending","sent","delivered","failed","rejected"]},"errorCode":{"anyOf":[{"type":"string"},{"type":"null"}]},"errorMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"contentHash":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"SHA-256 of the UBL payload"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"statusAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","organizationId","invoiceId","direction","providerName","messageId","senderPeppolId","receiverPeppolId","documentType","status","errorCode","errorMessage","contentHash","createdAt","updatedAt","statusAt"]},{"type":"null"}],"description":"Persisted log row — present for every attempt that reached the provider"},"errorCode":{"type":"string"},"errorMessage":{"type":"string"}},"required":["success","transmission"]}}}},"501":{"description":"Dispatch layer not available in this deployment yet","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"missing":{"type":"string"}},"required":["error","missing"]}}}},"502":{"description":"Access Point rejected the document or was unreachable","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"transmission":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"invoiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"direction":{"type":"string","enum":["outbound","inbound"]},"providerName":{"type":"string","example":"storecove"},"messageId":{"type":"string","description":"Provider-assigned message id (or local-* for failed sends)"},"senderPeppolId":{"type":"string","example":"9930:DE123456789"},"receiverPeppolId":{"type":"string","example":"9930:DE987654321"},"documentType":{"type":"string"},"status":{"type":"string","enum":["pending","sent","delivered","failed","rejected"]},"errorCode":{"anyOf":[{"type":"string"},{"type":"null"}]},"errorMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"contentHash":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"SHA-256 of the UBL payload"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"statusAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","organizationId","invoiceId","direction","providerName","messageId","senderPeppolId","receiverPeppolId","documentType","status","errorCode","errorMessage","contentHash","createdAt","updatedAt","statusAt"]},{"type":"null"}],"description":"Persisted log row — present for every attempt that reached the provider"},"errorCode":{"type":"string"},"errorMessage":{"type":"string"}},"required":["success","transmission"]}}}}}}},"/api/v1/peppol/receivers/{peppolId}":{"get":{"operationId":"getApiV1PeppolReceiversByPeppolId","tags":["Peppol"],"summary":"Check whether a receiver is reachable in the Peppol network","description":"Runs an SMP discovery lookup via the configured Access Point. Use before sending to validate the receiver address. Query params: `environment` (sandbox|production, default production), `documentType` (invoice|credit-note, default invoice).","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Lookup result","content":{"application/json":{"schema":{"type":"object","properties":{"reachable":{"type":"boolean","description":"Whether the receiver accepts the document type (SMP discovery)"},"participant":{"anyOf":[{"type":"object","properties":{"peppolId":{"type":"object","properties":{"scheme":{"type":"string"},"identifier":{"type":"string"},"formatted":{"type":"string"}},"required":["scheme","identifier","formatted"]},"name":{"type":"string"},"country":{"type":"string"},"documentTypes":{"type":"array","items":{"type":"string"}},"accessPoint":{"type":"string"}},"required":["peppolId","documentTypes"]},{"type":"null"}]},"errorCode":{"type":"string"},"errorMessage":{"type":"string"}},"required":["reachable","participant"]}}}},"400":{"description":"Invalid Peppol id","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]}}}},"501":{"description":"Dispatch layer not available in this deployment yet","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"missing":{"type":"string"}},"required":["error","missing"]}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"peppolId","required":true}]}},"/api/v1/peppol/transmissions":{"get":{"operationId":"getApiV1PeppolTransmissions","tags":["Peppol"],"summary":"List Peppol transmissions","description":"Outbound and inbound transmission log for the organization. Query params: `direction` (outbound|inbound), `status` (pending|sent|delivered|failed|rejected), `limit` (1-500, default 100).","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Transmission log","content":{"application/json":{"schema":{"type":"object","properties":{"transmissions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"invoiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"direction":{"type":"string","enum":["outbound","inbound"]},"providerName":{"type":"string","example":"storecove"},"messageId":{"type":"string","description":"Provider-assigned message id (or local-* for failed sends)"},"senderPeppolId":{"type":"string","example":"9930:DE123456789"},"receiverPeppolId":{"type":"string","example":"9930:DE987654321"},"documentType":{"type":"string"},"status":{"type":"string","enum":["pending","sent","delivered","failed","rejected"]},"errorCode":{"anyOf":[{"type":"string"},{"type":"null"}]},"errorMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"contentHash":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"SHA-256 of the UBL payload"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"statusAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","organizationId","invoiceId","direction","providerName","messageId","senderPeppolId","receiverPeppolId","documentType","status","errorCode","errorMessage","contentHash","createdAt","updatedAt","statusAt"]}}},"required":["transmissions"]}}}}}}},"/api/v1/peppol/transmissions/{messageId}/refresh":{"post":{"operationId":"postApiV1PeppolTransmissionsByMessageIdRefresh","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"environment":{"default":"production","type":"string","enum":["sandbox","production"],"description":"Peppol settings scope to use (which provider config + API key)"}}}}}},"tags":["Peppol"],"summary":"Refresh the delivery status of a sent document","description":"Re-queries the Access Point for the current delivery status and syncs the transmissions log row. Synthetic local-* ids (failed sends that never reached the provider) are returned unchanged.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Current transmission state","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"transmission":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"invoiceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"direction":{"type":"string","enum":["outbound","inbound"]},"providerName":{"type":"string","example":"storecove"},"messageId":{"type":"string","description":"Provider-assigned message id (or local-* for failed sends)"},"senderPeppolId":{"type":"string","example":"9930:DE123456789"},"receiverPeppolId":{"type":"string","example":"9930:DE987654321"},"documentType":{"type":"string"},"status":{"type":"string","enum":["pending","sent","delivered","failed","rejected"]},"errorCode":{"anyOf":[{"type":"string"},{"type":"null"}]},"errorMessage":{"anyOf":[{"type":"string"},{"type":"null"}]},"contentHash":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"SHA-256 of the UBL payload"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"statusAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","organizationId","invoiceId","direction","providerName","messageId","senderPeppolId","receiverPeppolId","documentType","status","errorCode","errorMessage","contentHash","createdAt","updatedAt","statusAt"]},{"type":"null"}],"description":"Persisted log row — present for every attempt that reached the provider"},"errorCode":{"type":"string"},"errorMessage":{"type":"string"}},"required":["success","transmission"]}}}},"404":{"description":"Unknown message id for this organization","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error code","example":"Bad Request"},"message":{"type":"string","description":"Human-readable error message","example":"Invoice data is required"}},"required":["error","message"]}}}},"501":{"description":"Dispatch layer not available in this deployment yet","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"missing":{"type":"string"}},"required":["error","missing"]}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"messageId","required":true}]}}}}