API: Create, export and validate e-invoices

E-invoices through the Local Automation API

This guide specifically covers the API. Premium and the running desktop app are required. Successfully creating a draft does not prove that a valid e-invoice can be generated.

Choose the API output workflow

confirmation and delivery_note only support PDF and JSON. Unsupported export combinations return HTTP 422. PDF designs affect PDF appearance; XML-only exports have no PDF layout.

Supply complete e-invoice data

Load the ZUGFeRD EN 16931 example for POST /invoices in the API tester. Replace sample data with your actual business data: seller/buyer addresses and tax identifiers, quantities, unit codes, tax categories/rates and payment details. Public-sector buyers may require a buyer reference and electronic address.

In complete formData, isEInvoice enables e-invoice generation and _eInvoiceOutputMode selects stored output, for example pdf_zugferd_en16931. The field reference lists the installed version’s supported values. export?format=… overrides output for that download only.

Generation refreshes seller details from the company profile for editable documents. Locked/finalized documents retain their snapshot. Configure the profile as well. A zero-tax item alone does not establish small-business tax treatment: tax regulation and exemption details must match the business case.

XRechnung specifically requires a buyer reference (BT-10), seller/buyer electronic addresses with schemes (BT-34/BT-49), and a seller contact name, phone and email (BT-41/BT-42/BT-43). Configure the seller contact in the company profile or select an appropriate internal contact. ZUGFeRD EN 16931 and XRechnung have different mandatory data; valid ZUGFeRD output does not guarantee a successful XRechnung export.

Export through the API

Using BASE_URL, BILLANCE_API_TOKEN and INVOICE_ID from the API introduction:

curl --fail-with-body -sS \
  -H "Authorization: Bearer $BILLANCE_API_TOKEN" \
  "$BASE_URL/invoices/$INVOICE_ID/export?format=zugferd" \
  --output invoice-zugferd.pdf

Expected: HTTP 200 and PDF bytes. Use an .xml output file for XML exports. Invalid business data may return HTTP 422 with code: "validation_failed" during generation. Inspect errors and correct the data rather than blindly retrying.

Validate or extract through the API

Encode the downloaded file into a request:

python3 - <<'PYTHON'
import base64, json
from pathlib import Path
request = {"fileType": "pdf", "base64Content": base64.b64encode(Path("invoice-zugferd.pdf").read_bytes()).decode()}
Path("validation-request.json").write_text(json.dumps(request))
PYTHON
curl --fail-with-body -sS -X POST "$BASE_URL/import/validate" \
  -H "Authorization: Bearer $BILLANCE_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @validation-request.json

For XML, set fileType: "xml". HTTP 200 means processing completed; inspect isValid, isAcceptable, status and findings. POST /import/einvoice returns validation, documentInfo and invoice instead; invoice can be null. Neither operation creates an outgoing document. There is no daily validation quota; the general HTTP rate limit still applies.