---
title: "API: E-Rechnungen erstellen, exportieren und prüfen"
description: "API: E-Rechnungen erstellen, exportieren und prüfen. HTTP-Aufrufe und Beispiele für die lokale Billance-API."
url: "https://billance.de/de/hilfe/help-center/api-e-rechnungen"
language: "de"
---

# API: E-Rechnungen erstellen, exportieren und prüfen

## E-Rechnungen über die lokale Automatisierungs-API

Diese Anleitung beschreibt ausschließlich die **API**. Premium und eine laufende Desktop-App sind erforderlich. Ein erfolgreicher API-Aufruf zum Anlegen eines Entwurfs bedeutet noch nicht, dass eine gültige E-Rechnung erzeugt werden kann.

## Ausgabeverfahren wählen

| API-Aufruf | Verhalten |
| --- | --- |
| `POST /invoices/simple` mit `outputMode: "zugferd_en16931"` | Einfachen Rechnungsentwurf mit ZUGFeRD-Auswahl anlegen |
| `POST /invoices` mit vollständigem `formData` | Weitere Steuer-, Zahlungs- und E-Rechnungsangaben übernehmen |
| `POST /invoices/{id}/generate` | Gespeicherte Ausgabe erzeugen und Dateipfad speichern |
| `GET /invoices/{id}/export?format=zugferd` | ZUGFeRD-PDF für diesen Download erzeugen |
| `GET /invoices/{id}/export?format=xrechnung` | XRechnung-CII-XML herunterladen |
| `GET /invoices/{id}/export?format=ubl` | XRechnung-UBL-XML herunterladen |

`confirmation` und `delivery_note` unterstützen nur PDF und JSON. Eine unzulässige Exportkombination liefert HTTP 422. PDF-Designs beeinflussen die PDF-Darstellung; reine XML-Exporte haben kein PDF-Layout.

## E-Rechnungsangaben vollständig übergeben

Nutze den API-Testbereich und lade das Beispiel **ZUGFeRD EN 16931** bei `POST /invoices`. Passe es an deine realen Geschäftsdaten an. Wichtig sind Verkäufer-/Empfängeradressen, Steuerkennungen, korrekte Positionsmengen und Einheiten, Steuerkategorie und Steuersatz sowie Zahlungsangaben. Bei öffentlichen Empfängern gehören auch die erforderliche Käuferreferenz und elektronische Adresse dazu.

Im vollständigen `formData` steuert `isEInvoice` die E-Rechnungserzeugung. `_eInvoiceOutputMode` speichert die Ausgabeauswahl, etwa `pdf_zugferd_en16931`. Die unterstützten Werte stehen in der Feldreferenz dieser App-Version. `export?format=…` überschreibt die Ausgabeauswahl nur für diesen Download.

Bei bearbeitbaren Dokumenten aktualisiert die Erzeugung Verkäuferangaben aus dem Firmenprofil. Gesperrte/finalisierte Dokumente verwenden ihren gespeicherten Stand. Richte deshalb auch das aktive Profil korrekt ein. Eine Nullsteuerposition allein macht keine Kleinunternehmerrechnung: Die Steuerregelung und gegebenenfalls Befreiungsangaben müssen zum Geschäftsfall passen.

Für XRechnung verlangt Billance insbesondere eine Käuferreferenz (BT-10), elektronische Adressen samt Schema für Verkäufer und Käufer (BT-34/BT-49) sowie Verkäuferkontakt, Telefon und E-Mail (BT-41/BT-42/BT-43). Hinterlege den Verkäuferkontakt im Firmenprofil oder wähle einen passenden internen Kontakt. ZUGFeRD EN 16931 und XRechnung haben unterschiedliche Pflichtangaben; ein gültiges ZUGFeRD-PDF garantiert deshalb keinen erfolgreichen XRechnung-Export.

## Geleistete Anzahlungen in einer Schlussrechnung abziehen

