API-Dokumentation – ZUGFeRD BT-13 Tool

Überblick

Die API ermöglicht es, das BT-13 (BuyerOrderReference)-Feld nachträglich in den eingebetteten XML-Teil einer ZUGFeRD- oder Factur-X-Rechnung einzufügen — vollständig programmatisch, ohne Browser-Interaktion.

Base URL:

https://zugferd-bt13.cloud

Alle Anfragen werden ausschließlich im Arbeitsspeicher verarbeitet. Es werden keine Dateien gespeichert, keine Daten geloggt, keine IP-Adressen protokolliert. DSGVO-konform.

BT-13 in PDF einfügen

POST

Endpunkt

POST /api/process

Erwartet eine ZUGFeRD- oder Factur-X-PDF und einen BT-13-Wert. Gibt die modifizierte PDF-Datei zurück.

Request — multipart/form-data

Feld	Typ	Pflicht	Beschreibung
pdf	file	Pflicht	ZUGFeRD oder Factur-X PDF-Datei (max. 20 MB)
bt13	string	Pflicht	Bestellnummer des Käufers (IssuerAssignedID), z. B. `4400378488`

Antworten

200 OK Modifizierte PDF — Content-Type: application/pdf

Die fertige Rechnung als Binär-Download. Der Dateiname lautet <originalname>_bt13.pdf.

400 / 422 Validierungsfehler — JSON

Beispiel

{ "error": "Missing field: bt13", "code": "MISSING_BT13" }

429 Rate Limit erreicht — JSON

Beispiel

{ "error": "Rate limit exceeded. Max 30 requests per minute.", "code": "RATE_LIMITED" }

Fehlercodes

Code	HTTP	Bedeutung
MISSING_PDF	400	Kein PDF-Feld im Request
MISSING_BT13	400	Kein bt13-Feld im Request
EMPTY_BT13	400	bt13 ist leer
INVALID_FILE_TYPE	400	Datei ist kein PDF
EMPTY_FILE	400	PDF-Datei ist leer
PROCESSING_ERROR	422	PDF ist kein gültiges ZUGFeRD/Factur-X Dokument
RATE_LIMITED	429	Mehr als 30 Anfragen pro Minute
INTERNAL_ERROR	500	Unerwarteter Server-Fehler

curl-Beispiel

curl -X POST https://zugferd-bt13.cloud/api/process \
  -F "pdf=@rechnung.pdf" \
  -F "bt13=4400378488" \
  --output rechnung_bt13.pdf

Health Check

GET

Endpunkt

GET /api/health

Gibt den aktuellen Status des Service zurück. Ideal für Monitoring und als Verbindungstest in n8n.

Antwort (200 OK)

{
  "status":  "ok",
  "version": "1.3.0",
  "service": "zugferd-bt13-api"
}

n8n-Integration

Die API lässt sich direkt mit einem HTTP Request-Node in n8n ansprechen. Die PDF kommt als Binärdatei zurück und kann direkt in nachfolgende Nodes weitergegeben werden (z. B. per E-Mail versenden, in Google Drive speichern, etc.).

Schritt-für-Schritt

1

HTTP Request Node hinzufügen

Node-Typ HTTP Request in den Workflow ziehen. Methode: POST.

2

URL eintragen

https://zugferd-bt13.cloud/api/process

3

Body-Typ auf „Form-Data (Multipart)" stellen

Im Abschnitt Body → Body Content Type: multipart/form-data wählen.

4

Felder konfigurieren

Parameter hinzufügen:
• pdf — Typ n8n Binary Data, Property Name des vorherigen Nodes (z. B. data)
• bt13 — Typ String, Wert z. B. aus vorherigem Node: {{ $json.bestellnummer }}

5

Response als Binärdatei empfangen

Unter Options → Response: Response Type auf File stellen. Die fertige PDF steht danach als Binary-Property im nächsten Node zur Verfügung.

Beispiel-Workflow (JSON)

Diesen Workflow-JSON direkt in n8n importieren (Workflows → Import from JSON):

{
  "nodes": [
    {
      "name": "BT-13 einfügen",
      "type": "n8n-nodes-base.httpRequest",
      "parameters": {
        "method": "POST",
        "url": "https://zugferd-bt13.cloud/api/process",
        "sendBody": true,
        "contentType": "multipart-form-data",
        "bodyParameters": {
          "parameters": [
            { "name": "pdf",  "value": "={{ $binary.data }}",          "parameterType": "formBinaryData" },
            { "name": "bt13", "value": "={{ $json.bestellnummer }}", "parameterType": "formData" }
          ]
        },
        "options": { "response": { "response": { "responseFormat": "file" } } }
      }
    }
  ]
}