Abholpunkte in Headless-Storefronts und mobilen Apps
Das Warenkorb-Widget von Globe läuft in einem Shopify-Theme. Eine native mobile App auf Basis der Storefront API oder eine Headless-Web-Storefront wie Hydrogen oder Next.js hat kein Theme, in das sich das Widget einbauen ließe. Diese Anleitung zeigt, wie Käufer in solchen Apps einen Abholpunkt wählen, bevor sie zum Shopify-Checkout gelangen.
Beide Optionen unten speichern den Punkt im Warenkorb der Storefront API als Warenkorbattribute. Danach behandeln Checkout und Bestellverarbeitung den Punkt genau so wie einen, der im Warenkorb-Widget gewählt wurde.
Option wählen
Abschnitt betitelt „Option wählen“| A: Gehostete Auswahlseite | B: Storefront-API für Abholpunkte | |
|---|---|---|
| Was Sie bauen | Eine URL in einer WebView, einem Pop-up oder einem iframe öffnen | Ihre eigene Karte oder Liste in der Oberfläche Ihrer App |
| Oberfläche | Karte, Liste, Suche, Standortbestimmung und Spediteurfilter von Globe | Ihre eigene |
| Wer in den Warenkorb schreibt | Globe | Ihre App, mit cartAttributesUpdate |
| Zugangsdaten | Keine. Die Seite läuft auf der Domain Ihres Shops | Ein veröffentlichbarer Schlüssel (glb_pk_…) |
| Worum sich Ihre App kümmert | Seite öffnen und Ergebnis lesen | Standort, Suche, Punkteliste und Schreiben in den Warenkorb |
Beginnen Sie mit A, wenn es schnell funktionieren soll. Wählen Sie B, wenn sich die Auswahl wie ein nativer Teil der App anfühlen muss. Sie können später wechseln: Beide schreiben dieselben Warenkorbattribute.
Bevor Sie beginnen
Abschnitt betitelt „Bevor Sie beginnen“- Globe ist mit einem aktiven Tarif installiert.
- Headless-Abholpunkte sind für Ihren Shop aktiviert. Wir schalten die Funktion pro Shop frei: Fragen Sie uns im Support-Chat in der App. Bis dahin zeigt Einstellungen → Headless- und Mobile-Apps nur Zugang anfragen, und die Auswahlseite sowie die Storefront-API für Abholpunkte melden, dass die Funktion nicht aktiviert ist.
- Mindestens ein Abholpunkt-Spediteur ist eingerichtet und Versandmethoden zugeordnet. Siehe Abholpunkt-Spediteure hinzufügen.
- Ihre App erstellt Warenkörbe mit der Storefront API und schickt Käufer zur
checkoutUrldes Warenkorbs.
Globe einrichten
Abschnitt betitelt „Globe einrichten“Gehen Sie in der Globe-Verwaltung zu Einstellungen → Headless- und Mobile-Apps.
Für die gehostete Auswahlseite
Abschnitt betitelt „Für die gehostete Auswahlseite“- Klicken Sie unter Seite für die Abholpunkt-Auswahl auf Einschalten.
- Klicken Sie unter Rückgabe-URLs auf Rückgabe-URL hinzufügen und fügen Sie jede Adresse hinzu, zu der die Seite Käufer zurückschicken darf:
- einen App-Deep-Link, zum Beispiel
myapp://pickup, - einen Universal Link oder Android App Link, zum Beispiel
https://app.example.com/pickup, - eine Webadresse Ihrer Headless-Storefront, zum Beispiel
https://shop.example.com/cart.
- einen App-Deep-Link, zum Beispiel
- Klicken Sie in der Speicherleiste auf Speichern.
Rückgabe-URLs sind optional, wenn Ihre App das Ergebnis nur über eine native Bridge oder postMessage liest. Für Weiterleitungen sind sie erforderlich, und die Web-Origins für postMessage stammen aus den https-Rückgabe-URLs. Siehe Return URLs.
Wenn der Bereich meldet, dass Globe die Berechtigungen für den Storefront-Warenkorb benötigt, öffnen Sie Globe einmal aus Ihrer Shopify-Verwaltung und bestätigen Sie die aktualisierten Berechtigungen. Bis dahin zeigt die Seite an, dass die Auswahl nicht verfügbar ist.
Für die Storefront-API für Abholpunkte
Abschnitt betitelt „Für die Storefront-API für Abholpunkte“- Klicken Sie unter Storefront-API für Abholpunkte auf Schlüssel erstellen und kopieren Sie den veröffentlichbaren Schlüssel.
- Optional: Klicken Sie unter Zulässige Web-Origins auf Origin hinzufügen und fügen Sie die Origins Ihrer Web-Storefront hinzu, zum Beispiel
https://shop.example.com. Ist kein Origin eingetragen, kann jede Website den Schlüssel verwenden. Native Apps sind davon nie betroffen. - Klicken Sie in der Speicherleiste auf Speichern.
Ein veröffentlichbarer Schlüssel durchsucht nur die Abholpunkte Ihrer Spediteure. Sie können ihn daher gefahrlos in einer App oder einem Browser-Bundle ausliefern. Siehe Authentication.
Option A: gehostete Auswahlseite
Abschnitt betitelt „Option A: gehostete Auswahlseite“-
Erstellen oder laden Sie den Warenkorb des Käufers mit der Storefront API und merken Sie sich seine
id. -
Öffnen Sie diese URL auf der Domain Ihres Shops:
https://{shop domain}/apps/appfleece-globe/select?cart={URL-encoded cart id}&return_url={allowlisted URL}&state={your value} -
Der Käufer wählt einen Punkt. Globe prüft ihn beim Spediteur und schreibt die Warenkorbattribute.
-
Ihre App erhält das Ergebnis: eine Weiterleitung zur
return_url, eine Nachricht über die native Bridge oderpostMessage. -
Fragen Sie den Warenkorb erneut ab und fahren Sie mit der
checkoutUrlfort.
Alle Parameter, Ergebnismeldungen und Code für iOS, Android, React Native und Hydrogen finden Sie unter Hosted selection page.
Option B: Storefront-API für Abholpunkte
Abschnitt betitelt „Option B: Storefront-API für Abholpunkte“- Fragen Sie den Standort des Käufers ab, oder lassen Sie ihn eine Karte verschieben.
- Suchen Sie Punkte:
GET https://api-globe.appfleece.app/v1/storefront/pickup-points?country=CZ&latitude=…&longitude=…mit dem HeaderX-Globe-Publishable-Key. - Zeigen Sie die Punkte an. Wenn der Käufer einen wählt, übernehmen Sie dessen
cart_attributes. - Führen Sie sie mit den vorhandenen Attributen des Warenkorbs zusammen und schreiben Sie die Liste mit der Storefront-API-Mutation
cartAttributesUpdate. - Fahren Sie mit der
checkoutUrlfort.
Endpunkte und Code für curl, Swift, Kotlin, TypeScript und Hydrogen finden Sie unter Storefront pickup API.
Vertrag der Warenkorbattribute
Abschnitt betitelt „Vertrag der Warenkorbattribute“Beide Optionen enden mit diesen Attributen im Warenkorb:
| Schlüssel | Wert |
|---|---|
globe_PickupPointId | Die ID des Punkts |
globe_PickupPointName | Der Name des Punkts |
globe_PickupPointAddress | Die Adresse in einer Zeile |
globe_PickupPointData | Der vollständige Punkt als JSON-String |
globe_DeliveryMethod | pickup |
globe_PickupPointCustomerId | Die DHL-Postnummer, sonst leer |
Schreiben Sie die vollständigen cart_attributes genau so, wie die Storefront-API für Abholpunkte sie zurückgibt. Globe akzeptiert globe_PickupPointId allein nur als Fallback und nur für Spediteurnetze, die Globe selbst speichert. Bei Spediteuren, die Globe live abfragt, etwa GLS oder DHL, lässt sich eine ID allein nicht prüfen, und der Punkt wird nicht in der Bestellung gespeichert.
Wechselt der Käufer zur Zustellung an die Adresse, entfernen Sie die Punkt-Schlüssel aus dem Warenkorb. Unter Cart attributes finden Sie den vollständigen Vertrag, den Fallback mit reiner ID und die Angaben, die bei Zustellung an die Adresse geschrieben werden sollen.
Was im Checkout passiert
Abschnitt betitelt „Was im Checkout passiert“Der Checkout liest die Warenkorbattribute über die Lieferanpassung von Globe, sofern Sie sie unter Einstellungen → Warenkorb-Widget → Checkout-Lieferanpassung eingeschaltet haben:
- Nur die Versandtarife des Spediteurs des gewählten Punkts bleiben sichtbar.
- Wenn Sie dort die Umbenennung von Tarifen eingerichtet haben, zeigt der Tarif den Namen des Punkts.
- Ändert der Käufer im Checkout das Lieferland auf ein Land, in dem der Punkt nicht liegt, zeigt der Checkout wie gewohnt alle Tarife.
Mit der gehosteten Auswahlseite und eingeschalteter Checkout-Adressvorausfüllung öffnet sich der Checkout zudem mit der Adresse des Punkts als Lieferadresse. Der Käufer kann sie trotzdem ändern. Die Storefront-API für Abholpunkte lässt die Lieferadresse unverändert.
Was beim Erstellen der Bestellung passiert
Abschnitt betitelt „Was beim Erstellen der Bestellung passiert“Wenn Shopify die Bestellung erstellt, liest Globe die Warenkorbattribute und prüft den Punkt im Netz des Spediteurs. Das gilt für jeden Kanal, auch für das Warenkorb-Widget im Theme.
| Ergebnis | Was Globe tut |
|---|---|
| Der Punkt existiert und ist aktiv | Ersetzt Name, Adresse und Koordinaten des Punkts durch die Daten des Spediteurs, speichert ihn in der Bestellung (Metafeld Globe.PickupPoint) und wendet die Tags, Bestellattribute und die Notiz des Spediteurs an |
| Der Punkt wird nicht gefunden, ist inaktiv, liegt in einem anderen Land, gehört zu einem Spediteur, der der Versandmethode der Bestellung nicht zugeordnet ist, oder die Versandmethode ist kein Abholpunkt-Tarif | Speichert keinen Punkt. Die Bestellung erhält das Tag Fehlender Abholpunkt (Standard point_unselected), sofern Sie eines festgelegt haben, und der übliche Erinnerungsablauf greift |
| Der Spediteur ist nicht erreichbar | Behält den Punkt aus globe_PickupPointData des Warenkorbs unverändert bei |
Der Warenkorb hatte nur globe_PickupPointId, und Globe konnte die ID nicht prüfen (bei Spediteuren, die Globe live abfragt, etwa GLS oder DHL, immer der Fall) | Speichert keinen Punkt und wendet das Tag für fehlende Abholpunkte an |
Labels, Exporte und ERP- oder WMS-Integrationen sehen dieselben Felder wie bei Bestellungen aus Ihrem Onlineshop. Siehe Punkt-Metafeld.
Fehlerbehebung
Abschnitt betitelt „Fehlerbehebung“Die Seite meldet „Die Auswahl des Abholpunkts ist für diesen Shop nicht aktiviert.“ Schalten Sie die Seite unter Einstellungen → Headless- und Mobile-Apps ein. Zeigt dieser Bereich nur Zugang anfragen, sind Headless-Abholpunkte für Ihren Shop noch nicht aktiviert. Fragen Sie uns im Support-Chat.
Die Storefront-API für Abholpunkte antwortet mit 403 access_required und „Headless pickup is not enabled for this shop.“
Die Funktion wird pro Shop aktiviert. Fragen Sie uns im Support-Chat. Ein früher erstellter Schlüssel funktioniert, sobald sie eingeschaltet ist.
Die Seite meldet „Dieser Warenkorb existiert nicht mehr.“ Der Warenkorb ist abgelaufen, wurde bereits in eine Bestellung umgewandelt oder gehört zu einem anderen Shop. Erstellen Sie einen neuen Warenkorb und öffnen Sie die Seite erneut.
Die Seite meldet „Diese Rückgabe-URL ist für diesen Shop nicht erlaubt.“
return_url beginnt nicht mit einer Ihrer Rückgabe-URLs. Prüfen Sie Schema, Host und Pfad. Subdomains werden nicht berücksichtigt.
Die Seite meldet „Die Auswahl des Abholpunkts ist vorübergehend nicht verfügbar.“ Globe hat keinen aktiven Tarif, oder die Berechtigungen für den Storefront-Warenkorb wurden nicht bestätigt. Öffnen Sie Globe aus Ihrer Shopify-Verwaltung.
Die Seite fragt nach einem Passwort. Der Onlineshop ist passwortgeschützt, wie es bei Entwicklungsshops der Fall ist. Geben Sie das Storefront-Passwort einmal in derselben WebView oder demselben Browser ein.
Die Bestellung hat keinen Abholpunkt.
Prüfen Sie, ob die Bestellung Ihr Tag für fehlende Abholpunkte trägt. Prüfen Sie dann, ob der Warenkorb vor dem Checkout globe_PickupPointData enthielt, ob der Käufer einen Abholpunkt-Tarif desselben Spediteurs gewählt hat und ob das Lieferland zu dem des Punkts passt.
Die API antwortet mit 403 origin_not_allowed.
Fügen Sie den Origin der Website unter Zulässige Web-Origins hinzu, oder entfernen Sie alle Origins, um jede Website zuzulassen.
Die API antwortet bei jedem Käufer mit 429 rate_limited.
Ihr Server ruft die API für alle Käufer von einer einzigen IP-Adresse auf. Rufen Sie sie stattdessen vom Gerät oder Browser des Käufers auf. Siehe Rate limits.
Der Checkout zeigt Abholpunkt-Tarife anderer Spediteure.
Schalten Sie Checkout-Lieferanpassung unter Einstellungen → Warenkorb-Widget ein, und stellen Sie sicher, dass der Warenkorb globe_PickupPointData enthält, nicht nur die ID.