{"openapi":"3.1.0","info":{"title":"invowerk","description":"E-Rechnungen prüfen: ZUGFeRD, Factur-X, XRechnung und Peppol. Kostenloses Prüf-Tool und API mit Prüfbericht.\n\nBase URL: `https://api.invowerk.dev`.\n\n### Authentication\nSend your key in the `X-API-Key` header. Calls without a key run anonymously at\na lower rate limit per IP address.\n\n### Rate limits\nEvery response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and\n`X-RateLimit-Reset` (seconds until the window resets). Over-budget calls return\n`429` with a `Retry-After` header. Check your live budget at `GET /v1/me`.\n\n### Pagination\nList endpoints return a keyset envelope: `{\"items\": [...], \"next_cursor\": \"...\"}`.\nPass `next_cursor` back as the `?cursor=` query param for the next page; it is\n`null` on the last page.\n\n### Errors\nErrors are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) `problem+json` with a\nstable machine-readable **`code`** (e.g. `rate_limited`, `credits_exhausted`,\n`validation_error`). Branch on `code`. The `title` and `detail` text may change.\n\n### Quickstart\n```sh\ncurl -H \"X-API-Key: $API_KEY\" https://api.invowerk.dev/v1/me\n```\n","version":"1"},"servers":[{"url":"https://api.invowerk.dev"}],"paths":{"/v1/me":{"get":{"tags":["Account"],"summary":"Your plan, remaining requests, and remaining credits","description":"Check where you stand before a call fails.\n\nReturns the plan this request runs on and whether your key was recognized.\nWithout an `X-API-Key`, the call runs anonymously at the rate limit for\ncalls without a key. It also returns the requests left in the current window\nand the features your plan includes. On plans priced in credits, it returns\nthe credits left in the current billing period.\n\nThis call does not count against your rate limit, so the numbers it reports\nare the numbers you have.\n\n**Credits:** free. This endpoint is not metered.","operationId":"get_me","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}}},"security":[{"APIKeyHeader":[]}],"x-credits-cost":0}},"/v1/parse":{"post":{"tags":["Transform"],"summary":"Read an e-invoice into JSON","description":"Read an existing e-invoice into JSON keyed on EN 16931 Business Terms.\n\nThe JSON in `model` is the request body of `POST /v1/generate`, so you can edit\nit and create the invoice again. Send an XML invoice (UBL or CII) or a\nZUGFeRD / Factur-X PDF as the raw request body or as a multipart file part, at\nmost 20 MB. A PDF may have at most 500 pages and 16 attachments. UBL credit\nnotes are not supported. The answer also has `detection` (syntax, flavor,\nCustomizationID) and `source` (`xml` or `pdf-embedded`). A file that cannot be\nread returns 422; `detail` starts with an error code. Costs 2 credits.\n\n**Credits:** 2 per call.","operationId":"parse_invoice_v1_parse_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParseResponse"}}}}},"security":[{"APIKeyHeader":[]}],"x-credits-cost":2}},"/v1/convert":{"post":{"tags":["Transform"],"summary":"Convert an e-invoice between UBL and CII","description":"Convert an e-invoice between UBL and CII.\n\nSend the invoice as for `POST /v1/parse`: XML or a ZUGFeRD / Factur-X PDF, raw\nbody or multipart file part, at most 20 MB. `target_syntax` is required (`ubl`\nor `cii`). `target_flavor` (`en16931` or `xrechnung`) is optional; without it\nthe flavor of the source is kept. invowerk checks the converted XML before\nanswering and never returns an invalid document. The answer is\n`application/xml`; `?format=json` returns `{xml, syntax, flavor,\nself_validation}`. Errors: 422 when the input cannot be read, with an error code\nat the start of `detail`; 500 when the converted XML fails the check (the\ncredits are refunded). Costs 3 credits.\n\n**Credits:** 3 per call.","operationId":"convert_invoice_v1_convert_post","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"target_syntax","in":"query","required":true,"schema":{"$ref":"#/components/schemas/Syntax","description":"The XML syntax to convert to: 'cii' or 'ubl'."},"description":"The XML syntax to convert to: 'cii' or 'ubl'."},{"name":"target_flavor","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/Flavor"},{"type":"null"}],"description":"Optional rule set of the result: 'en16931' or 'xrechnung'. Without it the flavor of the source is kept.","title":"Target Flavor"},"description":"Optional rule set of the result: 'en16931' or 'xrechnung'. Without it the flavor of the source is kept."},{"name":"format","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"'json' returns {xml, syntax, flavor, self_validation}; omitted returns raw application/xml.","title":"Format"},"description":"'json' returns {xml, syntax, flavor, self_validation}; omitted returns raw application/xml."}],"responses":{"200":{"description":"The converted XML (default) or the JSON object (?format=json).","content":{"application/json":{"schema":{}},"application/xml":{}}},"500":{"description":"The converted XML failed invowerk's own check. No document is returned and the credits are refunded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Validation Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-credits-cost":3}},"/v1/generate":{"post":{"tags":["Generation"],"summary":"Create an e-invoice from JSON","description":"Create an EN 16931 e-invoice from JSON.\n\nThe JSON body is keyed on EN 16931 Business Terms (BT-*). `syntax` selects UBL\n(default) or CII. `flavor` selects plain EN 16931 (default) or XRechnung, which\nrequires `buyer_reference` (BT-10, the Leitweg-ID). invowerk writes your\namounts as given. It does not compute or correct them. Before answering,\ninvowerk checks the generated XML and never returns an invalid document. The\nanswer is `application/xml`; `?format=json` returns\n`{xml, syntax, flavor, self_validation}`. Errors: 422 for invalid input, with\ndetails per field; 500 when the generated XML fails the check (the credits are\nrefunded). Costs 5 credits.\n\n**Credits:** 5 per call.","operationId":"generate_invoice_v1_generate_post","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"format","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"'json' returns {xml, syntax, flavor, self_validation}; omitted returns raw application/xml.","title":"Format"},"description":"'json' returns {xml, syntax, flavor, self_validation}; omitted returns raw application/xml."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateRequest"}}}},"responses":{"200":{"description":"The generated XML (default) or the JSON object (?format=json).","content":{"application/json":{"schema":{}},"application/xml":{}}},"500":{"description":"The generated XML failed invowerk's own check. No document is returned and the credits are refunded.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Validation Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-credits-cost":5}},"/v1/explain":{"get":{"tags":["Rules"],"summary":"Explain an error code","description":"Explain rule codes and invowerk's own `IW-*` Hinweise in German or English.\n\nFor each code the answer has the title, what the rule requires, common causes,\nhow to fix the invoice, the affected Business Terms and `explain_url`, the path\nof the German page under `/codes/`. The codes appear in `findings` and `hints`\nof `POST /v1/validate`. If any code has no explanation, the answer is HTTP 404\nand names those codes. Costs 0 credits; an API key is not needed and does not\nraise the rate limit.\n\n**Credits:** free. This endpoint is not metered.","operationId":"explain_v1_explain_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"code","in":"query","required":true,"schema":{"type":"array","items":{"type":"string"},"minItems":1,"description":"One or more codes; repeat the parameter: ?code=BR-DE-21&code=IW-IBAN.","title":"Code"},"description":"One or more codes; repeat the parameter: ?code=BR-DE-21&code=IW-IBAN."},{"name":"lang","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Language of the explanation, `de` or `en`. Without it, the Accept-Language header decides, otherwise German.","title":"Lang"},"description":"Language of the explanation, `de` or `en`. Without it, the Accept-Language header decides, otherwise German."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExplainResponse"}}}},"422":{"description":"Validation Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-credits-cost":0}},"/v1/render":{"post":{"tags":["Rendering"],"summary":"Render an e-invoice as HTML","description":"Render an XML e-invoice as a readable HTML page.\n\nSend an XML invoice (UBL or CII, e.g. XRechnung) as the raw request body or as\na multipart `file` part. PDFs are not accepted. invowerk renders it with the\nKoSIT XRechnung visualization and answers with `text/html`; `?format=json`\nreturns `{html, lang, flavor, syntax}` instead. `lang` sets the label language\n(`de` or `en`; otherwise `Accept-Language`, then `de`). Errors: 400 for an\nempty body, 415 for a file that is not an XML invoice, 422 for malformed XML or\na DOCTYPE. Costs 1 credit.\n\n**Credits:** 1 per call.","operationId":"render_invoice_v1_render_post","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"lang","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Label language, 'de' or 'en'. Default: Accept-Language, then 'de'.","title":"Lang"},"description":"Label language, 'de' or 'en'. Default: Accept-Language, then 'de'."},{"name":"format","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"'json' returns {html, lang, flavor, syntax}; omitted returns raw text/html.","title":"Format"},"description":"'json' returns {html, lang, flavor, syntax}; omitted returns raw text/html."}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_render_invoice_v1_render_post"}}}},"responses":{"200":{"description":"The rendered HTML (default) or the JSON object (?format=json).","content":{"application/json":{"schema":{}},"text/html":{}}},"422":{"description":"Validation Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-credits-cost":1}},"/v1/validate":{"post":{"tags":["Validation"],"summary":"Check an e-invoice","description":"Check an e-invoice against EN 16931 and the German rules.\n\nSend an XML invoice (UBL or CII, e.g. XRechnung) or a ZUGFeRD / Factur-X PDF as\nthe raw request body or as a multipart file part, at most 20 MB. A PDF may have\nat most 500 pages and 16 attachments. invowerk detects the format from the\nbytes, not from the Content-Type. A larger body gets HTTP 413. Otherwise the\nanswer is always HTTP 200, because a failed check is a result, not an error.\n`valid` is the result, `findings` lists each problem, `e_rechnung_de` maps the\nresult onto the BMF categories and `evidence` identifies the checked file.\n`hints` are extra observations that never change `valid`. For XRechnung the\nKoSIT validator decides `valid`. If it is unreachable, invowerk's own check\nwith the same rules decides, `verdict_source` is `local` and the\n`X-EInvoice-Degraded` header is set (`official-lane-unavailable`;\n`pdfa-lane-unavailable` when the PDF/A check did not answer; comma-separated).\n`disagreement` is true when both checks ran and differ. For a PDF,\n`pdfa_verdict` is the PDF/A check with veraPDF. `?explain=true` adds the\nexplanation for rules that have one, in `lang` (`de` or `en`). Costs 1 credit.\n\n**Credits:** 1 per call.","operationId":"validate_v1_validate_post","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"explain","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Explain"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","default":"de","title":"Lang"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}},"422":{"description":"Validation Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"x-credits-cost":1}}},"components":{"schemas":{"Body_render_invoice_v1_render_post":{"properties":{"file":{"anyOf":[{"type":"string","contentMediaType":"application/octet-stream"},{"type":"null"}],"title":"File","description":"The invoice XML as a multipart file part."}},"type":"object","title":"Body_render_invoice_v1_render_post"},"Buyer":{"properties":{"name":{"type":"string","title":"Name","description":"Buyer name (BT-44)."},"address":{"$ref":"#/components/schemas/PostalAddress","description":"Buyer postal address (BG-8)."},"electronic_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Electronic Address","description":"Buyer electronic address (BT-49)."}},"type":"object","required":["name","address"],"title":"Buyer","description":"The buyer (BG-7)."},"ContentClass":{"properties":{"status":{"type":"string","title":"Status","description":"Always 'not_machine_checkable'.","default":"not_machine_checkable"},"note":{"type":"string","title":"Note","description":"Fixed note: a format check cannot judge whether the content is correct."}},"type":"object","required":["note"],"title":"ContentClass","description":"Reminder that the content of an invoice cannot be checked by machine.\n\nIt never contains findings. A clean result means the invoice is well-formed\nand follows the rules. It does not mean that prices, amounts or the\ndelivered service are correct."},"CreditsInfo":{"properties":{"balance":{"type":"integer","title":"Balance"},"granted":{"type":"integer","title":"Granted"},"period_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period End"}},"type":"object","required":["balance","granted"],"title":"CreditsInfo","description":"Your credit balance for the current billing period. `granted` is what\nyour plan included, `balance` what is still unspent, and `period_end` the\ndate (ISO 8601) your allowance refills. Present only on plans that are\npriced in credits."},"DocumentTotals":{"properties":{"line_total":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"}],"title":"Line Total","description":"Sum of the line net amounts (BT-106)."},"tax_exclusive":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"}],"title":"Tax Exclusive","description":"Invoice total without VAT (BT-109)."},"tax_inclusive":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"}],"title":"Tax Inclusive","description":"Invoice total with VAT (BT-112)."},"payable":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Payable","description":"Amount due for payment (BT-115). Defaults to the total with VAT."}},"type":"object","required":["line_total","tax_exclusive","tax_inclusive"],"title":"DocumentTotals","description":"The document totals (BG-22)."},"ERechnungDe":{"properties":{"status":{"type":"string","title":"Status","description":"'e_rechnung' (no errors), 'e_rechnung_mit_fehlern' (rule errors), 'keine_e_rechnung' (not a structured e-invoice) or 'nicht_pruefbar' (the file could not be checked)."},"reason":{"type":"string","title":"Reason","description":"Why this status applies, in German, naming the finding."},"basis":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Basis","description":"The BMF letter or UStAE passage for the category; null for 'nicht_pruefbar'."},"note":{"type":"string","title":"Note","description":"Fixed German note, the same on every answer: invowerk checks the technical format, not whether content and amounts are correct or what tax consequences an error has."}},"type":"object","required":["status","reason","note"],"title":"ERechnungDe","description":"The result mapped onto the categories of the BMF letter of 15.10.2025\n(Germany).\n\nIt describes the format check only. It is not a tax assessment (see\n``note``)."},"ErrorClasses":{"properties":{"format":{"items":{"$ref":"#/components/schemas/Finding"},"type":"array","title":"Format","description":"Problems with the file or XML structure: unknown format, malformed XML, a forbidden DOCTYPE, XML schema (XSD) errors."},"business_rules":{"items":{"$ref":"#/components/schemas/Finding"},"type":"array","title":"Business Rules","description":"Failed rules of the applied rule set (EN 16931, XRechnung, ZUGFeRD / Factur-X or Peppol BIS)."},"carrier":{"items":{"$ref":"#/components/schemas/Finding"},"type":"array","title":"Carrier","description":"Problems with the PDF of a ZUGFeRD / Factur-X invoice: PDF/A conformance and how the XML is embedded (BR-HYBRID-* rules). Always empty for an XML file."},"content":{"$ref":"#/components/schemas/ContentClass","description":"Always the not_machine_checkable reminder. Never contains findings."}},"type":"object","required":["content"],"title":"ErrorClasses","description":"The findings grouped by where the problem is. ``findings`` has the same\nfindings as one list."},"Evidence":{"properties":{"document_sha256":{"type":"string","title":"Document Sha256","description":"Hex SHA-256 of the exact bytes you sent (compare with `sha256sum <file>`)."},"document_bytes":{"type":"integer","title":"Document Bytes","description":"Size in bytes of what you sent."},"checked_at":{"type":"string","title":"Checked At","description":"UTC time of the check, ISO 8601 to the second, e.g. '2026-09-24T10:15:00Z'."},"validator":{"$ref":"#/components/schemas/ValidatorVersions","description":"The software versions."}},"type":"object","required":["document_sha256","document_bytes","checked_at","validator"],"title":"Evidence","description":"Which file was checked, when, and with which software. Keep it with a\nsaved report: the SHA-256 ties the report to one file."},"ExplainResponse":{"properties":{"lang":{"type":"string","title":"Lang","description":"Language of all explanations: 'de' or 'en'."},"explanations":{"items":{"$ref":"#/components/schemas/RuleExplanation"},"type":"array","title":"Explanations","description":"One explanation per requested code, in request order, duplicates removed."}},"type":"object","required":["lang","explanations"],"title":"ExplainResponse","description":"The answer of GET /v1/explain: one explanation per requested code.\n\nPass several codes with repeated ``?code=`` parameters. If any code is\nunknown, the call returns HTTP 404 and names it; there is no partial\nanswer."},"Finding":{"properties":{"rule_id":{"type":"string","title":"Rule Id","description":"Code of the rule that failed, e.g. 'BR-DE-21', or 'XSD' for a schema error."},"error_class":{"type":"string","title":"Error Class","description":"Where the problem is: 'format' (file or XML structure), 'business_rules' (a rule of the applied rule set) or 'carrier' (the PDF around the XML)."},"severity":{"type":"string","title":"Severity","description":"'fatal' (the invoice fails the check), 'warning' or 'information'."},"xpath":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Xpath","description":"Where the problem is in the XML (an XPath or a schema line), if known."},"message":{"type":"string","title":"Message","description":"The message of the failed rule or check."},"explain_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Explain Url","description":"Path of the German explanation page /codes/<CODE>, if invowerk has one."},"explain":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Explain","description":"Explanation of the rule (meaning, causes, fixes) in the requested language. Set only with ?explain=true and if invowerk has an entry for the code."}},"type":"object","required":["rule_id","error_class","severity","message"],"title":"Finding","description":"One problem found in the invoice.\n\n``error_class`` says where the problem is: in the file or XML structure\n(``format``), in a rule of the applied rule set (``business_rules``) or in\nthe PDF around the invoice data (``carrier``). ``explain_url`` links the\nGerman explanation page for the code. ``explain`` holds the explanation\nitself when you call with ``?explain=true``."},"Flavor":{"type":"string","enum":["en16931","xrechnung"],"title":"Flavor","description":"The rule set the invoice follows: plain EN 16931, or XRechnung (German rules)."},"GenerateRequest":{"properties":{"syntax":{"$ref":"#/components/schemas/Syntax","description":"XML syntax of the invoice: 'ubl' or 'cii'.","default":"ubl"},"flavor":{"$ref":"#/components/schemas/Flavor","description":"Rule set: 'en16931' (plain EN 16931) or 'xrechnung' (German rules).","default":"en16931"},"invoice_number":{"type":"string","title":"Invoice Number","description":"Invoice number (BT-1)."},"issue_date":{"type":"string","title":"Issue Date","description":"Issue date, 'YYYY-MM-DD' (BT-2)."},"currency":{"type":"string","maxLength":3,"minLength":3,"title":"Currency","description":"Currency code, ISO 4217, e.g. 'EUR' (BT-5).","default":"EUR"},"invoice_type_code":{"type":"string","title":"Invoice Type Code","description":"Invoice type code from UNTDID 1001; '380' is a commercial invoice (BT-3).","default":"380"},"buyer_reference":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Buyer Reference","description":"Buyer reference, in Germany often the Leitweg-ID (BT-10). Required for flavor 'xrechnung' (BR-DE-15), optional for plain EN 16931."},"due_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Due Date","description":"Payment due date, 'YYYY-MM-DD' (BT-9)."},"payment_iban":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payment Iban","description":"IBAN of the payee account for a bank transfer (BT-84)."},"seller":{"$ref":"#/components/schemas/Seller"},"buyer":{"$ref":"#/components/schemas/Buyer"},"lines":{"items":{"$ref":"#/components/schemas/InvoiceLine"},"type":"array","minItems":1,"title":"Lines","description":"One or more invoice lines (BG-25)."},"tax_breakdown":{"items":{"$ref":"#/components/schemas/TaxBreakdown"},"type":"array","minItems":1,"title":"Tax Breakdown","description":"One or more VAT breakdowns, one per VAT category and rate (BG-23)."},"totals":{"$ref":"#/components/schemas/DocumentTotals"}},"additionalProperties":false,"type":"object","required":["invoice_number","issue_date","seller","buyer","lines","tax_breakdown","totals"],"title":"GenerateRequest","description":"The request body of POST /v1/generate: an EN 16931 invoice, keyed on\nBusiness Terms (BT-*).\n\nAll amounts are your own figures. invowerk writes them into the XML and\nchecks the result against EN 16931 (and XRechnung, if selected). It does not\ncompute or correct them."},"HintInfo":{"properties":{"code":{"type":"string","title":"Code","description":"The hint code, e.g. 'IW-IBAN'."},"severity":{"type":"string","title":"Severity","description":"'warning' or 'information'. A hint is never fatal."},"message":{"type":"string","title":"Message","description":"The observation, in the requested language."},"bt_refs":{"items":{"type":"string"},"type":"array","title":"Bt Refs","description":"The EN 16931 Business Terms the hint is about."},"explain_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Explain Url","description":"Path of the German page /codes/<CODE> that explains the hint."}},"type":"object","required":["code","severity","message"],"title":"HintInfo","description":"One hint: an extra observation by invowerk. Hints never change the result."},"InvoiceLine":{"properties":{"name":{"type":"string","title":"Name","description":"Item name (BT-153)."},"net_price":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"}],"title":"Net Price","description":"Net price per unit (BT-146)."},"quantity":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"}],"title":"Quantity","description":"Invoiced quantity (BT-129)."},"unit_code":{"type":"string","title":"Unit Code","description":"Unit code from UN/ECE Recommendation 20; 'C62' means 'one' (BT-130).","default":"C62"},"line_net_amount":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"}],"title":"Line Net Amount","description":"Line net amount, quantity × net price, as you state it (BT-131)."},"tax_category":{"type":"string","title":"Tax Category","description":"VAT category code of the line, e.g. 'S' for standard rate (BT-151).","default":"S"},"tax_rate":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"}],"title":"Tax Rate","description":"VAT rate of the line in percent, e.g. 19.00 (BT-152).","default":"19.00"}},"type":"object","required":["name","net_price","quantity","line_net_amount"],"title":"InvoiceLine","description":"One invoice line (BG-25)."},"MeResponse":{"properties":{"tier":{"type":"string","title":"Tier","description":"The plan this request is served on."},"is_keyed":{"type":"boolean","title":"Is Keyed","description":"Whether the request carried a valid API key. Without an `X-API-Key`, the call runs anonymously at the rate limit for calls without a key."},"rate_limit":{"$ref":"#/components/schemas/RateLimitInfo"},"credits":{"anyOf":[{"$ref":"#/components/schemas/CreditsInfo"},{"type":"null"}],"description":"Null on plans that are not priced in credits."},"features":{"items":{"type":"string"},"type":"array","title":"Features","description":"The features your plan includes."}},"type":"object","required":["tier","is_keyed","rate_limit","features"],"title":"MeResponse","description":"The `GET /v1/me` payload: who the request is authenticated as, what is\nleft of your request and credit allowances, and which features your plan\nincludes."},"ParseDetection":{"properties":{"syntax":{"type":"string","title":"Syntax","description":"Syntax of the source document: 'ubl' or 'cii'."},"flavor":{"type":"string","title":"Flavor","description":"Rule set of the source, read from its CustomizationID: 'xrechnung', 'peppol_bis', 'factur_x', 'en16931' or 'unknown'."},"customization_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Customization Id","description":"The CustomizationID (specification identifier, BT-24) of the source, if any."}},"type":"object","required":["syntax","flavor","customization_id"],"title":"ParseDetection","description":"What invowerk detected about the source document, from its bytes."},"ParseResponse":{"properties":{"model":{"additionalProperties":true,"type":"object","title":"Model","description":"The invoice as JSON keyed on Business Terms. It has the schema of the POST /v1/generate request body (GenerateRequest), so you can edit it and create the invoice again."},"detection":{"$ref":"#/components/schemas/ParseDetection","description":"What invowerk detected: syntax, rule set and CustomizationID."},"source":{"type":"string","title":"Source","description":"Where the XML came from: 'xml' (you sent XML) or 'pdf-embedded' (taken from a ZUGFeRD / Factur-X PDF)."}},"type":"object","required":["model","detection","source"],"title":"ParseResponse","description":"The answer of POST /v1/parse: the invoice as JSON and what invowerk detected."},"PostalAddress":{"properties":{"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City","description":"City (BT-37 seller, BT-52 buyer)."},"post_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Post Code","description":"Post code (BT-38 seller, BT-53 buyer)."},"country_code":{"type":"string","maxLength":2,"minLength":2,"title":"Country Code","description":"Country code, ISO 3166-1 alpha-2, e.g. 'DE' (BT-40 seller, BT-55 buyer)."}},"type":"object","required":["country_code"],"title":"PostalAddress","description":"A postal address (BG-5 seller, BG-8 buyer).\n\nEN 16931 requires only the country. XRechnung also requires city and post\ncode for the seller. invowerk does not check that the address exists."},"RateLimitInfo":{"properties":{"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit"},"remaining":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Remaining"},"reset":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Reset"}},"type":"object","title":"RateLimitInfo","description":"How many requests you may still make in the current window. These are the\nsame numbers as the `X-RateLimit-*` response headers. `limit` is the size of the\nwindow, `remaining` what is left of it, and `reset` how many seconds until\nit refills (not a timestamp). All three are `null` in the rare case the\ncounter cannot be read; treat that as \"unknown\", not zero."},"RuleExplanation":{"properties":{"code":{"type":"string","title":"Code","description":"The rule code, e.g. 'BR-DE-21'."},"lang":{"type":"string","title":"Lang","description":"Language of the explanation: 'de' or 'en'."},"severity":{"type":"string","title":"Severity","description":"Severity of the rule: 'fatal', 'warning' or 'information'."},"standard":{"type":"string","title":"Standard","description":"Source of the rule: 'EN16931', 'XRechnung', 'ZUGFeRD' or 'invowerk' (IW-* hints)."},"bt_refs":{"items":{"type":"string"},"type":"array","title":"Bt Refs","description":"The EN 16931 Business Terms the rule is about, e.g. 'BT-10'."},"title":{"type":"string","title":"Title","description":"Short title of the rule."},"meaning":{"type":"string","title":"Meaning","description":"What the rule requires."},"causes":{"items":{"type":"string"},"type":"array","title":"Causes","description":"Common reasons why the rule fails."},"fixes":{"items":{"type":"string"},"type":"array","title":"Fixes","description":"How to fix the invoice data."},"xpath_hints":{"items":{"type":"string"},"type":"array","title":"Xpath Hints","description":"XPaths of the fields the rule checks."},"explain_url":{"type":"string","title":"Explain Url","description":"Path of the German explanation page /codes/<CODE>."}},"type":"object","required":["code","lang","severity","standard","bt_refs","title","meaning","causes","fixes","xpath_hints","explain_url"],"title":"RuleExplanation","description":"The explanation of one rule code in the requested language.\n\nIt explains the format rule and how to fix the invoice data. It is not tax\nadvice. ``explain_url`` links the German page for the code."},"ScenarioInfo":{"properties":{"config":{"type":"string","title":"Config","description":"'kosit-xrechnung' (the KoSIT configuration for XRechnung and EN 16931) or 'zugferd' (the FeRD rules for ZUGFeRD / Factur-X)."},"name":{"type":"string","title":"Name","description":"The scenario name as the configuration states it."}},"type":"object","required":["config","name"],"title":"ScenarioInfo","description":"The rule set that was applied: its configuration and scenario."},"Seller":{"properties":{"name":{"type":"string","title":"Name","description":"Seller name, the registered name (BT-27)."},"address":{"$ref":"#/components/schemas/PostalAddress","description":"Seller postal address (BG-5)."},"vat_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vat Id","description":"Seller VAT ID, e.g. 'DE123456789' (BT-31). Needed when a line has VAT category 'S' (BR-S-02)."},"contact_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact Name","description":"Seller contact name; required for XRechnung (BT-41)."},"contact_phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact Phone","description":"Seller contact phone; required for XRechnung (BT-42)."},"contact_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact Email","description":"Seller contact email; required for XRechnung (BT-43)."},"electronic_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Electronic Address","description":"Seller electronic address, e.g. an email address (BT-34)."}},"type":"object","required":["name","address"],"title":"Seller","description":"The seller (BG-4)."},"Syntax":{"type":"string","enum":["cii","ubl"],"title":"Syntax","description":"The XML syntax of the invoice: UBL or CII."},"TaxBreakdown":{"properties":{"taxable_amount":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"}],"title":"Taxable Amount","description":"Taxable amount of the category (BT-116)."},"tax_amount":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"}],"title":"Tax Amount","description":"VAT amount of the category (BT-117)."},"category":{"type":"string","title":"Category","description":"VAT category code, e.g. 'S' for standard rate (BT-118).","default":"S"},"rate":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"}],"title":"Rate","description":"VAT rate of the category in percent (BT-119).","default":"19.00"}},"type":"object","required":["taxable_amount","tax_amount"],"title":"TaxBreakdown","description":"One VAT breakdown: the totals for one VAT category and rate (BG-23)."},"ValidationResponse":{"properties":{"valid":{"type":"boolean","title":"Valid","description":"The overall result. For the XML, the KoSIT validator decides when it answered (verdict_source 'official'); otherwise invowerk's own check decides (no fatal finding). A fatal problem with the PDF of a ZUGFeRD / Factur-X invoice always makes it false."},"verdict_source":{"type":"string","title":"Verdict Source","description":"'official' when the KoSIT validator decided the XML result, 'local' when invowerk's own check did (ZUGFeRD or Peppol rules, or KoSIT did not answer)."},"local_verdict":{"type":"string","title":"Local Verdict","description":"invowerk's own result, 'valid' or 'invalid': 'invalid' when any format, business rule or PDF finding is fatal."},"disagreement":{"type":"boolean","title":"Disagreement","description":"True when the KoSIT validator and invowerk's own check reach different results for the XML. The KoSIT result decides; the findings explain the difference."},"lane":{"type":"string","title":"Lane","description":"'official' when invowerk asked the KoSIT validator (even if it did not answer), else 'local'."},"official_verdict":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Official Verdict","description":"The KoSIT validator's result: 'valid', 'invalid' or 'unavailable' (it did not answer). Null when it was not asked, e.g. for ZUGFeRD or Peppol."},"scenario":{"anyOf":[{"$ref":"#/components/schemas/ScenarioInfo"},{"type":"null"}],"description":"The rule set that was applied, or null when no rule set matched."},"pdfa_verdict":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pdfa Verdict","description":"PDF/A check of a ZUGFeRD / Factur-X PDF with veraPDF: 'valid', 'invalid' or 'unavailable'. Null when not checked (always for XML). Null does not mean the PDF is fine."},"detection":{"additionalProperties":true,"type":"object","title":"Detection","description":"What invowerk detected from the bytes: kind, syntax, flavor, customization_id, is_hybrid_pdf. For a PDF it describes the embedded XML."},"errors":{"$ref":"#/components/schemas/ErrorClasses","description":"The findings grouped by where the problem is."},"findings":{"items":{"$ref":"#/components/schemas/Finding"},"type":"array","title":"Findings","description":"All format, business rule and PDF findings as one ordered list."},"rulesets":{"additionalProperties":{"type":"string"},"type":"object","title":"Rulesets","description":"The rule set versions used for this check, as {name: version}."},"evidence":{"$ref":"#/components/schemas/Evidence","description":"SHA-256 and size of the file, time of the check, software versions."},"e_rechnung_de":{"$ref":"#/components/schemas/ERechnungDe","description":"The result mapped onto the e-invoice categories of the German BMF. Describes the format only, not a tax assessment."},"hints":{"items":{"$ref":"#/components/schemas/HintInfo"},"type":"array","title":"Hints","description":"Extra observations by invowerk (IW-* codes), e.g. a wrong IBAN check digit. They never change valid, verdict_source or e_rechnung_de."}},"type":"object","required":["valid","verdict_source","local_verdict","disagreement","lane","detection","errors","evidence","e_rechnung_de"],"title":"ValidationResponse","description":"The result of POST /v1/validate. Always HTTP 200: a failed check is data,\nnot an error."},"ValidatorVersions":{"properties":{"invowerk":{"type":"string","title":"Invowerk","description":"The invowerk version, or 'unknown'."},"appkit":{"type":"string","title":"Appkit","description":"The version of the platform invowerk runs on, or 'unknown'."}},"type":"object","required":["invowerk","appkit"],"title":"ValidatorVersions","description":"The software versions that produced the result."},"Problem":{"description":"The RFC 9457 error body. Every error response uses it.","properties":{"type":{"default":"about:blank","description":"Problem type URI (RFC 9457).","title":"Type","type":"string"},"title":{"description":"Short human-readable summary of the status.","title":"Title","type":"string"},"status":{"description":"The HTTP status code, repeated in the body.","title":"Status","type":"integer"},"detail":{"description":"What went wrong with this request.","title":"Detail","type":"string"},"instance":{"description":"The request path that produced the error.","title":"Instance","type":"string"},"code":{"description":"Stable machine-readable error code. Branch on this, not on the text.","title":"Code","type":"string"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Correlation id for this request; quote it when asking for support.","title":"Request Id"},"errors":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"default":null,"description":"Per-field validation failures. Present on 422 only.","title":"Errors"},"upgrade_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Where to add credits or move to a larger plan. Present on 402/403/429.","title":"Upgrade Url"}},"required":["title","status","detail","instance","code"],"title":"Problem","type":"object"}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}}},"tags":[{"name":"Transform"},{"name":"Generation"},{"name":"Rules"},{"name":"Rendering"},{"name":"Validation"},{"name":"Account","description":"Check your plan, your remaining requests and credits, and what your plan includes. `GET /v1/me` is always free."}]}