Die OXID eShop B2B Edition spricht jetzt GraphQL
Die OXID eShop B2B Edition spricht jetzt GraphQL
Mit der OXID eShop B2B Edition 6.5.x (rev.: 5.0.0) stellen wir Ihnen die gesamte B2B-Funktionalität zusätzlich zum herkömmlichen Frontend auch über die OXID GraphQL-Schnittstelle zur Verfügung.
OXID eShop Enterprise B2B Edition
Die OXID eShop Enterprise B2B Edition (im Folgenden kurz B2B Edition) besteht aus elf Modulen, die Ihnen eine Reihe von B2B-spezifischen Funktionen zu Selbstverwaltung, Genehmigungsverfahren, Budgetverwaltung, Schnell-, Sammel- und Terminbestellungen, Serviceleistungen im Warenkorb, kundenindividuellen Preisen und Angeboten zur Verfügung stellen.
Die komplette Funktionalität der B2B Edition ist in der (passwortgeschützten) Anwenderdokumentation beschrieben https://docs.oxid-esales.com/de/b2b-edition/einfuehrung.html
Wir werden in diesem Blogpost anhand von einem der B2B Edition Features, dem Genehmigungsverfahren, beispielhaft zeigen, wie wir die GraphQL-Funktionalität um die OXID B2B-Features ergänzt haben (OXID B2B GraphQL-Funktionalität).
OXID GraphQL-Schnittstelle
Ganz kurz ein paar einführende Informationen für diejenigen, die bisher noch nicht intensiver mit der OXID GraphQL-Schnittstelle gearbeitet haben.
Folgende OXID GraphQL-Module bilden die Basis, auf welche die OXID B2B GraphQL-Funktionalität aufsetzt:
- Das **GraphQL Base-Modul** stellt den OXID GraphQL-Endpunkt zur Verfügung
Es ist verantwortlich für den Aufbau des OXID GraphQL-Schemas sowie für die Authentifizierung und Autorisierung von Zugriffen über die OXID GraphQL-Schnittstelle. Das OXID GraphQL-Schema definiert, welche Objekttypen Sie anfordern können und welche Felder enthalten sein müssen.
Im Gegensatz zum 'normalen' Frontend gibt es bei OXID GraphQL keine Session im herkömmlichen Sinn, d.h. keine Identifizierung von Kunden anhand von (session id) Cookies.
Zwischen den Anfragen werden Daten in der Datenbank persistiert. Das System identifiziert Kunden anhand eines JWT (JSON Web Token).
In jeder Anfrage an die OXID GraphQL-Schnittstelle, welche einen 'eingeloggten' Kunden erfordert, muss ein JWT im Autorisierungs-Header mitgeschickt werden.
Details dazu hier: https://docs.oxid-esales.com/interfaces/graphql/en/latest/consuming/PlaceOrder.html#retrieve-and-send-the-jwt
- Das **GraphQL Storefront-Modul** erweitert das OXID GraphQL-Schema um Frontend-Funktionalitäten des OXID eShops.
Dazu gehören unter anderem die Abfrage des Produktkatalogs, das Anlegen und Verwalten von Kundenaccounts durch den Käufer sowie der Checkout-Prozess.
Unsere ausführliche Dokumentation des OXID GraphQL Base- und des OXID GraphQL Storefront-Moduls finden Sie unter https://docs.oxid-esales.com/interfaces/graphql/en/latest/.
Die Kurzfassung
- Die OXID GraphQL-Schnittstelle hat einen einzigen Endpunkt.
- Queries (Abfragen) und Mutations (Datenänderungen) lassen sich an diesen Endpunkt schicken.
- Die OXID GraphQL-Schnittstelle hat ein (jederzeit einsehbares) Schema, welches alle verfügbaren Queries, Mutations, Datentypen und Felder beschreibt.
- Das OXID GraphQL-Schema lässt sich mit Modulen beliebig erweitern.
Systemvoraussetzungen
Die OXID eShop B2B Edition 6.5.x (rev.: 5.0.0) ist kompatibel mit der OXID eShop Enterprise Edition 6.5.x. Wer ergänzend zum herkömmlichen Frontend oder sogar ausschließlich die B2B GraphQL-Funktionalität verwenden möchte, muss als Voraussetzung die oben erwähnten Module OXID GraphQL Base und OXID GraphQL Storefront installieren und aktivieren.
B2B Frontend versus OXID GraphQL
Es gibt keine feste Grenze, ob und welche der B2B Edition-Funktionalitäten über das herkömmliche Frontend oder über die OXID GraphQL-Schnittstelle angesteuert werden. Ein Nutzer der B2B Edition kann Änderungen per OXID GraphQL ausführen und sie im Frontend auslesen und umgekehrt.
Im Hintergrund verwenden Frontend und OXID GraphQL dieselbe Logik. Um dies zu verdeutlichen, spielen wir ein Genehmigungsverfahren durch.
Genehmigungsverfahren bedeutet folgendes: Die B2B Edition führt eine Benutzer-Hierarchie ein, welche einem Chefeinkäufer mit B2B-Rechten einen oder mehrere andere Einkäufer (ebenfalls mit B2B-Rechten) unterordnet.
Einkäufer können bei aktiviertem Genehmigungsverfahren nur dann eine Bestellung durchführen, wenn der Chefeinkäufer den Warenkorb zur Bestellung freigibt.
Mit der B2B Edition kann ein Einkäufer übrigens mehrere Warenkörbe parallel vorbereiten.
Beispiel: Genehmigung eines Warenkorbs im Frontend
Frontend: Der Chefeinkäufer aktiviert das Genehmigungsverfahren für einen ihm zugeordneten Einkäufer
Frontend: Der Einkäufer befüllt den Warenkorb, kann aber nicht direkt bestellen.
Frontend: der Einkäufer wartet auf Genehmigung durch seinen Chefeinkäufer
Frontend: Sobald der Chefeinkäufer den Warenkorb freigegeben hat, kann der Einkäufer die Bestellung abschließen.
Genehmigung eines Warenkorbs über die OXID GraphQL-Schnittstelle
GraphQL: Aktivierung des Genehmigungsverfahrens für den Einkäufer
Wie bereits erwähnt, hat ab der OXID eShop B2B Edition 6.5.x (rev.: 5.0.0) jede B2B Frontend-Funktionalität eine entsprechende Query oder Mutation in der OXID GraphQL-Schnittstelle.
Das gilt auch für die Aktivierung des Genehmigungsverfahrens durch den Chefeinkäufer.
Bitte beachten Sie, dass die OXID GraphQL-Schnittstelle, wie oben erwähnt, bei jeder Anfrage auf Authentifizierung und Autorisierung prüft.
Request (B2B mutation B2BApprovalProcedureActivate)
mutation B2BApprovalProcedureActivate {
B2BApprovalProcedureActivate(customerId: "buyingagent")
}
Response (B2B mutation B2BApprovalProcedureActivate)
{
"data": {
"B2BApprovalProcedureActivate": true
}
}
Diese Anfrage kann über jeden geeigneten Client gesendet werden, wie beispielsweise Altair, aber auch einfach per Command Line durch Verwendung von curl.
OXID GraphQL-Schnittstelle: Der vom Einkäufer befüllte Warenkorb muss durch den Chefeinkäufer freigegeben werden
Ein genehmigungspflichtiger Warenkorb kann nicht 'einfach so' bestellt werden, auch nicht über die OXID GraphQL-Schnittstelle.
Wird trotzdem eine Bestellung versucht, kommt eine Fehlermeldung zurück.
Request (Storefront's placeOrder mutation)
mutation placeOrder {
placeOrder(
basketId: "05c9c30fc5e653630fde8803a23d0766"
confirmTermsAndConditions: true
remark: "checkout basket via GraphQL"
) {
id
orderNumber
}
}
Response (Storefront's placeOrder mutation)
{
"errors": [
{
"message": "Basket needs to be approved",
"extensions": {
"category": "requesterror"
},
...
"path": [
"placeOrder"
]
}
]
}
Wenn wir den Warenkorb über die OXID GraphQL-Schnittstelle abfragen, dann sehen wir zusätzliche Felder mit B2B-Präfix (z.B. B2BApprovalStatus) im GraphQL-Schema.
Request (Storefront's basket query)
query singlebasket {
basket(basketId: "05c9c30fc5e653630fde8803a23d0766") {
id
B2BName
B2BApprovalStatus
items {
amount
product {
title
}
}
}
}
Response (Storefront's basket query)
{
"data": {
"basket": {
"id": "05c9c30fc5e653630fde8803a23d0766",
"B2BName": "mein_warenkorb",
"B2BApprovalStatus": "PENDING",
"items": [
{
"amount": 1,
"product": {
"title": "Kuyichi Ledergürtel JEVER"
}
}
]
}
}
}
Wir sehen in der Antwort der OXID GraphQL-Schnittstelle, dass der betreffende Warenkorb auf Freigabe wartet (B2BApprovalStatus PENDING).
Im Frontend können wir an dieser Stelle ebenfalls den auf Genehmigung wartenden Warenkorb sehen.
Der Chefeinkäufer gibt den Warenkorb frei. Per OXID GraphQL-Schnittstelle geschieht das wie folgt
Request (mutation B2BApprovalProcedureApprove)
mutation approve {
B2BApprovalProcedureApprove
(basketId: "05c9c30fc5e653630fde8803a23d0766")
{
id
B2BName
B2BApprovalStatus
}
}
#### Response (mutation B2BApprovalProcedureApprove)
{
"data": {
"B2BApprovalProcedureApprove": {
"id": "05c9c30fc5e653630fde8803a23d0766",
"B2BName": "mein_warenkorb",
"B2BApprovalStatus": "APPROVED"
}
}
}
Nachdem der Warenkorb freigegeben wurde, kann der Einkäufer die Bestellung nun wahlweise per Frontend oder per OXID GraphQL-Schnittstelle (placeOrder mutation) abschließen.
Neugierig?
Sie möchten bestimmte Funktionen der OXID eShop B2B Edition wie in unserem Beispiel mit OXID GraphQL implementieren?
Dann machen Sie als Nutzer der OXID eShop Enterprise B2B Edition ein Update auf B2B Edition 6.5.x (rev.: 5.0.0).
Installieren Sie die kostenfreien Module OXID GraphQL Base (https://github.com/OXID-eSales/graphql-base-module) und OXID GraphQL Storefront (https://github.com/OXID-eSales/graphql-storefront-module). Danach können Sie loslegen.
Wie Sie die Module installieren, beschreiben wir unter https://docs.oxid-esales.com/interfaces/graphql/en/latest/install.html.
Empfehlung: Nutzen Sie den Altair GraphQL Client (https://altairgraphql.dev), um sich (wie auch in unserem Beispiel) mit der OXID GraphQL-Schnittstelle vertraut zu machen.
Weitere Beispiele finden sie auch in unserem Webinar https://www.oxid-esales.com/blog/oxid-graphql-mehr-freiheiten-im-client.
Sie haben alle Möglichkeiten von der Realisierung einer vollständigen eigenen Oberfläche, einer App für mobile Endgeräte oder auch ausschließlich einzelner Bereiche wie der Verwaltung der B2B-Kunden.
Senden Sie uns Feedback, damit wir unsere OXID GraphQL-Schnittstelle weiter verbessern können. Wir freuen uns auf Sie.
Sie haben als Händler Ihre OXID eShop Enterprise Edition noch nicht mit unseren B2B-Funktionalitäten erweitert? Kontaktieren Sie unser Sales-Team, um sich über Ihre Vorteile und die Konditionen zu informieren.