Aller au contenu
Ce guide est destiné spécifiquement aux développeurs.

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.


A : page de sélection hébergéeB : Storefront API des points relais
Ce que vous construisezUne URL à ouvrir dans une WebView, une fenêtre pop-up ou une iframeVotre propre carte ou liste, dans l’interface de votre application
InterfaceLa carte, la liste, la recherche, la géolocalisation et le filtre par transporteur de GlobeLa vôtre
Qui écrit dans le panierGlobeVotre application, avec cartAttributesUpdate
IdentifiantsAucun. La page s’exécute sur le domaine de votre boutiqueUne clé publiable (glb_pk_…)
Ce que gère votre applicationL’ouverture de la page et la lecture du résultatLa 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.


  • 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 checkoutUrl du panier.

Dans Globe, accédez à Paramètres → Applications headless et mobiles.

  1. Sous Page de sélection du point relais, cliquez sur Activer.
  2. 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.
  3. 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.

  1. Sous Storefront API des points relais, cliquez sur Créer une clé et copiez la clé publiable.
  2. 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.
  3. 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.


  1. Créez ou chargez le panier de l’acheteur avec la Storefront API et conservez son id.

  2. 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}
  3. L’acheteur choisit un point. Globe le vérifie auprès du transporteur et écrit les attributs de panier.

  4. Votre application reçoit le résultat : une redirection vers return_url, un message du pont natif ou postMessage.

  5. 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.

  1. Demandez la position de l’acheteur, ou laissez-le déplacer une carte.
  2. Recherchez : GET https://api-globe.appfleece.app/v1/storefront/pickup-points?country=CZ&latitude=…&longitude=… avec l’en-tête X-Globe-Publishable-Key.
  3. Affichez les points. Lorsque l’acheteur en choisit un, récupérez ses cart_attributes.
  4. Fusionnez-les avec les attributs existants du panier et écrivez la liste avec la mutation cartAttributesUpdate de la Storefront API.
  5. Redirigez l’acheteur vers le checkoutUrl.

Les endpoints et le code pour curl, Swift, Kotlin, TypeScript et Hydrogen se trouvent dans Storefront pickup API.


À la fin des deux options, le panier contient ces attributs :

CléValeur
globe_PickupPointIdL’ID du point
globe_PickupPointNameLe nom du point
globe_PickupPointAddressL’adresse sur une ligne
globe_PickupPointDataLe point complet sous forme de chaîne JSON
globe_DeliveryMethodpickup
globe_PickupPointCustomerIdLe 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.


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.

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ésultatCe que fait Globe
Le point existe et est actifRemplace 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 relaisN’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 injoignableConserve 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.


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.