API-Doku

Vollständige JSON-API für ERP, Warenwirtschaft oder eigene Automatisierungen. Authentifizierung per X-API-Key · EN 16931 konform · optionaler ZUGFeRD-Output.

🔑 Authentifizierung

Jeder Request (außer /health) benötigt den Header X-API-Key: <dein-key>. API-Keys findest du in deinem Dashboard.

X-API-Key: xr_abc123...
Content-Type: application/json

⚡ Rate Limit: 60 Req/Min pro Key TLS empfohlen (nginx / Caddy)

📋 Endpunkte

GET /api/v1/health Ping – kein Auth nötig ▶

Einfacher Liveness-Check. Gibt DB-Status zurück. Ideal für Monitoring.

Antwort:

{ "status": "ok", "db": true }

GET /api/v1/profiles Verfügbare Rechnungsprofile ▶

Liefert alle unterstützten Profile mit Metadaten (Pflichtfelder, Export-Typ).

{ "profiles": ["XRECHNUNG", "B2B_UBL", "ZUGFERD"] }

POST /api/v1/invoices JSON → XRechnung XML (+ optional ZUGFeRD-PDF) ▶

Rechnung als JSON übergeben → valide XML erzeugen (und optional ZUGFeRD-PDF einbetten).

Request-Body:

{
  "profile":          "XRECHNUNG",
  "invoice_number":   "RE-2026-0042",
  "issue_date":       "2026-04-20",
  "due_date":         "2026-05-04",
  "currency":         "EUR",
  "buyer_reference":  "04011000-1234567-89",
  "seller": {
    "name":   "Mustermann IT GmbH",
    "vat_id": "DE123456789",
    "address": { "street":"Musterstraße 12","postal_code":"70173",
                 "city":"Stuttgart","country_code":"DE" }
  },
  "buyer": {
    "name": "Landratsamt Musterhausen",
    "address": { "street":"Rathausplatz 1","postal_code":"70173",
                 "city":"Musterhausen","country_code":"DE" }
  },
  "lines": [{
    "name": "Webentwicklung", "quantity": "12",
    "unit": "HUR", "unit_price": "120.00", "tax_percent": "19"
  }],
  "bank_account": { "iban": "DE89370400440532013000" },
  "include_zugferd": false
}

Erfolgreiche Antwort (200):

{
  "invoice":      { ... },
  "validation":   { "ok": true, "errors": [] },
  "xml_base64":   "PD94bWwgdmVyc2lvbj0iMS4wIi4uLg==",
  "zugferd_base64": null
}

ⓘ unit = UN/CEFACT-Code: HUR Stunde, C62 Stück, KGM kg. Bei XRechnung ist buyer_reference (Leitweg-ID) Pflicht.

POST /api/v1/validate Nur Validierung, keine Ausgabe ▶

Gleicher Body wie /invoices, gibt aber nur das Validierungsergebnis zurück — kein XML, kein PDF.

{
  "ok":     false,
  "errors": [
    { "level": "error", "code": "BR-04",
      "message": "Seller VAT identifier is mandatory." }
  ]
}

POST /api/v1/extract PDF hochladen → Felder extrahieren + XML erzeugen ▶

Schickt eine PDF-Rechnung als multipart/form-data. Der Scanner extrahiert alle erkennbaren Felder und liefert direkt valides XML zurück.

curl -X POST https://rechnung.syypro.com/api/v1/extract \
     -H "X-API-Key: $XR_KEY" \
     -F "file=@rechnung.pdf" \
     -F "profile=ZUGFERD"

Antwort-Felder:

confidence – Erkennungsqualität 0–100
warnings – Felder die unklar waren
checklist – Vollständigkeits-Check mit BT-Codes
xml_base64 – fertige XRechnung/ZUGFeRD XML
zugferd_base64 – ZUGFeRD-PDF (wenn Profil ZUGFERD)

⚠ Fehler-Codes

HTTP	Code	Bedeutung
400	`invalid_body`	JSON fehlerhaft oder Pflichtfelder fehlen
401	`unauthorized`	API-Key fehlt oder ungültig
413	`too_large`	Upload > 16 MB
415	`wrong_type`	Nur PDF erlaubt beim Extract
422	`invalid_invoice`	Rechnung schlägt EN-16931-Validierung fehl
429	`rate_limited`	Mehr als 60 Requests/Minute
503	`api_disabled`	API nicht aktiviert oder kein Key konfiguriert

🧪 API ausprobieren Schritt für Schritt testen

So funktioniert der Tester:
Wähle eine Funktion (Schritt 2), gib deinen API-Key ein (Schritt 1) und klicke auf Anfrage senden. Das Ergebnis erscheint direkt darunter.
→ Einloggen um deinen Key zu verwenden

1 API-Key eingeben

Deinen Key findest du im Dashboard unter "API-Keys". Er beginnt immer mit xr_.

2 Funktion wählen – was möchtest du tun?

Prüft ob die API erreichbar ist. Kein Key nötig. Ideal zum Testen der Verbindung.

2 Anfrage senden