API und Integrationen
Die API-Dokumentation beschreibt die technische Oberfläche hinter Web-, Mobile- und Integrationsabläufen. Sie ist öffentlich lesbar; fachliche Endpunkte bleiben durch Anmeldung, API-Schlüssel, Mandantenkontext, Capability und Berechtigungen geschützt.
API-Dokumentation öffnen
| Ansicht | Adresse | Verwendung |
|---|---|---|
| API-Übersicht | https://app.insidebase.de/api/ | Fachbereiche und wichtige Endpunkte schnell finden |
| Swagger UI | https://app.insidebase.de/api/swagger/ | Requests, Parameter und Responses interaktiv prüfen |
| ReDoc | https://app.insidebase.de/api/redoc/ | Öffentlichen Integrationsvertrag lesefreundlich durchsuchen |
| OpenAPI-Schema | https://app.insidebase.de/api/schema/ | Clients, Tests und externe Dokumentation generieren |
Authentifizierung und Mandantenkontext
- Verwende für die Webanwendung die bestehende Sitzung oder die dokumentierten Token-Endpunkte.
- Verwende
X-API-KEYnur für ausdrücklich freigegebene Business-Integrationen. - Sende Anfragen an die App-Domain des richtigen Produkts und Mandanten.
- Prüfe vor Schreibzugriffen Capability und konkrete Berechtigung.
- Behandle Token, Cookies, API-Schlüssel und Webhook-Geheimnisse wie Passwörter.
Ein erfolgreicher Login allein erlaubt noch keinen Zugriff auf jeden Mandanten oder jedes Modul. Produkt, Host, aktive Mitgliedschaft, Capability und Rollenrecht werden getrennt ausgewertet.
Öffentlich unterstützte Ressourcen
Das öffentliche Schema enthält ausschließlich ausdrücklich freigegebene Business-Ressourcen: Kontakte, Aufgaben, Tickets, Projekte, Kommentare, Wiki, Zeiterfassung, Kalenderereignisse, Dateien, Ordner und globale Suche sowie in insideCRM Leads, Kunden, Deals und Objekte. Interne UI-, Login-, Administrations-, Realtime- und Webhook-Endpunkte sind kein öffentlicher Integrationsvertrag.
curl --request GET \
--url "https://TENANT-HOST/api/contacts/" \
--header "Accept: application/json" \
--header "X-API-KEY: API_KEY_PLACEHOLDER"Nutze für Seitengröße, Cursor oder Filter ausschließlich Parameter aus dem aktuellen Schema. Bei schreibenden Aufrufen vor einer Wiederholung erst Antwort, Objektzustand und dokumentierte Idempotenz prüfen.
Backend-Funktionsgruppen
| Gruppe | Beispiele |
|---|---|
| Plattform und Konten | Bootstrap, Zielauswahl, Login, MFA, Profile, Benutzer und API-Schlüssel |
| Kommunikation | Mailkonten, Nachrichten, Kalender, Messenger, Inbox, Anrufe und Meetings |
| Organisation | Aufgaben, Tickets, Projekte, Wiki, Meilensteine und Zeitbuchungen |
| Inhalte und Sicherheit | Dateien, Versionen, Freigaben, Papierkorb, private Vaults und Team-Safes |
| Administration | Branding, Workspace-Einstellungen, Custom Fields, Nummernkreise und Lizenzdaten | | Benachrichtigung und Suche | Ereignisse, Zustellstatus, persönliche Regeln und globale Suche |
Die vollständige kundenrelevante Zuordnung mit API-Routenanzahl und Support-Fokus steht im Backend-Modulinventar. Autorisierte Administratoren können die vollständige interne Schemaansicht unter /api/internal/swagger/ verwenden; sie ist kein öffentlicher Integrationsvertrag.
Externe Integrationen und Webhooks
- Microsoft, Google und IMAP verbinden Mailkonten und Kalenderdaten. OAuth-Rückleitungen müssen zur konfigurierten Produktdomain passen.
- Microsoft- und Google-Mail-Webhooks melden Änderungen; die Anwendung verarbeitet sie anschließend asynchron.
- LiveKit transportiert interne Anrufe und Meetings. Der Webhook hält Session-, Lobby- und Teilnehmerstatus aktuell.
- Stripe verarbeitet Zahlungsarten, Checkout, Abonnements und Rechnungsereignisse. Der lokale Status darf erst nach verarbeiteter Rückmeldung als bestätigt gelten.
Asynchrone Verarbeitung erkennen
Ein erfolgreicher Request kann eine Verarbeitung nur angenommen haben. Das betrifft insbesondere Mail-Synchronisierung, Versand, Dokumentindexierung, Portalabgleich, Benachrichtigungen, Reports und Abrechnungsevents.
Prüfe bei verzögerten Ergebnissen:
- HTTP-Status und fachliche Response des auslösenden Requests.
- Request-ID aus Response oder Fehlerseite.
- Statusfeld des betroffenen Objekts statt nur die sichtbare Liste.
- Zeitpunkt, Zeitzone und letzte erfolgreiche Synchronisierung.
- Erst danach einen erneuten Versuch; wiederholte Schreibrequests können Duplikate erzeugen.
Fehlerbilder richtig zuordnen
| Signal | Typische Bedeutung | Erste Prüfung |
|---|---|---|
400 | Eingabe oder fachlicher Zustand ungültig | Pflichtfelder, Format und Abhängigkeiten |
401 | Anmeldung oder Token fehlt/ist abgelaufen | Sitzung erneuern, Systemzeit und Tokenquelle prüfen |
403 | Zugriff authentifiziert, aber nicht erlaubt | Produkt, Mandant, Capability und Rollenrecht prüfen |
404 | Pfad oder Objekt im aktuellen Kontext nicht sichtbar | Host, ID, Mandant und Löschstatus prüfen |
409 | Konflikt mit aktuellem Zustand | Objekt neu laden und konkurrierende Änderung prüfen |
429 | Schutz- oder Ratenlimit aktiv | Wartezeit beachten und Request-Schleifen stoppen |
5xx | serverseitige Verarbeitung fehlgeschlagen | Request-ID, Zeitpunkt, Pfad und Statusseite sichern |
Sicher an den Support übergeben
Übermittle Produkt, vollständigen Pfad ohne geheime Query-Werte, Zeitpunkt mit Zeitzone, Request-ID, erwartetes Ergebnis, tatsächlichen Statuscode und eine kurze reproduzierbare Schrittfolge. Entferne Token, Cookies, API-Schlüssel, Passwörter, personenbezogene Inhalte und vollständige Payloads, sofern sie nicht ausdrücklich über einen geschützten Supportkanal angefordert wurden.
Weitere Hilfe: Fehlerbehebung und Support-Diagnose.
Ergebnis
Integratoren finden die aktuelle technische Vertragsgrundlage, Support kann eine Anfrage dem richtigen Modul zuordnen, und geschützte Aufrufe bleiben trotz öffentlich lesbarer Dokumentation zugriffskontrolliert.