{"openapi":"3.0.0","info":{"title":"e2invoice API","version":"1.0.0","description":"REST API for creating, reading and validating EN 16931 e-invoices (XRechnung, Factur-X/ZUGFeRD).\n\n**Usage limits**\n\n- Without API key: 10 free calls per day for create, read and validate (resets at midnight Europe/Berlin). Downloading the PDF of a created invoice is not counted.\n- With API key: unlimited. API keys are free and can be created in the dashboard after login.\n\nSend the key as `x-api-key: e2i_…` header or as `Authorization: Bearer e2i_…`.\nResponses of metered calls carry `X-RateLimit-Limit`, `X-RateLimit-Remaining` and\n`X-RateLimit-Reset` (seconds until reset); an exhausted quota returns HTTP 429 with `Retry-After`.","contact":{"name":"e2invoice Support"}},"servers":[{"url":"https://www.e2invoice.com"}],"security":[{},{"ApiKeyHeader":[]},{"BearerApiKey":[]}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key","description":"Free API key from the dashboard (unlimited calls). Optional: without key the free daily limit applies."},"BearerApiKey":{"type":"http","scheme":"bearer","description":"Same API key, sent as `Authorization: Bearer e2i_…`."}},"schemas":{"InvoiceLine":{"type":"object","required":["invoiceLineIdentifier","invoicedQuantity","item","price"],"properties":{"invoiceLineIdentifier":{"type":"string","description":"Unique identifier for the invoice line","example":"line-1"},"invoicedQuantity":{"type":"object","required":["value"],"properties":{"value":{"type":"number","description":"Quantity of items","example":5},"unitCode":{"type":"string","description":"Unit of measurement code (e.g., C62 for pieces)","example":"C62"}}},"item":{"type":"object","required":["name","classifiedTaxCategory"],"properties":{"name":{"type":"string","description":"Name of the item","example":"Consulting Services"},"description":{"type":"string","description":"Detailed description of the item","example":"Software development consultation"},"classifiedTaxCategory":{"type":"object","required":["taxCategoryCode","taxRate"],"properties":{"taxCategoryCode":{"type":"string","description":"Tax category code (e.g., S for standard rate)","example":"S"},"taxRate":{"type":"number","description":"VAT rate in percent","example":19}}}}},"price":{"type":"object","required":["priceAmount"],"properties":{"priceAmount":{"type":"number","description":"Price per unit","example":100},"baseQuantity":{"type":"object","properties":{"value":{"type":"number","example":1},"unitCode":{"type":"string","example":"C62"}}}}}}},"Party":{"type":"object","required":["name","postalAddress"],"properties":{"name":{"type":"string","description":"Legal name of the party","example":"Acme Corp GmbH"},"postalAddress":{"type":"object","required":["countryCode"],"properties":{"addressLine1":{"type":"string","description":"First address line (street and number)","example":"Hauptstraße 123"},"addressLine2":{"type":"string","description":"Second address line (additional info)","example":"Building A"},"addressLine3":{"type":"string","description":"Third address line","example":""},"city":{"type":"string","description":"City name","example":"Berlin"},"postCode":{"type":"string","description":"Postal code","example":"10115"},"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code","example":"DE"},"countrySubdivision":{"type":"string","description":"State or region","example":"Berlin"}}},"VATIdentifier":{"type":"string","description":"VAT identification number","example":"DE123456789"},"taxRegistrationIdentifier":{"type":"string","description":"Tax registration identifier","example":"12/345/67890"},"tradingName":{"type":"string","description":"Trading name (if different from legal name)","example":"Acme Solutions"},"electronicAddress":{"type":"object","description":"Electronic address (e.g., email)","properties":{"value":{"type":"string","example":"invoice@acme.com"},"schemeIdentifier":{"type":"string","example":"EM"}}},"identifier":{"type":"object","description":"Party identifier","properties":{"value":{"type":"string","example":"SELLER123"},"schemeIdentifier":{"type":"string","example":"0088"}}},"legalRegistrationIdentifier":{"type":"object","description":"Legal registration identifier","properties":{"value":{"type":"string","example":"HRB 12345"},"schemeIdentifier":{"type":"string","example":"0002"}}},"additionalLegalInformation":{"type":"string","description":"Additional legal information","example":"Registergericht Berlin, HRB 12345"},"contact":{"type":"object","description":"Contact information","properties":{"contactPoint":{"type":"string","description":"Contact person name","example":"John Doe"},"telephoneNumber":{"type":"string","description":"Phone number","example":"+49 30 12345678"},"emailAddress":{"type":"string","format":"email","description":"Email address","example":"contact@acme.com"}}}}},"InvoiceInput":{"type":"object","required":["invoiceNumber","invoiceIssueDate","invoiceCurrencyCode","seller","buyer","invoiceLines","buyerReference"],"properties":{"invoiceNumber":{"type":"string","description":"Unique invoice number","example":"INV-2024-001"},"invoiceIssueDate":{"type":"string","format":"date","description":"Date when the invoice was issued (YYYY-MM-DD)","example":"2024-01-15"},"invoiceCurrencyCode":{"type":"string","description":"ISO 4217 currency code (3 characters)","example":"EUR"},"documentType":{"type":"string","enum":["invoice","credit_note","cancellation"],"description":"Document type that determines PDF template and invoiceTypeCode (defaults to invoice). invoice=380, credit_note=381, cancellation=384","example":"invoice"},"buyerReference":{"type":"string","description":"Reference provided by the buyer (required for German e-invoices, BR-DE-15)","example":"PO-12345"},"purchaseOrderReference":{"type":"string","description":"Purchase order reference","example":"PO-2024-001"},"seller":{"$ref":"#/components/schemas/Party"},"buyer":{"$ref":"#/components/schemas/Party"},"invoiceLines":{"type":"array","description":"List of invoice line items","minItems":1,"items":{"$ref":"#/components/schemas/InvoiceLine"}},"invoiceNote":{"type":"string","description":"Additional notes or comments for the invoice","example":"Payment due within 30 days"},"paymentDueDate":{"type":"string","format":"date","description":"Due date for payment","example":"2024-02-15"},"paymentInstructions":{"type":"object","description":"Payment method and bank details","properties":{"paymentMeansTypeCode":{"type":"string","description":"UNTDID 4461 code (30=Bank transfer, 48=Card, etc.)","example":"30"},"paymentMeansText":{"type":"string","description":"Description of payment means","example":"Bank transfer"},"remittanceInformation":{"type":"string","description":"Payment reference or remittance information","example":"INV-2024-001"},"creditTransfer":{"type":"object","description":"Credit transfer (bank transfer) information","properties":{"paymentAccountIdentifier":{"type":"string","description":"IBAN or account number","example":"DE89370400440532013000"},"paymentAccountName":{"type":"string","description":"Account holder name","example":"Acme Corp GmbH"},"paymentServiceProviderIdentifier":{"type":"string","description":"BIC/SWIFT code","example":"COBADEFFXXX"}}},"paymentCardInformation":{"type":"object","description":"Payment card information","properties":{"primaryAccountNumber":{"type":"string","description":"Card number (masked)","example":"XXXX-XXXX-XXXX-1234"},"holderName":{"type":"string","description":"Cardholder name","example":"John Doe"}}},"directDebit":{"type":"object","description":"Direct debit information","properties":{"mandateReferenceIdentifier":{"type":"string","description":"SEPA mandate reference","example":"MANDATE-2024-001"},"debitedAccountIdentifier":{"type":"string","description":"Debited account IBAN","example":"DE98765432109876543210"}}}}},"companyLogoUrl":{"type":"string","format":"uri","description":"URL to company logo for PDF","example":"https://example.com/logo.png"}}},"DocumentTotals":{"type":"object","description":"Auto-calculated document totals","properties":{"sumOfInvoiceLineNetAmount":{"type":"number","description":"Sum of all invoice line net amounts","example":500},"invoiceTotalAmountWithoutVAT":{"type":"number","description":"Invoice total excluding VAT","example":500},"invoiceTotalAmountWithVAT":{"type":"number","description":"Invoice total including VAT","example":595},"amountDueForPayment":{"type":"number","description":"Amount due for payment","example":595},"sumOfAllowancesOnDocumentLevel":{"type":"number","description":"Sum of document-level allowances (if any)","example":0},"sumOfChargesOnDocumentLevel":{"type":"number","description":"Sum of document-level charges (if any)","example":0}}},"VATBreakdownItem":{"type":"object","description":"VAT breakdown by tax rate","properties":{"taxableAmount":{"type":"number","description":"Taxable amount for this tax rate","example":500},"taxAmount":{"type":"number","description":"Calculated tax amount","example":95},"taxCategoryCode":{"type":"string","description":"Tax category code (S=Standard, Z=Zero, E=Exempt)","example":"S"},"taxRate":{"type":"number","description":"VAT rate in percent","example":19}}},"InvoiceConfig":{"type":"object","description":"Complete invoice configuration with all calculated fields","properties":{"invoiceNumber":{"type":"string","example":"INV-2024-001"},"invoiceIssueDate":{"type":"string","format":"date","example":"2024-01-15"},"invoiceTypeCode":{"type":"string","description":"Auto-set based on documentType (380=invoice, 381=credit_note, 384=cancellation)","example":"380"},"invoiceCurrencyCode":{"type":"string","example":"EUR"},"documentType":{"type":"string","enum":["invoice","credit_note","cancellation"],"example":"invoice"},"buyerReference":{"type":"string","example":"PO-12345"},"seller":{"$ref":"#/components/schemas/Party"},"buyer":{"$ref":"#/components/schemas/Party"},"invoiceLines":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/InvoiceLine"},{"type":"object","properties":{"lineExtensionAmount":{"type":"number","description":"Auto-calculated line net amount","example":500}}}]}},"documentTotals":{"$ref":"#/components/schemas/DocumentTotals"},"VATBreakdown":{"type":"array","items":{"$ref":"#/components/schemas/VATBreakdownItem"}}}},"InvoiceResponse":{"type":"object","required":["configId","documentUrl","config"],"properties":{"configId":{"type":"string","format":"uuid","description":"Unique identifier for the stored invoice configuration (valid for 24 hours)","example":"550e8400-e29b-41d4-a716-446655440000"},"documentUrl":{"type":"string","format":"uri","description":"URL to retrieve the PDF document","example":"https://e2invoice.com/api/invoice/550e8400-e29b-41d4-a716-446655440000/pdf"},"invoiceId":{"type":"string","nullable":true,"description":"Id of the invoice stored in the account (authenticated requests), otherwise null. Use it with /api/invoices/{id}.","example":"cmabc123invoice"},"config":{"$ref":"#/components/schemas/EInvoiceConfig"}}},"HealthResponse":{"type":"object","properties":{"server":{"type":"string","enum":["ok","error"],"example":"ok"},"redis":{"type":"string","enum":["ok","error"],"example":"ok"}}},"ApiError":{"type":"object","description":"Generic API error response","properties":{"statusCode":{"type":"number","description":"HTTP status code","example":500},"statusMessage":{"type":"string","description":"Error message","example":"Internal Server Error"},"data":{"type":"string","description":"Additional error details","example":"Detailed error message"}}},"ValidationError":{"type":"object","description":"Validation error response with field-level errors","properties":{"statusCode":{"type":"number","example":400},"statusMessage":{"type":"string","example":"Validation failed"},"data":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","description":"JSON path to the invalid field","example":"invoiceLines.0.item.name"},"message":{"type":"string","description":"Validation error message","example":"Item name is required"},"code":{"type":"string","description":"Zod error code","example":"too_small"}}}}}}}},"StoredInvoice":{"type":"object","properties":{"id":{"type":"string"},"invoiceNumber":{"type":"string","example":"S-2026-001"},"documentType":{"type":"string","example":"final_invoice"},"documentTypeName":{"type":"string","example":"Schlussrechnung"},"issueDate":{"type":"string","format":"date"},"currency":{"type":"string","example":"EUR"},"sellerName":{"type":"string"},"buyerName":{"type":"string"},"netAmount":{"type":"number","example":5000},"grossAmount":{"type":"number","example":5950},"amountDue":{"type":"number","example":4165},"status":{"type":"string","enum":["issued","cancelled","settled"],"description":"cancelled = a cancellation exists; settled = partial invoice settled by a final invoice"},"cancels":{"$ref":"#/components/schemas/InvoiceReference"},"cancelledBy":{"$ref":"#/components/schemas/InvoiceReference"},"settledBy":{"$ref":"#/components/schemas/InvoiceReference"},"settles":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceReference"}},"canCancel":{"type":"boolean"},"canSettle":{"type":"boolean","description":"Open partial/prepayment invoice that can be passed in partialInvoiceIds"},"canDelete":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}},"InvoiceReference":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"invoiceNumber":{"type":"string"}}},"EInvoiceConfig":{"type":"object","description":"Full E-Invoice configuration according to EN 16931 standard.\nThis is the complete configuration that POST /api/invoice/simple builds\nand returns in its response (config field); the planned advanced\n/api/invoice endpoint will accept it directly.\n","required":["invoiceNumber","invoiceIssueDate","invoiceTypeCode","invoiceCurrencyCode","buyerReference","seller","buyer","invoiceLines","documentTotals","VATBreakdown"],"properties":{"creationMethod":{"type":"string","description":"How the invoice was created (e.g., 'simple', 'advanced')","example":"advanced"},"noWatermark":{"type":"boolean","description":"If true, there is no watermark on created pdf file","default":false},"specificationIdentifier":{"type":"string","description":"Specification identifier for the invoice format","example":"urn:cen.eu:en16931:2017"},"businessProcessType":{"type":"string","description":"Business process type identifier","example":"urn:fdc:peppol.eu:2017:poacc:billing:01:1.0"},"invoiceNumber":{"type":"string","description":"Unique invoice identifier","example":"INV-2024-001"},"invoiceIssueDate":{"type":"string","description":"Invoice issue date (YYYY-MM-DD)","example":"2024-01-15"},"invoiceTypeCode":{"type":"string","description":"Invoice type code according to UNTDID 1001 (XRechnung subset):\n- 326: Partial invoice (Abschlagsrechnung/Teilrechnung)\n- 380: Commercial invoice (Rechnung)\n- 381: Credit note (Gutschrift)\n- 384: Corrected invoice (Rechnungskorrektur/Storno)\n- 386: Prepayment invoice (Anzahlungsrechnung)\n- 389: Self-billed invoice\n- 875: Partial construction invoice (Abschlagsrechnung Bauleistung)\n- 876: Partial final construction invoice (Teilschlussrechnung Bauleistung)\n- 877: Final construction invoice (Schlussrechnung Bauleistung)\n","example":"380"},"invoiceCurrencyCode":{"type":"string","description":"ISO 4217 currency code.\nSupported currencies: EUR, USD, GBP, CHF, JPY, CNY, AUD, CAD, SEK, NOK, DKK, PLN, CZK, HUF, RON, BGN, HRK, RUB, TRY, INR, BRL, MXN, ZAR, NZD, SGD, HKD, KRW, THB, MYR, IDR, PHP, AED, SAR, ILS, EGP\n","example":"EUR"},"documentType":{"type":"string","enum":["invoice","credit_note","corrected_invoice","cancellation","prepayment_invoice","partial_invoice","final_invoice","partial_construction_invoice","partial_final_construction_invoice","final_construction_invoice"],"description":"Document type (defaults to 'invoice'), mapped to UNTDID 1001 codes:\n- invoice (Rechnung) → 380\n- credit_note (Gutschrift) → 381\n- corrected_invoice (Rechnungskorrektur) → 384\n- cancellation (Stornorechnung) → 384\n- prepayment_invoice (Anzahlungsrechnung) → 386\n- partial_invoice (Abschlagsrechnung/Teilrechnung) → 326\n- final_invoice (Schlussrechnung) → 380 + paidAmount/precedingInvoices\n- partial_construction_invoice (Abschlagsrechnung Bauleistung) → 875\n- partial_final_construction_invoice (Teilschlussrechnung Bauleistung) → 876\n- final_construction_invoice (Schlussrechnung Bauleistung) → 877\n","example":"invoice"},"companyLogoUrl":{"type":"string","format":"uri","description":"Company logo URL for PDF generation","example":"https://example.com/logo.png"},"invoiceNote":{"type":"string","description":"Additional notes or payment terms","example":"Payment due within 30 days"},"paymentDueDate":{"type":"string","description":"Payment due date (YYYY-MM-DD)","example":"2024-02-15"},"buyerReference":{"type":"string","description":"Reference provided by buyer (required per BR-DE-15)","example":"PO-12345"},"purchaseOrderReference":{"type":"string","description":"Purchase order reference","example":"PO-2024-001"},"seller":{"type":"object","description":"Seller/supplier information","required":["name","postalAddress","contact"],"properties":{"name":{"type":"string","description":"Company or person name","example":"Acme Corp GmbH"},"postalAddress":{"type":"object","required":["countryCode"],"properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code","example":"DE"},"addressLine1":{"type":"string","description":"Street and house number","example":"Hauptstraße 123"},"addressLine2":{"type":"string","description":"Additional address line","example":"Building A"},"addressLine3":{"type":"string","description":"Additional address line","example":"Floor 2"},"city":{"type":"string","description":"City name","example":"Berlin"},"postCode":{"type":"string","description":"Postal code","example":"10115"},"countrySubdivision":{"type":"string","description":"Country subdivision (state/province)","example":"Berlin"}}},"electronicAddress":{"type":"object","description":"Electronic address for e-invoicing","properties":{"value":{"type":"string","description":"Electronic address value","example":"invoice@acme.com"},"schemeIdentifier":{"type":"string","description":"Scheme identifier (e.g., EM for email, GLN, DUNS)","example":"EM"}}},"identifier":{"type":"object","description":"Seller identifier","properties":{"value":{"type":"string","example":"1234567890"},"schemeIdentifier":{"type":"string","example":"0088"}}},"legalRegistrationIdentifier":{"type":"object","description":"Legal registration identifier","properties":{"value":{"type":"string","example":"HRB 12345"},"schemeIdentifier":{"type":"string","example":"0002"}}},"VATIdentifier":{"type":"string","description":"VAT identification number","example":"DE123456789"},"taxRegistrationIdentifier":{"type":"string","description":"Tax registration identifier","example":"12/345/67890"},"tradingName":{"type":"string","description":"Trading name if different from legal name","example":"Acme"},"additionalLegalInformation":{"type":"string","description":"Free-text legal information (BT-33). If omitted, it is composed from legalForm, registrationCourt/legalRegistrationIdentifier and managingDirectors.","example":"Registered at Amtsgericht Berlin"},"legalForm":{"type":"string","description":"Legal form of the company (Rechtsform), shown in the PDF footer and folded into BT-33","example":"GmbH"},"registrationCourt":{"type":"string","description":"Register court (Registergericht), shown in the PDF footer and folded into BT-33","example":"Amtsgericht Berlin"},"managingDirectors":{"type":"string","description":"Managing director(s) (Geschaeftsfuehrung), shown in the PDF footer and folded into BT-33","example":"Max Mustermann, Erika Musterfrau"},"website":{"type":"string","description":"Company website, shown in the PDF footer","example":"www.acme.com"},"contact":{"type":"object","required":["contactPoint","telephoneNumber","emailAddress"],"properties":{"contactPoint":{"type":"string","description":"Contact person name (required per BR-DE-5)","example":"Max Mustermann"},"telephoneNumber":{"type":"string","description":"Contact phone number (required per BR-DE-6)","example":"+49 30 12345678"},"emailAddress":{"type":"string","format":"email","description":"Contact email address","example":"invoice@acme.com"}}}}},"buyer":{"type":"object","description":"Buyer/customer information","required":["name","postalAddress"],"properties":{"name":{"type":"string","description":"Company or person name","example":"Client GmbH"},"postalAddress":{"type":"object","required":["countryCode"],"properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code","example":"DE"},"addressLine1":{"type":"string","description":"Street and house number","example":"Kundenstraße 456"},"addressLine2":{"type":"string","description":"Additional address line"},"addressLine3":{"type":"string","description":"Additional address line"},"city":{"type":"string","description":"City name","example":"München"},"postCode":{"type":"string","description":"Postal code","example":"80331"},"countrySubdivision":{"type":"string","description":"Country subdivision (state/province)"}}},"electronicAddress":{"type":"object","description":"Electronic address for e-invoicing","properties":{"value":{"type":"string"},"schemeIdentifier":{"type":"string"}}},"identifier":{"type":"object","properties":{"value":{"type":"string"},"schemeIdentifier":{"type":"string"}}},"legalRegistrationIdentifier":{"type":"object","properties":{"value":{"type":"string"},"schemeIdentifier":{"type":"string"}}},"VATIdentifier":{"type":"string","description":"VAT identification number","example":"DE987654321"},"tradingName":{"type":"string","description":"Trading name if different from legal name"},"contact":{"type":"object","properties":{"contactPoint":{"type":"string","description":"Contact person name"},"telephoneNumber":{"type":"string","description":"Contact phone number"},"emailAddress":{"type":"string","format":"email","description":"Contact email address"}}}}},"invoiceLines":{"type":"array","minItems":1,"description":"Invoice line items (at least one required)","items":{"type":"object","required":["invoiceLineIdentifier","invoicedQuantity","lineExtensionAmount","item","price"],"properties":{"invoiceLineIdentifier":{"type":"string","description":"Unique line identifier within the invoice","example":"1"},"invoicedQuantity":{"type":"object","required":["value"],"properties":{"value":{"type":"number","minimum":0.01,"description":"Quantity of items/units","example":5},"unitCode":{"type":"string","description":"UN/ECE Recommendation 20 unit code.\nCommon units: C62 (Piece), EA (Each), HUR (Hour), DAY (Day), MTR (Meter), KGM (Kilogram), LTR (Liter)\n","example":"HUR"}}},"lineExtensionAmount":{"type":"number","description":"Line net amount (quantity × price)","example":500},"item":{"type":"object","required":["name","classifiedTaxCategory"],"properties":{"name":{"type":"string","description":"Item/service name","example":"Consulting Services"},"description":{"type":"string","description":"Additional item description","example":"Software development consultation"},"sellersItemIdentifier":{"type":"string","description":"Seller's item identifier","example":"CONS-001"},"standardItemIdentifier":{"type":"object","properties":{"value":{"type":"string"},"schemeIdentifier":{"type":"string"}}},"classifiedTaxCategory":{"type":"object","required":["taxCategoryCode","taxRate"],"properties":{"taxCategoryCode":{"type":"string","description":"Tax category code:\n- S: Standard rate\n- Z: Zero rated\n- E: Exempt\n- AE: Reverse charge\n- K: Intra-community supply\n- G: Export outside EU\n- O: Not subject to VAT\n- L: Canary Islands\n- M: Ceuta and Melilla\n","example":"S"},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"VAT rate in percent","example":19}}}}},"price":{"type":"object","required":["priceAmount"],"properties":{"priceAmount":{"type":"number","description":"Price per unit (net, without VAT). Can be negative for discounts or credit items.","example":100},"baseQuantity":{"type":"object","properties":{"value":{"type":"number","minimum":0.01},"unitCode":{"type":"string"}}}}},"lineAllowances":{"type":"array","description":"Line-level allowances (discounts)","items":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number","description":"Allowance amount"},"reason":{"type":"string","description":"Reason for allowance"},"reasonCode":{"type":"string","description":"Allowance reason code"}}}},"lineCharges":{"type":"array","description":"Line-level charges","items":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number","description":"Charge amount"},"reason":{"type":"string","description":"Reason for charge"},"reasonCode":{"type":"string","description":"Charge reason code"}}}}}}},"documentTotals":{"type":"object","description":"Invoice totals","required":["sumOfInvoiceLineNetAmount","invoiceTotalAmountWithoutVAT","invoiceTotalAmountWithVAT","amountDueForPayment"],"properties":{"sumOfInvoiceLineNetAmount":{"type":"number","description":"Sum of all line net amounts","example":1000},"invoiceTotalAmountWithoutVAT":{"type":"number","description":"Invoice total without VAT","example":1000},"invoiceTotalAmountWithVAT":{"type":"number","description":"Invoice total with VAT","example":1190},"amountDueForPayment":{"type":"number","description":"Amount due for payment","example":1190},"sumOfAllowancesOnDocumentLevel":{"type":"number","description":"Sum of document-level allowances"},"sumOfChargesOnDocumentLevel":{"type":"number","description":"Sum of document-level charges"},"paidAmount":{"type":"number","description":"Already paid amount"},"roundingAmount":{"type":"number","description":"Rounding amount"}}},"VATBreakdown":{"type":"array","minItems":1,"description":"VAT breakdown by tax category and rate","items":{"type":"object","required":["taxableAmount","taxAmount","taxCategoryCode","taxRate"],"properties":{"taxableAmount":{"type":"number","description":"Taxable amount for this category","example":1000},"taxAmount":{"type":"number","description":"VAT amount for this category","example":190},"taxCategoryCode":{"type":"string","description":"Tax category code (S, Z, E, AE, K, G, O, L, M)","example":"S"},"taxRate":{"type":"number","minimum":0,"maximum":100,"description":"VAT rate in percent","example":19},"taxExemptionReason":{"type":"string","description":"Reason for tax exemption"},"taxExemptionReasonCode":{"type":"string","description":"Tax exemption reason code"}}}},"paymentInstructions":{"type":"object","description":"Payment instructions","properties":{"paymentMeansTypeCode":{"type":"string","description":"Payment means type code (UNTDID 4461):\n- 30: Credit transfer\n- 48: Bank card\n- 49: Direct debit\n- 57: Standing agreement\n- 58: SEPA credit transfer\n- 59: SEPA direct debit\n","example":"30"},"paymentMeansText":{"type":"string","description":"Payment means description","example":"Bank transfer"},"remittanceInformation":{"type":"string","description":"Remittance information","example":"Please reference invoice number"},"creditTransfer":{"type":"object","description":"Credit transfer payment details","properties":{"paymentAccountIdentifier":{"type":"string","description":"IBAN","example":"DE89370400440532013000"},"paymentAccountName":{"type":"string","description":"Account holder name","example":"Acme Corp GmbH"},"paymentServiceProviderIdentifier":{"type":"string","description":"BIC/SWIFT code","example":"COBADEFFXXX"},"paymentServiceProvider":{"type":"string","description":"Bank name","example":"Commerzbank"}}},"paymentCardInformation":{"type":"object","description":"Payment card details","properties":{"primaryAccountNumber":{"type":"string","description":"Masked card number"},"holderName":{"type":"string","description":"Card holder name"}}},"directDebit":{"type":"object","description":"Direct debit details","properties":{"mandateReferenceIdentifier":{"type":"string","description":"SEPA mandate reference"},"debitedAccountIdentifier":{"type":"string","description":"Debited account IBAN"}}}}},"documentAllowances":{"type":"array","description":"Document-level allowances (discounts)","items":{"type":"object","required":["amount","taxCategoryCode","taxRate"],"properties":{"amount":{"type":"number","description":"Allowance amount"},"taxCategoryCode":{"type":"string","description":"Tax category code"},"taxRate":{"type":"number","description":"Tax rate in percent"},"reason":{"type":"string","description":"Reason for allowance"},"reasonCode":{"type":"string","description":"Allowance reason code"}}}},"documentCharges":{"type":"array","description":"Document-level charges","items":{"type":"object","required":["amount","taxCategoryCode","taxRate"],"properties":{"amount":{"type":"number","description":"Charge amount"},"taxCategoryCode":{"type":"string","description":"Tax category code"},"taxRate":{"type":"number","description":"Tax rate in percent"},"reason":{"type":"string","description":"Reason for charge"},"reasonCode":{"type":"string","description":"Charge reason code"}}}},"precedingInvoices":{"type":"array","description":"References to preceding invoices (for credit notes)","items":{"type":"object","required":["invoiceNumber"],"properties":{"invoiceNumber":{"type":"string","description":"Preceding invoice number","example":"INV-2024-001"},"issueDate":{"type":"string","description":"Preceding invoice issue date","example":"2024-01-15"}}}},"deliveryInformation":{"type":"object","description":"Delivery information","properties":{"actualDeliveryDate":{"type":"string","description":"Actual delivery date (YYYY-MM-DD)","example":"2024-01-20"},"deliverToAddress":{"type":"object","properties":{"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"addressLine3":{"type":"string"},"city":{"type":"string"},"postCode":{"type":"string"},"countrySubdivision":{"type":"string"}}},"deliverToPartyName":{"type":"string","description":"Deliver to party name"}}},"invoicingPeriod":{"type":"object","description":"Invoicing period (Leistungszeitraum) according to EN 16931.\nBT-73: Start date of the invoicing period\nBT-74: End date of the invoicing period\n","properties":{"startDate":{"type":"string","description":"Start date of the invoicing period (YYYY-MM-DD)","example":"2024-01-01"},"endDate":{"type":"string","description":"End date of the invoicing period (YYYY-MM-DD)","example":"2024-01-31"}}},"additionalDocuments":{"type":"array","description":"Additional supporting documents","items":{"type":"object","required":["documentTypeCode"],"properties":{"documentTypeCode":{"type":"string","description":"Document type code"},"description":{"type":"string","description":"Document description"},"attachedDocument":{"type":"string","description":"Base64 encoded document content"},"mimeCode":{"type":"string","description":"MIME type of attached document","example":"application/pdf"},"filename":{"type":"string","description":"Filename of attached document"},"externalDocumentLocation":{"type":"string","format":"uri","description":"URL to external document"}}}}}},"Contact":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["SELLER","BUYER"]},"name":{"type":"string"},"data":{"$ref":"#/components/schemas/ContactData"},"updatedAt":{"type":"string","format":"date-time"}}},"ContactData":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Kunde AG"},"tradingName":{"type":"string"},"address":{"type":"string","example":"Kundenweg 2"},"postCode":{"type":"string","example":"80331"},"city":{"type":"string","example":"München"},"countryCode":{"type":"string","example":"DE"},"vatId":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"contactPerson":{"type":"string"},"customerNumber":{"type":"string","description":"Recipients only"},"taxNumber":{"type":"string","description":"Senders only"},"legalForm":{"type":"string"},"registrationNumber":{"type":"string"},"registrationCourt":{"type":"string"},"managingDirectors":{"type":"string"},"website":{"type":"string"},"logoUrl":{"type":"string"},"bankAccount":{"type":"object","description":"Senders only","properties":{"iban":{"type":"string"},"bic":{"type":"string"},"accountHolder":{"type":"string"},"bank":{"type":"string"}}}}},"ValidationIssue":{"type":"object","description":"A single validation finding with its EN 16931 / XRechnung rule id","properties":{"rule":{"type":"string","description":"Rule identifier (e.g. BR-02, BR-CO-15, BR-DE-15, IBAN-1)","example":"BR-CO-15"},"path":{"type":"string","description":"Business term / element path the finding refers to","example":"BT-112"},"message":{"type":"string","description":"Human readable description of the finding","example":"Invoice total with VAT (BT-112) does not equal total without VAT + VAT"},"severity":{"type":"string","enum":["error","warning"],"example":"error"}}}},"parameters":{"StoredInvoiceId":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Id of the stored invoice (`invoiceId` of the create response)"}},"responses":{"DailyLimitReached":{"description":"Free daily quota exhausted (only for calls without API key).\nCreate a free API key in the dashboard for unlimited calls.\n","headers":{"Retry-After":{"description":"Seconds until the quota resets","schema":{"type":"integer"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":429},"statusMessage":{"type":"string","example":"Daily limit reached"},"data":{"type":"object","properties":{"message":{"type":"string","example":"Das kostenlose Tageslimit von 10 Anfragen ist erreicht. Erstelle kostenlos einen API Key im Dashboard für unbegrenzte Anfragen."},"limit":{"type":"integer","example":10},"resetInSeconds":{"type":"integer","example":36000}}}}}}}},"InvalidApiKey":{"description":"The sent API key is unknown or inactive"}}},"paths":{"/api/invoices":{"get":{"summary":"List stored invoices","description":"Invoices of the account (created while logged in or with an API key), newest first.\nRequires a login session or an API key (`x-api-key` / `Authorization: Bearer`).\n","tags":["Stored invoices"],"responses":{"200":{"description":"Stored invoices","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/StoredInvoice"}}}}},"401":{"description":"Login or API key required"}}}},"/api/invoices/{id}":{"get":{"summary":"Get a stored invoice","description":"Summary plus the original simple API input (`input`) and the full EN 16931 configuration (`config`).","tags":["Stored invoices"],"parameters":[{"$ref":"#/components/parameters/StoredInvoiceId"}],"responses":{"200":{"description":"Stored invoice","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/StoredInvoice"},{"type":"object","properties":{"input":{"type":"object","description":"Validated input of POST /api/invoice/simple"},"config":{"$ref":"#/components/schemas/EInvoiceConfig"}}}]}}}},"401":{"description":"Login or API key required"},"404":{"description":"Invoice not found"}}},"delete":{"summary":"Delete a stored invoice","description":"Removes an invoice that was created by mistake and never sent. Invoices linked to a\ncancellation or final invoice cannot be deleted (409) – a sent invoice is cancelled instead.\n","tags":["Stored invoices"],"parameters":[{"$ref":"#/components/parameters/StoredInvoiceId"}],"responses":{"200":{"description":"Deleted"},"409":{"description":"Invoice is linked to a cancellation or final invoice"}}}},"/api/invoices/{id}/pdf":{"get":{"summary":"Download a stored invoice as PDF","description":"Regenerates the PDF/A-3 with embedded Factur-X XML from the stored configuration. Not counted against the daily limit.","tags":["Stored invoices"],"parameters":[{"$ref":"#/components/parameters/StoredInvoiceId"}],"responses":{"200":{"description":"PDF with embedded XML","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Invoice not found"}}}},"/api/invoices/{id}/cancel":{"post":{"summary":"Cancel a stored invoice (Stornorechnung)","description":"Creates and stores the cancellation of an invoice: same parties and lines with negative\nquantities and amounts (type code 384), referencing the original invoice (BG-3).\n\n- The cancellation of a final invoice also reverses its prepayment deduction and releases\n  the settled partial invoices, so a new final invoice can be created.\n- A partial invoice that is already settled has to be released first by cancelling its final invoice (409).\n- An invoice can only be cancelled once; cancellations themselves cannot be cancelled.\n\nCounts against the free daily limit like creating an invoice.\n","tags":["Stored invoices"],"parameters":[{"$ref":"#/components/parameters/StoredInvoiceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["invoiceNumber"],"properties":{"invoiceNumber":{"type":"string","description":"Number of the cancellation (unique in the account)","example":"ST-2026-001"},"invoiceDate":{"type":"string","format":"date","description":"Date of the cancellation (defaults to today)","example":"2026-10-01"},"note":{"type":"string","description":"Reason, appended to the statement that the invoice is cancelled","example":"Rechnung irrtümlich doppelt gestellt"}}}}}},"responses":{"200":{"description":"Cancellation created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/InvoiceResponse"},{"type":"object","properties":{"invoice":{"$ref":"#/components/schemas/StoredInvoice"}}}]}}}},"400":{"description":"Validation failed or invoice is a cancellation itself"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"404":{"description":"Invoice not found"},"409":{"description":"Already cancelled, settled by a final invoice, or number already used"},"429":{"$ref":"#/components/responses/DailyLimitReached"}}}},"/api/health":{"get":{"summary":"Health check endpoint","description":"Returns the health status of the server and Redis connection","tags":["System"],"responses":{"200":{"description":"Health status of all services","content":{"application/json":{"schema":{"type":"object","properties":{"server":{"type":"string","enum":["ok","error"],"description":"Server health status","example":"ok"},"redis":{"type":"string","enum":["ok","error"],"description":"Redis connection status","example":"ok"}}}}}}}}},"/api/contacts":{"get":{"summary":"List address book entries","description":"Senders (SELLER, incl. bank account) and recipients (BUYER) of the account. Requires a login session or an API key.","tags":["Address book"],"parameters":[{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["SELLER","BUYER"]}}],"responses":{"200":{"description":"Contacts","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}}}}},"401":{"description":"Login or API key required"}}},"post":{"summary":"Save an address book entry","description":"Creates a contact, or updates the existing one with the same type and name.\nThe `data` fields match `seller` / `buyer` of POST /api/invoice/simple, so a stored contact can be passed to the API as it is.\n","tags":["Address book"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type","data"],"properties":{"type":{"type":"string","enum":["SELLER","BUYER"]},"data":{"$ref":"#/components/schemas/ContactData"}}}}}},"responses":{"200":{"description":"Saved contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"400":{"description":"Validation failed"}}}},"/api/contacts/{id}":{"patch":{"summary":"Update an address book entry","tags":["Address book"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ContactData"}}}}}},"responses":{"200":{"description":"Updated contact"},"404":{"description":"Contact not found"}}},"delete":{"summary":"Delete an address book entry","tags":["Address book"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"},"404":{"description":"Contact not found"}}}},"/api/invoice/validate":{"post":{"summary":"Validate e-invoice (PDF or XML)","description":"Validates an e-invoice file against the EN 16931 business rules and the\nGerman XRechnung CIUS, and extracts key information.\n\n**Supported file types:**\n- **XML files**: Direct e-invoice XML (XRechnung, Factur-X, ZUGFeRD; UBL Invoice/CreditNote and CII)\n- **PDF files**: PDF/A-3 with embedded XML (Factur-X/ZUGFeRD compliant PDFs)\n\n**Format/profile detection:**\n- XRechnung (UBL and CII syntax) including version\n- Factur-X / ZUGFeRD profiles (MINIMUM, BASIC WL, BASIC, EN 16931, EXTENDED)\n- Peppol BIS Billing 3.0\n\n**Validation checks (each finding carries its rule id):**\n- XML well-formedness and document structure\n- Required fields (BR-01 .. BR-16): specification identifier, invoice number,\n  issue date, type code, currency, seller/buyer name and country, lines\n- Code lists: UNTDID 1001 type codes (incl. XRechnung subset), UNTDID 5305\n  VAT categories, ISO 4217 currencies, ISO 3166 country codes, UN/ECE units\n- Calculation rules (BR-CO-10 .. BR-CO-17): line sums, allowance/charge\n  totals, VAT per category, totals with/without VAT, amount due\n- VAT category rules (BR-S/Z/E/AE/K/G/O-*): rate consistency and required\n  exemption reasons\n- Date validation: format, real calendar dates, period consistency\n- Payment: IBAN checksum (ISO 7064 mod 97-10), BIC format, direct debit\n  mandate reference\n- VAT identifier formats (country specific patterns)\n- XRechnung rules (BR-DE-1 .. BR-DE-29): payment instructions, seller\n  contact (name/phone/email), addresses, buyer reference/Leitweg-ID,\n  electronic addresses\n- Final invoices: prepaid amounts (BT-113) vs. preceding invoice\n  references (BG-3)\n\n**Response includes:**\n- Validation result (valid/invalid)\n- Source type (xml or pdf)\n- Detected format, profile and syntax (UBL/CII)\n- Extracted invoice metadata (number, date, parties, amount)\n- List of errors and warnings with rule ids and BT/BG paths\n\n**File size limit:** 10MB\n\nNote: This endpoint performs semantic business-rule validation. For a\ncertified schema/schematron validation use the official KOSIT validator.\n","tags":["Invoice"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"The e-invoice file to validate.\nSupported formats:\n- XML files (application/xml, text/xml, .xml)\n- PDF files with embedded XML (application/pdf, .pdf)\n"}}},"encoding":{"file":{"contentType":"application/pdf, application/xml, text/xml"}}}}},"responses":{"200":{"description":"Validation completed (check 'valid' field for result)","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean","description":"Whether the invoice passed all validation checks","example":true},"format":{"type":"string","nullable":true,"description":"Detected invoice format","example":"Factur-X-EN16931"},"profile":{"type":"string","nullable":true,"description":"Detected profile/version (e.g. XRechnung 3.0, EN 16931, BASIC)","example":"EN 16931"},"syntax":{"type":"string","nullable":true,"enum":["UBL","CII"],"description":"Invoice syntax (UBL or CII)","example":"CII"},"sourceType":{"type":"string","enum":["xml","pdf"],"description":"Type of uploaded file","example":"pdf"},"filename":{"type":"string","nullable":true,"description":"Original filename of uploaded file","example":"invoice-2024-001.pdf"},"invoiceNumber":{"type":"string","nullable":true,"description":"Extracted invoice number (BT-1)","example":"INV-2024-001"},"invoiceDate":{"type":"string","nullable":true,"description":"Extracted invoice issue date (BT-2), normalized to YYYY-MM-DD","example":"2024-01-15"},"sellerName":{"type":"string","nullable":true,"description":"Extracted seller name (BT-27)","example":"Acme Corp GmbH"},"buyerName":{"type":"string","nullable":true,"description":"Extracted buyer name (BT-44)","example":"Client GmbH"},"totalAmount":{"type":"string","nullable":true,"description":"Extracted total amount with VAT (BT-112)","example":"1190.00"},"currency":{"type":"string","nullable":true,"description":"Extracted currency code (BT-5)","example":"EUR"},"errors":{"type":"array","description":"List of validation errors","items":{"$ref":"#/components/schemas/ValidationIssue"}},"warnings":{"type":"array","description":"List of validation warnings","items":{"$ref":"#/components/schemas/ValidationIssue"}}}},"examples":{"validPdf":{"summary":"Valid Factur-X PDF","value":{"valid":true,"format":"Factur-X-EN16931","profile":"EN 16931","syntax":"CII","sourceType":"pdf","filename":"invoice-2024-001.pdf","invoiceNumber":"INV-2024-001","invoiceDate":"2024-01-15","sellerName":"Acme Corp GmbH","buyerName":"Client GmbH","totalAmount":"1190.00","currency":"EUR","errors":[],"warnings":[]}},"validXml":{"summary":"Valid XRechnung XML","value":{"valid":true,"format":"XRechnung (UBL)","profile":"XRechnung 3.0","syntax":"UBL","sourceType":"xml","filename":"xrechnung.xml","invoiceNumber":"INV-2024-001","invoiceDate":"2024-01-15","sellerName":"Acme Corp GmbH","buyerName":"Client GmbH","totalAmount":"1190.00","currency":"EUR","errors":[],"warnings":[]}},"invalidXml":{"summary":"Invalid invoice with errors","value":{"valid":false,"format":"UBL (Unknown Profile)","profile":null,"syntax":"UBL","sourceType":"xml","filename":"invoice.xml","invoiceNumber":null,"invoiceDate":"2024-01-15","sellerName":"Acme Corp GmbH","buyerName":"Client GmbH","totalAmount":"1200.00","currency":"EUR","errors":[{"rule":"BR-02","path":"BT-1","message":"Invoice number (BT-1) is required","severity":"error"},{"rule":"BR-CO-15","path":"BT-112","message":"Invoice total with VAT (BT-112) 1200.00 does not equal total without VAT + VAT (expected 1190.00)","severity":"error"}],"warnings":[{"rule":"FORMAT-1","path":"CustomizationID","message":"Unknown customization ID: custom-profile","severity":"warning"}]}},"pdfNoXml":{"summary":"PDF without embedded XML","value":{"valid":false,"format":null,"profile":null,"syntax":null,"sourceType":"pdf","filename":"regular-invoice.pdf","invoiceNumber":null,"invoiceDate":null,"sellerName":null,"buyerName":null,"totalAmount":null,"currency":null,"errors":[{"rule":"PDF-1","path":"pdf","message":"No embedded XML invoice found in PDF. This PDF does not appear to be a Factur-X/ZUGFeRD compliant e-invoice.","severity":"error"}],"warnings":[]}}}}}},"400":{"description":"Invalid request (e.g., no file uploaded, unsupported file type, file too large)","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":400},"statusMessage":{"type":"string","example":"No file uploaded"},"data":{"type":"object","properties":{"message":{"type":"string","example":"Please upload a PDF or XML file using multipart/form-data with field name \"file\""}}}}}}}},"401":{"$ref":"#/components/responses/InvalidApiKey"},"429":{"$ref":"#/components/responses/DailyLimitReached"},"500":{"description":"Server error"}}}},"/api/invoice/simple":{"post":{"summary":"Create invoice configuration (simplified)","description":"Simplified endpoint to create an invoice configuration with minimal required fields.\n\n**Key differences from /api/invoice:**\n- Simpler nested structure for seller, buyer, and items\n- Automatic handling of optional fields\n- Default values for common fields (VAT rate: 19%, unit: C62, tax category: S, currency: EUR, countryCode: DE)\n- Flat address structure (single address field instead of addressLine1/2/3)\n- Simplified item structure (quantity, price, vatRate instead of complex nested objects)\n\nReturns a unique ID valid for 24 hours that can be used to generate a PDF via GET /api/invoice/{id}/pdf\n\n**Stored invoices:** Send `\"store\": true` together with your API key to save the invoice in the account;\nthe response then contains `invoiceId`. Stored invoices can be listed, downloaded at any time and\ncancelled via `/api/invoices`. Invoice numbers must be unique per account: an identical retry returns the\nstored invoice, the same number with different content is rejected (409). Without `store` nothing is\nsaved, so integrations that regenerate invoices under the same number keep working. Invoices created\nin the web UI while logged in are always stored.\n\n**Final invoices from stored partial invoices:** send `partialInvoiceIds` with a final document type.\nReferences (BG-3), the gross prepayment (BT-113) and the VAT contained in it are taken from the stored\npartial/prepayment invoices, which are then marked as settled.\n","tags":["Invoice"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["invoiceNumber","invoiceDate","buyerReference","seller","buyer","items"],"properties":{"noWatermark":{"type":"boolean","description":"If true, there is no watermark on created pdf file","default":false},"invoiceNumber":{"type":"string","description":"Unique invoice identifier","example":"INV-2024-001"},"invoiceDate":{"type":"string","format":"date","description":"Invoice issue date (YYYY-MM-DD)","example":"2024-01-15"},"dueDate":{"type":"string","format":"date","description":"Payment due date (YYYY-MM-DD)","example":"2024-02-15"},"currency":{"type":"string","description":"ISO 4217 currency code (defaults to EUR).\nSupported currencies: EUR, USD, GBP, CHF, JPY, CNY, AUD, CAD, SEK, NOK, DKK, PLN, CZK, HUF, RON, BGN, HRK, RUB, TRY, INR, BRL, MXN, ZAR, NZD, SGD, HKD, KRW, THB, MYR, IDR, PHP, AED, SAR, ILS, EGP\n","example":"EUR"},"documentType":{"type":"string","enum":["invoice","credit_note","corrected_invoice","cancellation","prepayment_invoice","partial_invoice","final_invoice","partial_construction_invoice","partial_final_construction_invoice","final_construction_invoice"],"description":"Document type (defaults to 'invoice'), mapped to UNTDID 1001 invoice type codes:\n- invoice (Rechnung) -> 380\n- credit_note (Gutschrift) -> 381\n- corrected_invoice (Rechnungskorrektur) -> 384\n- cancellation (Stornorechnung) -> 384\n- prepayment_invoice (Anzahlungsrechnung, before the supply) -> 386\n- partial_invoice (Abschlagsrechnung/Teilrechnung, during the supply) -> 326\n- final_invoice (Schlussrechnung, settles prepayments) -> 380 + BT-113/BG-3\n- partial_construction_invoice (Abschlagsrechnung Bauleistung) -> 875\n- partial_final_construction_invoice (Teilschlussrechnung Bauleistung) -> 876\n- final_construction_invoice (Schlussrechnung Bauleistung) -> 877\n\nFor final invoice types, use `prepaidAmount` and `precedingInvoices` to\ndeduct and reference the already invoiced partial/prepayment invoices – or\n`partialInvoiceIds` to take them from stored invoices.\n\nFor `cancellation`, enter the items exactly as in the cancelled invoice: quantities,\namounts and VAT are reversed (negative) automatically, and `precedingInvoices` must\nreference the cancelled invoice. Stored invoices are cancelled more easily with\nPOST /api/invoices/{id}/cancel.\n","example":"invoice"},"prepaidAmount":{"type":"number","minimum":0,"description":"Only for final invoice types (final_invoice, partial_final_construction_invoice,\nfinal_construction_invoice): gross amount of prepayments already received\n(Anzahlungen/Abschlaege) that is deducted from the amount due (BT-113).\n","example":1190},"prepaidVatAmount":{"type":"number","minimum":0,"description":"Only for final invoice types: VAT contained in prepaidAmount. § 14 Abs. 5 UStG requires\nthe final invoice to deduct the prepayments and the VAT on them separately. Derived\nautomatically when the invoice uses a single VAT rate; required with several rates.\nThe split is shown on the PDF and documented as invoice note (BT-22) in the XML.\n","example":190},"partialInvoiceIds":{"type":"array","description":"Only for final invoice types and authenticated requests: ids of stored partial or\nprepayment invoices this final invoice settles. Replaces prepaidAmount,\nprepaidVatAmount and precedingInvoices (sending both is rejected). The partial\ninvoices are assumed to be paid in full and must not be cancelled or settled yet.\n","items":{"type":"string"},"example":["cmabc123partial1","cmabc123partial2"]},"store":{"type":"boolean","description":"Save the invoice in the account (requests with API key). Defaults to false for API keys,\nexcept with partialInvoiceIds, which always store the final invoice so the partial invoices\nare marked as settled.\n"},"precedingInvoices":{"type":"array","description":"References to preceding invoices (BG-3): the settled partial/prepayment invoices of a\nfinal invoice, or the cancelled/corrected invoice (required for cancellation).\n","items":{"type":"object","required":["invoiceNumber"],"properties":{"invoiceNumber":{"type":"string","example":"INV-2024-A1"},"invoiceDate":{"type":"string","format":"date","example":"2024-01-05"}}}},"note":{"type":"string","description":"Additional notes or payment terms","example":"Payment due within 30 days"},"logoUrl":{"type":"string","format":"uri","description":"Company logo URL for PDF","example":"https://example.com/logo.png"},"buyerReference":{"type":"string","description":"Reference provided by buyer (required per BR-DE-15)","example":"PO-12345"},"purchaseOrderReference":{"type":"string","description":"Purchase order reference","example":"PO-2024-001"},"serviceDate":{"type":"string","format":"date","description":"Service/delivery date (Leistungsdatum) in format YYYY-MM-DD.\nFor a service period, this is the start date.\nMaps to BT-72 (Actual delivery date) and BT-73 (Invoicing period start date).\n","example":"2024-01-15"},"serviceDateEnd":{"type":"string","format":"date","description":"End date of service period (Leistungszeitraum Ende) in format YYYY-MM-DD.\nOnly required when the service spans multiple days.\nMaps to BT-74 (Invoicing period end date).\n","example":"2024-01-31"},"seller":{"type":"object","required":["name","address","postCode","city","email","phone","contactPerson"],"description":"Seller/supplier information.\nvatId is optional: provide vatId or taxNumber (§ 14 Abs. 4 Nr. 2 UStG). Sellers outside\nGermany may use registrationNumber instead (BR-CO-26). Items with VAT category AE or K\nrequire vatId (BR-AE-02 / BR-IC-02).\n","properties":{"name":{"type":"string","description":"Company or person name","example":"Acme Corp GmbH"},"address":{"type":"string","description":"Street and house number","example":"Hauptstrasse 123"},"postCode":{"type":"string","description":"Postal code","example":"10115"},"city":{"type":"string","description":"City name","example":"Berlin"},"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code (defaults to DE)","example":"DE"},"vatId":{"type":"string","description":"VAT identification number","example":"DE123456789"},"email":{"type":"string","format":"email","description":"Contact email address","example":"invoice@acme.com"},"phone":{"type":"string","description":"Contact phone number (required per BR-DE-6)","example":"+49 30 12345678"},"contactPerson":{"type":"string","description":"Contact person name (required per BR-DE-5)","example":"Max Mustermann"},"tradingName":{"type":"string","description":"Trading name (Geschaeftsbezeichnung), if different from the legal name","example":"Acme Solutions"},"legalForm":{"type":"string","description":"Legal form of the company (Rechtsform)","example":"GmbH"},"registrationNumber":{"type":"string","description":"Commercial register number (Handelsregisternummer). Mapped to the legal registration identifier (BT-30); replaces vatId/taxNumber only for sellers outside Germany.","example":"HRB 12345"},"registrationCourt":{"type":"string","description":"Register court (Registergericht), displayed in the PDF footer / Impressum","example":"Amtsgericht Muenchen"},"taxNumber":{"type":"string","description":"German tax number (Steuernummer), mapped to seller tax registration identifier (BT-32)","example":"123/456/78901"},"managingDirectors":{"type":"string","description":"Managing director(s) (Geschaeftsfuehrung), displayed in the PDF footer / Impressum","example":"Max Mustermann, Erika Musterfrau"},"website":{"type":"string","description":"Company website, displayed in the PDF footer","example":"www.acme.com"},"additionalLegalInformation":{"type":"string","description":"Free-text legal information (BT-33). If omitted, it is composed from legalForm, registrationCourt/registrationNumber and managingDirectors.","example":"GmbH | Amtsgericht Berlin, HRB 12345 | Geschaeftsfuehrung: Max Mustermann"},"legalRegistrationIdentifier":{"type":"object","description":"Legal registration identifier (e.g., commercial register number)","properties":{"value":{"type":"string","description":"The registration identifier value","example":"HRB 12345"},"schemeIdentifier":{"type":"string","description":"Scheme identifier for the registration (e.g., \"0002\" for German Handelsregister)","example":"0002"}}}}},"buyer":{"type":"object","required":["name","address","city","postCode"],"description":"Buyer/customer information","properties":{"name":{"type":"string","description":"Company or person name","example":"Client GmbH"},"address":{"type":"string","description":"Street and house number","example":"Kundenstrasse 456"},"postCode":{"type":"string","description":"Postal code","example":"80331"},"city":{"type":"string","description":"City name","example":"Muenchen"},"countryCode":{"type":"string","description":"ISO 3166-1 alpha-2 country code (defaults to DE)","example":"DE"},"vatId":{"type":"string","description":"VAT identification number","example":"DE987654321"},"email":{"type":"string","format":"email","description":"Contact email address","example":"billing@client.com"},"phone":{"type":"string","description":"Contact phone number","example":"+49 89 98765432"},"contactPerson":{"type":"string","description":"Contact person name","example":"Erika Musterfrau"},"tradingName":{"type":"string","description":"Trading name, if different from the legal name","example":"Client Trading"},"customerNumber":{"type":"string","description":"Buyer identifier / customer number (BT-46), displayed on the PDF","example":"KD-1001"}}},"items":{"type":"array","minItems":1,"description":"Invoice line items","items":{"type":"object","required":["name","price"],"properties":{"name":{"type":"string","description":"Item/service name","example":"Consulting Services"},"description":{"type":"string","description":"Additional item description","example":"Software development consultation (5 hours)"},"quantity":{"type":"number","minimum":0.01,"description":"Quantity of items/units (defaults to 1)","example":5},"unit":{"type":"string","description":"UN/ECE Recommendation 20 unit code (defaults to C62 for pieces).\nCommon units: C62 (Piece), EA (Each), SET (Set), HUR (Hour), DAY (Day), WEE (Week), MON (Month), ANN (Year), MTR (Meter), KGM (Kilogram), LTR (Liter), MTK (Square meter), KWH (Kilowatt hour).\nFull list: C62, EA, SET, PR, DZN, GRO, PCK, BX, CT, PK, HUR, DAY, WEE, MON, ANN, MIN, SEC, MTR, CMT, MMT, KMT, INH, FOT, YRD, MTK, CMK, MMK, KMK, HAR, ACR, LTR, MLT, CLT, HLT, MTQ, CMQ, MMQ, GLI, GLL, PTI, PTL, QTI, QTL, OZA, BLL, KGM, GRM, MGM, TNE, LBR, ONZ, CWI, CWA, DTN, KWH, MWH, GWH, JOU, KJO, MJO, E34, 4L, E35, LS, NAR, NPR, NPL, P1\n","example":"HUR"},"price":{"type":"number","description":"Price per unit (net, without VAT). Can be negative for discounts or credit items.","example":100},"vatRate":{"type":"number","minimum":0,"maximum":100,"description":"VAT rate in percent. Defaults to 19% for category S (or when no category is given),\nand to 0% for all other categories. Must be 0 for VAT categories other than S.\n","example":19},"vatCategory":{"type":"string","enum":["S","Z","E","AE","K","G","O"],"description":"VAT category code (UNTDID 5305). Defaults to S for vatRate > 0 and E for vatRate 0.\n- S: Standard rate\n- Z: Zero rated goods\n- E: Exempt from tax (e.g. Kleinunternehmer § 19 UStG)\n- AE: Reverse charge (§ 13b UStG)\n- K: Intra-community supply\n- G: Export outside the EU\n- O: Not subject to VAT\n","example":"S"},"vatExemptionReason":{"type":"string","description":"Exemption reason (BT-120), used for categories E, AE, K, G, O.\nIf omitted, a sensible German default text is used\n(e.g. \"Steuerschuldnerschaft des Leistungsempfängers\" for AE).\n","example":"Steuerbefreite Leistung gem. § 19 UStG (Kleinunternehmerregelung)"}}}},"payment":{"type":"object","description":"Payment information","properties":{"type":{"type":"string","enum":["credit_transfer","direct_debit"],"description":"Payment method type (defaults to 'credit_transfer')\n- credit_transfer -> paymentMeansTypeCode: 30 (Bank transfer)\n- direct_debit -> paymentMeansTypeCode: 59 (SEPA Direct Debit)\n","example":"credit_transfer"},"remittanceInformation":{"type":"string","description":"Payment reference or remittance information","example":"Invoice INV-2024-001"}}},"directDebit":{"type":"object","description":"SEPA Direct Debit specific information (used when payment.type is 'direct_debit')","properties":{"mandateReference":{"type":"string","description":"SEPA mandate reference identifier","example":"MANDATE-2024-001"}}},"bankAccount":{"type":"object","description":"Bank account information for payment","properties":{"iban":{"type":"string","description":"IBAN","example":"DE89370400440532013000"},"bic":{"type":"string","description":"BIC/SWIFT code","example":"COBADEFFXXX"},"accountHolder":{"type":"string","description":"Account holder name","example":"Acme Corp GmbH"},"bank":{"type":"string","description":"Bank name","example":"Commerzbank"}}}}}}}},"responses":{"200":{"description":"Invoice configuration created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceResponse"}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"$ref":"#/components/responses/InvalidApiKey"},"429":{"$ref":"#/components/responses/DailyLimitReached"},"500":{"description":"Server error"}}}},"/api/invoice/read":{"post":{"summary":"Read/open an e-invoice","description":"Public endpoint to read an e-invoice (XRechnung UBL/CII, Factur-X, ZUGFeRD).\n\nAccepts an XML file or a PDF file with an embedded XML invoice (PDF/A-3)\nand returns the complete structured invoice data: parties (including all\nlegal/Impressum details), invoice lines, totals, VAT breakdown, payment\ninformation, references, attachments and the raw XML.\n\nThe invoice is additionally validated against EN 16931 and XRechnung\n(BR-DE) business rules; the validation summary is included in the response.\n","tags":["Invoice"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"XML or PDF file (max. 10 MB)"}}}}}},"responses":{"200":{"description":"Invoice successfully parsed","content":{"application/json":{"schema":{"type":"object","properties":{"sourceType":{"type":"string","enum":["xml","pdf"]},"filename":{"type":"string","example":"invoice.pdf"},"format":{"type":"string","nullable":true,"example":"XRechnung (UBL)"},"profile":{"type":"string","nullable":true,"example":"XRechnung 3.0"},"syntax":{"type":"string","enum":["UBL","CII"]},"documentType":{"type":"string","nullable":true,"description":"Normalized document type key derived from the UNTDID 1001 type code","example":"invoice"},"documentTypeName":{"type":"object","nullable":true,"properties":{"de":{"type":"string","example":"Rechnung"},"en":{"type":"string","example":"Invoice"}}},"invoice":{"type":"object","description":"Fully structured invoice data: invoiceNumber, issueDate, dueDate,\ntypeCode, currency, buyerReference, references, notes,\ninvoicingPeriod, seller/buyer (name, address, VAT id, tax number,\nlegal registration, contact), paymentMeans, paymentTerms,\nallowances/charges, vatBreakdown, totals, lines, attachments,\nprecedingInvoices.\n"},"validation":{"type":"object","properties":{"valid":{"type":"boolean"},"errorCount":{"type":"number"},"warningCount":{"type":"number"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationIssue"}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/ValidationIssue"}}}},"xml":{"type":"string","description":"The raw invoice XML (extracted from the PDF if applicable)"}}}}}},"400":{"description":"Invalid request (no file, unsupported type, too large)"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"422":{"description":"File could not be parsed as an e-invoice (no embedded XML or invalid XML)"},"429":{"$ref":"#/components/responses/DailyLimitReached"},"500":{"description":"Server error"}}}},"/api/invoice/rate-limit":{"get":{"summary":"Get remaining free daily quota","description":"Returns the remaining free calls for today without consuming one.\n\nWithout API key, create, read and validate calls share a free daily\nquota per user (default 10 calls, reset at midnight Europe/Berlin).\nThe user is recognised by several signals (login session, device\ncookie, IP address + user agent), plus an upper bound per IP network.\n\nWhen a valid API key is sent (`x-api-key` or `Authorization: Bearer`),\nthe response reports `unlimited: true`.\n","tags":["Invoice"],"responses":{"200":{"description":"Quota information","headers":{"X-RateLimit-Limit":{"description":"Free calls per day (only without API key)","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining free calls today (only without API key)","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the quota resets (only without API key)","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["unlimited"],"properties":{"unlimited":{"type":"boolean","description":"True when the request carries a valid API key","example":false},"limit":{"type":"integer","nullable":true,"description":"Free calls per day (null with API key)","example":10},"used":{"type":"integer","nullable":true,"description":"Calls used today (null with API key)","example":3},"remaining":{"type":"integer","nullable":true,"description":"Remaining free calls today (null with API key)","example":7},"resetInSeconds":{"type":"integer","nullable":true,"description":"Seconds until the quota resets (null with API key)","example":36000}}}}}},"401":{"description":"Invalid or inactive API key"},"500":{"description":"Server error"}}}},"/api/invoice/number":{"get":{"summary":"Get invoice number details","description":"Returns the global invoice count and the next invoice number that will be assigned.","tags":["Invoice"],"responses":{"200":{"description":"Invoice number information","content":{"application/json":{"schema":{"type":"object","required":["count","nextNumber"],"properties":{"count":{"type":"integer","description":"Total number of invoices created globally","example":42},"nextNumber":{"type":"string","description":"The next invoice number that will be assigned (format IYYYYMMnnnnnn)","example":"I202601100001"}}}}}},"500":{"description":"Server error"}}}},"/api/invoice/{id}/pdf":{"get":{"summary":"Generate invoice PDF with embedded X-Rechnung XML","description":"Generates a PDF/A-3 compliant invoice document with embedded X-Rechnung XML file.\n\nThe PDF generation process:\n1. Retrieves the invoice configuration from Redis using the provided ID\n2. Transforms the configuration to UBL format\n3. Generates X-Rechnung compliant XML using @e-invoice-eu/core\n4. Renders a PDF from HTML template using Gotenberg\n5. Embeds the XML file into the PDF as an attachment\n\nThe configuration ID is valid for 24 hours after creation.\n","tags":["Invoice"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"},"description":"Invoice configuration ID obtained from POST /api/invoice","example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"PDF/A-3 document with embedded X-Rechnung XML","headers":{"Content-Type":{"schema":{"type":"string","example":"application/pdf"},"description":"MIME type of the response"},"X-Invoice-ID":{"schema":{"type":"string","format":"uuid"},"description":"The invoice configuration ID used to generate the PDF"}},"content":{"application/pdf":{"schema":{"type":"string","format":"binary","description":"PDF file with embedded XML invoice data"}}}},"400":{"description":"Invalid or missing invoice ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Invoice configuration not found or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"PDF generation or X-Rechnung XML generation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"tags":[]}