---
title: "API: Erste Rechnung erstellen und als PDF herunterladen"
description: "API: Erste Rechnung erstellen und als PDF herunterladen. HTTP-Aufrufe und Beispiele für die lokale Billance-API."
url: "https://billance.de/de/hilfe/help-center/api-erste-rechnung-pdf"
language: "de"
---

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

```bash
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.

```bash
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

```bash
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

```bash
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.
