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.
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 unterdownPaymentDeductionsaufgeführten Anzahlungen. Addiere dieselben Anzahlungen nicht doppelt.downPaymentDeductions: die einzelnen Anzahlungen mitinvoiceNumber, optionalinvoiceDateundinvoiceIdsowietaxLines. Jede Steuerzeile enthälttaxCategory,taxRate,netAmountundtaxAmount.
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.
Passende Artikel
Lokale Automatisierungs-API verwenden
Rechnungen aus eigener Software erzeugen: die lokale Automatisierungs-API von Billance mit Endpunkten, Token und Beispielen.
Desktop
API: Erste Rechnung erstellen und als PDF herunterladen
API: Erste Rechnung erstellen und als PDF herunterladen. HTTP-Aufrufe und Beispiele für die lokale Billance-API.
Desktop
API: Wiederholungen, Konflikte und Synchronisierung sicher behandeln
API: Wiederholungen, Konflikte und Synchronisierung sicher behandeln. HTTP-Aufrufe und Beispiele für die lokale Billance-API.
Desktop