{"openapi":"3.0.0","info":{"title":"e2invoice API","version":"1.0.0","description":"REST API for generating X-Rechnung compliant e-invoices and PDFs","contact":{"name":"e2invoice Support"}},"servers":[{"url":"https://www.e2invoice.com"}],"components":{"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"},"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"}}}}}}}},"EInvoiceConfig":{"type":"object","description":"Full E-Invoice configuration according to EN 16931 standard.\nThis schema is used for the advanced /api/invoice endpoint.\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:\n- 380: Commercial invoice\n- 381: Credit note\n- 384: Corrected invoice\n- 389: Self-billed invoice\n- 751: Invoice information for accounting purposes\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","cancellation"],"description":"Document type (defaults to 'invoice')\n- invoice → invoiceTypeCode: 380\n- credit_note → invoiceTypeCode: 381\n- cancellation → invoiceTypeCode: 384\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":"Additional legal information","example":"Registered at Amtsgericht Berlin"},"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"}}}}}}}},"paths":{"/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/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"}}}}}}},"/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/rate-limit":{"get":{"summary":"Get available rate limit","description":"Returns the remaining number of invoice creation requests available for the current IP address.","tags":["Invoice"],"responses":{"200":{"description":"Rate limit information","content":{"application/json":{"schema":{"type":"object","required":["availableCount","expireIn"],"properties":{"availableCount":{"type":"integer","description":"Number of remaining requests","example":5},"expireIn":{"type":"integer","description":"Number of seconds until the rate limit will expire"}}}}}},"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","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"],"description":"Document type (defaults to 'invoice')\n- invoice -> invoiceTypeCode: 380\n- credit_note -> invoiceTypeCode: 381\n","example":"invoice"},"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","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"},"additionalLegalInformation":{"type":"string","description":"Additional legal information (e.g., court of registration, managing director)","example":"Amtsgericht Berlin"},"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"}}},"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%)","example":19}}}},"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"}}}},"429":{"description":"Too many requests - rate limit exceeded"},"500":{"description":"Server error"}}}},"/api/invoice/validate":{"post":{"summary":"Validate e-invoice (PDF or XML)","description":"Validates an e-invoice file and extracts key information.\n\n**Supported file types:**\n- **XML files**: Direct e-invoice XML (XRechnung, Factur-X, ZUGFeRD)\n- **PDF files**: PDF/A-3 with embedded XML (Factur-X/ZUGFeRD compliant PDFs)\n\n**Supported formats:**\n- XRechnung (UBL and CII syntax)\n- Factur-X / ZUGFeRD (EN16931 and Basic profiles)\n\n**Validation checks:**\n- XML well-formedness\n- Required fields according to EN16931 standard:\n  - Invoice number (BT-1)\n  - Invoice issue date (BT-2)\n  - Document currency code (BT-5)\n  - Seller name (BT-27)\n  - Buyer name (BT-44)\n  - Invoice total amount with VAT (BT-112)\n  - At least one invoice line\n\n**Response includes:**\n- Validation result (valid/invalid)\n- Source type (xml or pdf)\n- Detected format and syntax (UBL/CII)\n- Extracted invoice metadata (number, date, parties, amount)\n- List of errors and warnings\n\n**File size limit:** 10MB\n\nNote: This endpoint performs structural validation. For full schema validation\nagainst official XRechnung/Factur-X schemas, 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 (e.g., XRechnung-UBL, Factur-X-EN16931)","example":"Factur-X-EN16931"},"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)","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":{"type":"object","properties":{"path":{"type":"string","description":"XPath-like path to the problematic element","example":"cbc:ID"},"message":{"type":"string","description":"Error description","example":"Invoice number (BT-1) is required"},"severity":{"type":"string","enum":["error","warning"],"example":"error"}}}},"warnings":{"type":"array","description":"List of validation warnings","items":{"type":"object","properties":{"path":{"type":"string","example":"cbc:CustomizationID"},"message":{"type":"string","example":"Unknown customization ID"},"severity":{"type":"string","enum":["error","warning"],"example":"warning"}}}}}},"examples":{"validPdf":{"summary":"Valid Factur-X PDF","value":{"valid":true,"format":"Factur-X-EN16931","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","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)","syntax":"UBL","sourceType":"xml","filename":"invoice.xml","invoiceNumber":null,"invoiceDate":"2024-01-15","sellerName":"Acme Corp GmbH","buyerName":null,"totalAmount":"1190.00","currency":"EUR","errors":[{"path":"cbc:ID","message":"Invoice number (BT-1) is required","severity":"error"},{"path":"cac:AccountingCustomerParty/cac:Party/cac:PartyLegalEntity/cbc:RegistrationName","message":"Buyer name (BT-44) is required","severity":"error"}],"warnings":[{"path":"cbc:CustomizationID","message":"Unknown customization ID: custom-profile","severity":"warning"}]}},"pdfNoXml":{"summary":"PDF without embedded XML","value":{"valid":false,"format":null,"syntax":null,"sourceType":"pdf","filename":"regular-invoice.pdf","invoiceNumber":null,"invoiceDate":null,"sellerName":null,"buyerName":null,"totalAmount":null,"currency":null,"errors":[{"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\""}}}}}}}},"429":{"description":"Too many requests - rate limit exceeded"},"500":{"description":"Server error"}}}}},"tags":[]}