Skip to content
Getting Started

API: Create, export and validate e-invoices

API: Create, export and validate e-invoices. HTTP requests and examples for the local Billance API.

4 min readDesktopLast updated on November 10, 2026

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 operationBehavior
POST /invoices/simple, outputMode: "zugferd_en16931"Create a simple invoice draft with ZUGFeRD selected
POST /invoices, complete formDataProvide additional tax, payment and e-invoice information
POST /invoices/{id}/generateGenerate stored output and persist its path
GET /invoices/{id}/export?format=zugferdGenerate a ZUGFeRD PDF download
GET /invoices/{id}/export?format=xrechnungDownload XRechnung CII XML
GET /invoices/{id}/export?format=ublDownload 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 in downPaymentDeductions. Do not add the same payments twice.
  • downPaymentDeductions: the individual down payments with invoiceNumber, optional invoiceDate and invoiceId, and taxLines. Each tax line contains taxCategory, taxRate, netAmount and taxAmount.

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.