API: Create, export and validate e-invoices
API: Create, export and validate e-invoices. HTTP requests and examples for the local Billance API.
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
| API operation | Behavior |
|---|---|
POST /invoices/simple, outputMode: "zugferd_en16931" | Create a simple invoice draft with ZUGFeRD selected |
POST /invoices, complete formData | Provide additional tax, payment and e-invoice information |
POST /invoices/{id}/generate | Generate stored output and persist its path |
GET /invoices/{id}/export?format=zugferd | Generate a ZUGFeRD PDF download |
GET /invoices/{id}/export?format=xrechnung | Download XRechnung CII XML |
GET /invoices/{id}/export?format=ubl | Download XRechnung UBL XML |
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.
Deduct paid down payments in a final invoice
Use POST /invoices with documentType: "invoice" and complete formData. The simplified /invoices/simple endpoint does not offer these fields. The final invoice line items contain the full supply being invoiced, including VAT.
Supply the following under formData.payment:
prepaidAmount: the total gross amount already paid (BT-113), including the down payments listed indownPaymentDeductions. Do not add the same payments twice.downPaymentDeductions: the individual down payments withinvoiceNumber, optionalinvoiceDateandinvoiceId, andtaxLines. Each tax line containstaxCategory,taxRate,netAmountandtaxAmount.
Example of the payment part within complete formData, not a standalone request:
{
"type": "58",
"prepaidAmount": 1190,
"downPaymentDeductions": [
{
"invoiceNumber": "AR-1001",
"invoiceDate": "2026-10-01",
"taxLines": [
{
"taxCategory": "S",
"taxRate": 19,
"netAmount": 1000,
"taxAmount": 190
}
]
}
]
}
All amounts use the invoice currency. Add deduction entries for further down payments and tax lines for different VAT rates. invoiceNumber must be nonempty and taxLines must contain at least one tax line; incomplete deduction entries are omitted from the output breakdown.
The API does not fetch an invoice using invoiceId or automatically calculate the deduction details or prepaidAmount. You must supply both consistently. The breakdown alone does not reduce the amount due. Without a rounding adjustment, a total supply of EUR 5,000 net plus EUR 950 VAT and the example down payment leaves EUR 4,760 due. Do not also deduct the down payments as negative line items.
The PDF lists each down payment with its net and VAT amounts. E-invoice data carries the gross amount already paid in BT-113 and the breakdown as an invoice note in BT-22. A subject such as “Final invoice” does not replace these payment fields or change the invoice type code by itself.
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.
Related articles
Use the Local Automation API
Create invoices from your own software: the local Billance automation API with endpoints, tokens and examples.
Desktop
API: Create your first invoice and download its PDF
API: Create your first invoice and download its PDF. HTTP requests and examples for the local Billance API.
Desktop
API: Handle retries, conflicts and synchronization safely
API: Handle retries, conflicts and synchronization safely. HTTP requests and examples for the local Billance API.
Desktop