API

API-Dokumentation

Du sendest JSON und bekommst eine Rechnung als PDF zurück. Optional kannst du einen API-Token mitsenden.

Kurz-Überblick

POST /api/invoices erzeugt eine Rechnung und liefert ein PDF zurück.
Ohne API-Token wird ein sichtbarer Hinweis ins PDF gesetzt: "Erstellt mit Zugio (https://zugio.de) – kostenfreie Version"
Mit API-Token wird der Werbehinweis nicht gesetzt.

Hinweis: Das Portal setzt (falls nicht angegeben) automatisch profile_urn = urn:cen.eu:en16931:2017.

Endpoint

Request

POST /api/invoices

Body: application/json

Optional: Authorization: Bearer <API_TOKEN>

Response

200: PDF (Content-Type: application/pdf)
Fehler: JSON ({ error: "..." }) mit passendem HTTP-Status

Hinweis: Das Portal setzt (falls nicht angegeben) automatisch profile_urn = urn:cen.eu:en16931:2017.

Request (cURL)

Vollständiges Beispiel: Datei invoice.json anlegen und danach das PDF erzeugen.

# 1) invoice.json erstellen
cat > invoice.json <<'JSON'
{
  "company": {
    "seller": {
      "name": "Firma GmbH",
  "street": "Musterstraße 1",
      "postcode": "10115",
      "city": "Berlin",
      "country_code": "DE",
      "contact_email": "rechnung@firma.de"
    },
    "defaults": {
      "locale": "de_DE",
      "currency": "EUR",
      "unit_code": "C62"
    }
  },
  "invoice": {
    "invoice_number": "RE-2026-0001",
    "issue_date": "2026-01-01",
    "delivery_date": "2026-01-01",
    "buyer": {
      "name": "Kunde AG",
      "street": "Kundenweg 5",
      "postcode": "20095",
      "city": "Hamburg",
      "country_code": "DE",
      "vat_id": "DE123456789"
    },
    "items": [
      {
        "name": "Beratung",
        "quantity": 1,
        "unit_price_net": 100,
        "vat_percent": 19
      }
    ]
  }
}
JSON

# 2) PDF erzeugen (ohne Token: mit sichtbarem Hinweis im PDF)
curl --fail-with-body --silent --show-error   --request POST   --header 'Content-Type: application/json'   --data-binary @invoice.json   --output invoice.pdf   'https://zugio.de/api/invoices'

echo 'OK: invoice.pdf erstellt'

Optional mit API-Token (ohne sichtbaren Werbehinweis im PDF):

curl --fail-with-body --silent --show-error   --request POST   --header 'Content-Type: application/json'   --header 'Authorization: Bearer <API_TOKEN>'   --data-binary @invoice.json   --output invoice.pdf   'https://zugio.de/api/invoices'

Debug-Hinweis: Wenn ein Fehler zurückkommt, entferne --output invoice.pdf und schau dir die JSON-Fehlermeldung an.

Tipp: Für lokale Entwicklung ist die Base URL typischerweise http://localhost:3000.

Payload-Struktur

Der Request besteht (minimal) aus company und invoice. Unten findest du Pflichtfelder und gängige optionale Felder.

Pflichtfelder (Minimal)

company.seller: Name + Adresse (siehe unten)
invoice.invoice_number
invoice.issue_date (YYYY-MM-DD)
invoice.buyer: Name + Adresse
invoice.items: mindestens 1 Position

He4ufig optional

company.defaults (We4hrung, Locale, Unit-Code)
invoice.delivery_date
invoice.notes / invoice.payment_terms
invoice.buyer.vat_id (B2B)
profile_urn, business_process_urn
payment_means (z.B. IBAN)

{
  "company": {
    "seller": {
      "name": "Firma GmbH",
      "street": "Musterstraße 1",
      "postcode": "10115",
      "city": "Berlin",
      "country_code": "DE",
      "contact_email": "rechnung@firma.de"
    },
    "defaults": {
      "locale": "de_DE",
      "currency": "EUR",
      "unit_code": "C62"
    }
  },
  "invoice": {
    "invoice_number": "RE-2026-0001",
    "issue_date": "2026-01-01",
    "delivery_date": "2026-01-01",
    "buyer": {
      "name": "Kunde AG",
      "street": "Kundenweg 5",
      "postcode": "20095",
      "city": "Hamburg",
      "country_code": "DE",
      "vat_id": "DE123456789"
    },
    "items": [
      {
        "name": "Beratung",
        "quantity": 1,
        "unit_price_net": 100,
        "vat_percent": 19
      }
    ]
  }
}

Tipp: Die Zahlformate sind echte Zahlen (nicht als String). Dezimalwerte z.B. 19.5.

Felder im Detail

Kurzreferenz ffcr die wichtigsten Felder. Formatangaben gelten ffcr typische Nutzung.

company.seller (Pflicht)

name (string)
street (string)
postcode (string)
city (string)
country_code (ISO-2, z.B. DE)

Optional

contact_email (string)
vat_id / tax_number (string)

invoice.buyer (Pflicht)

name (string)
street, postcode, city
country_code (ISO-2)

Optional

vat_id (B2B)
buyer_reference (v.a. XRechnung)

invoice (Pflicht/Optional)

Pflicht

invoice_number (string)
issue_date (YYYY-MM-DD)

Optional

delivery_date (YYYY-MM-DD)
notes (string)
payment_terms (string)

invoice.items (Pflicht)

Mindestens 1 Position, je Position:

name (string)
quantity (number)
unit_price_net (number)
vat_percent (number, z.B. 19)

Optional

unit_code (z.B. C62)
description (string)

Tipp: Zahlenformate sind echte Zahlen (nicht als String). Dezimalwerte z.B. 19.5.

Profile / Versionen (profile_urn)

Das PDF enthält eine eingebettete XML nach EN16931. Über profile_urn steuerst du, welchen Guideline-Identifier die XML trägt.

EN16931 (Default): urn:cen.eu:en16931:2017
ZUGFeRD 2.1 (EN16931): urn:ferd:invoice:2p1:en16931
Factur‑X 1.0 (EN16931): urn:factur-x.eu:1p0:en16931
XRechnung 3.0 (optional): urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0

Wichtig: Für XRechnung 3.0 sind zusätzliche Pflichtfelder üblich (z.B. business_process_urn, invoice.buyer_reference, invoice.delivery_date, sowie elektronische Adressen und Zahlungsdaten).

{
  "company": { ... },
  "invoice": { ... },
  "profile_urn": "urn:ferd:invoice:2p1:en16931"
}

// XRechnung 3.0 (Beispiel)
{
  "company": { ... },
  "invoice": { ... },
  "profile_urn": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0",
  "business_process_urn": "...",
  "payment_means": { "iban": "..." }
}

API-Token (optional)

Für server-to-server Integrationen kannst du einen API-Token verwenden. Erstelle ihn im eingeloggten Bereich unter Sicherheit.

Ohne Token erhe4ltst du weiterhin ein PDF, jedoch mit sichtbarem Hinweis im Dokument.

Token-Verwaltung

Fehlercodes (Auszug)

400: INVALID_INPUT / INVALID_JSON
401: UNAUTHORIZED
402: INSUFFICIENT_CREDITS
413: REQUEST_TOO_LARGE
502: API_UNREACHABLE / API_ERROR

Hinweis: Wenn du ein PDF erwartest, aber JSON bekommst, entferne beim Debuggen in cURL das --output.