API: Erste Rechnung erstellen und als PDF herunterladen

Eine Rechnung über die lokale Automatisierungs-API

Diese Anleitung verwendet HTTP-Aufrufe der API, nicht die manuelle Rechnungserstellung. Voraussetzungen: Premium, laufende Billance-Desktop-App, aktivierte lokale API und ein vollständig eingerichtetes aktives Firmenprofil. Die Beispiele sind für Bash, cURL und Python 3. Sie erstellen echte lokale Entwürfe. Nutze für das Ausprobieren ein eigenes Testprofil und eindeutige Rechnungsnummern.

1. Verbindung über die API prüfen

Übernimm die angezeigte Basis-URL, falls du einen anderen Port nutzt. Gib den Token verdeckt ein; speichere ihn nicht in Skripten oder Git.

BASE_URL="http://127.0.0.1:47115/api/integration/v1"
read -r -s -p "Billance API token: " BILLANCE_API_TOKEN
printf '\n'
export BILLANCE_API_TOKEN
curl --fail-with-body -sS -H "Authorization: Bearer $BILLANCE_API_TOKEN" "$BASE_URL/health"

Erwartet: HTTP 200 mit status: "ok". Die Antwort enthält außerdem apiVersion, appVersion und capabilities. Ohne gültigen Token liefert auch /health HTTP 401.

2. Einen Entwurf über die API anlegen

Die einfache API übernimmt Verkäuferangaben aus dem aktiven Firmenprofil. Einzelpreise sind netto. Das Beispiel ergibt 100 EUR netto und 119 EUR brutto.

NUMBER="API-$(date +%Y%m%d-%H%M%S)"
DATE="$(date +%Y-%m-%d)"
CREATE_KEY="create-$NUMBER"
cat > invoice-request.json <<JSON
{
  "invoiceNumber": "$NUMBER",
  "invoiceDate": "$DATE",
  "paymentDueDays": 14,
  "currency": "EUR",
  "outputMode": "pdf",
  "recipient": {
    "name": "ACME GmbH", "street": "Kundenweg 2",
    "postcode": "20095", "city": "Hamburg", "country": "DE"
  },
  "items": [{"name": "Beratung", "quantity": 1, "unit": "HUR", "unitPrice": 100, "taxPercent": 19}]
}
JSON
curl --fail-with-body -sS -X POST "$BASE_URL/invoices/simple" \
  -H "Authorization: Bearer $BILLANCE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $CREATE_KEY" \
  --data-binary @invoice-request.json > invoice-response.json
INVOICE_ID="$(python3 -c 'import json; print(json.load(open("invoice-response.json"))["id"])')"

Erwartet: HTTP 201. invoice-response.json enthält unter anderem id, status: "draft", grandTotal: 119, currency: "EUR" und die normalisierten formData. Die Antwort hat mehr Felder als diese Übersicht. Bei einem Fehler nicht mit den nächsten Schritten fortfahren. Für eine Wiederholung nach einem Timeout bleiben Datei und CREATE_KEY unverändert; nicht das ganze Skript erneut starten.

3. PDF über die API herunterladen

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

Erwartet: HTTP 200 mit Content-Type: application/pdf. Die API erzeugt für diesen Download ein neues PDF und räumt ihre temporären Exportdateien auf. invoice.pdf ist deine heruntergeladene Kopie. Der Entwurf wird dadurch weder finalisiert noch als dauerhaft erzeugtes Dokument gespeichert. Bei einer Fehlerantwort kann die Ausgabedatei Fehler-JSON enthalten; werte deshalb den cURL-Exitcode und HTTP-Status aus.

Optional: Ausgabe dauerhaft in Billance erzeugen

curl --fail-with-body -sS -X POST \
  -H "Authorization: Bearer $BILLANCE_API_TOKEN" \
  -H "Idempotency-Key: generate-$NUMBER" \
  "$BASE_URL/invoices/$INVOICE_ID/generate"

generate nutzt die gespeicherten Ausgabeeinstellungen, speichert den erzeugten Pfad beim Dokument und antwortet mit HTTP 200 und file, xmlFile, invoiceNumber. Das sind lokale Pfade, keine Dateibytes. Auch dieser Aufruf finalisiert nicht. Erst POST /invoices/{id}/finalize löst die Finalisierung gemäß Dokumentart aus.

PDF-Design und vollständige Formulardaten

GET /invoice-designs liefert items mit Design-IDs. Für eine gezielte Auswahl ergänze designTemplateId im äußeren JSON; ohne Auswahl gilt das Standarddesign. Für weitere E-Rechnungsfelder oder andere Dokumentarten nutze POST /invoices mit documentType und formData. Die Feldreferenz und API-Beispiele stehen in Einstellungen → Integrationen → Lokale Automatisierungs-API.