Invoice API for shops and your own systems

With the BelegDock API, your shop or software issues invoices and corrective invoices without you having to build invoicing software. You send the amounts of the order; BelegDock assigns the invoice number, creates the e-invoice, checks it with the official KoSIT validator, renders the PDF in your design, archives everything and, if you want, sends it by email.

What you get

• Gap-free numbers. Invoices and corrective invoices share one number sequence per year (RE-2026-…). If something fails, no number is used up.
• E-invoices for business customers. Either an XRechnung (UBL) plus a PDF as a readable copy, or a ZUGFeRD PDF (PDF/A-3 with embedded XML, profile EN 16931). Consumers receive the PDF only.
• Validated before a number is assigned. The XML must pass the KoSIT validator before the document gets its number: the XRechnung against the XRechnung rules, the ZUGFeRD XML against the EN 16931 standard. We check the PDF/A-3 container of the ZUGFeRD PDFs in our tests with the Mustang validator.
• Immutable. Issued documents can be neither changed nor deleted; you correct mistakes with a corrective invoice.
• Your design. You set the logo, accent color and a footer of up to six lines in your workspace, not per request.

What a call looks like

curl https://belegdock.io/v1/invoices \
  -H "Authorization: Bearer bd_test_..." \
  -H "Content-Type: application/json" \
  -d @order-1001.json

The response is 202 Accepted with the document in status queued. You poll GET /v1/documents/{id} until the status is issued, sent or delivered, and then download /pdf and, for business customers, /xml.

Rules that keep your integration safe

• Idempotent. external_id is the permanent ID of the order, such as the Shopify order GID. The same ID with the same data returns the same document (200, Idempotent-Replayed: true). The same ID with different data is an error (409), not a second document.
• No tax calculation. BelegDock does not calculate, it checks: the VAT of every line item must match its tax rate to the cent, and the totals per tax rate must be exact. If something does not match, the API answers immediately with 422 and names the field and the rule.
• Error classes. 422 means: change the data. 429 and 5xx mean: retry later with the same external_id.
• Test keys. With bd_test_…, documents get the number TEST-… and are marked as TESTDOKUMENT (test document) in the PDF and XML. They are never sent by email and do not count toward your allowance.

Access and security

Owners create API keys in the workspace under API; this requires two-factor sign-in. BelegDock stores only a hash of the key and shows the key exactly once. Keys can be revoked at any time. A key is valid for exactly one workspace and sees only that workspace's documents.

Documentation

• Interactive API reference
• OpenAPI specification (JSON) for generating clients, also available for download in the workspace under API

What the API does not cover

Version 1 issues invoices for paid orders, in euros, to buyers in Germany, with 19% and 7% VAT. It rejects other currencies and countries, reverse charge, intra-community supplies, OSS, the margin scheme, small businesses under § 19 UStG (Kleinunternehmer), down-payment invoices and invoices to public authorities with a Leitweg-ID. More on the scope page.