{"openapi":"3.1.0","info":{"title":"normbill API","version":"1.0.0","description":"Headless e-invoicing: invoice JSON in, compliant XRechnung XML out — validated against the official KoSIT validator.","x-logo":{"url":"https://normbill.com/logo-512.png","altText":"normbill","href":"https://normbill.com"},"contact":{"name":"normbill support","email":"support@normbill.com","url":"https://normbill.com/docs"},"license":{"name":"Proprietary API; TypeScript SDK MIT","url":"https://www.npmjs.com/package/@normbill/xrechnung"}},"servers":[{"url":"https://api.normbill.com"}],"security":[{"apiKey":[]}],"paths":{"/v1/invoices/generate":{"post":{"operationId":"generateInvoice","summary":"Generate a compliant e-invoice","description":"Formats: xrechnung-3.0 (UBL) and xrechnung-cii-3.0 (CII / UN-CEFACT D16B) — both the XRechnung CIUS with authoritative KoSIT validation; peppol-bis-3.0 (UBL, BIS Billing 3.0 CIUS); zugferd-2.x / facturx-1.0 (CII payload embedded in a hybrid PDF/A-3, returned base64 in the pdf field — paid plans). Non-XRechnung formats are validated at the structural tier; the report's tier field states this.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Opaque key (≤255 chars) making generate safe to retry. Same key + same body replays the original result without double-billing; same key + different body → 422; in-flight key → 409.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateRequest"},"example":{"format":"xrechnung-3.0","invoice":{"number":"INV-2026-0001","issue_date":"2026-06-15","due_date":"2026-07-15","currency":"EUR","buyer_reference":"04011000-1234512345-06","seller":{"name":"Muster Lieferant GmbH","vat_id":"DE123456789","address":{"country":"DE","city":"Berlin","postal_code":"10115"},"contact":{"name":"Billing","phone":"+49 30 1234567","email":"billing@lieferant.example"}},"buyer":{"name":"Beispiel Kunde AG","address":{"country":"DE","city":"Hamburg","postal_code":"20095"},"contact":{"email":"ap@kunde.example"}},"payment":{"iban":"DE89370400440532013000"},"lines":[{"name":"Beratungsleistung","qty":10,"unit_price":100,"vat":19}]}}}}},"responses":{"200":{"description":"Generated and validated","headers":{"X-RateLimit-Limit":{"description":"Included document quota for the current billing period (generate + parse); annual plans pool 12 monthly allowances. On validate, the free fair-use allowance.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Documents remaining in the current billing period.","schema":{"type":"string"}},"X-Quota-Warning":{"description":"Present only once billable usage reaches ≥80% of the included quota, e.g. \"82% of included documents used\".","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateResponse"}}}},"400":{"description":"Malformed request body, or a request-schema ceiling exceeded — at most 1,000 invoice lines, and at most 1024 KiB of UTF-8 in validate/parse content. Those ceilings live in the request schema, so the SDKs reject the document locally and the API answers 400 invalid-request (never a 413) when one is exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"A request with the same Idempotency-Key is still in flight — retry once it completes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"413":{"description":"Request body exceeds the 2 MB transport limit. Rejected by the HTTP layer before routing, so nothing is processed, counted or billed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"description":"Validation failed — the report lists each issue with rule, JSON path, message and fix","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}},"429":{"description":"One of four limits, distinguished by the problem `type`: the included document quota for the current billing period (quota-exceeded), the plan's bill-shock cap (overage-cap-reached), a free fair-use budget — validation (validate-fair-use) or failed generate attempts, which are budgeted per UTC day (generate-failure-fair-use) — or the burst rate limit, 20 requests/second per API key (rate-limited). Every limit except the burst one carries `retry_after_seconds` and a `Retry-After` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Validator temporarily unavailable — the KoSIT sidecar is down or its circuit breaker is open. Retry later; generate calls may pass options.validate=false to skip tier-3 validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/invoices/validate":{"post":{"operationId":"validateInvoice","summary":"Validate an existing e-invoice document","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateRequest"}}}},"responses":{"200":{"description":"Document is valid","headers":{"X-RateLimit-Limit":{"description":"Included document quota for the current billing period (generate + parse); annual plans pool 12 monthly allowances. On validate, the free fair-use allowance.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Documents remaining in the current billing period.","schema":{"type":"string"}},"X-Quota-Warning":{"description":"Present only once billable usage reaches ≥80% of the included quota, e.g. \"82% of included documents used\".","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationReport"}}}},"400":{"description":"Malformed request body, or a request-schema ceiling exceeded — at most 1,000 invoice lines, and at most 1024 KiB of UTF-8 in validate/parse content. Those ceilings live in the request schema, so the SDKs reject the document locally and the API answers 400 invalid-request (never a 413) when one is exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"413":{"description":"Request body exceeds the 2 MB transport limit. Rejected by the HTTP layer before routing, so nothing is processed, counted or billed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"description":"Validation failed — the report lists each issue with rule, JSON path, message and fix","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}},"429":{"description":"One of four limits, distinguished by the problem `type`: the included document quota for the current billing period (quota-exceeded), the plan's bill-shock cap (overage-cap-reached), a free fair-use budget — validation (validate-fair-use) or failed generate attempts, which are budgeted per UTC day (generate-failure-fair-use) — or the burst rate limit, 20 requests/second per API key (rate-limited). Every limit except the burst one carries `retry_after_seconds` and a `Retry-After` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Validator temporarily unavailable — the KoSIT sidecar is down or its circuit breaker is open. Retry later; generate calls may pass options.validate=false to skip tier-3 validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/invoices/parse":{"post":{"operationId":"parseInvoice","summary":"Parse an e-invoice document into invoice JSON","description":"Maps an inbound e-invoice back to the normbill invoice model — the receive side of the German e-invoicing mandate. Both syntaxes are accepted and auto-detected: UBL 2.1 (XRechnung) and CII / UN-CEFACT D16B (ZUGFeRD, Factur-X). The response format field states which was detected.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParseRequest"}}}},"responses":{"200":{"description":"Document parsed","headers":{"X-RateLimit-Limit":{"description":"Included document quota for the current billing period (generate + parse); annual plans pool 12 monthly allowances. On validate, the free fair-use allowance.","schema":{"type":"string"}},"X-RateLimit-Remaining":{"description":"Documents remaining in the current billing period.","schema":{"type":"string"}},"X-Quota-Warning":{"description":"Present only once billable usage reaches ≥80% of the included quota, e.g. \"82% of included documents used\".","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParseResponse"}}}},"400":{"description":"Malformed request body, or a request-schema ceiling exceeded — at most 1,000 invoice lines, and at most 1024 KiB of UTF-8 in validate/parse content. Those ceilings live in the request schema, so the SDKs reject the document locally and the API answers 400 invalid-request (never a 413) when one is exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"413":{"description":"Request body exceeds the 2 MB transport limit. Rejected by the HTTP layer before routing, so nothing is processed, counted or billed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"description":"Validation failed — the report lists each issue with rule, JSON path, message and fix","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationProblem"}}}},"429":{"description":"One of four limits, distinguished by the problem `type`: the included document quota for the current billing period (quota-exceeded), the plan's bill-shock cap (overage-cap-reached), a free fair-use budget — validation (validate-fair-use) or failed generate attempts, which are budgeted per UTC day (generate-failure-fair-use) — or the burst rate limit, 20 requests/second per API key (rate-limited). Every limit except the burst one carries `retry_after_seconds` and a `Retry-After` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Validator temporarily unavailable — the KoSIT sidecar is down or its circuit breaker is open. Retry later; generate calls may pass options.validate=false to skip tier-3 validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/health":{"get":{"operationId":"health","summary":"Liveness probe","description":"Cheap liveness check — no I/O, no dependencies, no authentication.","security":[],"responses":{"200":{"description":"The process is up","content":{"application/json":{"schema":{"type":"object","required":["status","service"],"properties":{"status":{"type":"string","enum":["ok"]},"service":{"type":"string","enum":["normbill-api"]}}},"example":{"status":"ok","service":"normbill-api"}}}}}}},"/ready":{"get":{"operationId":"ready","summary":"Readiness probe","description":"Readiness with a severity split. Postgres and the KoSIT validator are hard dependencies: without either the instance answers 503 and must leave rotation. The PDF sidecar is soft: a dead one yields 200 with status \"degraded\" so it is visible and alertable without taking the whole API down. The body always names every dependency, so a monitor can tell exactly what is broken from either status.","security":[],"responses":{"200":{"description":"Ready — serving, possibly degraded","content":{"application/json":{"schema":{"type":"object","required":["status","checks"],"properties":{"status":{"type":"string","enum":["ok","degraded"],"description":"\"degraded\" = serving, but the (non-critical) PDF sidecar is down."},"checks":{"type":"object","required":["database","validator","pdf"],"properties":{"database":{"type":"string","enum":["up","down","not-configured"],"description":"\"not-configured\" is a deliberate non-failure — the deployment has no such sidecar."},"validator":{"type":"string","enum":["up","down","not-configured"],"description":"The authoritative KoSIT validator sidecar."},"pdf":{"type":"string","enum":["up","down","not-configured"],"description":"The Mustang PDF sidecar backing ZUGFeRD/Factur-X output. A soft dependency: when it is \"down\" the API stays in rotation and reports status \"degraded\" (200), because taking every endpoint out of rotation over one paid format would turn a partial outage into a total one. \"not-configured\" means PDF_URL is unset — that deployment simply does not offer hybrid PDFs and answers 503 pdf-unavailable for them."}}}}},"example":{"status":"degraded","checks":{"database":"up","validator":"up","pdf":"down"}}}}},"503":{"description":"A hard dependency (database or KoSIT validator) is unavailable","content":{"application/problem+json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","properties":{"checks":{"type":"object","required":["database","validator","pdf"],"properties":{"database":{"type":"string","enum":["up","down","not-configured"],"description":"\"not-configured\" is a deliberate non-failure — the deployment has no such sidecar."},"validator":{"type":"string","enum":["up","down","not-configured"],"description":"The authoritative KoSIT validator sidecar."},"pdf":{"type":"string","enum":["up","down","not-configured"],"description":"The Mustang PDF sidecar backing ZUGFeRD/Factur-X output. A soft dependency: when it is \"down\" the API stays in rotation and reports status \"degraded\" (200), because taking every endpoint out of rotation over one paid format would turn a partial outage into a total one. \"not-configured\" means PDF_URL is unset — that deployment simply does not offer hybrid PDFs and answers 503 pdf-unavailable for them."}}}}}]},"example":{"type":"https://normbill.com/docs/errors/not-ready","title":"Service Unavailable","status":503,"detail":"One or more critical dependencies are unavailable.","checks":{"database":"down","validator":"up","pdf":"up"}}}}}}}}},"components":{"schemas":{"GenerateRequest":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"format":{"type":"string","enum":["xrechnung-3.0","xrechnung-cii-3.0","zugferd-2.x","facturx-1.0","peppol-bis-3.0"]},"version":{"type":"string"},"invoice":{"type":"object","properties":{"number":{"type":"string","minLength":1},"issue_date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"due_date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"type_code":{"default":"380","type":"string","enum":["326","380","381","384","389","875","876","877"]},"currency":{"default":"EUR","type":"string","pattern":"^[A-Z]{3}$"},"buyer_reference":{"type":"string","minLength":1},"invoicing_period":{"type":"object","properties":{"start_date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},"additionalProperties":false},"order_reference":{"type":"string","minLength":1},"preceding_invoice":{"type":"string","minLength":1},"supporting_documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"description":{"type":"string","minLength":1},"url":{"type":"string","minLength":1},"content_base64":{"type":"string","minLength":1},"mime_type":{"type":"string","enum":["application/pdf","image/png","image/jpeg","text/csv","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","application/vnd.oasis.opendocument.spreadsheet"]},"filename":{"type":"string","minLength":1}},"required":["id"],"additionalProperties":false}},"seller":{"type":"object","properties":{"name":{"type":"string","minLength":1},"id":{"type":"string","minLength":1},"legal_registration_id":{"type":"string","minLength":1},"vat_id":{"type":"string","minLength":1},"tax_number":{"type":"string","minLength":1},"address":{"type":"object","properties":{"street":{"type":"string","minLength":1},"city":{"type":"string","minLength":1},"postal_code":{"type":"string","minLength":1},"country":{"type":"string","pattern":"^[A-Z]{2}$"}},"required":["country"],"additionalProperties":false},"contact":{"type":"object","properties":{"name":{"type":"string","minLength":1},"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"phone":{"type":"string","minLength":1}},"additionalProperties":false},"electronic_address":{"type":"object","properties":{"scheme":{"default":"EM","type":"string","minLength":1},"value":{"type":"string","minLength":1}},"required":["scheme","value"],"additionalProperties":false}},"required":["name","address"],"additionalProperties":false},"buyer":{"type":"object","properties":{"name":{"type":"string","minLength":1},"id":{"type":"string","minLength":1},"legal_registration_id":{"type":"string","minLength":1},"vat_id":{"type":"string","minLength":1},"tax_number":{"type":"string","minLength":1},"address":{"type":"object","properties":{"street":{"type":"string","minLength":1},"city":{"type":"string","minLength":1},"postal_code":{"type":"string","minLength":1},"country":{"type":"string","pattern":"^[A-Z]{2}$"}},"required":["country"],"additionalProperties":false},"contact":{"type":"object","properties":{"name":{"type":"string","minLength":1},"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"phone":{"type":"string","minLength":1}},"additionalProperties":false},"electronic_address":{"type":"object","properties":{"scheme":{"default":"EM","type":"string","minLength":1},"value":{"type":"string","minLength":1}},"required":["scheme","value"],"additionalProperties":false}},"required":["name","address"],"additionalProperties":false},"payment":{"type":"object","properties":{"iban":{"type":"string","minLength":15,"maxLength":34},"bic":{"type":"string","minLength":8,"maxLength":11},"account_name":{"type":"string","minLength":1},"means_code":{"type":"string","pattern":"^\\d{1,3}$"},"terms":{"type":"string","minLength":1},"reference":{"type":"string","minLength":1},"mandate_id":{"type":"string","minLength":1},"creditor_id":{"type":"string","minLength":1},"debited_iban":{"type":"string","minLength":15,"maxLength":34}},"additionalProperties":false},"notes":{"type":"array","items":{"type":"string","minLength":1}},"delivery_date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"delivery_address":{"type":"object","properties":{"street":{"type":"string","minLength":1},"city":{"type":"string","minLength":1},"postal_code":{"type":"string","minLength":1},"country":{"type":"string","pattern":"^[A-Z]{2}$"}},"required":["country"],"additionalProperties":false},"lines":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1},"description":{"type":"string","minLength":1},"qty":{"type":"number"},"unit":{"default":"C62","type":"string","minLength":1},"unit_price":{"type":"number","minimum":0},"price_discount":{"type":"number","minimum":0},"gross_price":{"type":"number","minimum":0},"price_base_qty":{"type":"number","exclusiveMinimum":0},"price_base_unit":{"type":"string","minLength":1},"vat":{"type":"number","minimum":0,"maximum":100},"vat_category":{"type":"string","enum":["S","Z","E","AE","K","G","O","L","M"]},"seller_item_id":{"type":"string","minLength":1},"buyer_item_id":{"type":"string","minLength":1},"standard_item_id":{"type":"object","properties":{"id":{"type":"string","minLength":1},"scheme":{"type":"string","minLength":1}},"required":["id","scheme"],"additionalProperties":false},"classifications":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","minLength":1},"scheme":{"type":"string","minLength":1},"version":{"type":"string","minLength":1}},"required":["code","scheme"],"additionalProperties":false}},"origin_country":{"type":"string","pattern":"^[A-Z]{2}$"},"period":{"type":"object","properties":{"start_date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},"additionalProperties":false},"allowances":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"number","exclusiveMinimum":0},"base_amount":{"type":"number","exclusiveMinimum":0},"percent":{"type":"number","minimum":0,"maximum":100},"reason":{"type":"string","minLength":1},"reason_code":{"type":"string","minLength":1}},"additionalProperties":false}},"charges":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"number","exclusiveMinimum":0},"base_amount":{"type":"number","exclusiveMinimum":0},"percent":{"type":"number","minimum":0,"maximum":100},"reason":{"type":"string","minLength":1},"reason_code":{"type":"string","minLength":1}},"additionalProperties":false}},"id":{"type":"string","minLength":1}},"required":["name","qty","unit","unit_price"],"additionalProperties":false}},"allowances":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"number","exclusiveMinimum":0},"base_amount":{"type":"number","exclusiveMinimum":0},"percent":{"type":"number","minimum":0,"maximum":100},"reason":{"type":"string","minLength":1},"reason_code":{"type":"string","minLength":1},"vat_category":{"type":"string","enum":["S","Z","E","AE","K","G","O","L","M"]},"vat":{"type":"number","minimum":0,"maximum":100}},"additionalProperties":false}},"charges":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"number","exclusiveMinimum":0},"base_amount":{"type":"number","exclusiveMinimum":0},"percent":{"type":"number","minimum":0,"maximum":100},"reason":{"type":"string","minLength":1},"reason_code":{"type":"string","minLength":1},"vat_category":{"type":"string","enum":["S","Z","E","AE","K","G","O","L","M"]},"vat":{"type":"number","minimum":0,"maximum":100}},"additionalProperties":false}},"tax_exemptions":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string","enum":["E","AE","K","G","O"]},"reason":{"type":"string","minLength":1},"reason_code":{"type":"string","minLength":1}},"required":["category"],"additionalProperties":false}},"paid_amount":{"type":"number","minimum":0},"totals":{"type":"object","properties":{"net":{"type":"number"},"tax":{"type":"number"},"gross":{"type":"number"}},"required":["net","tax","gross"],"additionalProperties":false},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["number","issue_date","type_code","currency","seller","buyer","lines"],"additionalProperties":false},"options":{"type":"object","properties":{"validate":{"default":true,"type":"boolean"}},"required":["validate"],"additionalProperties":false}},"required":["format","invoice"],"additionalProperties":false},"GenerateResponse":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"format":{"type":"string","enum":["xrechnung-3.0","xrechnung-cii-3.0","zugferd-2.x","facturx-1.0","peppol-bis-3.0"]},"profile":{"type":"string"},"xml":{"type":"string"},"pdf":{"type":"string"},"validation":{"type":"object","properties":{"valid":{"type":"boolean"},"format":{"type":"string","enum":["xrechnung-3.0","xrechnung-cii-3.0","zugferd-2.x","facturx-1.0","peppol-bis-3.0"]},"profile":{"type":"string"},"tier":{"type":"string","enum":["structural","schema","schematron"]},"counts":{"type":"object","properties":{"errors":{"type":"integer","minimum":0,"maximum":9007199254740991},"warnings":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["errors","warnings"],"additionalProperties":false},"issues":{"type":"array","items":{"type":"object","properties":{"severity":{"type":"string","enum":["error","warning"]},"rule":{"type":"string"},"path":{"type":["string","null"]},"message":{"type":"string"},"fix":{"type":["string","null"]},"docs_url":{"type":["string","null"]},"location":{"type":["string","null"]}},"required":["severity","rule","path","message","fix","docs_url","location"],"additionalProperties":false}}},"required":["valid","format","profile","tier","counts","issues"],"additionalProperties":false},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["format","profile","xml","validation"],"additionalProperties":false},"ValidateRequest":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"format":{"type":"string","enum":["xrechnung-3.0","xrechnung-cii-3.0","zugferd-2.x","facturx-1.0","peppol-bis-3.0"]},"content":{"type":"string","minLength":1,"maxLength":1048576}},"required":["content"],"additionalProperties":false},"ParseRequest":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"content":{"type":"string","minLength":1,"maxLength":1048576}},"required":["content"],"additionalProperties":false},"ParseResponse":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"format":{"type":"string","enum":["xrechnung-3.0","xrechnung-cii-3.0","zugferd-2.x","facturx-1.0","peppol-bis-3.0"]},"profile":{"type":"string"},"invoice":{"type":"object","properties":{"number":{"type":"string","minLength":1},"issue_date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"due_date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"type_code":{"default":"380","type":"string","enum":["326","380","381","384","389","875","876","877"]},"currency":{"default":"EUR","type":"string","pattern":"^[A-Z]{3}$"},"buyer_reference":{"type":"string","minLength":1},"invoicing_period":{"type":"object","properties":{"start_date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},"additionalProperties":false},"order_reference":{"type":"string","minLength":1},"preceding_invoice":{"type":"string","minLength":1},"supporting_documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"description":{"type":"string","minLength":1},"url":{"type":"string","minLength":1},"content_base64":{"type":"string","minLength":1},"mime_type":{"type":"string","enum":["application/pdf","image/png","image/jpeg","text/csv","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","application/vnd.oasis.opendocument.spreadsheet"]},"filename":{"type":"string","minLength":1}},"required":["id"],"additionalProperties":false}},"seller":{"type":"object","properties":{"name":{"type":"string","minLength":1},"id":{"type":"string","minLength":1},"legal_registration_id":{"type":"string","minLength":1},"vat_id":{"type":"string","minLength":1},"tax_number":{"type":"string","minLength":1},"address":{"type":"object","properties":{"street":{"type":"string","minLength":1},"city":{"type":"string","minLength":1},"postal_code":{"type":"string","minLength":1},"country":{"type":"string","pattern":"^[A-Z]{2}$"}},"required":["country"],"additionalProperties":false},"contact":{"type":"object","properties":{"name":{"type":"string","minLength":1},"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"phone":{"type":"string","minLength":1}},"additionalProperties":false},"electronic_address":{"type":"object","properties":{"scheme":{"default":"EM","type":"string","minLength":1},"value":{"type":"string","minLength":1}},"required":["scheme","value"],"additionalProperties":false}},"required":["name","address"],"additionalProperties":false},"buyer":{"type":"object","properties":{"name":{"type":"string","minLength":1},"id":{"type":"string","minLength":1},"legal_registration_id":{"type":"string","minLength":1},"vat_id":{"type":"string","minLength":1},"tax_number":{"type":"string","minLength":1},"address":{"type":"object","properties":{"street":{"type":"string","minLength":1},"city":{"type":"string","minLength":1},"postal_code":{"type":"string","minLength":1},"country":{"type":"string","pattern":"^[A-Z]{2}$"}},"required":["country"],"additionalProperties":false},"contact":{"type":"object","properties":{"name":{"type":"string","minLength":1},"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"phone":{"type":"string","minLength":1}},"additionalProperties":false},"electronic_address":{"type":"object","properties":{"scheme":{"default":"EM","type":"string","minLength":1},"value":{"type":"string","minLength":1}},"required":["scheme","value"],"additionalProperties":false}},"required":["name","address"],"additionalProperties":false},"payment":{"type":"object","properties":{"iban":{"type":"string","minLength":15,"maxLength":34},"bic":{"type":"string","minLength":8,"maxLength":11},"account_name":{"type":"string","minLength":1},"means_code":{"type":"string","pattern":"^\\d{1,3}$"},"terms":{"type":"string","minLength":1},"reference":{"type":"string","minLength":1},"mandate_id":{"type":"string","minLength":1},"creditor_id":{"type":"string","minLength":1},"debited_iban":{"type":"string","minLength":15,"maxLength":34}},"additionalProperties":false},"notes":{"type":"array","items":{"type":"string","minLength":1}},"delivery_date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"delivery_address":{"type":"object","properties":{"street":{"type":"string","minLength":1},"city":{"type":"string","minLength":1},"postal_code":{"type":"string","minLength":1},"country":{"type":"string","pattern":"^[A-Z]{2}$"}},"required":["country"],"additionalProperties":false},"lines":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1},"description":{"type":"string","minLength":1},"qty":{"type":"number"},"unit":{"default":"C62","type":"string","minLength":1},"unit_price":{"type":"number","minimum":0},"price_discount":{"type":"number","minimum":0},"gross_price":{"type":"number","minimum":0},"price_base_qty":{"type":"number","exclusiveMinimum":0},"price_base_unit":{"type":"string","minLength":1},"vat":{"type":"number","minimum":0,"maximum":100},"vat_category":{"type":"string","enum":["S","Z","E","AE","K","G","O","L","M"]},"seller_item_id":{"type":"string","minLength":1},"buyer_item_id":{"type":"string","minLength":1},"standard_item_id":{"type":"object","properties":{"id":{"type":"string","minLength":1},"scheme":{"type":"string","minLength":1}},"required":["id","scheme"],"additionalProperties":false},"classifications":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","minLength":1},"scheme":{"type":"string","minLength":1},"version":{"type":"string","minLength":1}},"required":["code","scheme"],"additionalProperties":false}},"origin_country":{"type":"string","pattern":"^[A-Z]{2}$"},"period":{"type":"object","properties":{"start_date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},"additionalProperties":false},"allowances":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"number","exclusiveMinimum":0},"base_amount":{"type":"number","exclusiveMinimum":0},"percent":{"type":"number","minimum":0,"maximum":100},"reason":{"type":"string","minLength":1},"reason_code":{"type":"string","minLength":1}},"additionalProperties":false}},"charges":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"number","exclusiveMinimum":0},"base_amount":{"type":"number","exclusiveMinimum":0},"percent":{"type":"number","minimum":0,"maximum":100},"reason":{"type":"string","minLength":1},"reason_code":{"type":"string","minLength":1}},"additionalProperties":false}},"id":{"type":"string","minLength":1}},"required":["name","qty","unit","unit_price"],"additionalProperties":false}},"allowances":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"number","exclusiveMinimum":0},"base_amount":{"type":"number","exclusiveMinimum":0},"percent":{"type":"number","minimum":0,"maximum":100},"reason":{"type":"string","minLength":1},"reason_code":{"type":"string","minLength":1},"vat_category":{"type":"string","enum":["S","Z","E","AE","K","G","O","L","M"]},"vat":{"type":"number","minimum":0,"maximum":100}},"additionalProperties":false}},"charges":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"number","exclusiveMinimum":0},"base_amount":{"type":"number","exclusiveMinimum":0},"percent":{"type":"number","minimum":0,"maximum":100},"reason":{"type":"string","minLength":1},"reason_code":{"type":"string","minLength":1},"vat_category":{"type":"string","enum":["S","Z","E","AE","K","G","O","L","M"]},"vat":{"type":"number","minimum":0,"maximum":100}},"additionalProperties":false}},"tax_exemptions":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string","enum":["E","AE","K","G","O"]},"reason":{"type":"string","minLength":1},"reason_code":{"type":"string","minLength":1}},"required":["category"],"additionalProperties":false}},"paid_amount":{"type":"number","minimum":0},"totals":{"type":"object","properties":{"net":{"type":"number"},"tax":{"type":"number"},"gross":{"type":"number"}},"required":["net","tax","gross"],"additionalProperties":false},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["number","issue_date","type_code","currency","seller","buyer","lines"],"additionalProperties":false}},"required":["format","profile","invoice"],"additionalProperties":false},"ValidationReport":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"valid":{"type":"boolean"},"format":{"type":"string","enum":["xrechnung-3.0","xrechnung-cii-3.0","zugferd-2.x","facturx-1.0","peppol-bis-3.0"]},"profile":{"type":"string"},"tier":{"type":"string","enum":["structural","schema","schematron"]},"counts":{"type":"object","properties":{"errors":{"type":"integer","minimum":0,"maximum":9007199254740991},"warnings":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["errors","warnings"],"additionalProperties":false},"issues":{"type":"array","items":{"type":"object","properties":{"severity":{"type":"string","enum":["error","warning"]},"rule":{"type":"string"},"path":{"type":["string","null"]},"message":{"type":"string"},"fix":{"type":["string","null"]},"docs_url":{"type":["string","null"]},"location":{"type":["string","null"]}},"required":["severity","rule","path","message","fix","docs_url","location"],"additionalProperties":false}}},"required":["valid","format","profile","tier","counts","issues"],"additionalProperties":false},"ValidationProblem":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number","const":422},"detail":{"type":"string"},"instance":{"type":"string"},"report":{"type":"object","properties":{"valid":{"type":"boolean"},"format":{"type":"string","enum":["xrechnung-3.0","xrechnung-cii-3.0","zugferd-2.x","facturx-1.0","peppol-bis-3.0"]},"profile":{"type":"string"},"tier":{"type":"string","enum":["structural","schema","schematron"]},"counts":{"type":"object","properties":{"errors":{"type":"integer","minimum":0,"maximum":9007199254740991},"warnings":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["errors","warnings"],"additionalProperties":false},"issues":{"type":"array","items":{"type":"object","properties":{"severity":{"type":"string","enum":["error","warning"]},"rule":{"type":"string"},"path":{"type":["string","null"]},"message":{"type":"string"},"fix":{"type":["string","null"]},"docs_url":{"type":["string","null"]},"location":{"type":["string","null"]}},"required":["severity","rule","path","message","fix","docs_url","location"],"additionalProperties":false}}},"required":["valid","format","profile","tier","counts","issues"],"additionalProperties":false}},"required":["type","title","status","report"],"additionalProperties":{}},"ProblemDetails":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"detail":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status"],"additionalProperties":{}}},"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key from the dashboard: sk_live_… or sk_test_…"}}}}