Zum Inhalt springen
Erste Schritte

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

API: E-Rechnungen erstellen, exportieren und prüfen. HTTP-Aufrufe und Beispiele für die lokale Billance-API.

4 Min. LesezeitDesktopZuletzt aktualisiert am 10. November 2026

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-AufrufVerhalten
POST /invoices/simple mit outputMode: "zugferd_en16931"Einfachen Rechnungsentwurf mit ZUGFeRD-Auswahl anlegen
POST /invoices mit vollständigem formDataWeitere Steuer-, Zahlungs- und E-Rechnungsangaben übernehmen
POST /invoices/{id}/generateGespeicherte Ausgabe erzeugen und Dateipfad speichern
GET /invoices/{id}/export?format=zugferdZUGFeRD-PDF für diesen Download erzeugen
GET /invoices/{id}/export?format=xrechnungXRechnung-CII-XML herunterladen
GET /invoices/{id}/export?format=ublXRechnung-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:

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

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:

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.