Maschinenintegrationen mit einem Workspace SDK anbinden

Nutzen Sie das offizielle Go-SDK für serverseitige Integrationen mit einem festen Mandanten. Nach diesem Quickstart erkennt Ihr Dienst die freigegebenen Ressourcen und greift mit einem eingeschränkten API-Key darauf zu. Node.js- und PHP-Pakete sind vorbereitet, aber noch nicht veröffentlicht.

SDK auswählen

Verwenden Sie das SDK in einem Backend oder Worker. Binden Sie den Node.js-Client und seinen API-Key nicht in Browsercode ein. Native Android-Apps verwenden stattdessen das Android-SDK.

Voraussetzungen

• eine über HTTPS erreichbare Workspace-Installation,
• ein tenantgebundener API-Key mit den minimal benötigten Berechtigungen,
• dieselbe Versionsnummer für Workspace und SDK.

Das Go-SDK ist ab Workspace 8.1.0 unterstützt. Node.js und PHP werden erst nach ihrer getrennten Erstveröffentlichung aktiviert. Nutzen Sie für diese Laufzeiten bis dahin den dokumentierten HTTP-Vertrag oder nucli.

Paket installieren

Installieren Sie exakt die Version Ihrer Workspace-Installation:

go get git.schukai.me/releases/nucleus-sdk-go/v8@v8.1.0

Bei einer neuen Workspace-Hauptversion ändert sich der Go-Modulpfad, zum Beispiel von /v7 auf /v8.

Client verbinden

Übergeben Sie Basis-URL, Key-ID und Key-Secret über die sichere Laufzeitkonfiguration Ihrer Anwendung. Der Client ruft zuerst die öffentliche Discovery und anschließend die authentifizierten Ressourcen-Entrypoints ab. Verwenden Sie nur die zurückgegebenen same-origin URLs; bauen Sie Ressourcenpfade nicht selbst zusammen.

Der Go-Client kann mit CurrentContext zusätzlich die vom Server bestimmte Tenant- und Identity-ID lesen. Vergleichen Sie beide Werte vor dem ersten Fachzugriff mit der aktivierten Connector-Konfiguration. Fehlt ein Wert oder weicht er ab, darf der Connector nicht starten. Diese Prüfung ergänzt die serverseitige Berechtigungsprüfung, ersetzt sie aber nicht.

Die SDKs unterstützen Discovery, Ressourcen-Entrypoints, Ressourcen-Metadaten, Listen und serverseitig angebotene Aktionen. Ein Entrypoint ohne direkte HTTP-Methode kann strukturierte Aktionen enthalten. Wählen Sie eine Aktion über ihre stabile ID und führen Sie sie mit ExecuteAction beziehungsweise executeAction aus. Übergeben Sie genau die angekündigten Pflichtheader. Das SDK prüft den erwarteten Status und gibt nur freigegebene Antwortheader zurück. Fachpayloads bleiben JSON. Interaktive Anmeldung, 2FA und Sitzungsverwaltung gehören nicht zum Maschinenprofil.

Für idempotente Schreibaktionen übergibt der Go-Client den vom Server geforderten Schlüssel mit ExecuteAction. Der Client sendet dabei nur die in der Discovery angekündigten Header und wiederholt Schreibzugriffe nicht automatisch.

Wareneingang anbinden

Die Wareneingangsintegration kündigt drei Aktionen an: Referenzdaten und erwartete Einkaufsbestellungspositionen lesen sowie eine geprüfte Abschlussentscheidung anwenden. Für den Zugriff benötigt der API-Key gezielt receiving_integrations:read, receiving_integrations:receive oder beide Berechtigungen. Da kein mitgeliefertes IAM-Preset diese Berechtigungen automatisch vergibt, legen Sie für den Connector eine eigene Maschinenrolle an und weisen nur die tatsächlich benötigten Berechtigungen zu.

Beim Schreiben muss operationId exakt dem Header Idempotency-Key entsprechen. Verwenden Sie für denselben fachlichen Vorgang immer denselben stabilen Wert. Eine identische Wiederholung liefert das gespeicherte Ergebnis; eine abweichende Payload mit derselben ID endet mit HTTP 409 und ERR_IDEMPOTENCY_CONFLICT. Akzeptierte Mengen können in den Bestand gebucht werden. Vollständig abgelehnte oder quarantinierte Mengen bleiben im Receiving-Case-Prozess und erzeugen keinen Wareneingangsbeleg. Der Server akzeptiert höchstens 500 Positionen und einen Request-Body bis 256 KiB.

Jedes Paket enthält ein ausführbares examples/quickstart-Programm. Es prüft API v1, wählt einen vom Server angekündigten lesbaren Entrypoint und lädt höchstens einen Datensatz. Die jeweilige README nennt die benötigten Umgebungsvariablen und den sprachspezifischen Startbefehl.

Ergebnis prüfen

Die Einrichtung ist erfolgreich, wenn:

1. Discovery den API-Major v1 meldet,
2. CurrentContext den erwarteten Tenant und die erwartete Identity bestätigt,
3. die Ressourcenabfrage nur die für Key und Mandant erlaubten Entrypoints liefert,
4. der Client nur serverseitig angekündigte Aktionen und Header verwendet,
5. Fehler über HTTP-Status und den stabilen errorCode verarbeitet werden.

Protokollieren Sie niemals API-Keys, Authorization-Header, vollständige Payloads oder komplette Fehlerantworten. Ordnen Sie errorCode in Ihrer Anwendung einer eigenen lokalisierten Meldung zu; die SDKs liefern derzeit nur englische technische Texte.

Nächster Schritt

Öffnen Sie nach der Installation die englische README des Pakets. Sie enthält sprachspezifische Beispiele für Authentisierung, Ressourcen, Fehlerbehandlung und Kompatibilität.