# i-Planner Developer Docs

> Entwicklerdokumentation für i-Planner. Jede Seite ist auch als Markdown abrufbar: `.md` an die Seiten-URL anhängen.

## API

- [Start](https://www.api.i-planner.app/rest/v3/start.md): Diese Referenz beschreibt die öffentliche i-Planner REST API in Version 3 — das stabile Daten-Interface für Kunden, Verträge und Dokumente.
- [Authentifizierung](https://www.api.i-planner.app/rest/v3/authentication.md): Hier erklären wir dir, wie du einen API-Token erhältst, ihn an die i-Planner REST API v3 sendest, welche Scopes welche Endpoints freischalten und wie die API auf fehlerhafte oder abgelaufene Tokens reagiert.
- [Scopes](https://www.api.i-planner.app/rest/v3/scopes.md): Vollständige Referenz aller v3-Scopes. Jeder API-Endpoint verlangt einen Scope nach dem Muster `v3:<resource>:<action>`; Die API prüft die aktuell am Organisationstoken gespeicherten Scopes. Diese Seite listet alle Scope-Familien, ihre geteilten Bezüge und gibt typische Token-Setups für gängige Integrationen.
- [Endpoints](https://www.api.i-planner.app/rest/v3/endpoints.md): Vollständige Methoden- und Berechtigungsübersicht der REST API v3, gemeinsam mit der OpenAPI-Datei aus dem aktuellen API-Vertrag erzeugt.
- [Fehlercodes](https://www.api.i-planner.app/rest/v3/errors.md): Alle HTTP-Statuscodes der i-Planner REST API v3 mit ihren JSON-Response-Bodies, möglichen `error`-Werten und wann sie ausgelöst werden. Konsolidierte Referenz für defensive Client-Implementierungen.
- [Playground](https://www.api.i-planner.app/rest/v3/playground.md)

## Ressourcen

- [Kunden](https://www.api.i-planner.app/rest/v3/customers.md): Endpoints für die Verwaltung von Kunden — Anlegen, Lesen, Aktualisieren und Löschen — plus alle direkt am Kunden hängenden Unterressourcen (Adressen, Bankverbindungen, Verträge, Schäden, Dokumente …).
- [Ansprechpartner](https://www.api.i-planner.app/rest/v3/contact-persons.md): Ansprechpartner bei Produktpartnern — B2B-Kontakte mit eigenen Stammdaten, die an einem Produktpartner-Datensatz hängen (z. B. „Maklerbetreuer Region Süd" bei der Allianz). Full-CRUD top-level über `/v3/contact-persons/{id}` plus parent-scoped Listing/Create unter `/v3/products/{kid}/contact-persons`.
- [Verträge](https://www.api.i-planner.app/rest/v3/contracts.md): Endpoints für die Verwaltung von Verträgen — Full-CRUD top-level über `/v3/contracts/{id}` plus parent-scoped Listing/Create unter `/v3/customers/{kid}/contracts`. Sub-Ressourcen (Personen, Tarife) und Annotations hängen über die Vertrag-`id` top-level.
- [Produktpartner](https://www.api.i-planner.app/rest/v3/products.md): Produktpartner deiner Organisation — Versicherer, Banken, Fondsgesellschaften und sonstige Anbieter, deren Produkte du Customers vermittelst. Strukturell identisch zu Customers (gleiche Stammdaten-Felder, gleiche Sub-Resources), unter eigenem API-Pfad und eigener Scope-Familie `v3:products:*`.
- [Schäden](https://www.api.i-planner.app/rest/v3/damages.md): Schadensfälle quer durch alle Customer-Verträge — Stammdaten, Status, beteiligte Personen. Full-CRUD top-level über `/v3/damages/{id}` plus parent-scoped Listing/Create unter `/v3/customers/{kid}/damages`.
- [Dokumente](https://www.api.i-planner.app/rest/v3/documents.md): Dokumente quer durch alle CRM-Objekte — PDFs, Briefe, Verträge, Schadens-Belege, Identitäts-Nachweise. Full-CRUD top-level über `/v3/documents/{id}` plus parent-scoped Listing/Create unter `/v3/customers/{kid}/documents`.
- [Aktivitäten](https://www.api.i-planner.app/rest/v3/activities.md): Aktivitäten an Customer, Produktpartner oder Benutzer — Termine, Aufgaben, ToDos, Anrufe und Notizen. Full-CRUD top-level über `/v3/activities/{id}` plus parent-scoped Listing/Create unter `/v3/customers/{kid}/activities`, `/v3/products/{kid}/activities` und `/v3/users/{kid}/activities`.
- [Ziele](https://www.api.i-planner.app/rest/v3/goals.md): Finanzielle Ziele und Sparpläne eines Customers — Zielbetrag, Zeitrahmen, aktueller Fortschritt. Full-CRUD top-level über `/v3/goals/{id}` plus parent-scoped Listing/Create unter `/v3/customers/{kid}/goals`.
- [Finanzen](https://www.api.i-planner.app/rest/v3/finances.md): Finanzdaten eines Customers — Einnahmen, Ausgaben, Vermögensbestand, Verbindlichkeiten. Full-CRUD top-level über `/v3/finances/{id}` plus parent-scoped Listing/Create unter `/v3/customers/{kid}/finances`.

## Beziehungen

- [Beziehungen](https://www.api.i-planner.app/rest/v3/relations.md): Typisierte Beziehungen zwischen Customers — Familien-, Geschäfts- und Gruppen-Relationen für eine 360°-Sicht über zusammenhängende Datensätze. Im Unterschied zu Links (untyped) tragen Relations einen Beziehungs-Typ wie „Ehepartner" oder „Geschäftsführer".

## Plattform

- [Benutzer](https://www.api.i-planner.app/rest/v3/users.md): Benutzer deiner Organisation — User-Stammdaten, Rollen, Lizenzen und Aktivierungs-Status. Strukturell identisch zu Customers (gleiche Stammdaten-Felder, gleiche Sub-Resources), unter eigenem API-Pfad und eigener Scope-Familie `v3:users:*`.
- [Portale](https://www.api.i-planner.app/rest/v3/portals.md): Anbieter-Portale eines Produktpartners — Login-URLs, Credentials und Metadaten zu den externen Portal-Zugängen (z. B. Allianz-Maklerportal, AXA-Vermittler-Login). Full-CRUD top-level über `/v3/portals/{id}` plus parent-scoped Listing/Create unter `/v3/products/{kid}/portals`.
- [Links](https://www.api.i-planner.app/rest/v3/links.md): Verknüpfungen zwischen beliebigen CRM-Objekten — Customer ↔ Vertrag, Vertrag ↔ Dokument, Schaden ↔ Aktivität etc. Verfügbar parent-scoped unter Customer, Produktpartner und Benutzer. Liefert die Cross-Reference-Layer für Workflows, die mehrere Ressourcen-Typen miteinander koppeln.
- [Suche](https://www.api.i-planner.app/rest/v3/search.md): Mandantengebundene CRM-Suche über die PostgreSQL-Tabelle crm_suche.
- [System](https://www.api.i-planner.app/rest/v3/system.md): System-Endpoints liefern organisationsweite Metadaten — Beziehungs-Typen, Sparten und das Tag-Katalog (mit Anlage/Pflege via API).

## Webhooks

- [Einrichten](https://www.api.i-planner.app/webhooks/start.md): Mit einem Webhook informiert i-Planner ein anderes System automatisch über Änderungen — zum Beispiel über einen neuen Kunden oder einen geänderten Vertrag. Auf dieser Seite erfährst du, was du dafür einrichten musst.
- [Events](https://www.api.i-planner.app/webhooks/events.md): Hier siehst du, welche Änderungen einen Webhook auslösen können und welche Daten i-Planner dabei sendet. Die verständliche Übersicht steht zuerst; darunter folgt das genaue Format für Entwickler.
- [Testen](https://www.api.i-planner.app/webhooks/testing.md): Sende zuerst einen Test aus den Webhook-Einstellungen. Damit prüfst du Ziel-Adresse, Header, Signatur und Antwort des Empfängers, ohne einen echten CRM-Datensatz anzulegen oder zu ändern.
- [Zustellung](https://www.api.i-planner.app/webhooks/delivery.md): Hier erfährst du, wann eine Zustellung erfolgreich ist, welche Fehler automatisch erneut versucht werden und wann i-Planner einen Webhook zum Schutz vor weiteren Fehlern deaktiviert.
- [Sicherheit](https://www.api.i-planner.app/webhooks/security.md): Mit HTTPS und der persönlichen Webhook-Signatur kann dein System prüfen, ob eine Nachricht sicher übertragen wurde und wirklich von i-Planner stammt. Die kurze Checkliste richtet sich an alle; darunter folgen Codebeispiele für Entwickler.
- [Fehlerbehebung](https://www.api.i-planner.app/webhooks/troubleshooting.md): Die häufigsten Probleme mit Webhooks – geordnet nach dem, was du beobachtest. Jeder Abschnitt nennt die Ursache und den nächsten Schritt.

## MCP

- [Einrichten](https://www.api.i-planner.app/mcp/start.md): Mit dem i-Planner-Connector arbeiten Claude und ChatGPT direkt mit deinen E-Mails in i-Planner – mit deinem persönlichen Zugang und nur mit den Rechten, die deine Organisation freigibt.
- [Tools](https://www.api.i-planner.app/mcp/tools.md): Der Connector stellt sechs Tools für E-Mails und Signaturen bereit. Jedes Tool wird einzeln freigegeben, lesende und schreibende Tools sind getrennt.
- [Beispiele](https://www.api.i-planner.app/mcp/examples.md): Diese Prompts funktionieren in Claude und ChatGPT, sobald der i-Planner-Connector verbunden ist und die passenden Tools freigegeben sind.
- [Sicherheit & Zugriff](https://www.api.i-planner.app/mcp/security.md): Der Zugriff des Assistenten ergibt sich bei jeder Anfrage neu aus mehreren Grenzen. Keine davon lässt sich über den Assistenten umgehen.
- [Fehlerbehebung](https://www.api.i-planner.app/mcp/troubleshooting.md): Die häufigsten Probleme beim i-Planner-Connector und wie du sie löst.