Workspace integrieren

Entwickler binden Workspace über veröffentlichte Discovery-, CLI- und API-Verträge an. Starten Sie mit Discovery, lesen Sie veröffentlichte Einstiegspunkte und vermeiden Sie hart codierte Pfade, wenn der Server einen Vertrag ausweist.

Wenn Sie zuerst entscheiden möchten, ob ein bestehendes System behalten, angebunden oder später migriert werden soll, starten Sie mit Integratoren. Diese Seite hier beschreibt danach die technische Umsetzung.

Integrationsablauf

  • Lesen Sie GET /api/v1/meta/discovery, bevor Sie Features nutzen.
  • Lesen Sie GET /api/v1/meta/entrypoints, wenn Sie Headless-Login oder Privacy-Metadaten benötigen.
  • Melden Sie sich über den veröffentlichten Auth-Einstieg an.
  • Lesen Sie GET /api/v1/profile/entrypoints für tenantgebundene Ressourcen.
  • Lesen Sie die Meta-Fläche einer Ressource, bevor Sie Listen, Details oder Mutationen bauen.
  • Behandeln Sie 401, 403, 404 und Validierungsfehler ausdrücklich im Client.
  • Behandeln Sie 409 ERR_PROFILE_IDENTITY_AMBIGUOUS bei GET /api/v1/profile als Administrationsfall. Wählen Sie nicht selbst eine Person anhand von E-Mail, Name, Staff-Profil oder Workforce-Status aus.

Wenn Sie eine eigene Oberfläche oder einen Headless-Client bauen, lesen Sie zusätzlich Backend-Integration für eigene Clients. Die Seite beschreibt Readiness-Antworten, Aktionsziele und robuste Fallbacks für eigene UI-Navigation.

Webseiten umsetzen

Wenn Sie eine öffentliche Website, Landingpage, einen Produktkatalog, ein Portal oder einen Onlineshop planen, starten Sie mit Webseiten umsetzen. Die Seite trennt allgemeinen Site-Bau, SEO-Grundlagen, typische Website-Archetypen und den Onlineshop als eigene Commerce-Lösung.

Onlineshop-Storefront bauen

Wenn Sie eine öffentliche Storefront bauen, starten Sie mit Onlineshop. Die Storefront nutzt öffentliche Storefront-Endpunkte für Kontext, Katalog, Preise, Warenkorb, Checkout, Payment, Login, Gastkauf, Firmenzugang und Angebotsanfrage.

Nutzen Sie diese Detailseiten:

Verwenden Sie keine internen PIM-, Commerce-, Inventory-, Admin- oder CRUD-Endpunkte als Storefront-Fallback. Der Server entscheidet über Site, Sales Channel, Preise, Verfügbarkeit, Versand, Checkout und Zahlarten.

CLI als Referenzclient

Nutzen Sie nucli, um Verträge zu prüfen, 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. Verwenden Sie --summary und Redaction-Optionen, wenn Sie Ergebnisse in Tickets oder Supportfällen teilen.

Staff-Teams-Ressourcen

Staff Teams sind eine tenantgebundene Admin-Ressource. Nutzen Sie sie, wenn eine Integration Personalstrukturen, Parent-Teams oder Teammitgliedschaften lesen oder pflegen soll. Leiten Sie daraus keine IAM-, Reporting-, Arbeitszeit- oder Genehmigungswirkung ab.

Prüfen Sie zuerst die verfügbaren Ressourcen:

bash
nucli --tenant <tenant> resources list
nucli --tenant <tenant> resources meta staff.teams
nucli --tenant <tenant> resources get staff.teams --all --max-pages 5 --summary

Teammitglieder hängen an einem konkreten Team. Verwenden Sie dafür die serververöffentlichten URLs aus der Team-Meta oder einen expliziten API-Aufruf mit Team-ID:

bash
nucli --tenant <tenant> api GET /api/v1/staff/teams/<team-id>/members --summary

Die fachliche Abgrenzung steht in Teams im Personalbereich.

Umgebung und Fehlerbehandlung

  • Trennen Sie Test- und Produktionsumgebungen sichtbar in Konfiguration und Zugangsdaten.
  • Nutzen Sie realistische, aber künstliche Beispieldaten in Tests und Dokumentation.
  • Speichern Sie keine Tokens, Passwörter oder Session-Werte in Logs, Screenshots oder Artefakten.
  • Wiederholen Sie mutierende Aufrufe nur, wenn der jeweilige Vertrag idempotente Wiederholungen vorsieht oder Ihr Client die Doppelverarbeitung verhindert.