Verwende `POST /invoices` mit `documentType: "invoice"` und vollständigem `formData`. Der vereinfachte Endpunkt `/invoices/simple` bietet diese Angaben nicht. Die Positionen der Schlussrechnung enthalten den gesamten abzurechnenden Leistungsumfang einschließlich Umsatzsteuer.

Unter `formData.payment` übergibst du:

- `prepaidAmount`: den bereits gezahlten **Bruttogesamtbetrag** (BT-113), einschließlich der unter `downPaymentDeductions` aufgeführten Anzahlungen. Addiere dieselben Anzahlungen nicht doppelt.
- `downPaymentDeductions`: die einzelnen Anzahlungen mit `invoiceNumber`, optional `invoiceDate` und `invoiceId` sowie `taxLines`. Jede Steuerzeile enthält `taxCategory`, `taxRate`, `netAmount` und `taxAmount`.

Beispiel für den `payment`-Teil innerhalb der vollständigen `formData`, kein eigenständiger Request:

```json
{
  "type": "58",
  "prepaidAmount": 1190,
  "downPaymentDeductions": [
    {
      "invoiceNumber": "AR-1001",
      "invoiceDate": "2026-10-01",
      "taxLines": [
        {
          "taxCategory": "S",
          "taxRate": 19,
          "netAmount": 1000,
          "taxAmount": 190
        }
      ]
    }
  ]
}
```

Alle Beträge stehen in der Rechnungswährung. Ergänze für weitere Anzahlungen zusätzliche Abzugseinträge und für verschiedene Steuersätze zusätzliche Steuerzeilen. `invoiceNumber` darf nicht leer sein und `taxLines` muss mindestens eine Steuerzeile enthalten; unvollständige Abzugseinträge werden bei der Ausgabe nicht als Aufschlüsselung übernommen.

Die API lädt anhand von `invoiceId` keine Rechnung nach und berechnet weder die Abzugsdetails noch `prepaidAmount` automatisch. Du musst beide Angaben konsistent liefern. Die Aufschlüsselung allein vermindert den Zahlbetrag nicht. Ohne Rundungsanpassung ergibt sich bei 5.000 EUR netto plus 950 EUR Umsatzsteuer und der Beispielanzahlung ein Restbetrag von 4.760 EUR. Ziehe die Anzahlungen nicht zusätzlich als negative Leistungspositionen ab.

Im PDF werden die Anzahlungen mit Nettobeträgen und Umsatzsteuer einzeln ausgewiesen. In den E-Rechnungsdaten steht die geleistete Bruttosumme in BT-113, die Aufschlüsselung zusätzlich als Rechnungshinweis in BT-22. Eine Betreffzeile wie „Schlussrechnung“ ersetzt diese Zahlungsangaben nicht und ändert für sich allein den Rechnungstypcode nicht.

## Über die API exportieren

Mit `BASE_URL`, `BILLANCE_API_TOKEN` und `INVOICE_ID` aus der API-Einstiegsanleitung:

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

Erwartet: HTTP 200 und PDF-Dateibytes. Bei XML-Exporten verwende eine `.xml`-Ausgabedatei. Fachlich ungültige Daten können bei der Erzeugung HTTP 422 mit `code: "validation_failed"` auslösen. Verarbeite die Fehlermeldung; ändere Daten gezielt statt blind zu wiederholen.

## Ergebnis über die API prüfen oder auslesen

Erzeuge aus der heruntergeladenen Datei einen Base64-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
```

Für XML setze `fileType: "xml"`. HTTP 200 bedeutet, dass die Verarbeitung abgeschlossen wurde; prüfe `isValid`, `isAcceptable`, `status` und die Befunde. `POST /import/einvoice` liefert stattdessen `validation`, `documentInfo` und `invoice`; `invoice` kann `null` sein. Beide API-Aufrufe legen kein Ausgangsdokument an. Es gibt kein tägliches Validierungslimit; das allgemeine HTTP-Rate-Limit gilt weiterhin.
