Workspace integrieren

Sie entwickeln einen Client, eine Website, eine Storefront oder eine Fachsystem-Integration für Workspace? Wählen Sie hier den technischen Einstieg und folgen Sie anschließend den vom Server veröffentlichten Verträgen. Am Ende steht ein klarer Pfad zu Discovery, API, CLI oder Storefront.

Falls noch offen ist, ob ein bestehendes System bleiben oder ersetzt werden soll, beginnen Sie bei Integratoren. Diese Seite setzt die fachliche Entscheidung voraus und beschreibt die technische Umsetzung.

Den technischen Einstieg wählen

Vorhaben	Startpunkt
Verfügbare Fähigkeiten und Ressourcen zur Laufzeit erkennen	Discovery und Ressourcen
API-Aufrufe mit einem Referenzclient prüfen	CLI und API
Einen eigenen Headless-Client oder eine Admin-Oberfläche bauen	Backend-Integration für eigene Clients
Daten chargenweise importieren	Import-Jobs
Eine Website oder ein Portal umsetzen	Webseiten umsetzen
Eine öffentliche Storefront bauen	B2B-Onlineshop bauen
API-Verträge über OpenAPI analysieren	OpenAPI verwenden

Die Vertragsreihenfolge

Lesen Sie GET /api/v1/meta/discovery, bevor Sie Fähigkeiten annehmen.
Verwenden Sie GET /api/v1/meta/entrypoints für veröffentlichte Authentisierungs- und Privacy-Einstiege.
Melden Sie sich über den veröffentlichten Auth-Einstieg an.
Lesen Sie GET /api/v1/profile/entrypoints für tenantgebundene Ressourcen.
Prüfen Sie die Meta-Fläche einer Ressource, bevor Sie Listen, Details oder Mutationen implementieren.
Behandeln Sie Status- und Validierungsfehler ausdrücklich im Client.

Hart codierte Pfade sind nur dann belastbar, wenn sie selbst Teil eines veröffentlichten Vertrags sind. Runtime-Discovery und Ressourcen-Meta bleiben die erste Quelle für eine laufende Instanz.

Kritische Client-Regeln

Behandeln Sie 401, 403, 404 und Validierungsfehler getrennt.
409 ERR_PROFILE_IDENTITY_AMBIGUOUS bei GET /api/v1/profile ist ein Administrationsfall. Wählen Sie nicht anhand von E-Mail, Name, Staff-Profil oder Workforce-Status selbst eine Person aus.
Wiederholen Sie mutierende Aufrufe nur bei einem belegten Idempotenzvertrag oder wenn der Client Doppelverarbeitung sicher verhindert.
Trennen Sie Test- und Produktionsumgebungen sichtbar.
Speichern Sie keine Tokens, Passwörter oder Session-Werte in Logs, Screenshots oder Testartefakten.
Verwenden Sie für Storefronts keine internen PIM-, Commerce-, Inventory-, Admin- oder CRUD-Endpunkte als Fallback.

`nucli` als Referenzclient

Prüfen Sie Verträge mit nucli, bevor Sie eigenen Code schreiben:

bash

nucli --host https://workspace.example discovery --json
nucli --tenant <tenant> resources list
nucli --tenant <tenant> resources meta <entrypoint-id>
nucli --tenant <tenant> resources get <entrypoint-id> --all --max-pages 5 --summary

nucli api eignet sich für gezielte Inspektion. Nutzen Sie --summary und Redaction-Optionen, bevor Ergebnisse in Tickets oder Supportfälle gelangen.

Fachliche Spezialfälle richtig zuordnen

Thema	Passende Dokumentation
Staff Teams, Teammitgliedschaften und Abgrenzung zu IAM	Teams im Personalbereich
Eigene Website oder Portal	Webseiten umsetzen
Katalog, Preise und Verfügbarkeit einer Storefront	Katalog, Preise und Produktdarstellung
Warenkorb, Checkout und Zahlung	Warenkorb, Checkout und Payment
Login, Gastkauf und B2B-Zugang	Login, Gastkauf und B2B

Die Integration ist bereit, wenn …

fachlicher Use Case und führendes System feststehen,
Discovery und Ressourcen-Meta ausgewertet werden,
Authentisierung, Berechtigungen und Tenant-Kontext geklärt sind,
Fehler- und Wiederholungsverhalten getestet sind,
Logs und Artefakte keine Zugangsdaten enthalten und
der passende Detailvertrag verlinkt und geprüft ist.