{"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, 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 generic \"System Template Standard\" 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 PL/PT/RO 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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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` > the built-in template for the invoice's country > a generic fallback. If all three are omitted, the invoice gets the layout of ITS OWN country — a German invoice gets the German template. Only countries without their own template fall back to the generic \"System Template Standard\".","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; the lineless `MINIMUM` and `BASIC WL` profiles are retired and rejected with a 400), `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` > the built-in template for the invoice's country > a generic fallback. If all three are omitted, the invoice gets the layout of ITS OWN country — a German invoice gets the German template. Only countries without their own template fall back to the generic \"System Template Standard\".\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 generic \"System Template Standard\").","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":"Legacy alias for `profile`. Prefer `profile` — this key is only still read on the `/convert` endpoint. Like `profile`, it rejects the retired `MINIMUM` and `BASIC WL` profiles with a 400.","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\n**Retired:** `MINIMUM` and `BASIC WL` / `BASIC_WL` are no longer available. They carry no invoice line items and are therefore not EN-16931 compliant — the specification defines them as a booking aid, not as an invoice. Requesting either returns a 400 naming the alternatives.","example":"EN16931","type":"string","enum":["EN16931","BASIC","EXTENDED"]},"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, unsupported country/format, or a retired format profile (`MINIMUM` / `BASIC WL`)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for pdf:de:generate","quota":{"current":100,"limit":100}}}}},"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+MDQwMTEwMDAtMTIzNDUtMzQ8L2NiYzpCdXllclJlZmVyZW5jZT4KICA8Y2FjOkFjY291bnRpbmdTdXBwbGllclBhcnR5PgogICAgPGNhYzpQYXJ0eT4KICAgICAgPGNiYzpFbmRwb2ludElEIHNjaGVtZUlEPSJFTSI+YmlsbGluZ0B0ZWNoY29ycC5kZTwvY2JjOkVuZHBvaW50SUQ+CiAgICAgIDxjYWM6UGFydHlJZGVudGlmaWNhdGlvbj4KICAgICAgICA8Y2JjOklEPkRFMTM2Njk1OTc2PC9jYmM6SUQ+CiAgICAgIDwvY2FjOlBhcnR5SWRlbnRpZmljYXRpb24+CiAgICAgIDxjYWM6UGFydHlOYW1lPgogICAgICAgIDxjYmM6TmFtZT5UZWNoQ29ycCBHbWJIPC9jYmM6TmFtZT4KICAgICAgPC9jYWM6UGFydHlOYW1lPgogICAgICA8Y2FjOlBvc3RhbEFkZHJlc3M+CiAgICAgICAgPGNiYzpTdHJlZXROYW1lPkthbnRzdHJhw59lIDEyPC9jYmM6U3RyZWV0TmFtZT4KICAgICAgICA8Y2JjOkNpdHlOYW1lPkJlcmxpbjwvY2JjOkNpdHlOYW1lPgogICAgICAgIDxjYmM6UG9zdGFsWm9uZT4xMDYyMzwvY2JjOlBvc3RhbFpvbmU+CiAgICAgICAgPGNhYzpDb3VudHJ5PgogICAgICAgICAgPGNiYzpJZGVudGlmaWNhdGlvbkNvZGU+REU8L2NiYzpJZGVudGlmaWNhdGlvbkNvZGU+CiAgICAgICAgPC9jYWM6Q291bnRyeT4KICAgICAgPC9jYWM6UG9zdGFsQWRkcmVzcz4KICAgICAgPGNhYzpQYXJ0eVRheFNjaGVtZT4KICAgICAgICA8Y2JjOkNvbXBhbnlJRD5ERTEzNjY5NTk3NjwvY2JjOkNvbXBhbnlJRD4KICAgICAgICA8Y2FjOlRheFNjaGVtZT4KICAgICAgICAgIDxjYmM6SUQ+VkFUPC9jYmM6SUQ+CiAgICAgICAgPC9jYWM6VGF4U2NoZW1lPgogICAgICA8L2NhYzpQYXJ0eVRheFNjaGVtZT4KICAgICAgPGNhYzpQYXJ0eVRheFNjaGVtZT4KICAgICAgICA8Y2JjOkNvbXBhbnlJRD4yNy8xMjMvNDU2Nzg8L2NiYzpDb21wYW55SUQ+CiAgICAgICAgPGNhYzpUYXhTY2hlbWU+CiAgICAgICAgICA8Y2JjOklEPkZDPC9jYmM6SUQ+CiAgICAgICAgPC9jYWM6VGF4U2NoZW1lPgogICAgICA8L2NhYzpQYXJ0eVRheFNjaGVtZT4KICAgICAgPGNhYzpQYXJ0eUxlZ2FsRW50aXR5PgogICAgICAgIDxjYmM6UmVnaXN0cmF0aW9uTmFtZT5UZWNoQ29ycCBHbWJIPC9jYmM6UmVnaXN0cmF0aW9uTmFtZT4KICAgICAgPC9jYWM6UGFydHlMZWdhbEVudGl0eT4KICAgICAgPGNhYzpDb250YWN0PgogICAgICAgIDxjYmM6TmFtZT5UZWNoQ29ycCBHbWJIPC9jYmM6TmFtZT4KICAgICAgICA8Y2JjOlRlbGVwaG9uZT4rNDkgMzAgMTIzNDU2NzwvY2JjOlRlbGVwaG9uZT4KICAgICAgICA8Y2JjOkVsZWN0cm9uaWNNYWlsPmJpbGxpbmdAdGVjaGNvcnAuZGU8L2NiYzpFbGVjdHJvbmljTWFpbD4KICAgICAgPC9jYWM6Q29udGFjdD4KICAgIDwvY2FjOlBhcnR5PgogIDwvY2FjOkFjY291bnRpbmdTdXBwbGllclBhcnR5PgogIDxjYWM6QWNjb3VudGluZ0N1c3RvbWVyUGFydHk+CiAgICA8Y2FjOlBhcnR5PgogICAgICA8Y2JjOkVuZHBvaW50SUQgc2NoZW1lSUQ9IkVNIj5pbnZvaWNlQG11c3Rlci5kZTwvY2JjOkVuZHBvaW50SUQ+CiAgICAgIDxjYWM6UGFydHlOYW1lPgogICAgICAgIDxjYmM6TmFtZT5NdXN0ZXIgR21iSDwvY2JjOk5hbWU+CiAgICAgIDwvY2FjOlBhcnR5TmFtZT4KICAgICAgPGNhYzpQb3N0YWxBZGRyZXNzPgogICAgICAgIDxjYmM6U3RyZWV0TmFtZT5IYXVwdHN0cmHDn2UgNDI8L2NiYzpTdHJlZXROYW1lPgogICAgICAgIDxjYmM6Q2l0eU5hbWU+TcO8bmNoZW48L2NiYzpDaXR5TmFtZT4KICAgICAgICA8Y2JjOlBvc3RhbFpvbmU+ODAzMzE8L2NiYzpQb3N0YWxab25lPgogICAgICAgIDxjYWM6Q291bnRyeT4KICAgICAgICAgIDxjYmM6SWRlbnRpZmljYXRpb25Db2RlPkRFPC9jYmM6SWRlbnRpZmljYXRpb25Db2RlPgogICAgICAgIDwvY2FjOkNvdW50cnk+CiAgICAgIDwvY2FjOlBvc3RhbEFkZHJlc3M+CiAgICAgIDxjYWM6UGFydHlUYXhTY2hlbWU+CiAgICAgICAgPGNiYzpDb21wYW55SUQ+REU4MTE1Njk4Njk8L2NiYzpDb21wYW55SUQ+CiAgICAgICAgPGNhYzpUYXhTY2hlbWU+CiAgICAgICAgICA8Y2JjOklEPlZBVDwvY2JjOklEPgogICAgICAgIDwvY2FjOlRheFNjaGVtZT4KICAgICAgPC9jYWM6UGFydHlUYXhTY2hlbWU+CiAgICAgIDxjYWM6UGFydHlMZWdhbEVudGl0eT4KICAgICAgICA8Y2JjOlJlZ2lzdHJhdGlvbk5hbWU+TXVzdGVyIEdtYkg8L2NiYzpSZWdpc3RyYXRpb25OYW1lPgogICAgICA8L2NhYzpQYXJ0eUxlZ2FsRW50aXR5PgogICAgPC9jYWM6UGFydHk+CiAgPC9jYWM6QWNjb3VudGluZ0N1c3RvbWVyUGFydHk+CiAgPGNhYzpEZWxpdmVyeT4KICAgIDxjYmM6QWN0dWFsRGVsaXZlcnlEYXRlPjIwMjYtMDMtMjA8L2NiYzpBY3R1YWxEZWxpdmVyeURhdGU+CiAgPC9jYWM6RGVsaXZlcnk+CiAgPGNhYzpQYXltZW50TWVhbnM+CiAgICA8Y2JjOlBheW1lbnRNZWFuc0NvZGU+NTg8L2NiYzpQYXltZW50TWVhbnNDb2RlPgogICAgPGNhYzpQYXllZUZpbmFuY2lhbEFjY291bnQ+CiAgICAgIDxjYmM6SUQ+REU4OTM3MDQwMDQ0MDUzMjAxMzAwMDwvY2JjOklEPgogICAgICA8Y2JjOk5hbWU+VGVjaENvcnAgR21iSDwvY2JjOk5hbWU+CiAgICAgIDxjYWM6RmluYW5jaWFsSW5zdGl0dXRpb25CcmFuY2g+CiAgICAgICAgPGNiYzpJRD5DT0JBREVGRlhYWDwvY2JjOklEPgogICAgICA8L2NhYzpGaW5hbmNpYWxJbnN0aXR1dGlvbkJyYW5jaD4KICAgIDwvY2FjOlBheWVlRmluYW5jaWFsQWNjb3VudD4KICA8L2NhYzpQYXltZW50TWVhbnM+CiAgPGNhYzpQYXltZW50VGVybXM+CiAgICA8Y2JjOk5vdGU+WmFobGJhciBpbm5lcmhhbGIgdm9uIDMwIFRhZ2VuIG9obmUgQWJ6dWc8L2NiYzpOb3RlPgogIDwvY2FjOlBheW1lbnRUZXJtcz4KICA8Y2FjOlRheFRvdGFsPgogICAgPGNiYzpUYXhBbW91bnQgY3VycmVuY3lJRD0iRVVSIj45MTIuMDA8L2NiYzpUYXhBbW91bnQ+CiAgICA8Y2FjOlRheFN1YnRvdGFsPgogICAgICA8Y2JjOlRheGFibGVBbW91bnQgY3VycmVuY3lJRD0iRVVSIj40ODAwLjAwPC9jYmM6VGF4YWJsZUFtb3VudD4KICAgICAgPGNiYzpUYXhBbW91bnQgY3VycmVuY3lJRD0iRVVSIj45MTIuMDA8L2NiYzpUYXhBbW91bnQ+CiAgICAgIDxjYWM6VGF4Q2F0ZWdvcnk+CiAgICAgICAgPGNiYzpJRD5TPC9jYmM6SUQ+CiAgICAgICAgPGNiYzpQZXJjZW50PjE5LjAwPC9jYmM6UGVyY2VudD4KICAgICAgICA8Y2FjOlRheFNjaGVtZT4KICAgICAgICAgIDxjYmM6SUQ+VkFUPC9jYmM6SUQ+CiAgICAgICAgPC9jYWM6VGF4U2NoZW1lPgogICAgICA8L2NhYzpUYXhDYXRlZ29yeT4KICAgIDwvY2FjOlRheFN1YnRvdGFsPgogIDwvY2FjOlRheFRvdGFsPgogIDxjYWM6TGVnYWxNb25ldGFyeVRvdGFsPgogICAgPGNiYzpMaW5lRXh0ZW5zaW9uQW1vdW50IGN1cnJlbmN5SUQ9IkVVUiI+NDgwMC4wMDwvY2JjOkxpbmVFeHRlbnNpb25BbW91bnQ+CiAgICA8Y2JjOlRheEV4Y2x1c2l2ZUFtb3VudCBjdXJyZW5jeUlEPSJFVVIiPjQ4MDAuMDA8L2NiYzpUYXhFeGNsdXNpdmVBbW91bnQ+CiAgICA8Y2JjOlRheEluY2x1c2l2ZUFtb3VudCBjdXJyZW5jeUlEPSJFVVIiPjU3MTIuMDA8L2NiYzpUYXhJbmNsdXNpdmVBbW91bnQ+CiAgICA8Y2JjOlBheWFibGVBbW91bnQgY3VycmVuY3lJRD0iRVVSIj41NzEyLjAwPC9jYmM6UGF5YWJsZUFtb3VudD4KICA8L2NhYzpMZWdhbE1vbmV0YXJ5VG90YWw+CiAgPGNhYzpJbnZvaWNlTGluZT4KICAgIDxjYmM6SUQ+MTwvY2JjOklEPgogICAgPGNiYzpJbnZvaWNlZFF1YW50aXR5IHVuaXRDb2RlPSJIVVIiPjQwPC9jYmM6SW52b2ljZWRRdWFudGl0eT4KICAgIDxjYmM6TGluZUV4dGVuc2lvbkFtb3VudCBjdXJyZW5jeUlEPSJFVVIiPjQ4MDAuMDA8L2NiYzpMaW5lRXh0ZW5zaW9uQW1vdW50PgogICAgPGNhYzpJdGVtPgogICAgICA8Y2JjOkRlc2NyaXB0aW9uPlNvZnR3YXJlIERldmVsb3BtZW50IFNlcnZpY2VzIOKAlCBNYXJjaCAyMDI2PC9jYmM6RGVzY3JpcHRpb24+CiAgICAgIDxjYmM6TmFtZT5Tb2Z0d2FyZSBEZXZlbG9wbWVudCBTZXJ2aWNlcyDigJQgTWFyY2ggMjAyNjwvY2JjOk5hbWU+CiAgICAgIDxjYWM6U2VsbGVyc0l0ZW1JZGVudGlmaWNhdGlvbj4KICAgICAgICA8Y2JjOklEPlNWQy1ERVYtMDAxPC9jYmM6SUQ+CiAgICAgIDwvY2FjOlNlbGxlcnNJdGVtSWRlbnRpZmljYXRpb24+CiAgICAgIDxjYWM6Q2xhc3NpZmllZFRheENhdGVnb3J5PgogICAgICAgIDxjYmM6SUQ+UzwvY2JjOklEPgogICAgICAgIDxjYmM6UGVyY2VudD4xOS4wMDwvY2JjOlBlcmNlbnQ+CiAgICAgICAgPGNhYzpUYXhTY2hlbWU+CiAgICAgICAgICA8Y2JjOklEPlZBVDwvY2JjOklEPgogICAgICAgIDwvY2FjOlRheFNjaGVtZT4KICAgICAgPC9jYWM6Q2xhc3NpZmllZFRheENhdGVnb3J5PgogICAgPC9jYWM6SXRlbT4KICAgIDxjYWM6UHJpY2U+CiAgICAgIDxjYmM6UHJpY2VBbW91bnQgY3VycmVuY3lJRD0iRVVSIj4xMjAuMDA8L2NiYzpQcmljZUFtb3VudD4KICAgIDwvY2FjOlByaWNlPgogIDwvY2FjOkludm9pY2VMaW5lPgo8L3VibDpJbnZvaWNlPg==","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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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":"JVBERi0xLjcKJYGBgYEKCjUgMCBvYmoKPDwKL0xlbmd0aCAyMDM4Ci9GaWx0ZXIgL0ZsYXRlRGVjb2RlCj4+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/Q6WbxTX65hR3EqmngLL7bGvOyCOMmeIqWPVA1G3u6qbm8YCPqzBzEbgWEeMXb8jc1YxqYw2lbmfY6u03rP4mNljQZAw1S7AqwWVswjouYHb2Qjk8yzyYfOEDFGM6/edXwZzEDcv1W0T7/JtgPU3A9rfsqjGMoq2Y/IzPyM5+4prmbhbBnIVIavn3MVRQ/TdUcoLk+W+PfvlGckoYojItBk1l/yhHDdTqn3Iw7HVWm1K8QnA/wMNvxQ5CmVuZHN0cmVhbQplbmRvYmoKCjE3IDAgb2JqCjw8Ci9MZW5ndGggOTQwMgovRmlsdGVyIC9GbGF0ZURlY29kZQo+PgpzdHJlYW0KeJyNegd4U+e5//t95xwNSx6yLRsQ5hxxkAzIW7a8sC08ZBvjbYNkPCTLE2xsxDBhxAbCiNh7JHYW+beEjGMSwKZtCg2hpGnSJt1t0vbejufflra37b2994Il3ec7RzKj46k569vfu37v+35ik2dzNyhhDCiI6ut2dYH09zwAWPr6ul3B8qcAsGhgyB0q/xUA9g26tg5LRbQDADj3lk1csEzG+4c93cF2fAEAf9w78FSPVGb6ABZ83De4aatUXmQBQIqe4d5BqWwoBIjcBwgAKOrMJxnfLOuIXPZfoFOIrbf/Q5NC3r9qeyPy/jzf95Tpio0AoAQsLQ4gH/CrAZQr7s/zr1CmK+CJv2IAyIBueB7+gng0jC6ii+gvuBa/jL+Bf0KVUGep/6RZup3+iJnH7GIuMG8y/1+WIuuRbZONy27LF8hH5N9XzFdUKY4qPlL8RSlXJisLlQ7lZeX7yk/CGsJGw8ZVjGqFaqfqc3W4eql6RH0qfFn40fDvRKCInIhnIt6I+EmkPDIvslekrxgugRa2gBwwREEqEE79OnIzUIBkAFpGgFhy03kQCxC4F7r9zsB/MQJoAQK/A4CvwE0Yh3G4AWfhLCSKpX3wZbgMN+ACfAfehvPo53BGLF1CKtgNb8KLcAhOwzRcgng4CRdgOxyEl+CnYv04XAvOchH2wctwGa7BV+EG7IYjcAFehivwHTgO5+ENeBveRR8gnzh3OZyD8eD85+EFuAQC7IK9cBBOwSW4CjcgHurADVthJ+yBg3AMzsHL8CZ8F36KjLAdnoWTMA6vwjv0YYiyBp7O3Nm8ozDAbs8PsNsKAuxT+VZ267IAO7KsgN2SJWc35wXYTXm97MbcWtaTG2A3WALscM5H7FBOgF2f3c4OZn/EDmQH2HXZyeza7Dlsf2aA7csIsL0ZH7E95gDbnR5gu9ICrDvtMtuZ1su6UgKsM2WM7UgNsO2pJ9m25ADbmhRg15gCbMvSj1jH0gBrXxrOrl4SYFctDrDNiYvYpsRkttHQzjYYAmy94TJbZwywtcYxtmZRgK3mTexK/jJbxQfYFfwqtpI3sRULA2w5F2BtnIct0wfYUr2HLWEDbPGCk+zyBQHWmhBgi+YH2IL8k9bfssvyM9m8rAg21+Jhcyy1bLZlIWvJOsmaM6xsepqHTU1ZwZqWWtnEuTRrNCxmDWbd3NZF86JZnpk3t3Xh3ACr5wpYLmdOXCs7J5ldEB9gE+IC7Pw4Oaszz52/Zk5m3Pw188hXPPnSzi2M+38tMenRzZr0qOZoR5QjPFPdzGTSzWoH7WDpDhpH0qP0H2kqsj2iWZUZ1izPlDWjdGiOcIQ5ZI5RGUqV1cqGZFSRrEM2KqPAkQooFYbgj0ApMxXNVCZuVjiwg8UdGEfiUfxHTFFWK4Om0DGhyVQ1JQ80VAnKujUCOiAYGsnTWt8iyA4I0Nyyxj6J0BHH3sOHIaG4SjjWaL9CASQUOyYxLqm3T9LUEcfGTWACk8lE3hs3bSYFUpQqyJf0RI/8IxWIXKQJiZ2lyr/9DH39TZNUEv8e7xP6mwMy6AKgFjMCUCAHFURCDMQDLNfqs8waXqPX8JoYrT4LIR5pkBlRSt8WnQXftsT7tmCv7608XC8+GMFiuV/HCOK9z2JhWu8fYjZJN1BwCUDWwAggAxVEgc4ajuURjErhUdMgxx4wZWRkmDIyNLlp6Y1mhMyIR+YYDY/IDn79JfQ5+uzLPuGEb/OrupsM/epNRnjQRr9Clpo54LtLFsU5ABieDdyjPqfzgAYdaK1hSCPzzKEolYoskJphykhL79aYNXxMdmwE5hem4CyNWRO7AJszLBaKvzE5rzq56+VNtXvazdP63HLjFm/Bfcr64A76KR64vq8qxXlhAN/wlVZ2ZMeteQ4QdATuUV+mayAL4q0qHURkLFF54iPkZDFThiY3Ny19eabRmJhCZWUWYnNGXJyWzzQa+YUymTZ2AY5fgLXiNozGLHNwDxS/bl3L8W5Lbv+pNbunOqezuiurO0xaS+fKva835Q+d7zh6p+cGXbcpd2WvBbGLy3K1MZkrukqsHntG6/m25Oac1IrFC1ITF2oWNG1bXb6lObXn5ZaVDsNiG2BQBu7h1cxyoEALMVZlmEbloTElE1lDOEMEHmPWxMbFmTMs2fEymbgz3OC7fmd6oYWNN4ejuPKMUk8JnXfkCJI/+DA7J1pJnZWHW0YHiG9rC9yj/kLXgAlYa1RvDJLFREfDXJXcswhUIZakmjva0tLLCOclnizAWq0+S5+VgvmFEVirlYSRHR+Bcc2G63tsNfteW7Pp0kDmzA/xEG1e31G0duVSU+PIys4D5mF+YDy2+tBNz9JnvnVsRd3RW57GsxEVB+xZfWc6l1bv78mrK3FkOZcBhsMA+BxdAzTEwVxruEypZGLlHkrmwWEeYhUZGRpzWvpyDa8xG+REQBFYLpdEhmzT76DVKH7JPGtnaaIsM7Fh1B6bSR2bGabzZK8z1OIKd/6Cztf3VikBwbbAPfpz5jaYiH6bli5l5mqjKM8iRimS/01zdG6quI4kdMKCaIuF6EU8/zj9lmyNPov+XLflW6/s/dkrjuozPz78hX8bjb4VXn1kuPuUMzV//fm23rGKGP9b+Hu+3y12V7a9jdArG15B8Hbbxm/sqt1du8J7e/vGp+8crODT45DteQAKDgLInhK5oIMM0Fs1S6JxysKF8SpK5lHJQ7zQmM0as8Yc4geVWEiJUtLwmkyJNQb531ShshvC/FUoZ/3FgZVj7ZnTuX22hvXFCfgrO1Du4Iu9q/e3pd3I7S0vaLfqKffMOJ3nV1NDXzlUbWo91uNLxXebe1LzevYkGB0Xx6pSOk71+HLxB2u6lyytbAcKDgXu0XoZAA3zIBXmWiP0cXKPSaXy0GEeAEmARH8bzRo5j7RBy07MknYpz8qUeCvXEtYW4kM3ol6jTucMPN/d+9zaIrW6aO2Fnp6JdTk3FhQP1Np6K5JVUZXb11StK+FkcP/TT7FRu+WDUw3l+94dad367v7y2hMfHtfWHx0sSqvvzf6TbVdDwcARkPCNUcxiqM4arpQpKIxlcuyRKcgmifJLekbsLAistHPm3oJbdMdNqnB8HHtC+AkIjJjFEfg6UKCYpDCkBgfiCP8cfP3cOcAwGLhH/ZauAR3kwRKr1pS0IHFBXl5kYrrKM2dumEfJRIpIlEG4QzRPE00QqVsTgiA+BEqa2Lh4LW80xsSLOigBALFBSkQA0o1SmXuqbP3508s2vNC55WpvTMytiCgOf6l2R1NSSltp8+5qqlZe2HvYvv7VNaVj7wxN42RrR2ZaTXKepy277qWn/ArLtqQobh1mds/NqMowN6VX9KU7lva0Faw63rJ6ryOFyNnvpFlRP5+QMzHUiIdyFvXyn8hZI8kZ2W68hn+Ts+757t6J9cvV6uLB53t6JgaybywsX79SlHNsxdY1VYPlC6m19//K/Nh3TxR06e5rnuG/EbTfZ9teVbT+KME5oo9rZdGQS7CE11kUOMyjQB6dKmg/ISwJsTeW8HQBpY2VEDUxW+JvVqbkF7KC8kClU7l9x+yDlzoTMxJtff0295vDlq3ueUv5vbYaVxKpWWpZmrEqu6wzk7Y/+CJtX//qUE7F6U116+przNmr61o81Z4zlVp99HNxlrS69NzV9S1b6pe11jtySxwphbsAQxYAXc8IooYmWCMouVyGMaNUe1QMLUJUdG5qrjk6V1I1ZKYQIjpa/+CX+NDZl/31eHQa/fbcIPUn/2e+dupOUFPbAWgzcxtYmGtVR0WptYyHYlmsJjNqzKaMjNS09G4y30NatXymBHyEOXJEm2fK0ed2V2K+p961yzo98N3nvLf7TVXuHP+2c+f24pjOZwdzKzbbqvat3v7Np1xvbbbu2f10gd9BMGFD4B4dydyGKOAgDaygt0aFFxQYkrVaOiuZ8STQ4ZLvic5NjQ7SFhREyCnLZ32yJJiY2XZpj0+205HbP9mz59NtJdsv9ez79Kkbtqcbm7eXluxctWpHybnhr23f+d76oa/t2Pm1oenC9ZWVgwUF5FmIvHunnc7pvauPD+T3vjNcv9Nm21nfNFJUNIIfrH2ts/O1taNX2tuv7K4cXl4wXF01XFg4DBg2Bu7RKuY2xEMq8dkmGRvNeGSEJFMQSyQzoELulKI0mSmUaMea2AUUMQRaZd16aW3TkQ11S5dvvdTffHS4dumN+KSS1ZbinrJF8SnFq7NKe8oWUit/+vZfz5QsbTvz/aM/ffvPJ61LHCe/69+MdJ2n1xaz6Wtf3+7/VeeZQZs+c+gtwGLsc5+5DfMhH5Za43TzF7A0QEJCtDk1dUm4JzxcGc2I8JNKIi8CftHxhPmS6v8dNeB5bZboVkKhmTk2ZChGI4/2P+MaLcoZXlUzUjI9/OG+Z+6sN697bWRi4uC1flPZzi+6O74wVjFdsrO5eXvJyoPtlHn5hvImT17B8MqhawNt1w9k7xwoWzxUvH7P8p6J9TmW3rOulZ6i/K1r1mzOJTZ9GQD/iJkCGaivymgPIsprksyYyTLgH037D2INM3W/gv7kwBfuQiAgRZrMHZmR5PZIDsvhGACEX6dwugah66vAlJkJUuxB/Tzodedaw6Px3/hbzT/xtcg2/dbCamTd9FJn3diatBsZTlvZhvpkqnHmjYdOtP30Ol8+/npzL3GioUjs93QNJBKLTJg7N1buoWlQqh7KIy29m0C8OcjqkCk8FofgwuLhCkZgRm5u3HZ1JD9/5Oq20XcHGYFZPrSieWNJwvySjc9YOgqcr3avOvPe4NLB986s6p0cLhlYXrLh2fKl5d7hkln6ZcRDzoN4q1qD48LkHgpmQ68Q9TF/l/jDf0u7DO6DDGZs/4D26wBoq+iH1VcBe5DioSTR1ltB9wpI9NdKRgAlid0pBaOUYw9mFCGwyBWHINHVaBjl13z8rVv452Q47X4wzggPLtA9gCEBgPYxAtDSPCBTICX2UIpH5+kWsxkUzyM8it74xPer0/6X0KWs075ff05/h2znQfLn0p72Bu7RCcwVsJD4ISJpzsKFSRTQnqSgvRMfTrhl1j4SKxJQJUKTyeQhDsbOSjXasogqioo6eWeTOaWuO9vaVbaIK3aXVu9tlnVGVG88Wjc40ZOet/GLQ1uETXmF51EUc2W844U7Pd93ne7JTHdsq1z+VEd21VPlaPiF7tSGZy+39L5zYKXr5Ts9qy+gxf9xhOy5K+Cn/oe5DTlkz5ATp9fnqE2MJ0f92J67xY2GXHRo59nm0FZnc4HYCIrnUXrMi3cHFifXduVYu8UtlxQONptp+/JNz7cOTHSn53kuDe0UhjIT6i/899WY51rOfbX7Z+4LfRZz647K5ds6c9ObB/IbX3qmtunQG46+awdrur746VDJht989wsuQFAfuEdvZG5DLrDWyDBjpCU93aT0zImNjaRCaWJqKHtLwf84e6MeQapg+jbJVu/vHXhzR7Ftz7Xhi7/aetN2ZLB33/LExl0tO97ZnFux70sbu997oeNmXvcuW/ehSjRsrrXmLeBqe55pbj62btnODzwNo5WFa0tTqqyWufyqdfubHcd6snOGXx2sWmfT5/QBhtbAPTqLrgEtmCDq+nyNypMoC2acaemNjzJS3Fv2rJaEmN9aOnZtg+f6rtLSXVc9nmu7SqeN1ZuqV25cmZhYvbF65cZqI9bEb/7gdGPj6Q82x2++Sz7uHoqvP7q+qGj90fr4uqNDVuvQUWLbBQD4Q5kWNKAFrVUVq5V5wmXIg0TTFjfk4jUSxMfLg6yLJ5HAS9PNL67nlrNh2qx5+c1Jv/Zdo1/f/FKjQnGWoVNbij1HjgANJgDmO3QeMBAGkaCFRdZYuQo0VKxMGaVGYTJPdAStDJs9OsgQ/Us3MssRT8XE8wjFmBFPEbtLRC+guG1z/L8aeen3mp3+O3TEv0/57+z4Dopit/g/n3OT2jY5M0Lnzey4RufN7KF2PrhD582c/hZ18C1C5SUA+uuMAPNggXhugVBCRGTkAuxJUAT9sIThLn22nrgrkdH6LH1IDAREsNn/bYxSnv92/7JNXxjwT6GKo/cut7a+8Rf/C7fG9/z+BcfO9/bbJjre9k2snvBd6QjCFAY9APUl8TzjIb7IPJQi7El8EelE30eLv+LfvuMnKF27w7/1C9RJkZK+l+k8QOTkHK0SkVh9dRaAg8i46oYEq4ReYtb9zG2gIBKirsvDZ/Pkj4PBN5VJJKqNJVESWnUjItuSlZubZcmm88hyiE0uLEw2FRQQdDiGDzJ3Kf7JLIa5e/8uxZ87R3oE/hNtgU9BBWFvU5KLSksfeWSFY/k5Ofnk7kxdvjw1xWolFHSISHkbeEgEE4lll5oSjUb5XBJzyB9GfOaPJU8nnWaQ4x7JlOODWT6JkbB4uKXVZ1GpeeszYnO2FY7cOVZbc+z9rUWbC2LTh/Pqdq1JS2/d5fGF47/4wg9ER70YEVV5/EfHUfWJH5+o1ES8FBWT2ffigH9y4MW+TCp+507/gx07AEGC/3OUBZ9BGCgmaYDUj0gYHEtgGmdloazWxn4uKf6z02s+LK1MWuOynCNRxd7Af6IBuow2wuL/ApDD4sBfqY3AQH/gd8we5n3QAA9ZUA5VwFs1lRlVTH7pkoz4CI5hPBmSl7idEXU7I6iRjaEQVhtKPrJDQWzWbNrxL/SJQYmov2Jfa/veivK9bW37Kw7yFRaLbSFfbskq53Hew6Z9lWJT+UK+PDurnP/Il9uHv05XVTceaGg40FhdT14T1SkNZnNDSnVqo9ncOFNX00BqG6TXizUpjWZzQ2pNKulDVT84Ukx7iMRXA9DbRL+uhHCC3LRarQzHHjlFsmyFlGyI6Ybob6QDyyxk5rX6LHrbjJG6MbNphDq4tWGmdXx8nN5//7NjDDcxARgyAOizwcxdaw0DiiJJuxQ4PDwZ0pPk+7138YkHz0nWOTEBFLj8zdSf6RqIgSVQCDprZJpB5cmbJ/dEyCI9IAvioJi1mjVPJoAaFILreC3JtWfR2mLJzpKCeGrFFzd9a3/O2ePprtLTlfaxct/i/KEJd8/5dYVqVdG6C72u8eH8aX3ZQFXr1vJYVXJ5n23lYJmeznvw+dFv9PONtvUN1uJd7VSh/33tjg9P1Jbvf3dr68i7+8obTn1wUFt/ZKCgZqzqT9m99WlFg0eDWPcNRoA5kAC8NVo3T0mp1SoVzJ87R+GJAyxZlmhaItw26sXoXSaTy/WJ+lCwrtfwepSNtJfQv1/8xUj92X6LPx+jVX1eW/HhIf/PblGN/okPUC8jdL13pOvVjfO145U7qpqeLrv/B3wK+UbUofMUZlbe861RMrmKUStkmKawJwyHAqz43KB4EEpEKAZlI7T2Fp3me8X/OocA/SbF96uN+IgkMZ/D/8LHaB7m7tfhO+dnXgrSe4ARYC6kwRJr7NwlRpyYiIzGCHUk9szX6SIUoSyWRDJmjVmKDB+nVSNCPWECFXQBYkO2Pl6qxoL/KEa1jTvKCnY6/b+8hT4fFrZbW18ZrPGvHETlrbtK83Z0+n+P0dYl/SeqR36ILz2X019Z1516/w+MkNxxoqfleGu4b/G4dXNd/RbrcznK7ufbD3zJRbJfsn/bIyf3CdYIVViYLDJCjj1U0Cykc/XUoFWQkycURDzaNuNLvEVl+9z4f33y8fFxJkbk0xFyFiXaRg2coDPpa+L8UVflcoqSYUi9Y466kxo8JCAHBJkz83DdNBX+5pvo0oPP6EUE+S8E7tEpjABLyJ4SlUqcMHduTLiHwdJJQzAnTEtfnhij1+opgkEPQ9dE82OhLXKfqsS/811JWry9rvvFDctyPW9sto9vrw4T1BWba4p7bAZj1YCtrQNfNeLvXfZvil9cNvbOUL+wpyK9+2xPw3BuyqptK8u22NMzyM5qAGij+EtEjFWJGEZGeyj1Ixk14pE+izb6Xn0Pt8zcY4S++1PMnHPEMw7682XfYs7CcuiDRGt0NMOUN8R4XF1dqra2hIRlS9Ig1UziXVFTQtgRtOwYMyULRr0W0bYpuYzk57O+CWdboi2WRYQN0Uyoa3xwdCH9iNeS3aXTnOcHynqXz1WYT5plMYvNc5a1L19Ey5e4nv/hwae/d+mpMpk8pXfi22P2qwVG2ydt5x7cGlsmlzef+gihsxfuf2VH7oO/yiMWL09KsBZaoovjK1u6MyvXl+qUypzG/i2FAztymhPardnO6kz0363TF9rSW3fX4aW+71e2pkcXDZ1sOn3/a/ts1ce+4Ttx5sH7z5YvXeRJTmp84Rdo4esX0cJ7l1ubJn7p/3nAtn5lYkJhl62iYUeTqWjTS+7+K4c6zUUm9/y0nOFXJS9O/emRk91wPU3HqTwmldyDIIidqaHfbP4FsMy+8ZpvTsGGcddDfOwY31BwQ28bqGodqYhVJ5f32lYO2vSfMin3AWv+BUgEBFsD9+gfMrchkXgH6UQfxCP9b5pN3xTzsX+WRYsnRnNuRo799q2xT87U15//4f5XfzkaeTNi5aENrpPujOTWI67tJ6rQt7w/HnVO/u/54+f/94pzx0+O9ZysW3Hg3U0n1335SH3NidC542viL+tEbzUyFfbIlOLJsvkx/yL+phV0MdRvb5740+FTfzz41aazXd1nmxhhJvHijwcHf3yR+tFMoudURcUp0bsmADALgnlsOEFCWi4PCw+XgUqtxgoKe5gQ4hKrzc01a4Jn2eR3OoQSzYgi/vG2f8H72DSKjvsTqFGc/LOZj5nU+5+I6Ju6634d1k1MEDsaCdxjwpjbYg4TY1UmyuZrqCAtoVMtLNHyyG8k0dRs+hjKaZiwhgs/2LvrB+Ormp//wa69P3iu8atZPSfbWo735uT0H29pP9GdSclaL/pnrjmd1xB9sfUioq47ndf9vgC07757wGY7cHd3+54PnrXZnv1A8jl06qNn+HKZDIepVBT24NlYP/gbzkMURWtvUbxvE/6jTxP0MxsmJvDRiQlAkAdAf8wIoIJ51gg5HYZoJSXK7TH/RX7vJEcEPELIiNpR+7/5M9EPfuE/7z//C/QDfyYj+D7FKb5Unx7n+r6Of4Y/ITJzAFBv03mzHjJcjIhkHhGko6HI/I/CIertmd/jv/oyN+Cvb2nwJZw7d45iZyoPUFfOnyfzHgagw8U8gcybYNWEPK9SRoEnDEu5R9Gs61XixGzJ85bfoGr9i/3/E/kVVJfrf9qJZqSswp/nl/v/8P6/o64HdzD9qm81YOim/4T/yNwBFcRDxDuUUhmphVSzmTC38ZHo3/DId3dOliUnx5KVg94KpRzMmmCysST4pg5Bl2wGLtH98Cythw48AUq6ENrwNTiMZgCYjbBNTsNB+mk4xFyFS9gCRroFBkmZ/hocokchix6FdnoUNtCjsJEehQ56FC6L862Dw3QatNF9cBgnw3UynpkDCfQo7KVHoYu+CfX0MWjFd6FARoGJscIl6uegR3+G59Gf4YisCI7h+XCMzIlOQgL6D9jLfAb99Iewmr4DGfTT4KL/AJcYBi7RhIZDcIn2Qg09ChfoUaiRp8IgvQc6mCzYyqTBISYHEphdMEIPwCWGhjzqf8BBR8BhygHd1hXnz509s3/f3mf27N41Nvr0zh3btz21dWTL5k0bPRuGh9YPDqxb29/X29Pd5e50OTva21rXtDjsq1c1NzXW19XWVK+sWlFZUW5bzEaFKZPQpCqshC/pDktOgskwVQlfokpOQoKsRJCLlUKtiROs9XZ9VYO9rFSn1zt0vF6wCrShjNyuLq871OBITgJBXiLIyBRVjXxVfYudK/M6xcbkpKqmx0pSe85sW/BLwCVNdsFm0un1j5TLxfJsseKJ5spQM88JUOf1dk0CZWiyC1bdJBI/mJKDDqHW5OCFThOv5+3djuSkSQWo9U3OkuSkSXXoC3HlAi7hpqKgcyoK3Kv5KRT8arELnLPHUZGcNAnYIIhX4xRk8Vulb6fAuTlOkBn4zjq7Vy8gJ68LlhvsvF5ALp1Xz+s5h2MqcGs+6c3rk5MmMRRP8uhA/aQVHWhssU9FgcAdaLJfwQiXOIsdk4vQgXr7FAeCVazFpJZUkgJHClCFqhrsV7BC7K+bsoIwJrbSYoVYdk8hEOukTtNWQOCewlJdlLSQkSw0bQUM7ilaarGGetPgnlJIdWNS78XB3gpwT0WRlmnACASxUfqbBCIZaxhjVViVVjUOx7pJRKquMFbFDQSgRPC2GoUj3eQYLmkQq6fQ2KTSqpsSZ2oI9hwDJSJ1Y7N1UxhIt0cmcjgkQg80P6SgucX+thrCkU58OhyOYvKXnFQ2iWtM/EO1rrcL2FA2iWpMToeOJ0XKUMZ1ed2CtdFO+jp1eodO73CUJicR7eLsfLeOd0zGxnqHy4RaEz/pkhmdJq+kZES1+Ki85CSBMlS6eZuT9BBog0AbKgXK4F7FOYVOp0mgDFyUzWsjeuAivSFuElOGSUQbUCEUTiIsUwthfHexoOKLZ1uKoEhqkZEWOV8soDiJz2V8GTen3+vmOzlOsNbZe3U9DpfAuQUr7xJovlg3SUOxXu+Yg5KTuLJJqDGVJidV1U9aa011a+ycSD7n9ZZyk1ba6HK7SLlUr+P13mATX1rqeGREGecVrC63U8fryxxi5+QkvozzlvEurkuw1gu0gROgkSf/kaqFjGlqsXvVXXwX32iftFq9Ls7t0nFuh87rcIs8Lk1OQslJkJzEPMSjIBxhYuUGd4+ADVMcdDr5TqmC2OOTdb1PVvQInPPROn4FWU58I/HtXcGXdQnYQG5Xl0CVNNj1XJdDUhKoE5HiH3ZCj3TiBMogTu6Nyg+VULAkUAaBMniF3seLfbNFG7mdAm1IkXRFoI1E1+x6Ya1OGHCYZru4hLFOzstF8Xk8eYiDy8ntFBhDuTDmdhE4khHdExjDCmHMzdk7dXqHQBttTm9I45KTBNo4u5Kw3vTYlDwnoCa7XsAGQo4wVsc5HZzTyQmo3q7X6ziBqbfruR4XUS4CtHUSPXUtdkK1y9to1wtATEYnyJvsXI+rm9fr9KTO4ZC4T/ZIG1YI0GgXQOf18l4BOQTaYON6XJzAGAWZsZK8GKMwbOJd3QLnJOtxrm5xrI3zStwhs+nKeL3D1S1gg8hL2shNYegkD7eXd3FCm9MkMAaNN9rL5Xrt09AWBQJtdK9ymng9F8XZOFHULh2vJ0yoJCVHfnKS1FFpIB0FxiBeRmHQNNkmNzysEa8hk9RZIc7KCdBgF+pCXeTixRiEDSYBx+cI0ECIRw0tdsJ8mYgKAmOodHKCtcGu15HRnICb7EHxiOMryVBdSGDSMByfIwItcYT60H5V0n6lRWXipRYvpUFQGIT1JoGOzwk2ywk5D5Vg0EQ2LY2hxO1KBFAGshQXbBEJcQYLtKFbpElygBwBTL1gdfHk1k0FbtbZBauTJ7fDQZZXiAuREeLUXmliwi4Zafx7rAiuJF0qclWKJDxaHSZecnHPpE0iiXmc8UHuTQVuBjmnD/4RnSFU7g9aZdDuunVCn8PUJY2SBRGc49wEud31Ynyxxq7X83q5jnML2MC5XZzQaPK6Jdr2S1xdIaED0Upk48EmMKEPiAMB+ApEHsAJiK8QMF+BZr/4KxiQgs8hLyWfM4mRXEBxBIyiwtVeN+91O7sk11xnFyBHt4wEQzJR0EpRtlsINDXZGR3tEFXGKIyYglosPbeYZttHiE3KQ5xUkDbvbCMjTjci6YYx+NxiUvzdUV7Fv7aYIihNQSm2ETQyKv75UpQkoBWSuFZgaeYVEk6sIDbt9RJom2yLIBaqNmoExhgthBlyBbkhN7hLpUHYYRKgjiytEGvEYpOdEKIKis2gEsIMUYLScEtSbZUgN0QJMsMtndRLUBmmAgFx31JviQkjJpEP5Ao2B0dL2jlicghhBhu5nYLCYCN30JJUQStVP4H6weklmSofb+RnJyOOnp+dkZQmkdrQZKd1jEMIM3JRAmXIE/lpVAlyIxflzZtEcmOwA0M6YEOe16sK4T+B/2kAK4jhJDi8T1YIO03JSV6vIvzvtyierA0Xq4NSDp99k8qgOYSVCKoSEr8Q36QkCpAiMIad7wcxRwwnHmGMWEVM8dHaOYT38hAkDJlCY0N86xFNOjj2idom+06BNhBOvU88iYAM7wuMUU9uHWGduBrR8SFTMLTdSaS7W5xut4nj+l0CXYJ4l+B0km/OxZHeCqMIcl6vi+t3uUQcEhOXOclJVQ0kHm5ssfNRHFoGy6T0hw9mFnZOoA32Zbpch4CcU4HfzHdIUIUN5eRu8nJclEZATi8XLSCXsFdkb7CNF+t4TpAZg70IBXtNXq/Uj+xejb1VjQJtJDlYWI4ujOR1oZTqnOmfNXNkvID4Kejjt+oJL6agnX9KL+ASXuC4VrueuPopqJ7v8Ho5L+flSf60yi49SSOagrT5JD4gscxs/4T5Dv6xCvV8oniuqcDl+SRVerjurtl1R/inxC9vaOEp6P27yxKVQ2skxRNoo0jLFOQIwEsboY3Btb2t3hZez+unYAFZPrgfUo6Y7xBncU0FTpIN/R8PqgFLCmVuZHN0cmVhbQplbmRvYmoKCjIwIDAgb2JqCjw8Ci9MZW5ndGggMzc1Ci9GaWx0ZXIgL0ZsYXRlRGVjb2RlCj4+CnN0cmVhbQp4nF1SPW+DMBDd+RUe2yHCYAOthJAqsjD0Q6WZqg6AzwipGGScIf++ws9Now7h6d27d3c5X1w3x8ZMjsVvdhlackxPRlnalrMdiPU0TiZKUqamwQXmv8PcrVFcN8f2sjmaG6MXVpYRY/E7jdPm7IXdPamlp/s99moV2cmM7O5Utz7Sntf1m2YyjvGoqpgiHcX1c7e+dDOx2FsPjSLjJnc5nOr2L+PjshJLPU8w0rAo2tZuINuZkaKSc86rUmutq4iM+icHU69vs1nJueQV+7yhykORAQRAeshDMPWQBkMBDb4cmnxASggm8MGgtAeBmgIGAYNAikBbAZ8eUIUA0HIY5CMAWpbDFwBaFgxom0MrMLXEEAWCeWi0+1KeQEvJsw5aChAdGBaSgWVhSyidhU30gMBgSBEUYKK4PsRuRxWJqTOkSGxC4j9IjJthBQW65331tb/77wvvJ7Cf6/W8hrO1ZJy/aX9S+zFNhq5nvy7r7vK/H8U9z/8KZW5kc3RyZWFtCmVuZG9iagoKMjEgMCBvYmoKPDwKL0xlbmd0aCA3MTkyCi9GaWx0ZXIgL0ZsYXRlRGVjb2RlCj4+CnN0cmVhbQp4nI15CXgUx5Xwq+pjNBpdoxN5BN1DMyNw6x6do4OWRhLoQLfEjJDEjEYjiRsGkMQpgQ2GMWCbw44PfG3wruPYLhkTy1cWOzhgx3Y2sbNf1s7v9bdxrjVJLP4k/waQ5v+qe0bIR7IZurrrvVdV79Wrd5XY4d/pAz1MAANxwz7PAGi/RwCgcHjY5wnBPwWAJRu3eMPwXwCge5NnbKsGohYAEL0jO8QQTPGzW/2+EB1vBsDvD23cNajBXBlAwp3Dm3aMafCCiwBABrcObdLg1K0AsYcBAQDD3L/2vg+n18aW/RlMESr10hfGLPr9Ve+zsdetMz/TeyK2A4AesMYcQLdxNgpAv/m6dbZC74mAr/wyACAPRuESikRVaC86j03Yj99nMBPDeJi3mb+yKWw5O8juYo+zx9mLHM+ZuQnuA57nffwZ/g1dos6rI7p3dL+JgIjlEcciPtEb9Mv0m/Rn9G+qMmfA05AEI6ADDHGQDQ8B4F/H7gQGEA+QxBFIpI21QyJA8Gq4zbqDf+YIJAEEPweA1+EinIWz8Ao8AA9AugodhtfgGXgFHoIP4Dw8iD6F+1XoaWSAg/AcPA7H4Ay8DE9DCpyCh2AP3A1PwCcq/ix8L7TKt+EwPAnPwPfgX+EVOAgn4CF4El6AD+A+eBCehfPwffQ2mlHXXgHfgrOh9R+Ex+BpIHAADsHdcBqehgvwCqRAC3hhDPbBHXA33AvfgifhOfgQPkFW2ANH4RSchXPwInsc4pTg/vx9nXsrgsKe0qCwuzwo7CpVhLGyoDBaVi6MFOiEnfagsMM+JGwvaRb8JUFhW2FQ2Fr8nrClOChsLuoTNhW9J2wsCgobijKF9UULhHX5QWE4LygM5b0nDNqCgi83KAzkBAVvzjNCf86Q4MkKCu6sCWFtdlDoyz4l9GYGhZ6MoLBGDgrdt78nuG4PCs7bo4XVy4JC19Kg0Jm+ROhIzxTaLX1CmyUotFqeEVqsQaHZOiE0LQkKqyRZaJSeERqkoFAvdQl1kiysXBwUVohBoVb0CzXmoFBt9gsOIShULTolVC4KCsrCoLA8LSiUl55S/lsoK80X7AUxQkmhXygubBaKChcLhQWnBFueIuTm+IXsrHpBvl0R0lNZwWpZKlhsptSeJbfFCxJ3W2rP4tSgYBbLBbF4QXKPsCBTWJQSFBYmB4W0ZJ1gsqWmrVmQn5y25jbaS6G9pNSK5Ke6E3LjO425cZ3xrjhXdH5UJ5fPdka5WJfArmVxLDvO/pFlYvtiOg35kZ26fL4T5UJnjCvSxbvGeZTNN/NbeGY5v5Yf5xlwZQPKhi3wR2D0+RGdTD7ujHBhl4DXYhyLx/EfMcMoCoem0L2kQ26Y0gXbGoi+ZQ1BR4ilnb6V1m7CHyHQ2b3GOYnQCdeh48dhYVUDubfd+QIDsLDKNYmxo9U5yTInXNt3gAyyLNPv9h07KUBBDUF72hvN+0cRiD6UhNTBGvLr3XDvayQNUn9fHhP+LQAeBgCYpRwBBnRggFhIgBSAyiRzgc0oGc1GyZiQZC5ASEJGZEOMfmbEVIgvFabMjODAzPN23Kq+OFJYeL2FI2o7XFjI9Vw/xu3QGmA4DcD+J0dgASwESYk33aZnoqIMBkhLXRDhTwbsBzlPzsuLL8m2xaeU5OS2m/OSk5MSeV6nM6eb8woLC/KtVslslMzIgpJOY+ap/97XctLXOJuL0ZrusfLS3X2z/3ODWT77HaRDazgy8IN7Nj21TbBcVrbUNm4rv7EAn0Az+6MBQWvwKhvJNoEMghI3lID4hPh4SDXo/EvAoElhLMm2re3Nya1ZnIULCvIrsC1vEU5KMheYC7KwtDgGJyUlLsK2vMKilBiMXWNv3LWy/s4X1+14bnvJzddwF852t5T1VpjTGzfWrD6SNy5tfSKx+cTFLUvH3z/V1HT8zZ1DzyZU+mtt7rs6lq7Y1W2rVfbYeu2AoCl4lZlmmyAdUpWohampiTo/y4JelSovW87LzsvJ9eUVFhbZYrB0S7bk5BRpnly4sHRtKfNLPPbDsb1Tu8vLd0/tOXhpG/4lU7C2qs5dmJJc5P5udkfRuu/6Ou+/tFXa+tb9nUMv7Srz2Et9+xySY7+3FADDbgDmOg/AwG2QokQZcXKkzs+AH0f6qSHlGW05uZXUNNIrGFU9RslIT2hxDEbrv/hhEyrf8sjalgN9udcyuyoqvVVmHq4DDzdr0NbvH1+V4Xl4y0wdfrmpZ1l+98gcP7YJWDBBqhIdj1MMDO836MIMjbYwRxvzDSw3TP9yYRNavu1RT9P4mpxrmZ3LK/odS5j2m8+y9lkD2n4x0CC7H9wyU4Nfa1qTHuI5GrzK/JW1qzyTlEhk5P0LGMag6js7T6baNtqMUkJRYkjfRptRO/hCRnfts8TWnIFHNjXfuTZ/Oi1HWTI0agsypTd+iD7Fm166qyHL/dAG/OqMo7Q5J7E1AAy0zXayUWwTJMAyqACTEptjMfjtt+n8MXysH3i6yzxZ5VppMybyvLTYak0vSk6m7AqMKGyHKUkxDBWmKGSDhUUFWQzVAZP78d5PTlY8cDx7m/3YqvadykxR2dbHfevODJTERFcMnvF5H9tWNr2wfG1l56bSKN5S0adUussXsfYbn518d8OSZuVEjVI+0slkzL6btOdHp5obj/9g1LHj4rHGttNv351UP+EpWrmn8ULp4Cq5uP8gIKgLXmUus01QACmKwQQxecsM/pQYXdiFSnJyK/Ot1vQsJmylSZJ6WjxPJU9ZhJNUtVqtBTZtI/jjJb7+rnsGi+0bH3Yf+cHwtNxVWdGanpS3umrveXf5jicGTr277nesw1dY6cxCliWlOYkJBY3D1VUj3flrHvbIDdnpFRaTLC2Kua113LNydHXOunMuR7MklQMDewH4vSH7ygOzYlwWj7MWL/6aldmood2ytLDz3zI1Tvd1HNo0/cvUtuKNT6yv37Mmdzp7dVn12rI0/Ni2og2PDrbf0ZNzLburrLjTvpDpu/mkapDUCeSeewdnsvFrzd3UIJnU/ucPNWa6H9w4U41fb+uWltX1AYZ9APhlVe5k6he8Xs8l6vwMP+eIc55os+g0aXSahMlo8/SvURdOtqVW9C1fzBQtbd3TmmxjNt48zdp1n7KsVNlTwg4+d2d9RDAI48E/oYfYVtYKKX8F0EFK8DrTAQy0BK+ymAdg4TbIphKYWTbZ4JcNOj+CkM1mhz3lHzDSuGsfzyyzb37U2396uCI6umL4jLf/7Gb7tMneW9m2vtzAWyrWVFT1lKZ9yonXARv/AVMEDF2qJzeBCeywTEmSMxalL7LbY9NzDf4FqZF+PRer2qXqXzTFGOOpffqMYYOUwiZqTExOSZKs1oQUNZ4mau5XlEK3Y7Wq28Of3N6plHblfFEx8u3B3a9vSkr8f8YECT/rGKxevHRVUf0WBTdF2XsPdKx/qq9yfGrkPzBr78haWi0rY32Fbef2zgr1O+W49F3o2pnUnGpZXrG03LV0w7K+zsLO+3q6DnVnA4bI4FW8k3MAA0mQoOgjjQY/ixleDUxqhEgyFyTYjJp4RSlasCjAG2ceJdML86XUrBi0qNnWPrGStROC9Dd+m1cQzzNT+pjSw1sglI2XhDJ+khLJYMzrsJ+PoAeqRVof5WCUjOySGUvtjcuXL7O/o5kdMPUkdC/378BALMS9pIues8X38zRDZPILbXk0d0uLrWj/tbi6SqW+XqmsY+03fsjaUVpRXV1R4cqVNLdQOfLnKg+TEq3jeRxpMDDYj1Vh8ow2mo21hREtQ2i75wazamYz/tWMSas3Zu64fBnvu3IlGNQsgXuPt0I00IuKvAUg+iUGt8Qi9E9dIOfn07vVMQC0X81uURfmklqIyf5rWqqi46h8P+YIpNAYhxGKiYrF/piQZJpc5oL51YkxXLbg12cPoT3e3SUlu72zP72Blz39+717f4+Fy8q2uppd9TcWcGT0J4ePv7MRMM37bBnbBEkgQ9xLaUaDP50PxdGc3PZbBUgoDYWcqoLmfy3vN1UfeHVk9NWD1dUHX1G/04uUgRqHVxGESm91tVdZhI0pO98+095+5u2dKTuv0M6VYyl1B/uLi/sP1qWsPDBQUjJwgO74cPBP6HGYAQNEnme00iMnd3TeiR5urKxqaKiqbBwrXrWquLixMWxP5zgCqZADy5TE1GVWnJ6OrFZVX2kmk6qyPKNN05rNaFP9r3JeZSepuqNJged1jLnollKLzCkaGn9v9jhG1W3by4q3u/7vDfSHsdcP1XT9y741s3XbUG2nvyRv4+rZX2O0pWTs4cZd/4VPvpTbW1XXczvVdZbn9GD3mT79TPblEl/1inUlL9Ww/Y903/2aBxjYF7zK5syLcTHmZJ1fNhj8bKQfQAuz6lHYjDoJhY8hvUArQ3ThU9AlaceybzrlI+Z8wYazQ777fTTG+c4MDD+2vmB6QVFvjdJTIfH60o2djp6iVB6u/+Y3OD1p7O3TrY3H3tzpGHnjeGPLqXfuSao70F+S0Thgv9Cwr6HQczDkK/x6jgAPBoijvoJ1MZwhwh/Fgk4tn2l4yzPS2tmGkA1JyJZglBCt4a9/is6hb3868+ELM1t+ZrnOwb/f4MiNs6yXOs/N/Nk06kboM3r+DcGr7AnuEpSAoMRGWmMLc3NlvX9BYmIsEy6LssPZPQv/7ezOhNVUYAuXTCdN1XvWDj9/cGXD3d/f/uTn438t39PnGrFbm0Zadr04VlZ/9F93rvvRU/03cp07Hc7RMjSaWWsvWig2rzva7Tq5oXTsnd0rtyiFPfZljpK8lCWrN9/t7Dk1VFS8/dkdKwaWL8rrBla1w1XzbjILlRhDZCQfG6PDfgar8S2kpex5MS4cV9hVN2+suMF0zLgZmIG5mDfz+KVL2H3lCjDQCsC8wdqBAT1EQ5oSzUZF6aN5v45heBwPy6lph1KyT7szFSCblGQuYN64+RETN1P1CH7l8d6Z2IsXL+LPbvY8zDx28SI9232zbjZbzfJfsUAaXGNuWaCa5/93C0Sbpz/BHxZteGTQ98Dw8ujo5cP3Dww+urFwOq2st1LpqVisi7Jv6KjsKU1j1l//C/fRzO+TRt4+09YQeHVr6+ibxxqb7/vRfUkNB/qL5EZf6Zsrx1YUe2nFtyF4lb3GXQKZWp98++1calIc41/C6dVY9a4tPhSptbKOhqf4wsKv3U/UhGo0F7DXhDt+/sTRz851tz/yf46d/3zC+JeomnHf6jtXZ9g8x5xdmyvjZ3+Cfzvz4TJPbe+LiHnKdw4xL/aO/vSuxrGaqompkaGxVyYqFy5LQOZXqeWOB6+yJRyBZfTU0/V6vDA1NSHaz2FWC6XZ4YidnmBOMjNUsnANmoXTbaGQqmqSRxsuNjPGmZeWLh5bNfRP/rLSkfO71/zznS38VX35oKPcWbrQXNmvdK3B57LxL96dfTgx3TF+YZuPHG4oWPewb4U3X27d7FDWN8l5VLLFs1OoD34LkRAxyQJkv5eT69Ml8rp0GsJRHxrsOJCWlfbb7w7+vLYhs2d4+QVAUA3AFqjenqDoEcfxrJ+JCmVEmv+RhMwFbMHMK7O4ZiaGI3de/5D94iLl9h1qUNwF4CHqAs/6UdSt3MYVWBiYnn0Yl3AXrjewD+y6/G90RhsAW8FdAoHeO+PiopI4PyMIOCocs/OyQ+ZM9TNXMWlHSxWoQ2zFzRz0UVO3xdZf27q5eHrHLx4++e6GjNbNVbNvXbx4DnPOiaHcmnXltXuaxz/Y1//inurDhw5Vz56juWM4eJWVuEuQAtl0rzIvxHN+PnreXrUzYsJXcYYx5mvVZJIxcRFDj42VHPuf39h1aqQ9s3r/8xtXn9rZnjGdmG6vzyp2lgmJS0saMkucZYuYtj88M31/bUbfmX87+ofv/v5Mtdxz6sezQyh/9aHeUpPc9+Cm2Xedh9eWp2V4HgEGeoJXWRt3CSRIB5la1e1yutWqS43n/KCL1qyK2vz72r1cq8PoNVELiSmhepxKiRNCMYZpLBzMWmjfX7nnvfvb2x/8yXjFztKFGUP5q/Z0ZWZ37Rq+eY2JuXnthbi4KzFxK+/52QnUfvLj0/XGmLdj47N6T/pmnxk47rod//no0dk/HT1K63MA9oQa8WhEEpRYNSJhGpFwKOAZ/1ZQYk/cjGZ+cfPAvzAHz/XeLKMBr+n6549xxitXAEMmAPvirRoRGIbWiEgrfuZuHeYkcwH+/K/4zRu7tFrsyhVAMBi8yn7OXYJ0OlOLEqCGiXdt8rt05t/9C4aaLb64HnXkL+Sunz/U2v7Ix0ef++JQ7PVIx8F1XRNdcnrrfueGQzXoo3v+c8JzfvbsrrOzF9wT/3Wy7/AKZe+FHXs2n5+orb4jlDO5lPn1pZ6P+HKxW5JtC1mZlgtoDcd23bxRcYO94zrTcvkydof/qgUYvOyvmAzuPTBACsS8yOj1sUmQbbPRsNI+r0ayzOt7q4tLqqtLiqvRj6tLimtqikuqOVeuw5Gb43Bkh77MMRjg9HCarYNWNhOaWD/sZnfAbnY7jLJHoY1dBHX8/8Be/CHsw2kwzh6EFrYFuvB3IJJtg9M4Evayw3BaxUXCMTQDwJngNBuAJlwCh7loOM2Owz4+CKfZn0MDewhOszy0Uhy3HTawx2AcvQOL2WNQzR6D77DHoI09BsPsMehhP4AW9lPI5EpgkHsWTjMnwavUP/itB+6/6/ChO+84eGBifP++vXt27xobHdm5Y7t/29Ytmzdt3LB+3fDQoG/A2+9xr+3r7VnT7XKu7ursaG9taW5a1dhQX7dyRe1SIS5Sn4EmDZEOyeGLzMyAyUiDQ3IYMjMQ4R1EpyJJsywSpdVpbmhz1lSbzGaXSTIThbCWGto8AwFvmODKzACicxCeLtHQLjW0djvFmoBbJWZmNHR8CdLoxXO0UI9gR4eT1Moms3kevEKF58CVXyHXhcmSSKAlEBiYBMbS4SSKaRKpHc5xt4s0yy6J9MuSWXL6XJkZkxEQZe5wOzIzJqPCPSSuINghTsVB/1QceFdLUyjU63YS0T3oWpmZMQnYQtSnfQoKpDGt7yaiVxQJb5H6W5wBM0FuyRSC25ySmSCPKWCWzKLLNRV8I42OlsyZGZMYqiYldKR1UkFH2rudU3FAxCMdzhcwwg53lWtyCTrS6pwSgSgqFlMsRVJApAA0oIY25ws4Qh1vmlKATKhUVkWosHcKgYrTBr2sAALvFNZwcRojK2X0skK9bIrVKEp4NAveqQgNN6GNXhoaHQHeqThKeRkwAqIStd8k0JNRIjklQtErUTgamyYRRb3AKRGvIAA9gvNRKBqZJiewo01FT6GJSb1imlJXaguNnAA9oriJOdwUBjps3kIul7bRI523dtDZ7TwfBdHIpL5dLlcV/WVm1EziJlm6ZdatToItNZOoSXa7TBIFGUuNOBDwEqXdSce6TWaXyexyVWdmUOsSnZLPJLkmExMDW2tIsyxNenirWw5oRkZNS4qzZ2YQxlLnlWrddARhLYS11BHG4u0S3aTfLRPGIsbVBmqpHXjoaEiexIxlErEWVAEVkwjzUSRS8lURg1Q1R1kOyzUKTyk6qYqgZE3PNVKNuGBdwCv1iyJRWpxDpkGXh4heokgewkpVpkkWqsxm1wKUmSHWTEKTXJ2Z0dA6qTTLLWucorp9MRCoFicV1urxeihcbTZJ5kCIJFVXu+bNqBEDRPF43SbJXONSB2dmSDVioEbyiANEaSWsRSTQLtH/pummczq6nYGoAWlAandOKkrAI3o9JtHrMgVcXlXH1ZkZKDMDMjO4W/EoFI4w9XKLd5Bgy5QI/W6pX0NQf/wqbuiriEEiuufjpHrKTv0i9Ruol2oGCLbQ5hkgjKPNaRYHXJqRQIsaKf7mIDRvkEgYi7p4IK40DKEQRBgLYSwBMvRlcHgOrKXNTVhLlmYrhLVSW3OayXoT2eiS54Z4yES/GBDjJLtEX+rkFbS5CWdZQSa8HhqOeGp7hLPUkwmv6Ow3mV2Etda6A2GLy8wgrHWOE9ksf2lJSSSow2km2EK3QyZaRLdLdLtFglqdZrNJJFyr0ywOeqhx0UDbou2npdtJd+0JtDvNBKjLmIiuwykOenyS2WSmOJdL0z6VkbXUE2h3EjAFAlKAIBdhLbXioEcknJXw1jr64axkqyx5fER0U36ix6fOrRUDmnboaqYayezy+Ai2qLpkreIUhn768gYkj0h63TLhLMZAfEAsCThfht44IKzV2+WWJbMYJ9aK6lF7TJKZKqGOQq7SzAxtoN5CBxLOoj5Wskme7NVZbmHUZ4usDY5QVxUJtDlJS3iITn04C9kmE5xSTKCNbh61dTup8nk1KhDOUucWidLmNJvobJHgDmfoeNT5dXSqKXxg2jScUqwGWpoIzWF5DZq8GlNefaLUR28hERayWSZsSnGIrKPbuWUEm2QqtDaHUcXVNsBYKCsxRFE34g4BrMWn7klLgCINmGaieCTaTFPBiy1Oorgl2lwuyj5CZURnqEsHtIWpunhK/CZVhDhpj4E+deoW5qMj1Uenykxp2pa4Lys+pL2p4MWQ5syhH7UZusu7Ql4Z8jufiQy75AFtFh+K4KLopZHb26rWF2ucZrNk1plEL8EW0esRSbsc8Gp7u0vTar0WHahVoloJagkX7kAyEJBWIvoCkSBpJcHSSjTXk17AgCKkYvrRS8WTGOkISqbBKC46KuCVAl73gJaaW5wEik1ltBji1YPWq2c7QkNTh5MzsS7VZKxkVA5ZsfYekefoo9QndWFNRlBaYI7IqcuNarZhDb1H5IhvnBWI+MeYRYROk+hVGo1G1oi/z4rRDqheO656rK1cr8WJeurTgQANbZO9MdRDo6xGwlnjSaSlhOgsJSEp9RayVybQQllHqBgV7HDSjRhCx2YxkEhLHNFb3tBM20B0ljjCW94waaOIwTIVDKpya6M1JYzKqh7oEyKHZmvWOSq7SKSlljY3ibDU0hbyJEPIS6O+EvVDy2tnqv8yUZpbjCZ6aW5FCk2iKEuHkzVxLhJpFeMIY7Gr+rQaiM4qxgXsk0hnDQ3g6ABssQcChnD8p+H/ZQAF1HISXIGvIsg+OTMjEIiI/mZKxFex0So6dMrRc1+KDLlDpIMYHLR+oblJTw0gi3CWfW+FYo5aTsxTjIqirjgfu4DqXhcOCVvk8Nyw3gZVlw7N/Qq2w7mPsBaqqbdoJiHI8hbhrGbaTFR1Kjdq41vkUGm7j57uQXW5g7IorvMQ1oEkD3G7aV/0iHR0hFUNcoGAR1zn8ahxSL24LMjMaGij9XB7t1OKE1EZlGnXHyl0s3CKhLU4y0wlLoLcU8Hfpbm0UIUtK2jrCIhinJEgd0CMJ8hDDqnqDdEkFSeJhLeGRtEdHJIDAW0clT4KBxraCWuld7DIYlMkvdeFr1Tfkv8eWaTzCZKmYFgaM1NdTEGftMtMsEMiotjjNNNUPwWr0lyBgBgQAxK9P3U5tTcloinISaP1Aa1l5sYvTHNJX0JEpVHD80wFn0mjV6VbfA/M8R2Vdqm9QJjxFAx9I1tqcmiNZniEtap7mYJiApImCGsN8Q70BLols2SegkWUfUgeCsekudRVPFPBU1Sg/w+aCuNOCmVuZHN0cmVhbQplbmRvYmoKCjI0IDAgb2JqCjw8Ci9MZW5ndGggMzI4Ci9GaWx0ZXIgL0ZsYXRlRGVjb2RlCj4+CnN0cmVhbQp4nF1Su27DMAzc/RUc0yGw/IpTwDBQOIuHPlA3U9FBkShDQC0LsjL47wuLalJ0sA9H8sQDybTrT73RHtI3N4sBPShtpMNlvjqBcMFRmyTLQWrhIwt/MXGbpF1/GtbF49QbNUPTJADpO4568W6F3ZOcL/iwxV6dRKfNCLtzN4TIcLX2Gyc0HljStiBRJWn3zO0LnxDSIN33Eo3Xft2fu+Fe8bFahDzwjCyJWeJiuUDHzYhJwxhjbaOUUm2CRv5LR9FF/a2GhrGct/B5p1Ue4FARFARHAgxQx1xNLJZIYiQvOAVLgoxyxEpBwUdihwAYKymXRy8EB0VB6l5GgwQlta3IREnOaupek7wknwXlcupQxCA5K6LrTZAzTiUVvVJF17HDsf3apvs7x23Q21HcliiuzqHx4XLC4raVaYO347Kz3VTh+wEm9LAnCmVuZHN0cmVhbQplbmRvYmoKCjI1IDAgb2JqCjw8Ci9OIDMKL0xlbmd0aCA0ODAKPj4Kc3RyZWFtCgAAAeBsY21zBCAAAG1udHJSR0IgWFlaIAfiAAMAFAAJAA4AHWFjc3BNU0ZUAAAAAHNhd3NjdHJsAAAAAAAAAAAAAAAAAAD21gABAAAAANMtaGFuZHnpv1ZaPgG2gyOFVUb3T6oAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACmRlc2MAAAD8AAAAJGNwcnQAAAEgAAAAInd0cHQAAAFEAAAAFGNoYWQAAAFYAAAALHJYWVoAAAGEAAAAFGdYWVoAAAGYAAAAFGJYWVoAAAGsAAAAFHJUUkMAAAHAAAAAIGdUUkMAAAHAAAAAIGJUUkMAAAHAAAAAIG1sdWMAAAAAAAAAAQAAAAxlblVTAAAACAAAABwAcwBSAEcAQm1sdWMAAAAAAAAAAQAAAAxlblVTAAAABgAAABwAQwBDADAAAFhZWiAAAAAAAAD21gABAAAAANMtc2YzMgAAAAAAAQw/AAAF3f//8yYAAAeQAAD9kv//+6H///2iAAAD3AAAwHFYWVogAAAAAAAAb6AAADjyAAADj1hZWiAAAAAAAABilgAAt4kAABjaWFlaIAAAAAAAACSgAAAPhQAAtsRwYXJhAAAAAAADAAAAAmZpAADypwAADVkAABPQAAAKWwplbmRzdHJlYW0KZW5kb2JqCgoyNyAwIG9iago8PAovVHlwZSAvTWV0YWRhdGEKL1N1YnR5cGUgL1hNTAovTGVuZ3RoIDcwMgo+PgpzdHJlYW0KPD94cGFja2V0IGJlZ2luPSLvu78iIGlkPSJXNU0wTXBDZWhpSHpyZVN6TlRjemtjOWQiPz48eDp4bXBtZXRhIHhtbG5zOng9ImFkb2JlOm5zOm1ldGEvIj48cmRmOlJERiB4bWxuczpyZGY9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkvMDIvMjItcmRmLXN5bnRheC1ucyMiPjxyZGY6RGVzY3JpcHRpb24gcmRmOmFib3V0PSIiIHhtbG5zOnBkZmFpZD0iaHR0cDovL3d3dy5haWltLm9yZy9wZGZhL25zL2lkLyIgeG1sbnM6ZGM9Imh0dHA6Ly9wdXJsLm9yZy9kYy9lbGVtZW50cy8xLjEvIiB4bWxuczp4bXA9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC8iIHhtbG5zOnBkZj0iaHR0cDovL25zLmFkb2JlLmNvbS9wZGYvMS4zLyI+PHBkZmFpZDpwYXJ0PjM8L3BkZmFpZDpwYXJ0PjxwZGZhaWQ6Y29uZm9ybWFuY2U+QjwvcGRmYWlkOmNvbmZvcm1hbmNlPjx4bXA6Q3JlYXRvclRvb2w+eGh1YmlvLXNhYXMgcGRmLWJhY2tlbmQ8L3htcDpDcmVhdG9yVG9vbD48eG1wOkNyZWF0ZURhdGU+MjAyNi0wOS0wN1QxNDozMTo0Nlo8L3htcDpDcmVhdGVEYXRlPjx4bXA6TW9kaWZ5RGF0ZT4yMDI2LTA5LTA3VDE0OjMxOjQ2WjwveG1wOk1vZGlmeURhdGU+PHBkZjpQcm9kdWNlcj54aHViaW8tc2FhcyBwZGYtYmFja2VuZDwvcGRmOlByb2R1Y2VyPjwvcmRmOkRlc2NyaXB0aW9uPjwvcmRmOlJERj48L3g6eG1wbWV0YT48P3hwYWNrZXQgZW5kPSJ3Ij8+CmVuZHN0cmVhbQplbmRvYmoKCjI4IDAgb2JqCjw8Ci9UeXBlIC9FbWJlZGRlZEZpbGUKL1N1YnR5cGUgL3RleHQjMkZ4bWwKL1BhcmFtcyA8PAovU2l6ZSA2Mzg0Ci9DcmVhdGlvbkRhdGUgKEQ6MjAyNjA5MDcxNDMxNDhaKQovTW9kRGF0ZSAoRDoyMDI2MDkwNzE0MzE0OFopCj4+Ci9MZW5ndGggNjM4NAo+PgpzdHJlYW0KPD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHJzbTpDcm9zc0luZHVzdHJ5SW52b2ljZSB4bWxuczpyc209InVybjp1bjp1bmVjZTp1bmNlZmFjdDpkYXRhOnN0YW5kYXJkOkNyb3NzSW5kdXN0cnlJbnZvaWNlOjEwMCIgeG1sbnM6cWR0PSJ1cm46dW46dW5lY2U6dW5jZWZhY3Q6ZGF0YTpzdGFuZGFyZDpRdWFsaWZpZWREYXRhVHlwZToxMDAiIHhtbG5zOnJhbT0idXJuOnVuOnVuZWNlOnVuY2VmYWN0OmRhdGE6c3RhbmRhcmQ6UmV1c2FibGVBZ2dyZWdhdGVCdXNpbmVzc0luZm9ybWF0aW9uRW50aXR5OjEwMCIgeG1sbnM6dWR0PSJ1cm46dW46dW5lY2U6dW5jZWZhY3Q6ZGF0YTpzdGFuZGFyZDpVbnF1YWxpZmllZERhdGFUeXBlOjEwMCI+CiAgPHJzbTpFeGNoYW5nZWREb2N1bWVudENvbnRleHQ+CiAgICA8cmFtOkd1aWRlbGluZVNwZWNpZmllZERvY3VtZW50Q29udGV4dFBhcmFtZXRlcj4KICAgICAgPHJhbTpJRD51cm46Y2VuLmV1OmVuMTY5MzE6MjAxNzwvcmFtOklEPgogICAgPC9yYW06R3VpZGVsaW5lU3BlY2lmaWVkRG9jdW1lbnRDb250ZXh0UGFyYW1ldGVyPgogIDwvcnNtOkV4Y2hhbmdlZERvY3VtZW50Q29udGV4dD4KICA8cnNtOkV4Y2hhbmdlZERvY3VtZW50PgogICAgPHJhbTpJRD5JTlYtMjAyNi0wMDQyPC9yYW06SUQ+CiAgICA8cmFtOlR5cGVDb2RlPjM4MDwvcmFtOlR5cGVDb2RlPgogICAgPHJhbTpJc3N1ZURhdGVUaW1lPgogICAgICA8dWR0OkRhdGVUaW1lU3RyaW5nIGZvcm1hdD0iMTAyIj4yMDI2MDMyMDwvdWR0OkRhdGVUaW1lU3RyaW5nPgogICAgPC9yYW06SXNzdWVEYXRlVGltZT4KICAgIDxyYW06SW5jbHVkZWROb3RlPgogICAgICA8cmFtOkNvbnRlbnQ+VmllbGVuIERhbmsgZsO8ciBJaHJlbiBBdWZ0cmFnITwvcmFtOkNvbnRlbnQ+CiAgICA8L3JhbTpJbmNsdWRlZE5vdGU+CiAgPC9yc206RXhjaGFuZ2VkRG9jdW1lbnQ+CiAgPHJzbTpTdXBwbHlDaGFpblRyYWRlVHJhbnNhY3Rpb24+CiAgICA8cmFtOkluY2x1ZGVkU3VwcGx5Q2hhaW5UcmFkZUxpbmVJdGVtPgogICAgICA8cmFtOkFzc29jaWF0ZWREb2N1bWVudExpbmVEb2N1bWVudD4KICAgICAgICA8cmFtOkxpbmVJRD4xPC9yYW06TGluZUlEPgogICAgICA8L3JhbTpBc3NvY2lhdGVkRG9jdW1lbnRMaW5lRG9jdW1lbnQ+CiAgICAgIDxyYW06U3BlY2lmaWVkVHJhZGVQcm9kdWN0PgogICAgICAgIDxyYW06U2VsbGVyQXNzaWduZWRJRD5TVkMtREVWLTAwMTwvcmFtOlNlbGxlckFzc2lnbmVkSUQ+CiAgICAgICAgPHJhbTpOYW1lPlNvZnR3YXJlIERldmVsb3BtZW50IFNlcnZpY2VzIOKAlCBNYXJjaCAyMDI2PC9yYW06TmFtZT4KICAgICAgPC9yYW06U3BlY2lmaWVkVHJhZGVQcm9kdWN0PgogICAgICA8cmFtOlNwZWNpZmllZExpbmVUcmFkZUFncmVlbWVudD4KICAgICAgICA8cmFtOk5ldFByaWNlUHJvZHVjdFRyYWRlUHJpY2U+CiAgICAgICAgICA8cmFtOkNoYXJnZUFtb3VudD4xMjAuMDA8L3JhbTpDaGFyZ2VBbW91bnQ+CiAgICAgICAgPC9yYW06TmV0UHJpY2VQcm9kdWN0VHJhZGVQcmljZT4KICAgICAgPC9yYW06U3BlY2lmaWVkTGluZVRyYWRlQWdyZWVtZW50PgogICAgICA8cmFtOlNwZWNpZmllZExpbmVUcmFkZURlbGl2ZXJ5PgogICAgICAgIDxyYW06QmlsbGVkUXVhbnRpdHkgdW5pdENvZGU9IkhVUiI+NDAuMDA8L3JhbTpCaWxsZWRRdWFudGl0eT4KICAgICAgPC9yYW06U3BlY2lmaWVkTGluZVRyYWRlRGVsaXZlcnk+CiAgICAgIDxyYW06U3BlY2lmaWVkTGluZVRyYWRlU2V0dGxlbWVudD4KICAgICAgICA8cmFtOkFwcGxpY2FibGVUcmFkZVRheD4KICAgICAgICAgIDxyYW06VHlwZUNvZGU+VkFUPC9yYW06VHlwZUNvZGU+CiAgICAgICAgICA8cmFtOkNhdGVnb3J5Q29kZT5TPC9yYW06Q2F0ZWdvcnlDb2RlPgogICAgICAgICAgPHJhbTpSYXRlQXBwbGljYWJsZVBlcmNlbnQ+MTkuMDA8L3JhbTpSYXRlQXBwbGljYWJsZVBlcmNlbnQ+CiAgICAgICAgPC9yYW06QXBwbGljYWJsZVRyYWRlVGF4PgogICAgICAgIDxyYW06U3BlY2lmaWVkVHJhZGVTZXR0bGVtZW50TGluZU1vbmV0YXJ5U3VtbWF0aW9uPgogICAgICAgICAgPHJhbTpMaW5lVG90YWxBbW91bnQ+NDgwMC4wMDwvcmFtOkxpbmVUb3RhbEFtb3VudD4KICAgICAgICA8L3JhbTpTcGVjaWZpZWRUcmFkZVNldHRsZW1lbnRMaW5lTW9uZXRhcnlTdW1tYXRpb24+CiAgICAgIDwvcmFtOlNwZWNpZmllZExpbmVUcmFkZVNldHRsZW1lbnQ+CiAgICA8L3JhbTpJbmNsdWRlZFN1cHBseUNoYWluVHJhZGVMaW5lSXRlbT4KICAgIDxyYW06QXBwbGljYWJsZUhlYWRlclRyYWRlQWdyZWVtZW50PgogICAgICA8cmFtOkJ1eWVyUmVmZXJlbmNlPjA0MDExMDAwLTEyMzQ1LTM0PC9yYW06QnV5ZXJSZWZlcmVuY2U+CiAgICAgIDxyYW06U2VsbGVyVHJhZGVQYXJ0eT4KICAgICAgICA8cmFtOkdsb2JhbElEIHNjaGVtZUlEPSIwMjA0Ij5ERTEzNjY5NTk3NjwvcmFtOkdsb2JhbElEPgogICAgICAgIDxyYW06TmFtZT5UZWNoQ29ycCBHbWJIPC9yYW06TmFtZT4KICAgICAgICA8cmFtOkRlZmluZWRUcmFkZUNvbnRhY3Q+CiAgICAgICAgICA8cmFtOlRlbGVwaG9uZVVuaXZlcnNhbENvbW11bmljYXRpb24+CiAgICAgICAgICAgIDxyYW06Q29tcGxldGVOdW1iZXI+KzQ5IDMwIDEyMzQ1Njc8L3JhbTpDb21wbGV0ZU51bWJlcj4KICAgICAgICAgIDwvcmFtOlRlbGVwaG9uZVVuaXZlcnNhbENvbW11bmljYXRpb24+CiAgICAgICAgICA8cmFtOkVtYWlsVVJJVW5pdmVyc2FsQ29tbXVuaWNhdGlvbj4KICAgICAgICAgICAgPHJhbTpVUklJRD5iaWxsaW5nQHRlY2hjb3JwLmRlPC9yYW06VVJJSUQ+CiAgICAgICAgICA8L3JhbTpFbWFpbFVSSVVuaXZlcnNhbENvbW11bmljYXRpb24+CiAgICAgICAgPC9yYW06RGVmaW5lZFRyYWRlQ29udGFjdD4KICAgICAgICA8cmFtOlBvc3RhbFRyYWRlQWRkcmVzcz4KICAgICAgICAgIDxyYW06UG9zdGNvZGVDb2RlPjEwNjIzPC9yYW06UG9zdGNvZGVDb2RlPgogICAgICAgICAgPHJhbTpMaW5lT25lPkthbnRzdHJhw59lIDEyPC9yYW06TGluZU9uZT4KICAgICAgICAgIDxyYW06Q2l0eU5hbWU+QmVybGluPC9yYW06Q2l0eU5hbWU+CiAgICAgICAgICA8cmFtOkNvdW50cnlJRD5ERTwvcmFtOkNvdW50cnlJRD4KICAgICAgICA8L3JhbTpQb3N0YWxUcmFkZUFkZHJlc3M+CiAgICAgICAgPHJhbTpVUklVbml2ZXJzYWxDb21tdW5pY2F0aW9uPgogICAgICAgICAgPHJhbTpVUklJRCBzY2hlbWVJRD0iRU0iPmJpbGxpbmdAdGVjaGNvcnAuZGU8L3JhbTpVUklJRD4KICAgICAgICA8L3JhbTpVUklVbml2ZXJzYWxDb21tdW5pY2F0aW9uPgogICAgICAgIDxyYW06U3BlY2lmaWVkVGF4UmVnaXN0cmF0aW9uPgogICAgICAgICAgPHJhbTpJRCBzY2hlbWVJRD0iVkEiPkRFMTM2Njk1OTc2PC9yYW06SUQ+CiAgICAgICAgPC9yYW06U3BlY2lmaWVkVGF4UmVnaXN0cmF0aW9uPgogICAgICAgIDxyYW06U3BlY2lmaWVkVGF4UmVnaXN0cmF0aW9uPgogICAgICAgICAgPHJhbTpJRCBzY2hlbWVJRD0iRkMiPjI3LzEyMy80NTY3ODwvcmFtOklEPgogICAgICAgIDwvcmFtOlNwZWNpZmllZFRheFJlZ2lzdHJhdGlvbj4KICAgICAgPC9yYW06U2VsbGVyVHJhZGVQYXJ0eT4KICAgICAgPHJhbTpCdXllclRyYWRlUGFydHk+CiAgICAgICAgPHJhbTpOYW1lPk11c3RlciBHbWJIPC9yYW06TmFtZT4KICAgICAgICA8cmFtOlBvc3RhbFRyYWRlQWRkcmVzcz4KICAgICAgICAgIDxyYW06UG9zdGNvZGVDb2RlPjgwMzMxPC9yYW06UG9zdGNvZGVDb2RlPgogICAgICAgICAgPHJhbTpMaW5lT25lPkhhdXB0c3RyYcOfZSA0MjwvcmFtOkxpbmVPbmU+CiAgICAgICAgICA8cmFtOkNpdHlOYW1lPk3DvG5jaGVuPC9yYW06Q2l0eU5hbWU+CiAgICAgICAgICA8cmFtOkNvdW50cnlJRD5ERTwvcmFtOkNvdW50cnlJRD4KICAgICAgICA8L3JhbTpQb3N0YWxUcmFkZUFkZHJlc3M+CiAgICAgICAgPHJhbTpVUklVbml2ZXJzYWxDb21tdW5pY2F0aW9uPgogICAgICAgICAgPHJhbTpVUklJRCBzY2hlbWVJRD0iRU0iPmludm9pY2VAbXVzdGVyLmRlPC9yYW06VVJJSUQ+CiAgICAgICAgPC9yYW06VVJJVW5pdmVyc2FsQ29tbXVuaWNhdGlvbj4KICAgICAgICA8cmFtOlNwZWNpZmllZFRheFJlZ2lzdHJhdGlvbj4KICAgICAgICAgIDxyYW06SUQgc2NoZW1lSUQ9IlZBIj5ERTgxMTU2OTg2OTwvcmFtOklEPgogICAgICAgIDwvcmFtOlNwZWNpZmllZFRheFJlZ2lzdHJhdGlvbj4KICAgICAgPC9yYW06QnV5ZXJUcmFkZVBhcnR5PgogICAgPC9yYW06QXBwbGljYWJsZUhlYWRlclRyYWRlQWdyZWVtZW50PgogICAgPHJhbTpBcHBsaWNhYmxlSGVhZGVyVHJhZGVEZWxpdmVyeT4KICAgICAgPHJhbTpBY3R1YWxEZWxpdmVyeVN1cHBseUNoYWluRXZlbnQ+CiAgICAgICAgPHJhbTpPY2N1cnJlbmNlRGF0ZVRpbWU+CiAgICAgICAgICA8dWR0OkRhdGVUaW1lU3RyaW5nIGZvcm1hdD0iMTAyIj4yMDI2MDMyMDwvdWR0OkRhdGVUaW1lU3RyaW5nPgogICAgICAgIDwvcmFtOk9jY3VycmVuY2VEYXRlVGltZT4KICAgICAgPC9yYW06QWN0dWFsRGVsaXZlcnlTdXBwbHlDaGFpbkV2ZW50PgogICAgPC9yYW06QXBwbGljYWJsZUhlYWRlclRyYWRlRGVsaXZlcnk+CiAgICA8cmFtOkFwcGxpY2FibGVIZWFkZXJUcmFkZVNldHRsZW1lbnQ+CiAgICAgIDxyYW06SW52b2ljZUN1cnJlbmN5Q29kZT5FVVI8L3JhbTpJbnZvaWNlQ3VycmVuY3lDb2RlPgogICAgICA8cmFtOlNwZWNpZmllZFRyYWRlU2V0dGxlbWVudFBheW1lbnRNZWFucz4KICAgICAgICA8cmFtOlR5cGVDb2RlPjU4PC9yYW06VHlwZUNvZGU+CiAgICAgICAgPHJhbTpQYXllZVBhcnR5Q3JlZGl0b3JGaW5hbmNpYWxBY2NvdW50PgogICAgICAgICAgPHJhbTpJQkFOSUQ+REU4OTM3MDQwMDQ0MDUzMjAxMzAwMDwvcmFtOklCQU5JRD4KICAgICAgICAgIDxyYW06QWNjb3VudE5hbWU+VGVjaENvcnAgR21iSDwvcmFtOkFjY291bnROYW1lPgogICAgICAgIDwvcmFtOlBheWVlUGFydHlDcmVkaXRvckZpbmFuY2lhbEFjY291bnQ+CiAgICAgICAgPHJhbTpQYXllZVNwZWNpZmllZENyZWRpdG9yRmluYW5jaWFsSW5zdGl0dXRpb24+CiAgICAgICAgICA8cmFtOkJJQ0lEPkNPQkFERUZGWFhYPC9yYW06QklDSUQ+CiAgICAgICAgPC9yYW06UGF5ZWVTcGVjaWZpZWRDcmVkaXRvckZpbmFuY2lhbEluc3RpdHV0aW9uPgogICAgICA8L3JhbTpTcGVjaWZpZWRUcmFkZVNldHRsZW1lbnRQYXltZW50TWVhbnM+CiAgICAgIDxyYW06QXBwbGljYWJsZVRyYWRlVGF4PgogICAgICAgIDxyYW06Q2FsY3VsYXRlZEFtb3VudD45MTIuMDA8L3JhbTpDYWxjdWxhdGVkQW1vdW50PgogICAgICAgIDxyYW06VHlwZUNvZGU+VkFUPC9yYW06VHlwZUNvZGU+CiAgICAgICAgPHJhbTpCYXNpc0Ftb3VudD40ODAwLjAwPC9yYW06QmFzaXNBbW91bnQ+CiAgICAgICAgPHJhbTpDYXRlZ29yeUNvZGU+UzwvcmFtOkNhdGVnb3J5Q29kZT4KICAgICAgICA8cmFtOlJhdGVBcHBsaWNhYmxlUGVyY2VudD4xOS4wMDwvcmFtOlJhdGVBcHBsaWNhYmxlUGVyY2VudD4KICAgICAgPC9yYW06QXBwbGljYWJsZVRyYWRlVGF4PgogICAgICA8cmFtOlNwZWNpZmllZFRyYWRlUGF5bWVudFRlcm1zPgogICAgICAgIDxyYW06RGVzY3JpcHRpb24+WmFobGJhciBpbm5lcmhhbGIgdm9uIDMwIFRhZ2VuIG9obmUgQWJ6dWc8L3JhbTpEZXNjcmlwdGlvbj4KICAgICAgICA8cmFtOkR1ZURhdGVEYXRlVGltZT4KICAgICAgICAgIDx1ZHQ6RGF0ZVRpbWVTdHJpbmcgZm9ybWF0PSIxMDIiPjIwMjYwNDE5PC91ZHQ6RGF0ZVRpbWVTdHJpbmc+CiAgICAgICAgPC9yYW06RHVlRGF0ZURhdGVUaW1lPgogICAgICA8L3JhbTpTcGVjaWZpZWRUcmFkZVBheW1lbnRUZXJtcz4KICAgICAgPHJhbTpTcGVjaWZpZWRUcmFkZVNldHRsZW1lbnRIZWFkZXJNb25ldGFyeVN1bW1hdGlvbj4KICAgICAgICA8cmFtOkxpbmVUb3RhbEFtb3VudD40ODAwLjAwPC9yYW06TGluZVRvdGFsQW1vdW50PgogICAgICAgIDxyYW06VGF4QmFzaXNUb3RhbEFtb3VudD40ODAwLjAwPC9yYW06VGF4QmFzaXNUb3RhbEFtb3VudD4KICAgICAgICA8cmFtOlRheFRvdGFsQW1vdW50IGN1cnJlbmN5SUQ9IkVVUiI+OTEyLjAwPC9yYW06VGF4VG90YWxBbW91bnQ+CiAgICAgICAgPHJhbTpHcmFuZFRvdGFsQW1vdW50PjU3MTIuMDA8L3JhbTpHcmFuZFRvdGFsQW1vdW50PgogICAgICAgIDxyYW06RHVlUGF5YWJsZUFtb3VudD41NzEyLjAwPC9yYW06RHVlUGF5YWJsZUFtb3VudD4KICAgICAgPC9yYW06U3BlY2lmaWVkVHJhZGVTZXR0bGVtZW50SGVhZGVyTW9uZXRhcnlTdW1tYXRpb24+CiAgICA8L3JhbTpBcHBsaWNhYmxlSGVhZGVyVHJhZGVTZXR0bGVtZW50PgogIDwvcnNtOlN1cHBseUNoYWluVHJhZGVUcmFuc2FjdGlvbj4KPC9yc206Q3Jvc3NJbmR1c3RyeUludm9pY2U+CmVuZHN0cmVhbQplbmRvYmoKCjMxIDAgb2JqCjw8Ci9UeXBlIC9NZXRhZGF0YQovU3VidHlwZSAvWE1MCi9MZW5ndGggMzM5Nwo+PgpzdHJlYW0KPD94cGFja2V0IGJlZ2luPSLvu78iIGlkPSJXNU0wTXBDZWhpSHpyZVN6TlRjemtjOWQiPz4KPHg6eG1wbWV0YSB4bWxuczp4PSJhZG9iZTpuczptZXRhLyI+CiAgPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4KICAgIDxyZGY6RGVzY3JpcHRpb24gcmRmOmFib3V0PSIiCiAgICAgIHhtbG5zOnhtcD0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wLyIKICAgICAgeG1sbnM6ZGM9Imh0dHA6Ly9wdXJsLm9yZy9kYy9lbGVtZW50cy8xLjEvIgogICAgICB4bWxuczpwZGY9Imh0dHA6Ly9ucy5hZG9iZS5jb20vcGRmLzEuMy8iCiAgICAgIHhtbG5zOnBkZmFpZD0iaHR0cDovL3d3dy5haWltLm9yZy9wZGZhL25zL2lkLyIKICAgICAgeG1sbnM6cGRmYUV4dGVuc2lvbj0iaHR0cDovL3d3dy5haWltLm9yZy9wZGZhL25zL2V4dGVuc2lvbi8iCiAgICAgIHhtbG5zOnBkZmFTY2hlbWE9Imh0dHA6Ly93d3cuYWlpbS5vcmcvcGRmYS9ucy9zY2hlbWEjIgogICAgICB4bWxuczpwZGZhUHJvcGVydHk9Imh0dHA6Ly93d3cuYWlpbS5vcmcvcGRmYS9ucy9wcm9wZXJ0eSMiCiAgICAgIHhtbG5zOmZ4PSJ1cm46ZmFjdHVyLXg6cGRmYTpDcm9zc0luZHVzdHJ5RG9jdW1lbnQ6aW52b2ljZToxcDAjIj4KICAgICAgPHhtcDpDcmVhdGVEYXRlPjIwMjYtMDktMDdUMTQ6MzE6NDguODQ1WjwveG1wOkNyZWF0ZURhdGU+CiAgICAgIDx4bXA6TW9kaWZ5RGF0ZT4yMDI2LTA5LTA3VDE0OjMxOjQ4Ljg0NVo8L3htcDpNb2RpZnlEYXRlPgogICAgICA8eG1wOkNyZWF0b3JUb29sPmxpYi1pbnZvaWNlLWZhY3R1cngtZW1iZWRkaW5nPC94bXA6Q3JlYXRvclRvb2w+CiAgICAgIDxkYzpmb3JtYXQ+YXBwbGljYXRpb24vcGRmPC9kYzpmb3JtYXQ+CiAgICAgIDxwZGY6UHJvZHVjZXI+cGRmLWxpYjwvcGRmOlByb2R1Y2VyPgogICAgICA8cGRmYWlkOnBhcnQ+MzwvcGRmYWlkOnBhcnQ+CiAgICAgIDxwZGZhaWQ6Y29uZm9ybWFuY2U+QjwvcGRmYWlkOmNvbmZvcm1hbmNlPgoKICAgICAgPHBkZmFFeHRlbnNpb246c2NoZW1hcz4KICAgICAgICA8cmRmOkJhZz4KICAgICAgICAgIDxyZGY6bGkgcmRmOnBhcnNlVHlwZT0iUmVzb3VyY2UiPgogICAgICAgICAgICA8cGRmYVNjaGVtYTpzY2hlbWE+RmFjdHVyLVggUERGQSBFeHRlbnNpb24gU2NoZW1hPC9wZGZhU2NoZW1hOnNjaGVtYT4KICAgICAgICAgICAgPHBkZmFTY2hlbWE6bmFtZXNwYWNlVVJJPnVybjpmYWN0dXIteDpwZGZhOkNyb3NzSW5kdXN0cnlEb2N1bWVudDppbnZvaWNlOjFwMCM8L3BkZmFTY2hlbWE6bmFtZXNwYWNlVVJJPgogICAgICAgICAgICA8cGRmYVNjaGVtYTpwcmVmaXg+Zng8L3BkZmFTY2hlbWE6cHJlZml4PgogICAgICAgICAgICA8cGRmYVNjaGVtYTpwcm9wZXJ0eT4KICAgICAgICAgICAgICA8cmRmOlNlcT4KICAgICAgICAgICAgICAgIDxyZGY6bGkgcmRmOnBhcnNlVHlwZT0iUmVzb3VyY2UiPgogICAgICAgICAgICAgICAgICA8cGRmYVByb3BlcnR5Om5hbWU+RG9jdW1lbnRGaWxlTmFtZTwvcGRmYVByb3BlcnR5Om5hbWU+CiAgICAgICAgICAgICAgICAgIDxwZGZhUHJvcGVydHk6dmFsdWVUeXBlPlRleHQ8L3BkZmFQcm9wZXJ0eTp2YWx1ZVR5cGU+CiAgICAgICAgICAgICAgICAgIDxwZGZhUHJvcGVydHk6Y2F0ZWdvcnk+ZXh0ZXJuYWw8L3BkZmFQcm9wZXJ0eTpjYXRlZ29yeT4KICAgICAgICAgICAgICAgICAgPHBkZmFQcm9wZXJ0eTpkZXNjcmlwdGlvbj5OYW1lIG9mIHRoZSBlbWJlZGRlZCBYTUwgaW52b2ljZSBmaWxlPC9wZGZhUHJvcGVydHk6ZGVzY3JpcHRpb24+CiAgICAgICAgICAgICAgICA8L3JkZjpsaT4KICAgICAgICAgICAgICAgIDxyZGY6bGkgcmRmOnBhcnNlVHlwZT0iUmVzb3VyY2UiPgogICAgICAgICAgICAgICAgICA8cGRmYVByb3BlcnR5Om5hbWU+RG9jdW1lbnRUeXBlPC9wZGZhUHJvcGVydHk6bmFtZT4KICAgICAgICAgICAgICAgICAgPHBkZmFQcm9wZXJ0eTp2YWx1ZVR5cGU+VGV4dDwvcGRmYVByb3BlcnR5OnZhbHVlVHlwZT4KICAgICAgICAgICAgICAgICAgPHBkZmFQcm9wZXJ0eTpjYXRlZ29yeT5leHRlcm5hbDwvcGRmYVByb3BlcnR5OmNhdGVnb3J5PgogICAgICAgICAgICAgICAgICA8cGRmYVByb3BlcnR5OmRlc2NyaXB0aW9uPlR5cGUgb2YgdGhlIGVtYmVkZGVkIGRvY3VtZW50PC9wZGZhUHJvcGVydHk6ZGVzY3JpcHRpb24+CiAgICAgICAgICAgICAgICA8L3JkZjpsaT4KICAgICAgICAgICAgICAgIDxyZGY6bGkgcmRmOnBhcnNlVHlwZT0iUmVzb3VyY2UiPgogICAgICAgICAgICAgICAgICA8cGRmYVByb3BlcnR5Om5hbWU+Q29uZm9ybWFuY2VMZXZlbDwvcGRmYVByb3BlcnR5Om5hbWU+CiAgICAgICAgICAgICAgICAgIDxwZGZhUHJvcGVydHk6dmFsdWVUeXBlPlRleHQ8L3BkZmFQcm9wZXJ0eTp2YWx1ZVR5cGU+CiAgICAgICAgICAgICAgICAgIDxwZGZhUHJvcGVydHk6Y2F0ZWdvcnk+ZXh0ZXJuYWw8L3BkZmFQcm9wZXJ0eTpjYXRlZ29yeT4KICAgICAgICAgICAgICAgICAgPHBkZmFQcm9wZXJ0eTpkZXNjcmlwdGlvbj5GYWN0dXItWCBjb25mb3JtYW5jZSBsZXZlbDwvcGRmYVByb3BlcnR5OmRlc2NyaXB0aW9uPgogICAgICAgICAgICAgICAgPC9yZGY6bGk+CiAgICAgICAgICAgICAgICA8cmRmOmxpIHJkZjpwYXJzZVR5cGU9IlJlc291cmNlIj4KICAgICAgICAgICAgICAgICAgPHBkZmFQcm9wZXJ0eTpuYW1lPlZlcnNpb248L3BkZmFQcm9wZXJ0eTpuYW1lPgogICAgICAgICAgICAgICAgICA8cGRmYVByb3BlcnR5OnZhbHVlVHlwZT5UZXh0PC9wZGZhUHJvcGVydHk6dmFsdWVUeXBlPgogICAgICAgICAgICAgICAgICA8cGRmYVByb3BlcnR5OmNhdGVnb3J5PmV4dGVybmFsPC9wZGZhUHJvcGVydHk6Y2F0ZWdvcnk+CiAgICAgICAgICAgICAgICAgIDxwZGZhUHJvcGVydHk6ZGVzY3JpcHRpb24+RmFjdHVyLVggdmVyc2lvbjwvcGRmYVByb3BlcnR5OmRlc2NyaXB0aW9uPgogICAgICAgICAgICAgICAgPC9yZGY6bGk+CiAgICAgICAgICAgICAgPC9yZGY6U2VxPgogICAgICAgICAgICA8L3BkZmFTY2hlbWE6cHJvcGVydHk+CiAgICAgICAgICA8L3JkZjpsaT4KICAgICAgICA8L3JkZjpCYWc+CiAgICAgIDwvcGRmYUV4dGVuc2lvbjpzY2hlbWFzPgogICAgICA8Zng6RG9jdW1lbnRGaWxlTmFtZT5mYWN0dXIteC54bWw8L2Z4OkRvY3VtZW50RmlsZU5hbWU+CiAgICAgIDxmeDpEb2N1bWVudFR5cGU+SU5WT0lDRTwvZng6RG9jdW1lbnRUeXBlPgogICAgICA8Zng6Q29uZm9ybWFuY2VMZXZlbD5FTiAxNjkzMTwvZng6Q29uZm9ybWFuY2VMZXZlbD4KICAgICAgPGZ4OlZlcnNpb24+MS4wPC9meDpWZXJzaW9uPgogICAgPC9yZGY6RGVzY3JpcHRpb24+CiAgPC9yZGY6UkRGPgo8L3g6eG1wbWV0YT4KPD94cGFja2V0IGVuZD0idyI/PgplbmRzdHJlYW0KZW5kb2JqCgozMiAwIG9iago8PAovRmlsdGVyIC9GbGF0ZURlY29kZQovVHlwZSAvT2JqU3RtCi9OIDIyCi9GaXJzdCAxNDkKL0xlbmd0aCAxNDY4Cj4+CnN0cmVhbQp4nMVXbW/bNhD+7l/BjwkGU3x/GYoCiR27xpY1yMtWtCgGxWJcobZlWHKR/Ps9pGTHbhI0KzAsgEPqeLw73j3PieKEEUGUIpJ4QxQRjBOD/5ZYIo0ijiiLJaKZIJwRLS3h0LB4EsRCmUvipCZcEW8xaOIdBkO8x+CwByLuoW08EYIIbuBQEqGwURgiGXYJT2R0LBmR0jny5k0vu35YBZJd5LNQ97JBtVk2hPey38qiJp8QGyOX5HPv7dte1B2GuqnTrj/yRYgKaSk7W9yGogjFqJxDCuvYtd3T2h/kTT6vZr3WEeFJo7Mi2of3m2a1aSbLJiybaBpBt86z89DkBQwQ2e07GcV1fxBc5+5iXU2vQoP17GI4Itl1uG9INlnA7Wk3DrpxEm2f3TfjqyZvQjrWuOaoRPIxrgXx26mMxegOlY0q5Chqj3gsVVIZpTptNQbVvFpfrfJpsgrJQS5iCmIi1iHmut1/HooyP63uEXe0qL2mwhGnOHU+hjmourzoVv8y1NVmPUX2TCu4qcP6ZlnG4h04252vl03zHy1mg5PvVeJhe9nV5rZJj1HIetlpXoeUhuz0Y/z75bK6rZqqfxlmm3m+RlqX06oolzOkukDcZfPQf5fwMw3LIl82cXMsMt8WMbuuED42BZDiKX72Iv33MQ4OYoyp3ixeHyJI9DREtR8iMFdspmFNju6/bG7Lql/neU1WxV3/Np9+hbVjRL0OeVP9WKWslsOIxqPhr4IJwzyzXEmuzEdonFfFi4uI5Qj2FvnXcLw/e0b1MHPxxOtyheBaaEdSvljX0Tyf1US1mqctYPtWWiqZMs6SvrCMeg9/CpRRjnqhrYs80YZyLSQ6IDI5QTcopyfL2TwQlOok5rwhXlhqpZJWb+vQwKBSlCtmBISDfPUulLMvDbEcbpLih06ihaNobpJLQKEJiz+j4RhlbEpgp30Kqu9wM5gMoySuiVdAHOpXDzU8TZZ3VeoHWCrrZv1Ajk6K6hbJz96vi7COGDvaYuw4Olyt5mERT8d2DeWxCrGbJ0r/lZrBJ+IZOoGVNGVYE605RZPXaIaaI6lcCiRYInfIt5IO7w5GRcyji12eOmM5er1AMToLxvFtLZw1NJoSsGs4jUJss1xSaZ1neENBQbYWtJLUKyjLfV3tFbXCaBOlgjLOLUj9s9O9s2lBhUpAgicaUQEZo0ATghWWU5/c7gdrpKEINWo+b95LGheB0XRkqSyFCcwsHCuD/CkCAYUEcxp9CpyaGwBQ7k+tQyQmGRVGUvPEK/cIxdqYY6EETctWCqpEq+k95YKn00HTWG9ihh/TalDauB6nKK1SkQOYPsLAAO/ap7QY8M8BBS+VwHmLynmRpCji9qCMui5xAEfKsEHWZTtz2OOi1VQK20nFDi8KcbPWPzPUxVgc+ZxeVpPhdTWeDM/z1WNzfUq95xvP8836hb6DokVAiu/6jsUhTKLF/953BP/pvvN8Jv6ztiPE07ZjhKcycR5dRVOj2qnYkU9rSFtKaGTapISlaZd0bYCNzgJX1LQtyoG+LXakllTzxMEDIoHxtm0q0tNkVEpgn9mEcsUokz5xUivqOuzvusNuz95q7H84A1yhTTgQEoBV+9QR1gLFsZJQ4GCBTQfcY5FVCDVNDdN0S0MFaiVy4uqO111H5N2uvWa7R1kBIieEykMiv35qGNIhUoMB6umWvN0JLESqLdFrKbl//wZaSDa+vvobd+gTvr2b4xJalPGG0hq4K+OVp74cnwJdCY3pgUzOBgbtz/TR9o7bj4Z2P+5JdyAFqvIMJ+KnwypMAUtydJdPm826f0/vF3NYuBmRN6Oz0YgxY/Dj+EkgQeGn8ROMiWFEBsazdjR4NoO3LZ3J0ceb8ShcDslk+a0qcSn/cP77cfyKuAzzdOOqv5RIy8m8CeslBN9wyzwbtVd8Irq38c1u+nif334F/Vx0B18w/wCoeoh3CmVuZHN0cmVhbQplbmRvYmoKCjMzIDAgb2JqCjw8Ci9TaXplIDM0Ci9Sb290IDMgMCBSCi9JbmZvIDEzIDAgUgovSUQgWyA8YzJhY2M2MjlkOWY1ODhlZTA1M2Q0YTBiZjdlMjViMmY+IDxjMmFjYzYyOWQ5ZjU4OGVlMDUzZDRhMGJmN2UyNWIyZj4gXQovRmlsdGVyIC9GbGF0ZURlY29kZQovVHlwZSAvWFJlZgovTGVuZ3RoIDEwOQovVyBbIDEgMiAyIF0KL0luZGV4IFsgMCAzNCBdCj4+CnN0cmVhbQp4nCXLOQqEUBRE0XrOU9vOsYmhmLmJRhTBVXQuGLkRt+Za9BcvOVAXCsDzWGgBIsQitiDT5hCXeMQnAQlJRGKSkA9JJVj0+yWZ9BsgQ6MtJ4X8DtOmWFspc2fmOuqsSC3/27RjN5wX8AJ+6gx2CmVuZHN0cmVhbQplbmRvYmoKCnN0YXJ0eHJlZgozMjY2OAolJUVPRg==","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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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 / retired profile (`MINIMUM` / `BASIC WL`)"},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"required":["error","message","quota"]},"example":{"error":"QUOTA_EXCEEDED","message":"Usage limit reached for e-invoice:de:zugferd:parse","quota":{"current":100,"limit":100}}}}},"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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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 PL/PT/RO 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","partial","partial_construction","partial_final_construction","final_construction","self_billed"],"description":"Invoice type. Maps to BT-3 (UNTDID 1001) where the target format supports it: invoice=380, credit_note=381, correction=384, proforma=325, partial=326, partial_construction=875, partial_final_construction=876, final_construction=877, self_billed=389. Where a format has no code for the type (e.g. Peppol BIS outside DE-to-DE, where 326 is restricted by PEPPOL-EN16931-P0112), the document is issued as 380 and the response carries a DOCUMENT_TYPE_FALLBACK warning — never silently. Where the type is not permitted at all (proforma in XRechnung/Peppol BIS), the request is rejected with HTTP 422. Note: `partial` (326) is a partial invoice for a delivered instalment. A prepayment REQUEST is not 386 — 386 is not permitted in XRechnung; use type=invoice, and report prepayments already received via `prepayments` (BT-113).","example":"invoice"},"issueDate":{"type":"string","description":"Issue date (ISO 8601: YYYY-MM-DD)","example":"2026-03-20"},"dueDate":{"description":"Due date (ISO 8601: YYYY-MM-DD). Optional when payment terms (BT-20) are given.","example":"2026-04-19","type":"string"},"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"},"prepaidAmount":{"description":"Amount already paid in advance (BT-113) — a deposit or down payment the buyer has already transferred. Lowers the payable amount only (BR-CO-16: BT-115 = BT-112 − BT-113 + BT-114); the taxable base (BT-109) and the tax amounts stay unchanged, because the buyer paid earlier, not less. Emitted as `cbc:PrepaidAmount` (UBL) resp. `ram:TotalPrepaidAmount` (CII), and as the national equivalent in ISDOC (`PaidDepositsAmount`), ebInterface (`PrepaidAmount`) and Facturae (`TotalPaymentsOnAccount`). Formats without an already-paid element ignore it: FatturaPA, myDATA, NAV, Swiss/Liechtenstein QR-Bill, SAF-T PT, ATCUD/AT-QR and TicketBAI/LROE/VeriFactu. KSeF FA(3) also omits it — it models payment *events* (amount plus payment date), and inventing a date for a clearance system would be worse than the missing amount.","example":500,"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"},"invoiceTypeCode":{"description":"BT-3 document type code, set explicitly. Takes precedence over `type` and is validated against the code list of the target format (and its conditions — e.g. Peppol permits 326/384 only when both parties are German). A code that contradicts `type` is rejected (HTTP 422) rather than silently resolved. Use this when your ERP already maps to UNTDID 1001 itself.","example":"326","type":"string"}},"required":["countryCode"],"additionalProperties":{}}},"required":["invoiceNumber","type","issueDate","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"},"parse":{"description":"false = generate-only format with no parse route (e.g. qr-bill: the Swiss Payments Code is a payment instruction, not machine-readable invoice data). Absent means parseable.","type":"boolean"}},"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"},"parse":{"description":"false = generate-only format with no parse route (e.g. qr-bill: the Swiss Payments Code is a payment instruction, not machine-readable invoice data). Absent means parseable.","type":"boolean"}},"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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"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":{"description":"Quota period type of the plan quota that was hit, when the rejection carries one ('monthly', 'yearly', ...). Absent whenever the rejection has no period at all — for example a lapsed subscription, where the limit is 0 and no plan quota was involved. This is a period TYPE, never a calendar label such as \"2026-03\".","example":"monthly","type":"string"}},"required":["current","limit"]}},"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}]}}}}