{"openapi":"3.1.0","info":{"title":"InvoiceHub API","version":"1.2.0","description":"Developer-first REST API for EU electronic invoicing. Validate UBL 2.1 invoices against the official EN 16931 (CEN) Schematron and generate EN 16931-conformant UBL 2.1 documents from structured JSON.","contact":{"name":"InvoiceHub","url":"https://invoicehub.dev/contact"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://api.invoicehub.dev","description":"Production"}],"tags":[{"name":"Validation","description":"Check invoices against EN 16931."},{"name":"Generation","description":"Build EN 16931-conformant UBL invoices."},{"name":"Metadata","description":"Service and capability discovery."}],"security":[{"ApiKeyAuth":[]}],"paths":{"/api/v1/validate":{"post":{"tags":["Validation"],"summary":"Validate an invoice","description":"Validates a UBL 2.1 Invoice or CreditNote against the official EN 16931 Schematron. Returns HTTP 200 when valid and 422 when the document fails one or more business rules.","operationId":"validateInvoice","requestBody":{"required":true,"content":{"application/xml":{"schema":{"type":"string","description":"Raw UBL 2.1 XML."}}}},"responses":{"200":{"description":"Document is valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"description":"Document failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/generate":{"post":{"tags":["Generation"],"summary":"Generate a UBL 2.1 invoice","description":"Builds an EN 16931-conformant UBL 2.1 invoice from a structured payload. The generated document is validated against the EN 16931 Schematron before it is returned; if it does not pass, the validation report is returned with HTTP 422 instead of an invalid document.","operationId":"generateInvoice","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateInvoiceInput"}}}},"responses":{"200":{"description":"Invoice generated and self-validated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateResponse"}}}},"400":{"description":"Invalid input payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"description":"Generated document did not pass validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateResponse"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/formats":{"get":{"tags":["Metadata"],"summary":"List supported and roadmap formats","operationId":"listFormats","security":[],"responses":{"200":{"description":"Format catalogue.","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","description":"Your InvoiceHub API key as a Bearer token."}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded for your plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"requestId":{"type":"string"}},"required":["error"]},"ValidationIssue":{"type":"object","properties":{"ruleId":{"type":"string","example":"BR-CO-15"},"severity":{"type":"string","enum":["CRITICAL","WARNING","INFO"]},"message":{"type":"string"},"path":{"type":"string"}},"required":["ruleId","severity","message"]},"ValidationResult":{"type":"object","properties":{"valid":{"type":"boolean"},"format":{"type":"string","enum":["UBL_2.1","UN_CEFACT_CII","UNKNOWN"]},"profile":{"type":"string","example":"Peppol BIS Billing 3.0"},"engine":{"type":"string","example":"EN16931-UBL-schematron-1.3.16"},"rulesEvaluated":{"type":"integer"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationIssue"}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/ValidationIssue"}},"metadata":{"type":"object"}},"required":["valid","format","engine","rulesEvaluated","errors","warnings"]},"ValidationResponse":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"requestId":{"type":"string"},"performance":{"type":"object","properties":{"duration_ms":{"type":"integer"}}},"report":{"$ref":"#/components/schemas/ValidationResult"}}},"GenerateAddress":{"type":"object","properties":{"street":{"type":"string"},"city":{"type":"string"},"postalZone":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 code.","example":"DE"}},"required":["country"]},"GenerateParty":{"type":"object","properties":{"name":{"type":"string"},"vatId":{"type":"string","description":"VAT identifier; required for standard-rated sales.","example":"DE123456789"},"address":{"$ref":"#/components/schemas/GenerateAddress"}},"required":["name","address"]},"GenerateLineInput":{"type":"object","properties":{"description":{"type":"string"},"quantity":{"type":"number"},"unitPrice":{"type":"number"},"unitCode":{"type":"string","description":"UN/ECE Rec 20 code.","default":"C62"},"vatRate":{"type":"number","description":"Percentage; required for category S.","example":21},"vatCategory":{"type":"string","description":"EN 16931 VAT category code.","default":"S"},"exemptionReason":{"type":"string","description":"Required for exempt/reverse-charge categories."}},"required":["description","quantity","unitPrice"]},"GenerateInvoiceInput":{"type":"object","properties":{"invoiceNumber":{"type":"string"},"issueDate":{"type":"string","format":"date"},"dueDate":{"type":"string","format":"date"},"currency":{"type":"string","example":"EUR"},"invoiceTypeCode":{"type":"string","default":"380"},"customizationId":{"type":"string"},"note":{"type":"string"},"seller":{"$ref":"#/components/schemas/GenerateParty"},"buyer":{"$ref":"#/components/schemas/GenerateParty"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/GenerateLineInput"},"minItems":1},"payment":{"type":"object","properties":{"iban":{"type":"string"},"meansCode":{"type":"string","default":"30"}}}},"required":["invoiceNumber","issueDate","currency","seller","buyer","lines"]},"GenerateResponse":{"type":"object","properties":{"xml":{"type":"string","description":"The generated UBL 2.1 document."},"report":{"$ref":"#/components/schemas/ValidationResult"}}}}}}