PPartnerDesk

130 — Public-API (für Tenant-Integratoren)

Aktualisiert am 1. Juni 2026

130 — Public-API (für Tenant-Integratoren)

PartnerDesk bietet eine REST-API, mit der Sie als Tenant Ihre Daten von externen Tools aus lesen und schreiben können — CRM, Reporting, Custom-Dashboards, Zapier/Make.

Base-URL

https://<tenant-slug>.partnerdesk.io/api/v1

Authentifizierung

Jeder Request braucht einen API-Key im Header:

X-API-Key: pdk_abc12345_<your-secret-here>

API-Key erzeugen

Admin → „Einstellungen" → „Sicherheit & API" → „API-Keys" → „Neu erstellen":

  1. Name eingeben (z. B. „CRM-Sync").
  2. Scopes auswählen:
    • read — Lesen aller Endpoints.
    • write — Schreiben (POST/PATCH) — siehe unten.
  3. Klick „Erstellen".
  4. Plain-Key wird einmalig angezeigt — sofort kopieren! Nach Schließen des Dialogs nie wieder lesbar.

Sicherheits-Tipp: API-Key in Ihrer Anwendung als Env-Variable, nicht im Code.

Verfügbare Endpoints

Lesen (read-Scope)

Methode Route Funktion
GET /me API-Key-Info (Name, Scopes, lastUsedAt)
GET /partners Liste mit Pagination + Filter
GET /partners/{partnerId} Detail
GET /customers Liste
GET /transactions Liste mit Date-/Status-Filter

Schreiben (write-Scope erforderlich)

Methode Route Funktion
POST /partners Neuen Partner anlegen
PATCH /partners/{partnerId} Stammdaten ändern

Bei fehlendem Scope: HTTP 403.

Pagination

Zwei Modi:

Klassisch (page / limit)

GET /api/v1/transactions?page=2&limit=50

Response:

{
  "data": [...],
  "pagination": { "page": 2, "limit": 50, "total": 312, "pages": 7 }
}

Cursor (besser für große Datenmengen)

GET /api/v1/transactions?cursor=<uuid-v7>&limit=100

Response:

{
  "data": [...],
  "pagination": { "nextCursor": "<uuid-v7>", "limit": 100 }
}

Cursor-Modus ist stabil bei parallelen Inserts — neue Datensätze verschieben die Pagination nicht.

Filter (Beispiele)

GET /api/v1/transactions?from=2026-05-01&to=2026-05-31&status=approved
GET /api/v1/partners?status=active&groupKey=premium
GET /api/v1/customers?lifetime=true

Rate-Limit

600 Requests/Minute pro API-Key. Bei Überschreitung: HTTP 429 mit Retry-After-Header.

Errors

Strukturiertes JSON-Format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "field": "email"
  }
}

Status-Codes:

  • 200: OK.
  • 201: Created.
  • 400: Validation-Error (Body fehlerhaft).
  • 401: Auth-Fehler (API-Key fehlt/ungültig).
  • 403: Forbidden (Scope reicht nicht).
  • 404: Resource nicht gefunden.
  • 429: Rate-Limit.
  • 500: Server-Fehler.

Beispiel — Curl

curl -H "X-API-Key: pdk_abc12345_xyz789" \
  "https://4leads.partnerdesk.io/api/v1/partners?limit=10"

Beispiel — Python

import requests

API_KEY = "pdk_abc12345_xyz789"
BASE = "https://4leads.partnerdesk.io/api/v1"

response = requests.get(
    f"{BASE}/partners",
    headers={"X-API-Key": API_KEY},
    params={"limit": 50}
)
data = response.json()

Webhooks (umgekehrte Richtung)

Wenn Sie über Events benachrichtigt werden wollen, statt aktiv zu pollen: siehe 131 — Outgoing-Webhooks.

Revoke

Falls ein API-Key kompromittiert ist:

Admin → API-Keys → Eintrag → „Widerrufen". Alle Requests mit diesem Key liefern fortan HTTP 401.

OpenAPI-Spec

Eine vollständige OpenAPI-3.0-Beschreibung steht in der Entwicklungs-/Staging-Umgebung unter /api/doc.json (Swagger-UI unter /api/doc). In Production aus Sicherheitsgründen abgeschaltet.

Verwandte Kapitel

Technische Tiefen-Doku: ../136-public-api.md, ../138-cursor-write-backoff.md, ../031-openapi-swagger.md