Authentifizierung

Basis-URL

Alle API-Anfragen verwenden die folgende Basis-URL:

https://api.planni.de/v1

API-Schlüssel

Jede Anfrage muss einen X-Api-Key-Header mit einem gültigen API-Schlüssel enthalten.

curl -H "X-Api-Key: ihr-api-schluessel" https://api.planni.de/v1/contacts

API-Schlüssel werden im planni Admin unter Einstellungen > Integrationen erstellt.

Scopes

Jedem API-Schlüssel können ein oder mehrere Scopes zugewiesen werden:

Ein API-Schlüssel, der ohne Scopes erstellt wird, hat vollen Zugriff. Eine leere Scope-Liste wird beim Erstellen abgelehnt, sodass die Auswahl keiner Berechtigung nie einen Schlüssel mit vollem Zugriff erzeugt.

Pagination

Listen-Endpunkte unterstützen Pagination mit limit und offset:

curl -H "X-Api-Key: ihr-api-schluessel" \
  "https://api.planni.de/v1/contacts?limit=10&offset=20"

Datensatz-IDs

Jeder Datensatz hat eine id. Ihre Form hängt vom Konto ab:

planni stellt jedes Konto einmal auf UUID-Schlüssel um. Ab dann enthalten Antworten den UUID-String in id.

Beide Formen werden als Eingabe akzeptiert. Eine Integer-ID, die Sie vor der Umstellung gespeichert haben, funktioniert danach weiter und liefert denselben Datensatz wie seine UUID: PUT /v1/contacts/42 und PUT /v1/contacts/0192f5a1-7b3c-7d2e-8f00-123456789abc aktualisieren denselben Kontakt. Bestell-IDs waren schon immer UUIDs: Eine Integer-Bestell-ID ergibt 404.

Eine ID, zu der es keinen Datensatz gibt oder die weder eine einfache Ganzzahl noch eine UUID ist (z. B. 007, +42 oder 42.0), ergibt 404 Not Found. Bei PUT /v1/contacts/{id} und GET /v1/orders/{id} wird eine ID mit mehr als 64 Zeichen mit 400 Bad Request abgelehnt, außer einer Bestell-ID nur aus Ziffern, die 404 ergibt.

Empfehlungen:

• Speichern und vergleichen Sie IDs als Strings, dann passen beide Formen.
• Rechnen Sie nicht mit IDs und zerlegen Sie sie nicht.
• Ein Tool, das über id dedupliziert (z. B. ein Zapier-Trigger), sieht jeden bestehenden Datensatz nach der Umstellung einmal unter seiner neuen ID.
• IDs, die bei der Bestellung in die Bestellung übernommen wurden (z. B. das Produkt einer Bestellposition), behalten ihren damaligen Wert.

Fehlerbehandlung

Die API gibt Standard-HTTP-Statuscodes zurück.

Fehlerantworten

{
  "error": "Unauthorized",
  "message": "Missing or invalid API key"
}

Statuscodes

Rate Limiting

Derzeit gibt es keine Rate Limits. Dies kann sich in zukünftigen Versionen ändern.