---
title: "API: Create, export and validate e-invoices"
description: "API: Create, export and validate e-invoices. HTTP requests and examples for the local Billance API."
url: "https://billance.de/en/help/help-center/api-e-invoices"
language: "en"
---

# 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

| 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 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:

```json
{
  "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:

```bash
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:

```bash
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.
