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

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.

Ü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.