Start

Ressourcen-Familien

Alle Endpoints liegen unter /v3/*. v3 ist die einzige öffentliche Version. Eine kompakte Methoden-Matrix aller Endpoints steht unter Endpoints↗; die folgende Liste fasst die Familien zusammen, in denen die Ressourcen gruppiert sind:

REST-Modell

Drei klare URL-Muster decken alle Endpoints ab:

1. Top-Level-Ressourcen — Stammdaten wie Kunden, Produktpartner und Benutzer werden über ihre Geschäfts-ID {kid} adressiert. Eigenständige Ressourcen wie Verträge und Dokumente verwenden ihre Datensatz-ID {id}. Das folgende Muster beschreibt die Datenressourcen; Suche, System und Posteingang unterstützen jeweils eigene Methoden:

Welche Methoden eine Ressource tatsächlich unterstützt (manche sind read-only), zeigt die Endpoints-Matrix↗.

2. Parent-scoped Sub-Ressourcen — Drei Parent-Typen halten ihre eigenen Sub-Familien:

Welche {sub}-Sektionen pro Parent existieren:

3. Customer-direkte Subs — Diese Sektionen existieren nur als parent-scoped Sub-Ressourcen, nicht als eigene Top-Level-Route (es gibt kein /v3/addresses/{id}):

addresses · contacts · banking · numbers · identity · jobs · tags · comments · followers · relations

Sie sind logisch Bestandteil des Customer-Datensatzes (1:n-Collections), haben aber Row-IDs für direkten Zugriff am jeweiligen Pfad /v3/customers/{kid}/{sub}/{id}.

Scope-Regel: Der Scope hängt an den Daten, nicht am URL-Pfad. /v3/customers/{kid}/contracts braucht v3:contracts:read|write (nicht customers), /v3/customers/{kid}/damages braucht v3:damages:*, usw. Customer-direkte Subs hingegen laufen über v3:customers:*, weil sie inhaltlich Customer-Felder sind. Volle Tabelle in Scopes↗.

Basis-URL

Alle Endpoints der i-Planner REST API werden gegen den folgenden Host aufgerufen:

https://www.api.i-planner.app

Die vollständige Request-URL setzt sich aus Basis-URL, Versionspräfix und Ressourcenpfad zusammen. <resource> steht dabei für eine der oben gelisteten Ressourcen-Familien↓:

https://www.api.i-planner.app/v3/<resource>

Es gibt keine regionalen oder mandantenspezifischen Subdomains: Tokens sind organisationsgebunden, der Host ist für alle Organisationen identisch.

Sende alle produktiven Requests direkt an die HTTPS-Basis-URL. Verlasse dich beim Übertragen eines Tokens nicht auf eine HTTP-Umleitung.

Authentifizierung

Die API nutzt organisationsgebundene Bearer-Tokens (JWT). Tokens werden im i-Planner-UI deiner Organisation erzeugt und über den Authorization-Header mitgeschickt:

Authorization: Bearer IPLANNER_API_TOKEN

curl https://www.api.i-planner.app/v3/customers \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

Volle Details — Token-Erzeugung, Scope-Modell, Token-Rotation, alle 401/403-Fehler-Bodies — in der Authentication-Doku↗.

Rate Limits

Für die v3-API gilt ein gemeinsames Request-Budget pro Organisation und Minute, entsprechend dem Tarif. Alle REST-Tokens derselben Organisation teilen dieses Budget; ein zusätzlicher Token erhöht das Limit nicht. Es gibt kein eigenes Request-Budget pro Token. Änderungen am Tariflimit können wegen des Konfigurationscaches bis zu fünf Minuten benötigen.

Der Organisationsplan ist maßgeblich: Verwendet werden die Rate-Limits der aktuell gewählten Planversion. Ein aktiver, organisationsspezifischer Plan hat Vorrang vor den Standardwerten dieser Version; seine Grenzwerte werden nicht zusätzlich mit den Standardwerten addiert. Dies gilt auch für eigene Entwicklungs- oder Testkonfigurationen. Integrationen sollten keine feste Tarifquote annehmen, sondern X-RateLimit-Limit und X-RateLimit-Remaining auswerten.

Das API-Budget stammt aus dem Planwert api_requests_per_minute. webhook_deliveries_per_minute ist ein eigener Grenzwert für Webhook-Zustellungen. Der API-Limitwert muss eine positive ganze Zahl sein. Ist die benötigte Plan-Konfiguration nicht verfügbar oder ungültig, wird kein Ersatzlimit erfunden; die API liefert 503.

Zusätzlich werden fehlgeschlagene Authentifizierungsversuche pro Client-IP gezählt. Dieser Schutz ist vom Organisationsbudget getrennt. Nach Prüfung von JWT-Signatur und gegebenenfalls älteren Ablauf-Claims wird das Organisationsbudget vor der abschließenden Token-Prüfung belastet. Auch spätere Scope-, IP- oder Eingabefehler können daher das Organisationsbudget verbrauchen.

Response-Header

• X-RateLimit-Limit — zulässige Aufrufe pro Minute im aktuellen Budget.
• X-RateLimit-Remaining — verbleibende Aufrufe, mindestens 0.
• X-RateLimit-Layer — organization für das Organisationsbudget; authFail bei Drosselung fehlgeschlagener Authentifizierungen.
• Retry-After — bei 429 die erforderliche Wartezeit in Sekunden, bei 503 derzeit 10.

Die drei X-RateLimit-*-Header werden gesetzt, sobald das Organisationsbudget geprüft wurde, einschließlich späterer Fehler-Responses. Für Requests ohne gültige JWT-Signatur fehlen sie, solange der Authentifizierungsschutz noch keine 429 erzeugt. Separate X-RateLimit-Tenant-*-Header und ein Reset-Zeitstempel werden nicht ausgegeben.

429: Budget ausgeschöpft

Die folgenden Beispiele zeigen die Fehlerdetails im Response-Feld data:

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Try again in 12 seconds.",
  "retry_after": 12
}

{
  "error": "too_many_auth_failures",
  "message": "Rate limit exceeded. Try again in 300 seconds.",
  "retry_after": 300
}

Beachte den tatsächlichen Retry-After-Header und data.retry_after. Der Authentifizierungsschutz kann eine zusätzliche Sperrzeit verhängen. Der Header X-RateLimit-Layer zeigt das auslösende Budget; der JSON-Body enthält kein eigenes layer-Feld. Wiederholte 429 erhöhen das Limit nicht.

503: Limit-Prüfung vorübergehend nicht möglich

Ist die Limit-Prüfung nicht verfügbar, wird der Aufruf mit 503 und Retry-After: 10 abgewiesen. Das gilt auch, wenn das aktuelle Organisationslimit nicht geladen werden kann.

{
  "error": "service_unavailable",
  "message": "Rate limiting service is temporarily unavailable. Please retry shortly.",
  "retry_after": 10
}

Debugging von Requests

Jede Response trägt HTTP-Header für Request-Tracing und Token-Health — in Produktiv-Deployments mitloggen, damit Support-Anfragen direkt mit einer Request-ID belegt werden können.

• x-request-id — Eindeutige UUID dieses API-Requests, server-seitig gesetzt. Bei Support-Tickets immer mitschicken.
• X-Token-Expires-At — ISO-Timestamp des Token-Ablaufs. Nach erfolgreicher Token-Prüfung gesetzt, sofern eine wirksame Gültigkeit besteht; unbegrenzte v5-Tokens liefern den Header nicht.
• X-Token-Expires-In-Days — Wird nur gesetzt, wenn der Token in ≤ 30 Tagen abläuft (Frühwarnung für Rotation).

Volle Fehler-Referenz mit allen HTTP-Codes, error-Strings und Response-Bodies steht in der Errors-Doku↗. Auth-spezifische 401/403 sind separat in der Authentication-Doku↗ beschrieben.

OpenAPI-Datei

Die maschinenlesbare Beschreibung ist ohne Token über GET /openapi/v3.yaml↗ abrufbar. Sie verwendet OpenAPI 3.1.0 und beschreibt Routen, Methoden, Eingaben, Responses und erforderliche Berechtigungen. Die Datenaufrufe unter /v3/* benötigen weiterhin einen REST-Bearer-Token.

Der erforderliche iPlanner-Scope steht je Aufruf in x-iplanner-required-scope; es handelt sich um Berechtigungen des Organisationstokens, nicht um einen OAuth-Flow. Die Endpoint-Übersicht↗ wird aus demselben Vertrag erzeugt.

Felder und Auswahlwerte können organisationsspezifisch sein. Nutze with_schema=true an einem unterstützten GET, um die aktuelle Feldbeschreibung zu erhalten. Die API weist unbekannte, geschützte oder ungültige Felder mit 400 ab; ein dynamisches OpenAPI-Modell erlaubt keine beliebigen Feldnamen. Bei leeren Ergebnissen können Feldmetadaten fehlen.

Feldtypen und Datenformate

Mit with_schema=true beschreiben fields die verfügbaren Felder. Bei gruppierten Antworten stehen diese Angaben innerhalb der jeweiligen Ressource, zum Beispiel fields.contracts.beitrag_kunde.

• data_type beschreibt den fachlichen Typ: string, number oder date. Dezimalwerte können als JSON-Strings zurückkommen, damit ihre Genauigkeit erhalten bleibt.
• data_format beschreibt die Form des Werts. Ein Dezimalfeld mit zwei Nachkommastellen liefert 0.00, eines mit fünf Nachkommastellen 0.00000. Bei einer festen Skala von null lautet die Angabe 0.
• Datumsfelder liefern 0000-00-00, Datums-/Zeitfelder 0000-00-00 00:00:00. Die Nullen sind Platzhalter; sende als Wert ein tatsächliches Datum wie 2026-09-23.
• Bei Feldern ohne feste Formatvorgabe kann data_format fehlen, etwa bei Text, Auswahl-IDs oder Gleitkommazahlen ohne festgelegte Nachkommastellen.

Das Anzeigeformat der Oberfläche, etwa currency oder dd.MM.yyyy, ist eine separate Angabe und wird von data_format nicht beschrieben. Geldbeträge werden für API-Aufrufe mit Dezimalpunkt übergeben, zum Beispiel 123.45.

Abwärtskompatibilität

• Die REST API v3 als einzige öffentliche Version
• Die Verwendung von Organisationstokens über den Authorization-Header. Der Token-String bleibt ein undurchsichtiges Secret; interne JWT-Claims sind kein öffentliches Datenschema.
• Die Ressourcen-Familien↓ und ihr URL-Schema

Abwärtskompatible Änderungen umfassen unter anderem:

• Neue Ressourcen (URLs) in der REST-API
• Neue optionale Query-Parameter und Request-Body-Felder
• Neue Properties in JSON-Response-Objekten
• Änderung der Reihenfolge von Properties in JSON-Responses
• Änderungen an Länge oder Format opaker Strings (z. B. UUIDs, Resource-Identifier)
• Zusätzliche Response-Header (sofern bestehende Header in Format und Bedeutung unverändert bleiben)

Sollten in Zukunft Breaking Changes nötig werden, wird das langfristig angekündigt — über eine neue Major-Version (/v4/*), die parallel zur bisherigen läuft, mit einer kommunizierten Migrationsfrist. Die bisherigen abwärtskompatiblen Änderungen findest du im Changelog der jeweiligen Release-Notes.