Points relais pour le headless et les applications mobiles
Le widget panier de Globe s’intègre à un thème Shopify. Une application mobile native construite sur la Storefront API, ou une boutique web headless comme Hydrogen ou Next.js, n’a pas de thème où le placer. Ce guide explique comment permettre aux acheteurs de ces applications de choisir un point relais avant d’arriver au checkout Shopify.
Les deux options ci-dessous enregistrent le point dans le panier de la Storefront API sous forme d’attributs de panier. À partir de là, le checkout et le traitement de la commande gèrent le point exactement comme un point choisi dans le widget panier.
Choisir une option
Section intitulée « Choisir une option »| A : page de sélection hébergée | B : Storefront API des points relais | |
|---|---|---|
| Ce que vous construisez | Une URL à ouvrir dans une WebView, une fenêtre pop-up ou une iframe | Votre propre carte ou liste, dans l’interface de votre application |
| Interface | La carte, la liste, la recherche, la géolocalisation et le filtre par transporteur de Globe | La vôtre |
| Qui écrit dans le panier | Globe | Votre application, avec cartAttributesUpdate |
| Identifiants | Aucun. La page s’exécute sur le domaine de votre boutique | Une clé publiable (glb_pk_…) |
| Ce que gère votre application | L’ouverture de la page et la lecture du résultat | La position, la recherche, la liste des points et l’écriture dans le panier |
Commencez par A si vous voulez une solution opérationnelle rapidement. Choisissez B lorsque le sélecteur doit avoir l’aspect et le comportement d’une interface native. Vous pourrez changer plus tard : les deux écrivent les mêmes attributs de panier.
Avant de commencer
Section intitulée « Avant de commencer »- Globe est installé avec un forfait actif.
- Les points relais headless sont activés pour votre boutique. Nous les activons boutique par boutique : demandez-le-nous dans le chat de support de l’application. D’ici là, Paramètres → Applications headless et mobiles n’affiche que Demander l’accès, et la page de sélection comme la Storefront API des points relais répondent que la fonctionnalité n’est pas activée.
- Au moins un transporteur de points de retrait est configuré et associé à des méthodes d’expédition. Voir Ajouter des transporteurs avec points de retrait.
- Votre application crée les paniers avec la Storefront API et envoie les acheteurs vers le
checkoutUrldu panier.
Configurer Globe
Section intitulée « Configurer Globe »Dans Globe, accédez à Paramètres → Applications headless et mobiles.
Pour la page de sélection hébergée
Section intitulée « Pour la page de sélection hébergée »- Sous Page de sélection du point relais, cliquez sur Activer.
- Sous URL de retour, cliquez sur Ajouter une URL de retour et ajoutez chaque adresse vers laquelle la page peut renvoyer les acheteurs :
- un deep link d’application, par exemple
myapp://pickup, - un universal link ou un Android App Link, par exemple
https://app.example.com/pickup, - une adresse web de votre boutique headless, par exemple
https://shop.example.com/cart.
- un deep link d’application, par exemple
- Cliquez sur Enregistrer dans la barre d’enregistrement.
Les URL de retour sont facultatives si votre application lit le résultat uniquement par un pont natif ou par postMessage. Elles sont obligatoires pour les redirections, et les origines web pour postMessage sont tirées des URL de retour en https. Voir Return URLs.
Si cette section indique que Globe a besoin des autorisations de panier de la boutique, ouvrez Globe une fois depuis votre admin Shopify et approuvez les autorisations mises à jour. D’ici là, la page indique que la sélection n’est pas disponible.
Pour la Storefront API des points relais
Section intitulée « Pour la Storefront API des points relais »- Sous Storefront API des points relais, cliquez sur Créer une clé et copiez la clé publiable.
- Facultatif : sous Origines web autorisées, cliquez sur Ajouter une origine et ajoutez les origines de votre boutique web, par exemple
https://shop.example.com. Si aucune origine n’est indiquée, n’importe quel site web peut utiliser la clé. Cette restriction ne s’applique jamais aux applications natives. - Cliquez sur Enregistrer dans la barre d’enregistrement.
Une clé publiable ne permet que de rechercher les points relais de vos transporteurs : elle peut donc être intégrée sans risque dans une application ou dans un bundle côté navigateur. Voir Authentication.
Option A : page de sélection hébergée
Section intitulée « Option A : page de sélection hébergée »-
Créez ou chargez le panier de l’acheteur avec la Storefront API et conservez son
id. -
Ouvrez cette URL sur le domaine de votre boutique :
https://{shop domain}/apps/appfleece-globe/select?cart={URL-encoded cart id}&return_url={allowlisted URL}&state={your value} -
L’acheteur choisit un point. Globe le vérifie auprès du transporteur et écrit les attributs de panier.
-
Votre application reçoit le résultat : une redirection vers
return_url, un message du pont natif oupostMessage. -
Interrogez à nouveau le panier et redirigez l’acheteur vers le
checkoutUrl.
Tous les paramètres, les messages de résultat et le code pour iOS, Android, React Native et Hydrogen se trouvent dans Hosted selection page.
Option B : Storefront API des points relais
Section intitulée « Option B : Storefront API des points relais »- Demandez la position de l’acheteur, ou laissez-le déplacer une carte.
- Recherchez :
GET https://api-globe.appfleece.app/v1/storefront/pickup-points?country=CZ&latitude=…&longitude=…avec l’en-têteX-Globe-Publishable-Key. - Affichez les points. Lorsque l’acheteur en choisit un, récupérez ses
cart_attributes. - Fusionnez-les avec les attributs existants du panier et écrivez la liste avec la mutation
cartAttributesUpdatede la Storefront API. - Redirigez l’acheteur vers le
checkoutUrl.
Les endpoints et le code pour curl, Swift, Kotlin, TypeScript et Hydrogen se trouvent dans Storefront pickup API.
Le contrat des attributs de panier
Section intitulée « Le contrat des attributs de panier »À la fin des deux options, le panier contient ces attributs :
| Clé | Valeur |
|---|---|
globe_PickupPointId | L’ID du point |
globe_PickupPointName | Le nom du point |
globe_PickupPointAddress | L’adresse sur une ligne |
globe_PickupPointData | Le point complet sous forme de chaîne JSON |
globe_DeliveryMethod | pickup |
globe_PickupPointCustomerId | Le Postnummer DHL, sinon vide |
Écrivez les cart_attributes complets exactement tels que la Storefront API des points relais les renvoie. Globe n’accepte globe_PickupPointId seul qu’en solution de repli, et uniquement pour les réseaux de transporteurs que Globe stocke lui-même : pour les transporteurs que Globe interroge en direct, comme GLS ou DHL, un ID seul ne peut pas être vérifié et le point n’est pas enregistré dans la commande.
Lorsque l’acheteur passe à la livraison à domicile, retirez du panier les clés du point. Cart attributes présente le contrat complet, la solution de repli avec l’ID seul et ce que la livraison à domicile doit écrire.
Ce qui se passe au checkout
Section intitulée « Ce qui se passe au checkout »Le checkout lit les attributs de panier via la personnalisation de la livraison de Globe, si vous l’avez activée dans Paramètres → Widget du panier → Personnalisation de la livraison au checkout :
- Seuls les tarifs d’expédition du transporteur du point sélectionné restent visibles.
- Si vous y avez configuré le renommage des tarifs, le tarif affiche le nom du point.
- Si l’acheteur change, au checkout, le pays de livraison pour un pays où le point ne se trouve pas, le checkout affiche tous les tarifs comme d’habitude.
Avec la page de sélection hébergée et le Préremplissage de l’adresse au checkout activé, le checkout s’ouvre aussi avec l’adresse du point comme adresse de livraison. L’acheteur peut toujours la modifier. La Storefront API des points relais ne touche pas à l’adresse de livraison.
Ce qui se passe à la création de la commande
Section intitulée « Ce qui se passe à la création de la commande »Lorsque Shopify crée la commande, Globe lit les attributs de panier et vérifie le point auprès du réseau du transporteur. Cela s’applique à tous les canaux, y compris le widget panier du thème.
| Résultat | Ce que fait Globe |
|---|---|
| Le point existe et est actif | Remplace le nom, l’adresse et les coordonnées du point par les données du transporteur, l’enregistre dans la commande (metafield Globe.PickupPoint) et applique les tags, les attributs de commande et la note du transporteur |
| Le point est introuvable, inactif, situé dans un autre pays, appartient à un transporteur non associé à la méthode d’expédition de la commande, ou la méthode d’expédition n’est pas un tarif en point relais | N’enregistre aucun point. La commande reçoit le tag Point de retrait manquant (par défaut point_unselected) si vous en avez défini un, et le processus de rappel habituel s’applique |
| Le transporteur est injoignable | Conserve tel quel le point issu de globe_PickupPointData du panier |
Le panier ne contenait que globe_PickupPointId et Globe n’a pas pu le vérifier (toujours le cas pour les transporteurs que Globe interroge en direct, comme GLS ou DHL) | N’enregistre aucun point et applique le tag de point manquant |
Les étiquettes, les exports et les intégrations ERP ou WMS voient les mêmes champs que pour les commandes de votre boutique en ligne. Voir Metafield du point de retrait.
Dépannage
Section intitulée « Dépannage »La page affiche « Pickup point selection is not enabled for this shop. » Activez la page dans Paramètres → Applications headless et mobiles. Si cette section n’affiche que Demander l’accès, les points relais headless ne sont pas encore activés pour votre boutique. Demandez-le-nous dans le chat de support.
La Storefront API des points relais répond 403 access_required avec « Headless pickup is not enabled for this shop. »
La fonctionnalité est activée boutique par boutique. Demandez-le-nous dans le chat de support. Une clé créée auparavant fonctionne dès que la fonctionnalité est activée.
La page affiche « This cart no longer exists. » Le panier a expiré, a déjà été converti en commande ou appartient à une autre boutique. Créez un nouveau panier et ouvrez à nouveau la page.
La page affiche « This return address is not allowed for this shop. »
return_url ne commence par aucune de vos URL de retour. Vérifiez le schéma, l’hôte et le chemin. Les sous-domaines ne sont pas pris en compte.
La page affiche « Pickup point selection is temporarily unavailable. » Globe n’a pas de forfait actif, ou les autorisations de panier de la boutique n’ont pas été approuvées. Ouvrez Globe depuis votre admin Shopify.
La page demande un mot de passe. La boutique en ligne est protégée par un mot de passe, comme les boutiques de développement. Saisissez une fois le mot de passe de la boutique dans la même WebView ou le même navigateur.
La commande n’a pas de point relais.
Vérifiez si les tags de la commande contiennent votre tag de point manquant. Vérifiez ensuite que le panier avait globe_PickupPointData avant le checkout, que l’acheteur a choisi un tarif en point relais du même transporteur et que le pays de livraison correspond à celui du point.
L’API répond 403 origin_not_allowed.
Ajoutez l’origine du site web sous Origines web autorisées, ou supprimez toutes les origines pour autoriser n’importe quel site web.
L’API répond 429 rate_limited pour tous les acheteurs.
Votre serveur appelle l’API pour tous les acheteurs depuis une seule adresse IP. Appelez-la plutôt depuis l’appareil ou le navigateur de l’acheteur. Voir Rate limits.
Le checkout affiche les tarifs en point relais d’autres transporteurs.
Activez Personnalisation de la livraison au checkout dans Paramètres → Widget du panier, et vérifiez que le panier contient globe_PickupPointData, pas seulement l’ID.