{"openapi":"3.1.0","info":{"title":"Invoir API","description":"Generate and validate EU e-invoices: Factur-X, ZUGFeRD, XRechnung (UBL and CII) and Peppol BIS Billing 3.0. Every request needs `Authorization: Bearer inv_...`; get a free key at https://validate.invoir.dev/signup. Full documentation: https://invoir.dev/docs","contact":{"name":"Invoir","url":"https://invoir.dev","email":"hello@invoir.dev"},"version":"v1"},"servers":[{"url":"https://validate.invoir.dev"}],"security":[{"apiKey":[]}],"tags":[{"name":"Invoices","description":"Generate e-invoices from JSON and download them"},{"name":"Branding and templates","description":"How your PDFs look: logo, colour, footer, defaults, and your own templates"},{"name":"Parse","description":"Read received e-invoices into invoice JSON"}],"paths":{"/api/v1/templates/{name}":{"get":{"tags":["Branding and templates"],"summary":"Get a template's HTML","description":"Works for built-in names too, as a starting point for your own.","operationId":"template","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"text/html":{"schema":{"type":"string"}}}}}},"put":{"tags":["Branding and templates"],"summary":"Create or replace a template","description":"Body: the Mustache HTML as text/html (up to 200 KB). Then use it with \"template\": \"<name>\".","operationId":"putTemplate","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"text/html":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}}}},"delete":{"tags":["Branding and templates"],"summary":"Delete a template","operationId":"deleteTemplate","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/branding":{"get":{"tags":["Branding and templates"],"summary":"Current branding","description":"The logo is reported by type and size, not returned.","operationId":"branding","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}}}},"put":{"tags":["Branding and templates"],"summary":"Set branding","description":"Replaces all branding fields: logo (base64 PNG/JPEG, up to 512 KB), accentColor (#rrggbb), footer text, and the default template and language for invoices that don't name one.","operationId":"setBranding","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Branding"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}}}},"delete":{"tags":["Branding and templates"],"summary":"Remove branding","operationId":"deleteBranding","responses":{"200":{"description":"OK"}}}},"/api/v1/validate":{"post":{"tags":["api-controller"],"operationId":"validate","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}},"required":["file"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/parse":{"post":{"tags":["Parse"],"summary":"Parse an e-invoice","description":"Upload XRechnung (UBL or CII), Peppol BIS, EN 16931 UBL/CII, Factur-X / ZUGFeRD XML or a hybrid PDF as multipart field \"file\". Returns the invoice as the JSON POST /api/v1/invoices takes, the totals as stated, the values that JSON has no field for (unmapped), warnings and the validation report. Invalid documents are read too; status says what the validation found. Nothing is stored.","operationId":"parse","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}},"required":["file"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/keys/test":{"post":{"tags":["Invoices"],"summary":"Create or rotate your test key","description":"Call with your live key. Returns a new inv_test_ key (shown once); the previous test key stops working. Documents made with a test key are watermarked, not counted and deleted after 24 hours.","operationId":"createTestKey","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/invoices":{"get":{"tags":["Invoices"],"summary":"List generated invoices","description":"Newest first. Page with before=<id of the last row>.","operationId":"list","parameters":[{"name":"before","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}}}},"post":{"tags":["Invoices"],"summary":"Generate an invoice","description":"Takes invoice JSON, returns the validated PDF/A-3 and XML as download URLs plus the validation report. Invalid documents come back as 422 with the report and are not stored.","operationId":"create","parameters":[{"name":"Idempotency-Key","in":"header","description":"Any string up to 100 characters; the same key with the same body returns the first answer again","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceResponse"}}}}}}},"/api/v1/extract":{"post":{"tags":["api-controller"],"operationId":"extract","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}},"required":["file"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/templates":{"get":{"tags":["Branding and templates"],"summary":"List templates","description":"The built-in templates and your own.","operationId":"templates","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}}}}},"/api/v1/invoices/{id}":{"get":{"tags":["Invoices"],"summary":"Get a generated invoice","description":"The same JSON the POST returned, while the document is kept.","operationId":"get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"string"}}}}}},"delete":{"tags":["Invoices"],"summary":"Delete a generated invoice","description":"Deletes the PDF, the XML and the stored answer at once, before the retention period ends (for example when a data subject asks for erasure). It stays counted in the month's usage.","operationId":"delete","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/invoices/{id}/xml":{"get":{"tags":["Invoices"],"summary":"Download the XML","operationId":"xml","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/xml":{"schema":{"type":"string","format":"byte"}}}}}}},"/api/v1/invoices/{id}/pdf":{"get":{"tags":["Invoices"],"summary":"Download the PDF","operationId":"pdf","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/pdf":{"schema":{"type":"string","format":"byte"}}}}}}}},"components":{"schemas":{"Branding":{"type":"object","properties":{"logo":{"type":"string"},"accentColor":{"type":"string"},"footer":{"type":"string"},"template":{"type":"string"},"language":{"type":"string"}}},"Address":{"type":"object","properties":{"street":{"type":"string"},"street2":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"region":{"type":"string"},"country":{"type":"string"}}},"AllowanceCharge":{"type":"object","properties":{"amount":{"type":"number"},"percent":{"type":"number"},"baseAmount":{"type":"number"},"reason":{"type":"string"},"reasonCode":{"type":"string"},"vatRate":{"type":"number"},"vatCategory":{"type":"string"},"vatExemptionReason":{"type":"string"},"vatExemptionReasonCode":{"type":"string"}}},"Attachment":{"type":"object","properties":{"filename":{"type":"string"},"mimeType":{"type":"string"},"description":{"type":"string"},"data":{"type":"string"}}},"Contact":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"}}},"Delivery":{"type":"object","properties":{"date":{"type":"string","format":"date"},"periodStart":{"type":"string","format":"date"},"periodEnd":{"type":"string","format":"date"},"name":{"type":"string"},"address":{"$ref":"#/components/schemas/Address"},"locationId":{"$ref":"#/components/schemas/Identifier"}}},"ElectronicAddress":{"type":"object","properties":{"scheme":{"type":"string"},"id":{"type":"string"}}},"Identifier":{"type":"object","properties":{"scheme":{"type":"string"},"id":{"type":"string"}}},"InvoiceRequest":{"type":"object","properties":{"profile":{"type":"string"},"conformance":{"type":"string"},"type":{"type":"string"},"number":{"type":"string"},"issueDate":{"type":"string","format":"date"},"dueDate":{"type":"string","format":"date"},"currency":{"type":"string"},"language":{"type":"string"},"seller":{"$ref":"#/components/schemas/Party"},"buyer":{"$ref":"#/components/schemas/Party"},"delivery":{"$ref":"#/components/schemas/Delivery"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/Line"}},"allowances":{"type":"array","items":{"$ref":"#/components/schemas/AllowanceCharge"}},"charges":{"type":"array","items":{"$ref":"#/components/schemas/AllowanceCharge"}},"payment":{"$ref":"#/components/schemas/Payment"},"references":{"$ref":"#/components/schemas/References"},"notes":{"type":"array","items":{"type":"string"}},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"}},"prepaidAmount":{"type":"number"},"roundingAmount":{"type":"number"},"template":{"type":"string"},"templateHtml":{"type":"string"},"branding":{"$ref":"#/components/schemas/Branding"},"pdf":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}},"Line":{"type":"object","properties":{"id":{"type":"string"},"description":{"type":"string"},"details":{"type":"string"},"quantity":{"type":"number"},"unit":{"type":"string"},"unitPrice":{"type":"number"},"priceBasisQuantity":{"type":"number"},"vatRate":{"type":"number"},"vatCategory":{"type":"string"},"vatExemptionReason":{"type":"string"},"vatExemptionReasonCode":{"type":"string"},"allowances":{"type":"array","items":{"$ref":"#/components/schemas/LineAllowanceCharge"}},"charges":{"type":"array","items":{"$ref":"#/components/schemas/LineAllowanceCharge"}},"periodStart":{"type":"string","format":"date"},"periodEnd":{"type":"string","format":"date"},"orderLineId":{"type":"string"},"sellerItemId":{"type":"string"},"buyerItemId":{"type":"string"},"accountingReference":{"type":"string"}}},"LineAllowanceCharge":{"type":"object","properties":{"amount":{"type":"number"},"percent":{"type":"number"},"reason":{"type":"string"},"reasonCode":{"type":"string"}}},"Party":{"type":"object","properties":{"name":{"type":"string"},"tradingName":{"type":"string"},"vatId":{"type":"string"},"taxId":{"type":"string"},"registrationId":{"type":"string"},"registrationScheme":{"type":"string"},"legalForm":{"type":"string"},"address":{"$ref":"#/components/schemas/Address"},"contact":{"$ref":"#/components/schemas/Contact"},"email":{"type":"string"},"phone":{"type":"string"},"electronicAddress":{"$ref":"#/components/schemas/ElectronicAddress"},"identifier":{"$ref":"#/components/schemas/Identifier"},"reference":{"type":"string"}}},"Payment":{"type":"object","properties":{"means":{"type":"string"},"meansCode":{"type":"string"},"iban":{"type":"string"},"bic":{"type":"string"},"accountName":{"type":"string"},"reference":{"type":"string"},"terms":{"type":"string"},"mandateId":{"type":"string"},"creditorId":{"type":"string"},"debtorIban":{"type":"string"}}},"PrecedingInvoice":{"type":"object","properties":{"number":{"type":"string"},"date":{"type":"string","format":"date"}}},"Project":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"References":{"type":"object","properties":{"order":{"type":"string"},"sellerOrder":{"type":"string"},"contract":{"type":"string"},"despatchAdvice":{"type":"string"},"receivingAdvice":{"type":"string"},"tender":{"type":"string"},"project":{"$ref":"#/components/schemas/Project"},"precedingInvoice":{"$ref":"#/components/schemas/PrecedingInvoice"},"buyerAccountingReference":{"type":"string"},"businessProcess":{"type":"string"}}},"CheckResult":{"type":"object","properties":{"name":{"type":"string"},"engine":{"type":"string"},"passed":{"type":"boolean"},"findings":{"type":"array","items":{"$ref":"#/components/schemas/Finding"}}}},"FileInfo":{"type":"object","properties":{"url":{"type":"string"},"filename":{"type":"string"},"bytes":{"type":"integer","format":"int64"},"contentType":{"type":"string"},"embeddedAs":{"type":"string"}}},"Finding":{"type":"object","properties":{"severity":{"type":"string","enum":["error","warning","info"]},"rule":{"type":"string"},"message":{"type":"string"},"location":{"type":"string"},"line":{"type":"integer","format":"int32"}}},"InvoiceResponse":{"type":"object","properties":{"id":{"type":"string"},"test":{"type":"boolean"},"status":{"type":"string"},"profile":{"type":"string"},"conformance":{"type":"string"},"number":{"type":"string"},"createdAt":{"type":"string"},"expiresAt":{"type":"string"},"pdf":{"$ref":"#/components/schemas/FileInfo"},"xml":{"$ref":"#/components/schemas/FileInfo"},"totals":{"$ref":"#/components/schemas/TotalsInfo"},"validation":{"$ref":"#/components/schemas/ValidationReport"},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}},"TotalsInfo":{"type":"object","properties":{"currency":{"type":"string"},"lineTotal":{"type":"number"},"allowanceTotal":{"type":"number"},"chargeTotal":{"type":"number"},"taxExclusive":{"type":"number"},"vat":{"type":"number"},"taxInclusive":{"type":"number"},"prepaid":{"type":"number"},"rounding":{"type":"number"},"due":{"type":"number"},"vatBreakdown":{"type":"array","items":{"$ref":"#/components/schemas/VatInfo"}}}},"ValidationReport":{"type":"object","properties":{"status":{"type":"string","enum":["valid","invalid","unsupported"]},"fileType":{"type":"string"},"format":{"type":"string"},"specificationId":{"type":"string"},"message":{"type":"string"},"errors":{"type":"integer","format":"int64"},"warnings":{"type":"integer","format":"int64"},"checks":{"type":"array","items":{"$ref":"#/components/schemas/CheckResult"}},"embeddedXml":{"type":"string"},"durationMs":{"type":"integer","format":"int64"}}},"VatInfo":{"type":"object","properties":{"category":{"type":"string"},"rate":{"type":"number"},"basis":{"type":"number"},"amount":{"type":"number"},"exemptionReason":{"type":"string"}}}},"securitySchemes":{"apiKey":{"type":"http","description":"Your inv_ or inv_test_ key","scheme":"bearer"}}}}