Create XRechnung and ZUGFeRD files and check e-invoice files from your own software, with a personal access token.
- POST /xrechnung builds an XRechnung 3.0 file (CII syntax, EN 16931), the version XRechnung configuration 3.0.2 covers, and returns it as application/xml.
- POST /zugferd builds a ZUGFeRD 2.x PDF (EN 16931 profile) with the XML embedded and no InkVoice branding on the page.
- POST /check reads a ZUGFeRD or Factur-X PDF, or an XRechnung, CII or UBL XML file, sent as the body itself (application/pdf, application/xml, text/xml, application/octet-stream; other types get 415).
- GET /usage reports the calls counted in the most recent period (the current one while the plan is active), by route. Reading it is not an API call.
- Send an invoice to its recipient, or archive it for you.
- Check a file when it creates it.
- Create credit notes or corrections, several tax rates on one invoice, intra-EU supply (K), export (G), or document-level allowances and charges.
- Give tax or legal advice.
The Developer plan
The Developer plan costs €19 a month and includes 1,000 API calls per period for the workspace. InkVoice is a Kleinunternehmer under § 19 UStG and charges no VAT, so the price is the final price.
- A call that returned a file or a verdict (
acceptorreject) counts, even if you don't read the answer. Refused or failed calls, checks withnot_checkedand reading usage don't count. - Once the included calls are used up, further calls are refused with
api_call_limit_reacheduntil the next period begins. Calls running at the same time can go over the limit. Unused calls lapse at the end of the period, and nothing is charged per call. - When the plan renews, the previous period's unused calls stay usable until InkVoice has received the new period from Stripe, for at most 3 days after the new period begins; a call in that time counts toward both periods.
- There is no free trial.
The workspace's Owner books the plan in the workspace's Settings and pays through Stripe. It is separate from the workspace's plan (Free, Pro or Master): booking, changing, cancelling or ending one doesn't affect the other. Paid plans can be booked only by customers whose registered office, residence or the establishment for which the plan is booked is in Germany.
Your first call
- 1Book the Developer plan
The workspace's Owner books the plan in the workspace's Settings and pays through Stripe.
- 2Create an access token
Create an access token under “Access tokens” with “Read and write”. The token is shown once, when it is created.
- 3Allow it for the API
A token works with the API only after the workspace's Owner turns on “Allow the Developer API” for it under “Access tokens”. No token has it until then.
- 4Send the invoice
Put the invoice request in
invoice.jsonand the token in the environment variableINKVOICE_TOKEN, then send it to/xrechnung. The answer is the XRechnung file. On an error, curl exits with a non-zero code, and the file holds the error's body, if it has one (see Errors);--fail-with-bodyneeds curl 7.76 or later.curl --fail-with-body -X POST https://api.inkvoice.net/api/v1/xrechnung \ -H "Authorization: Bearer $INKVOICE_TOKEN" \ -H "Content-Type: application/json" \ --data @invoice.json -o xrechnung.xml
Routes
Every route is under https://api.inkvoice.net/api/v1. Every call except openapi.json needs a personal access token as Authorization: Bearer inkv_…. A web sign-in isn't accepted, and browsers can't call the API (no CORS). Creating and checking need a token with “Read and write”; a read-only token may read usage only.
| Route | Body | Answer |
|---|---|---|
POST /xrechnung | The invoice request as JSON | The XRechnung file, application/xml |
POST /zugferd | The invoice request as JSON | The ZUGFeRD PDF, application/pdf |
POST /check | The file itself, as application/pdf, application/xml, text/xml or application/octet-stream | What the rule set reported, as JSON |
GET /usage | None | The calls counted in the most recent period, by route, as JSON. Not an API call |
GET /openapi.json | None | The contract, OpenAPI 3.1, readable without a token |
The invoice request
The request is JSON of at most 512 KiB, with number, issueDate, dueDate, currency, taxRate, taxCategoryCode, seller, buyer and lines (dueDate not before the issue date). Seller and buyer each need a name and an email (the electronic address XRechnung requires), and the seller a taxNumber (VAT ID or tax number). taxRate is above 0 for S and 0 for Z, E and AE. taxExemptionReason is required for E and AE and refused for S and Z. For AE, the buyer also needs a VAT ID in taxNumber (BT-48). /xrechnung also requires buyerReference (BT-10) and iban (BR-DE-1), which are optional on /zugferd. An omitted deliveryDate is stated as the issue date. On /check, a body over 8 MiB gets 413 request_too_large, and an XML file, or the XML inside a PDF, over 512 KiB gets 422 e_invoice_file_xml_too_large.
{
"number": "2026-0001",
"issueDate": "2026-11-16",
"dueDate": "2026-11-30",
"currency": "EUR",
"taxRate": 19,
"taxCategoryCode": "S",
"buyerReference": "04011000-1234512345-06",
"iban": "DE02120300000000202051",
"seller": {
"name": "Muster GmbH",
"email": "rechnung@example.com",
"addressLine": "Musterstraße 1",
"postalCode": "10115",
"city": "Berlin",
"country": "DE",
"taxNumber": "DE123456789"
},
"buyer": {
"name": "Beispiel AG",
"email": "eingang@example.com",
"addressLine": "Beispielweg 2",
"postalCode": "20095",
"city": "Hamburg",
"country": "DE"
},
"lines": [
{
"description": "Beratung",
"quantity": 8,
"unitPrice": 95
}
]
}Every member, required and optional, is described in the contract.
What the check reports
The check runs, inside InkVoice, KoSIT's XRechnung configuration (KoSIT rules, XRechnung 3.0.2 (2026-08-31)) and FeRD's ZF_250 rules (ZUGFeRD rules, ZF_250, 1.09.2 (2026-08-04)). When CEN's EN 16931 CII stylesheet also ran, the configuration ends in , EN 16931 CII 1.3.16. It doesn't run the KoSIT Prüftool or Mustang, and doesn't test a PDF's PDF/A conformance. The answer's validator names the rule set and version that judged the file.
The rule sets follow the versions InkVoice pins, and a change of them is announced in openapi.json. This page lists the current versions.
accept or reject says what that rule set reported for the file, with its messages. It doesn't say the invoice meets legal requirements or that a recipient will accept it. not_checked, with a notCheckedReason, means no rule set judged the file.
curl --fail-with-body -X POST https://api.inkvoice.net/api/v1/check \
-H "Authorization: Bearer $INKVOICE_TOKEN" \
-H "Content-Type: application/xml" \
--data-binary @xrechnung.xmlWhat the created files are tested against
Created files aren't checked when they are created. Send one to /check to have it checked; that is an API call. The files are built by the code of InkVoice's free generator: the XML is the free generator's for the same invoice, and the PDF embeds that XML with no branding line. In the free generator's test suite, every scenario in the test tables, pairwise per profile, is accepted by the KoSIT Prüftool 1.6.3 with the XRechnung 3.0.2 configuration (2026-08-31), and by Mustang 2.26.0 as EN 16931 in PDF/A-3b. Both run as separate tools in the tests, not in the API.
The API can't create credit notes or corrections, several tax rates on one invoice, intra-EU supply (K), export (G), or document-level allowances and charges. An invoice has one tax category (S, Z, E or AE) and one rate for all lines. The test suite doesn't cover text in scripts with no bundled font. Amounts are written with two decimals in every currency; for JPY and KWD the suite shows the rule sets accept that, not that it is the currency's minor unit.
Errors
A refusal with a code has the body { error, code, args }; error is fixed English, so match on code.
| Status | Code | Meaning | Counted |
|---|---|---|---|
| 400 | – | The request has mistakes. The body is { errors: [...] }, naming paths such as seller.name. | No |
| 401 | – | No access token, or one that is not accepted. No body. | No |
| 403 | – | The token isn't allowed for the API (“Allow the Developer API”, step 3), or a read-only token called a create or check route. No body. | No |
| 404 | – | The API is switched off, or the route doesn't exist. | No |
| 413 | request_too_large | The body is larger than the route accepts. | No |
| 415 | – | The body has a content type the route does not read. No body. | No |
| 422 | developer_plan_required | The workspace has no active Developer plan. | No |
| 422 | api_call_limit_reached | The included calls are used up. args.included is the included calls, args.date the last UTC day of the period. | No |
| 422 | e_invoice_file_empty, e_invoice_file_encrypted, e_invoice_file_no_invoice_xml, e_invoice_file_not_an_invoice, e_invoice_file_not_xml, e_invoice_file_number_out_of_range, e_invoice_file_older_zugferd, e_invoice_file_several_invoice_xml, e_invoice_file_too_complex, e_invoice_file_too_large, e_invoice_file_unreadable, e_invoice_file_xml_too_large | On /check: the file isn't readable as an invoice. | No |
| 429 | rate_limited | Too many calls. Try again after Retry-After seconds. | No |
| 429 | e_invoice_check_busy | On /check: too many checks at once. Try again after Retry-After seconds. | No |
Limits
The API limits how many calls a token, a workspace and an address may make per minute and at once. Past a limit it answers 429 with Retry-After in seconds, and the call isn't counted. There is no promise of availability, response time or throughput.
Contract and versions
The contract is OpenAPI 3.1 at https://api.inkvoice.net/api/v1/openapi.json, readable without a token. v1 changes only by adding (new optional members, routes or codes); anything else becomes /api/v2.
Terms
The AGB (Ziffer 4a), the annex „Entwickler-API“ (Developer API) of the AVV (data processing agreement) and the Datenschutzerklärung (privacy policy) apply. This page translates the Leistungsbeschreibung (service description) under Ziffer 4a (section 4a) of the AGB (terms and conditions); the German page is binding.
The Developer plan is booked in your workspace's Settings.