Backend-Integration für eigene Clients
Nutzen Sie die Backend-Verträge, wenn Sie eine eigene Oberfläche, einen Headless-Client oder eine spezialisierte Arbeitsoberfläche gegen Workspace bauen. Starten Sie mit Discovery und Ressourcen-Metadaten, und behandeln Sie Readiness-Antworten als Maschinenvertrag, nicht als fertige UI.
Discovery zuerst lesen
Lesen Sie zuerst die öffentlichen und tenantgebundenen Einstiegspunkte:
nucli --host https://workspace.example discovery --json
nucli --tenant <tenant> resources list
nucli --tenant <tenant> resources meta <entrypoint-id>Verwenden Sie veröffentlichte URLs, Methoden und Felder aus den Antworten. Bauen Sie Fachpfade nicht aus Annahmen zusammen, wenn der Server einen Einstiegspunkt oder eine Ressourcen-Meta-Fläche bereitstellt.
Angemeldete Kundenportale für Vorgänge anbinden
Die Vorgangs-API unterstützt eigene Support-, Service- und Ankaufsportale. Für den persönlichen Zugriff benötigen Sie eine aktive Anmeldung im Tenant der Site. Ein Shop, ein Vertriebskanal oder ein zusätzlicher Personendatensatz ist dafür nicht erforderlich. Die API liefert nur ausdrücklich freigegebene Vorgänge und Nachrichten. Bestehende Firmenkontexte behalten ihre eigene Zugriffsprüfung.
Konfigurieren Sie einen Vorgangseingang mit accessMode=authenticated oder restricted. Für strukturierte Daten aktivieren Sie structuredEnabled und geben je Vorgangstyp die zulässigen Felder über externalFields frei. Die Auswahl gilt für Felder auf der obersten Ebene: Wenn Sie ein Objekt oder eine wiederholbare Gruppe freigeben, gehört deren gesamter deklarierter Unterbaum zum externen Vertrag. Legen Sie interne Daten außerhalb solcher freigegebenen Gruppen ab.
uploadsEnabled erlaubt private Anhänge bei der Einreichung. Für spätere Dateinachreichungen aktivieren Sie am Vorgangstyp zusätzlich externalCommentUploadsEnabled; diese Freigabe gilt auch für Vorgänge, die beispielsweise aus E-Mails entstanden sind. Beide Uploadfreigaben sind standardmäßig ausgeschaltet. uploadFields ordnet Dateifelder je Vorgangstyp zu, etwa /devices/*/photos. Das Feld muss im Schema als Liste von Zeichenketten deklariert sein. Der Vorgangstyp bestimmt Daten und Workflow; Support und Ankauf verwenden dieselben Schnittstellen.
Alle folgenden Pfade beginnen mit /api/v1/public/v1:
| Aufruf | Aufgabe |
|---|---|
GET /case-intakes/{intakeKey} | Erlaubte Vorgangstypen und deren externen Vertrag lesen. |
POST /case-intakes/{intakeKey}/upload-sessions | Uploads für eine neue Einreichung vorbereiten. |
GET /case-intakes/{intakeKey}/upload-sessions/{sessionId} | Dateien und Scanstatus der eigenen Sitzung lesen. |
POST /case-intakes/{intakeKey}/upload-sessions/{sessionId}/files | Eine Datei als Multipart-Feld file hochladen. |
DELETE /case-intakes/{intakeKey}/upload-sessions/{sessionId}/files/{attachmentId} | Eine noch nicht eingereichte Datei entfernen. |
POST /case-intakes/{intakeKey}/submissions | Einreichung absenden; angenommene Anfragen erzeugen einen Vorgang. |
GET /account/cases | Berechtigte Vorgänge auflisten. |
GET /account/cases/{caseID} | Vorgang und ursprüngliche Einreichung lesen. |
GET /account/cases/{caseID}/comments | Freigegebenen Nachrichtenverlauf seitenweise lesen. |
POST /account/cases/{caseID}/comments | Antworten und weitere Dateien nachreichen. |
uploads liefert die konfigurierten Dateigrenzen und unterstützten Medientypen. uploads.enabled bezeichnet die Freigabe am Eingang, keine Erreichbarkeitsprüfung des Scanners. Ein nicht verfügbarer Speicher oder Scanner kann den späteren Upload deshalb weiterhin verhindern.
Lesen Sie zuerst caseTypes[].contract. Übernehmen Sie dessen version als contractVersion. schema beschreibt den unterstützten Ausschnitt des Workspace-Validierungsvertrags, keinen vollständigen JSON-Schema-Dialekt. Berücksichtigen Sie allOf, wenn mehrere hinterlegte Regeln zusammenwirken. Die Kennzeichnung x-nucleus-string-length-unit: "utf8-bytes" bedeutet, dass minLength und maxLength UTF-8-Bytes zählen. Ein unverändert eingesetzter Standardvalidator kann bei Umlauten oder Emojis andere Ergebnisse liefern. Interne Referenz-IDs werden dafür nicht benötigt.
Für mehrere Geräte laden Sie die Bilder in derselben Sitzung hoch und geben beispielsweise fieldPath=/devices/0/photos beziehungsweise /devices/1/photos an. In den entsprechenden Dateifeldern unter attributes stehen die IDs der Uploadanhänge. Beliebige Storage-Objekt-IDs können dort nicht eingesetzt werden.
Senden Sie die Einreichung mit caseType, subject, message, den benötigten Kontaktmetadaten sowie attributes, contractVersion, idempotencyKey und gegebenenfalls uploadSessionId. Beachten Sie die Origin-Allowlist und die bestehenden Eingangsprüfungen. Ein Name oder eine E-Mail-Adresse im Formular ändert keine Zugriffsrechte.
Bei einer angenommenen strukturierten Anfrage enthält die Antwort caseId für den anschließenden Detailaufruf. Eine Quarantäne kann zunächst ohne Vorgang zur internen Prüfung bestehen bleiben. Wenn das Vorgangsschema vor der späteren Freigabe verschärft wird, muss der neu anzulegende Vorgang die aktuellen Regeln erfüllen. Die ursprünglichen Angaben werden dafür nicht still ergänzt; gegebenenfalls ist eine neue Einreichung erforderlich.
Bewahren Sie den Idempotenzschlüssel bis zur bestätigten Antwort auf. Bei einem Verbindungsfehler wiederholen Sie denselben Request mit demselben Schlüssel. Abweichender Inhalt führt zu einem Konflikt. Bei einem neuen Request mit veraltetem Schemavertrag laden Sie die Konfiguration erneut und lassen die Angaben prüfen.
Dateien bleiben bis zum erfolgreichen Scan gesperrt. Ein deaktivierter Scan, skipped oder ein Scannerfehler ist keine Freigabe. Standardmäßig gelten zehn Dateien, 15 MiB je Datei, insgesamt 50 MiB und eine Stunde Sitzungsdauer. Verwenden Sie die wirksamen Limits aus der Upload-Sitzung, nicht allein die konfigurierten Grenzen aus der Eingangskonfiguration. Unterstützte Dateiformate bedeuten nicht automatisch, dass für jedes Format eine Bildvorschau verfügbar ist.
Die ursprünglichen Angaben finden Sie im Vorgangsdetail unter submission. Sie werden nicht nachträglich überschrieben. submission.files ordnet die ursprünglichen Upload-IDs über id und fieldPath den berechtigten Dateiansichten zu. So können Sie beispielsweise Fotos auch später wieder dem jeweiligen Gerät zuordnen. Für Ergänzungen erzeugen Sie eine Upload-Sitzung unter /account/cases/{caseID}/upload-sessions und senden deren uploadSessionId zusammen mit content an den Kommentar-Endpunkt. Auch hier verwenden Sie bei einer Wiederholung dieselbe Sitzung und denselben Inhalt. Verwenden Sie zum Lesen verknüpfter Dateien die autorisierten URLs in comments[].attachments; konstruieren Sie keine Storage-Rohpfade.
Listen liefern nextCursor. Fordern Sie weitere Seiten mit cursor und optional limit an. Cursor gehören zum jeweiligen persönlichen oder Firmenkontext. Übertragen Sie sie nicht auf andere Konten oder Vorgänge. comments[].isOwn kennzeichnet eigene Nachrichten; daraus lässt sich keine Mitarbeiterrolle anderer Absender ableiten. Interne Kommentare und live gepflegte interne Vorgangsattribute gehören nicht zur Kundenprojektion.
Die API erstellt keinen verbindlichen Kaufvertrag und bucht keinen Ankauf. Fachliche Entscheidungen und Statusübergänge folgen dem hinterlegten Vorgangsworkflow. Für angemeldete Kunden ist kein öffentlicher Antwortlink erforderlich.
Gültigkeit neuer Angebote übergeben
Senden Sie bei POST /api/v1/quotes immer validUntil als RFC3339-Zeitpunkt mit Zeitzone. Aufrufer, die bisher kein Datum übergeben haben, müssen angepasst werden. Fehlende oder nullwertige Angaben werden als Feldfehler abgewiesen. Ein individuelles Datum bleibt möglich.
Angebotsdatum vorbelegen
GET/api/v1/quotes/create-defaults
Der tenantgebundene Aufruf benötigt quotes:create und legt kein Angebot an. Er berechnet das Datum aus commerce.quote_validity_days; ohne abweichende Einstellung gelten 30 Tage. Übernehmen Sie die Antwort nur, solange der Nutzer das Feld noch nicht bearbeitet oder bewusst geleert hat. Scheitert das Laden, kann Ihr Client die manuelle Datumseingabe anbieten.
| Bereich | Name | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
| Response | data.validUntil | string (RFC3339) | Ja | Berechneter Zeitpunkt für ein neues Angebot im aktuellen Tenant. |
| Status | Bedeutung |
|---|---|
200 | Vorbelegung gelesen. |
400 | Tenant-Kontext fehlt oder ist ungültig. |
403 | Berechtigung zum Anlegen von Angeboten fehlt. |
Bei partiellen Updates bleibt ein nicht mitgesendetes Datumsfeld erhalten. Ein vorhandenes Datum darf nicht auf null gesetzt werden. Bestehende Entwürfe ohne Datum werden nicht automatisch ergänzt; Finalisierung und Versand behalten ihre eigenen Prüfungen.
Readiness-Antworten auswerten
Readiness-Endpunkte helfen Clients, fehlende Voraussetzungen vor einer Aktion sichtbar zu machen. Sie ändern keine Daten und ersetzen keine Validierung im Schreibpfad.
Werten Sie die Statuswerte ready, warning und blocked aus. blocked verhindert die primäre Aktion. warning weist auf eine nicht blockierende Folgeaktion hin; lassen Sie die primäre Aktion weiterhin zu. Prüfen Sie bei jedem Eintrag in checks und blockers dessen eigenen status, denn der kompatible Container blockers kann auch Warnungen enthalten.
Werten Sie diese Felder aus:
| Feld | Verwendung im Client |
|---|---|
status | Entscheidet, ob der Vorgang bereit, mit Warnung ausführbar oder blockiert ist. |
checks[] | Enthält alle geprüften Bedingungen. Nutzen Sie die Liste für Diagnose- oder Detailansichten. |
blockers[] | Kompatibler Container für offene Punkte. Prüfen Sie den Status jedes Eintrags. |
code | Stabiler technischer Schlüssel für Fallbacks, Tests und Telemetrie. |
reasonKey | Stabiler fachlicher Schlüssel für den Nutzertext im Client. |
detailKeys[] | Optionale Unterschlüssel für genauere Hinweise. |
field | Fachliches Feld oder Bereich, der den Blocker ausgelöst hat. |
ownerArea | Zuständiger Produktbereich, zum Beispiel documents, positions oder commerce. |
category | Art des Blockers, zum Beispiel user_data, configuration, template oder system_state. |
responsibility | Zuständigkeit, zum Beispiel user, admin, template_owner oder system. |
actionability | Steuert die Darstellung: direct, escalate oder none. |
actionRouteKey | Bevorzugter logischer Navigationsschlüssel für andere Seiten oder Module. |
actionUrl | Fallback oder lokales Ziel innerhalb einer Detailansicht. |
Erzeugen Sie Nutzertexte aus reasonKey, detailKeys[] und optional code. Verlassen Sie sich nicht auf serverseitige Freitexte.
Aktionsziele mappen
Behandeln Sie actionRouteKey als bevorzugten Navigationsvertrag. Pflegen Sie in Ihrem Client eine eigene Routen-Tabelle:
const routeMap = {
"commerce-document-template-mappings": "/settings/document-template-mappings",
"commerce-profiles": "/settings/commerce-profiles",
"pim-price-lists": "/pim/price-lists",
"warehouses": "/inventory/warehouses",
};Wenn actionRouteKey fehlt, kann actionUrl ein lokales Ziel enthalten. Lokale Ziele beginnen typischerweise mit # und verweisen auf einen Bereich der aktuellen Detailansicht. Übernehmen Sie diese Werte nicht ungeprüft als eigene Tab-IDs. Mappen Sie sie auf Ihre eigene Oberfläche:
const localReadinessTargets = {
"#quotes-tab-items": { resource: "quotes", panel: "items" },
"#quotes-tab-details": { resource: "quotes", panel: "details" },
"#quotes-tab-documents": { resource: "quotes", panel: "documents" },
"#quotes-tab-workflow": { resource: "quotes", panel: "workflow" },
"#quotes-tab-service-context": { resource: "quotes", panel: "serviceContext" },
"#quotes-tab-finance": { resource: "quotes", panel: "finance" },
"#commerce-orders-tab-details": { resource: "orders", panel: "details" },
"#commerce-orders-tab-profile": { resource: "orders", panel: "profile" },
};OpenAPI beschreibt die Antwortstruktur. Konkrete actionUrl-Werte sind fachliche Laufzeitwerte und können mit neuen Readiness-Pfaden wachsen. Schreiben Sie Ihren Client deshalb tolerant:
- Öffnen Sie bei bekanntem
actionRouteKeydie gemappte Seite. - Öffnen Sie bei bekannter lokaler
actionUrlden gemappten Bereich. - Öffnen Sie bei unbekannter lokaler
actionUrldie Detailansicht und zeigen Sie den Blocker trotzdem an. - Zeigen Sie Blocker mit
actionability: "none"ohne Pflichtlink an.
Beispiel: Angebots-Readiness
Ein Angebots-Readiness-Blocker für fehlende Positionen kann so aussehen:
{
"code": "items_val_required",
"status": "blocked",
"field": "items",
"reasonKey": "items",
"actionUrl": "#quotes-tab-items",
"ownerArea": "positions",
"category": "user_data",
"responsibility": "user",
"actionability": "direct"
}Ihr Client sollte daraus nicht ableiten, dass Ihre Oberfläche einen Tab mit der ID quotes-tab-items braucht. Leiten Sie stattdessen aus field, reasonKey oder Ihrer actionUrl-Adapter-Tabelle ab, dass der Nutzer die Positionen des Angebots öffnen soll.
Fallbacks gestalten
Zeigen Sie Readiness-Blocker auch dann an, wenn Sie das Aktionsziel nicht kennen. Nutzen Sie einen neutralen Fallback:
function resolveReadinessTarget(blocker) {
const routeKey = String(blocker?.actionRouteKey || "").trim();
if (routeKey && routeMap[routeKey]) return routeMap[routeKey];
const actionUrl = String(blocker?.actionUrl || "").trim();
if (actionUrl && localReadinessTargets[actionUrl]) {
return localReadinessTargets[actionUrl];
}
return { resource: "current", panel: "details" };
}Protokollieren Sie unbekannte actionRouteKey- und actionUrl-Werte in Ihrer Client-Telemetrie. So erkennen Sie neue Backend-Verträge früh, ohne Nutzer zu blockieren.
Bestell-Dokumentempfänger integrieren
Behandeln Sie customerEmailSnapshot bei Bestellungen als revisionsfesten Snapshot. Senden Sie dieses Feld nicht in Update-Payloads. Der Server lehnt Update-Versuche mit VAL_PROTECTED_FIELD ab, auch wenn der gesendete Wert dem aktuellen Snapshot entspricht.
Wenn ein Client den Empfänger einer Auftragsbestätigung ändern soll, verwenden Sie den dokumenttypbezogenen Override der Bestellung:
GET /api/v1/commerce/orders/{id}/document-recipient-overrides
PUT /api/v1/commerce/orders/{id}/document-recipient-overrides/order_confirmation/email
DELETE /api/v1/commerce/orders/{id}/document-recipient-overrides/order_confirmation/emailFür PUT senden Sie nur die operative Zieladresse:
{
"recipientEmail": "rechnung@example.test"
}Der effektive Empfänger der Auftragsbestätigung folgt dieser Reihenfolge:
- aktiver Override für
order_confirmationundemail, - E-Mail im Rechnungsadress-Snapshot der Bestellung,
customerEmailSnapshot.
Zeigen Sie diese drei Ebenen getrennt an. Schreiben Sie Override-Felder nicht in den normalen Order-Update-Payload. Checkout-Eingangsbestätigungen und andere Dokumenttypen verwenden diesen Override-Vertrag nicht automatisch.
Physische Fulfillment-Strategien integrieren
Lesen und schreiben Sie die Erfüllungsstrategie bei Produktvarianten nur im Logistikmodul. Das Feld heißt physicalFulfillmentStrategy und gilt nur für Varianten mit isPhysical: true.
Zulässige Werte sind:
stocknosdropshipfinish_to_orderassemble_to_ordermake_to_orderprocure_to_order
Behandeln Sie standard nur als alten Eingabewert für stock. Verwenden Sie die Strategie nicht als Ersatz für Produkt-Capabilities wie Lizenz, Service oder Digitalprodukt. Senden Sie kein modules.logistics für nicht-physische Varianten; der Server lehnt diese Capability-Kombination ab.
Wenn Ihr Client Bestellungen, Fulfillment oder operative Übersichten anzeigt, werten Sie den OrderItem-Typ als serverseitigen Snapshot aus. Schreiben Sie ihn nicht selbst. stock kann im OrderItem weiterhin als standard erscheinen. Nicht lagerwirksame Strategien bestätigen die Position, erzeugen aber keine fertige Warenreservierung. Zeigen Sie dafür einen Folgeprozess an, statt eine fehlende Reservierung als Lagerfehler zu behandeln.
Für finish_to_order, assemble_to_order und make_to_order kann der Folgeprozess auf einen Fertigungsauftrag verweisen. Leiten Sie daraus keine automatische Fertigmeldung oder Bestandsbuchung ab. Ein positiver Fertigungsfolgeprozess setzt voraus, dass ein freigegebener Fertigungsplan die bestellte Variante als primäres Ergebnis führt. Fehlt diese Voraussetzung, zeigen Sie den Blocker als Konfigurations- oder Stammdatenproblem an.
Behandeln Sie nos und procure_to_order unterschiedlich. nos ist ein lagernaher Backorder-Pfad für reguläre Sortimentsartikel und kann Pending- oder Backorder-Reservationen nutzen. procure_to_order ist auftragsbezogene Beschaffung; der aktuelle Vertrag erzeugt dafür keine Reservation, keine PurchaseOrder und keine automatische Bestandsbewegung.
Compliance und Contracts integrieren
Compliance-Ressourcen sind tenantgebunden, workflow-nah und teilweise vertragsgebunden. Lesen Sie zuerst die Ressourcen-Metadaten, bevor Sie eigene Formulare oder Automationen bauen. Der Server veröffentlicht unter anderem Ressourcen für Anforderungen, Vertragspflicht-Verknüpfungen, Kontrollen, Prüfungen und Nachweise, wenn die aktuelle Session die nötigen Rechte hat.
Behandeln Sie Contracts als Quelle für Vertragsstatus, Vertragsattribute, Sichtbarkeit und Fristen. Compliance dupliziert diese Daten nicht. Eine Vertragspflicht verknüpft eine requirementId mit einer contractId und trägt Rolle, Löschregel, Nachweisstärke und Gültigkeitszeitraum.
Wichtige Integrationsregeln:
- Schreiben Sie Status- und Workflow-Felder von Anforderungen und Prüfungen nicht direkt. Nutzen Sie die veröffentlichten Workflow-Transitionen.
- Legen Sie Nachweise an der konkreten Prüfung an, nicht nur an einer Anforderung oder einem Vertrag.
- Laden Sie Dateien über den veröffentlichten Evidence-Upload hoch, wenn Ihr Client Dateiinhalt übertragen soll. Der Server berechnet den Hash und verknüpft optional ein Storage-Objekt.
- Werten Sie Sichtbarkeit so aus, wie der Server sie liefert. Verknüpfte Compliance-Daten können durch den sichtbaren Contract-Kontext eingeschränkt sein.
- Zeigen Sie Contract-Fristen aus Compliance-Berichten als abgeleitete Berichtswerte an. Korrigieren Sie Fristen über den Contract und seine strukturierten Attribute.
- Exportieren Sie Evidence-Snapshots nur in freigegebene Storage-Ziele und behandeln Sie Prüfsummen als Audit-Metadaten.
Typische Statuswerte für Prüfungen sind open, in_progress, in_review, closed und failed. Typische Anforderungsstatus sind draft, active, retired und deprecated. Diese Werte sind fachliche Verträge; behandeln Sie unbekannte künftige Werte fail-closed oder mit einem neutralen Fallback.
Seriennummern und Chargen integrieren
Lesen und schreiben Sie Tracking-Felder über die veröffentlichten Ressourcen-Metadaten. Verwenden Sie keine internen Inventory- oder Fulfillment-Pfade als Ersatz, wenn eine Ressource im aktuellen Kontext nicht veröffentlicht ist.
Für Produktvarianten sind diese Felder relevant:
| Feld | Verwendung im Client |
|---|---|
trackingType | Entscheidet bei physischen Varianten, ob Lagerbestand ohne Tracking, chargengeführt oder seriennummerngeführt ist. |
serialNumberSource | Beschreibt nur bei trackingType=serial_number, ob Nummern extern übernommen oder intern erzeugt werden. |
serialNamespaceId | Ordnet eine sichtbare Seriennummer einem Hersteller-, Lieferanten- oder internen Nummernkreis zu. |
serialIdentityId | Referenziert die erzeugte Serienidentität im Tracking-Pool. |
Behandeln Sie Tracking als Prozessvertrag:
- Wareneingänge müssen Tracking-Daten liefern, wenn die Variante
batchoderserial_numberverlangt. Für Chargen verwenden ClientstrackingNumbers. Für Seriennummern verwenden ClientsserialAssignmentsmitserialNamespaceIdundserialNumber. - Verwenden Sie eine sichtbare Seriennummer nie allein als Identität. Die fachliche Identität ist
Mandant + Seriennummern-Namensraum + normalisierte Seriennummer. - Lieferanten- und Papierwareneingänge akzeptieren für Seriennummern nur
serialNumberSource=external_document. Sie dürfen weder interne Nummern erzeugen noch durch eine frei gelieferte Produktionsreferenz Fertigungsprovenienz behaupten. - Nur der Manufacturing-Buchungspfad erzeugt Tracking mit
serialNumberSource=internal_production; der aktuelle serialisierte Umrüstungsschnitt übernimmt dabei die reservierte Eingangsseriennummer. - Picking und Versand dürfen trackingpflichtige Positionen erst abschließen, wenn die konkrete Nummer oder Charge zugeordnet ist.
- Seriennummern stehen für einzelne Einheiten; Chargen können Mengen tragen und bei Teilversand Restmengen behalten.
- Software- oder Lizenznummern werden nicht über diese Lager-Tracking-Felder geführt, sondern über Lizenz- und Provisioning-Verträge.
- Korrekturen, Sperrungen und Retouren brauchen einen nachvollziehbaren fachlichen Grund.
Details zu API-Ressourcen und Beispielpayloads stehen in Serienidentitäten über die API integrieren.
Zeigen Sie Konflikte wie fehlende, bereits verwendete oder nicht verfügbare Nummern als fachlichen Zustand an. Geben Sie keine internen Tabellennamen, Datenbankfehler, Rohfehler oder Lagerpfad-Details an Benutzer weiter.