Przejdź do głównej zawartości
Ten przewodnik jest przeznaczony dla deweloperów.

Punkty odbioru w sklepach headless i aplikacjach mobilnych

Widżet koszyka Globe działa w motywie Shopify. Natywna aplikacja mobilna zbudowana na Storefront API albo sklep headless, na przykład na Hydrogen lub Next.js, nie ma motywu, w którym można by go umieścić. Ten przewodnik pokazuje, jak kupujący w takich aplikacjach wybierają punkt odbioru, zanim dotrą do kasy Shopify.

Obie opcje opisane poniżej zapisują punkt w koszyku Storefront API jako atrybuty koszyka. Od tego momentu kasa i przetwarzanie zamówienia traktują punkt dokładnie tak samo jak punkt wybrany w widżecie koszyka.


A: hostowana strona wyboruB: Storefront API punktów odbioru
Co budujeszOtwierasz adres URL w WebView, oknie popup lub iframeWłasną mapę lub listę w interfejsie swojej aplikacji
InterfejsMapa, lista, wyszukiwarka, geolokalizacja i filtr przewoźników GlobeTwój własny
Kto zapisuje koszykGlobeTwoja aplikacja, przez cartAttributesUpdate
Dane uwierzytelniająceBrak. Strona działa w domenie Twojego sklepuKlucz publiczny (glb_pk_…)
Czym zajmuje się Twoja aplikacjaOtwarciem strony i odczytaniem wynikuLokalizacją, wyszukiwaniem, listą punktów i zapisem koszyka

Zacznij od opcji A, jeśli chcesz szybko mieć działające rozwiązanie. Wybierz B, gdy selektor ma wyglądać i działać natywnie. Później możesz przejść na drugą opcję: obie zapisują te same atrybuty koszyka.


  • Globe jest zainstalowany i ma aktywny plan.
  • Wybór punktu w trybie headless jest włączony dla Twojego sklepu. Włączamy go dla każdego sklepu osobno: napisz do nas na czacie wsparcia w aplikacji. Do tego czasu sekcja Ustawienia → Aplikacje headless i mobilne pokazuje tylko przycisk Poproś o dostęp, a strona wyboru i Storefront API punktów odbioru odpowiadają, że funkcja nie jest włączona.
  • Co najmniej jeden przewoźnik z punktami odbioru jest skonfigurowany i przypisany do metod wysyłki. Zobacz Dodawanie przewoźników z punktami odbioru.
  • Twoja aplikacja tworzy koszyki przez Storefront API i kieruje kupujących na checkoutUrl koszyka.

W panelu Globe przejdź do Ustawienia → Aplikacje headless i mobilne.

  1. W sekcji Strona wyboru punktu odbioru kliknij Włącz.
  2. W sekcji Adresy powrotu kliknij Dodaj adres powrotu i dodaj każdy adres, na który strona może odesłać kupujących:
    • deep link aplikacji, na przykład myapp://pickup,
    • universal link lub Android App Link, na przykład https://app.example.com/pickup,
    • adres internetowy Twojego sklepu headless, na przykład https://shop.example.com/cart.
  3. Kliknij Zapisz na pasku zapisu.

Adresy powrotu są opcjonalne, jeśli Twoja aplikacja odczytuje wynik wyłącznie przez natywny most lub postMessage. Są wymagane przy przekierowaniach, a dozwolone źródła dla postMessage pochodzą z adresów powrotu https. Zobacz Adresy powrotu.

Jeśli karta informuje, że Globe potrzebuje uprawnień do koszyka sklepu, otwórz raz Globe z panelu administracyjnego Shopify i zatwierdź zaktualizowane uprawnienia. Do tego czasu strona pokazuje, że wybór jest niedostępny.

  1. W sekcji Storefront API punktów odbioru kliknij Utwórz klucz i skopiuj klucz publiczny.
  2. Opcjonalnie: w sekcji Dozwolone źródła internetowe kliknij Dodaj źródło i dodaj źródła (origins) swojego sklepu internetowego, na przykład https://shop.example.com. Bez żadnych źródeł na liście klucza może używać każda strona internetowa. Aplikacji natywnych to nie dotyczy.
  3. Kliknij Zapisz na pasku zapisu.

Klucz publiczny służy tylko do wyszukiwania punktów odbioru Twoich przewoźników, dlatego można go bezpiecznie umieścić w aplikacji lub w kodzie uruchamianym w przeglądarce. Zobacz Uwierzytelnianie.


  1. Utwórz lub wczytaj koszyk kupującego przez Storefront API i zachowaj jego id.

  2. Otwórz ten adres URL w domenie swojego sklepu:

    https://{shop domain}/apps/appfleece-globe/select?cart={URL-encoded cart id}&return_url={allowlisted URL}&state={your value}
  3. Kupujący wybiera punkt. Globe weryfikuje go u przewoźnika i zapisuje atrybuty koszyka.

  4. Twoja aplikacja otrzymuje wynik: przekierowanie na return_url, wiadomość przez natywny most albo postMessage.

  5. Pobierz koszyk ponownie i przejdź do checkoutUrl.

Pełną listę parametrów, komunikaty wyniku i kod dla iOS, Androida, React Native i Hydrogen znajdziesz na stronie Hosted selection page.

  1. Poproś kupującego o lokalizację albo pozwól mu przesuwać mapę.
  2. Wyszukaj: GET https://api-globe.appfleece.app/v1/storefront/pickup-points?country=CZ&latitude=…&longitude=… z nagłówkiem X-Globe-Publishable-Key.
  3. Wyświetl punkty. Gdy kupujący wybierze jeden z nich, pobierz jego cart_attributes.
  4. Scal je z istniejącymi atrybutami koszyka i zapisz listę mutacją Storefront API cartAttributesUpdate.
  5. Przejdź do checkoutUrl.

Endpointy i kod dla curl, Swift, Kotlin, TypeScript i Hydrogen znajdziesz na stronie Storefront pickup API.


Obie opcje kończą się tymi atrybutami w koszyku:

KluczWartość
globe_PickupPointIdID punktu
globe_PickupPointNameNazwa punktu
globe_PickupPointAddressAdres w jednej linii
globe_PickupPointDataPełne dane punktu jako ciąg JSON
globe_DeliveryMethodpickup
globe_PickupPointCustomerIdPostnummer DHL, w przeciwnym razie puste

Zapisz pełne cart_attributes dokładnie w takiej postaci, w jakiej zwraca je Storefront API punktów odbioru. Globe akceptuje samo globe_PickupPointId tylko awaryjnie i tylko dla sieci przewoźników, które Globe przechowuje u siebie. U przewoźników, których Globe odpytuje na żywo, na przykład GLS lub DHL, samego ID nie da się zweryfikować i punkt nie zostanie zapisany w zamówieniu.

Gdy kupujący przełączy się na dostawę do domu, usuń klucze punktu z koszyka. Na stronie Cart attributes znajdziesz pełny kontrakt, tryb awaryjny z samym ID oraz informacje o tym, co zapisać przy dostawie do domu.


Kasa odczytuje atrybuty koszyka przez dostosowanie dostawy Globe, jeśli jest ono włączone w Ustawienia → Widget koszyka → Dostosowanie dostawy w kasie:

  • Widoczne pozostają tylko stawki wysyłki przewoźnika wybranego punktu.
  • Jeśli skonfigurujesz tam zmianę nazw stawek, stawka pokazuje nazwę punktu.
  • Jeśli kupujący zmieni w kasie kraj dostawy na taki, w którym punkt się nie znajduje, kasa pokazuje wszystkie stawki jak zwykle.

Przy hostowanej stronie wyboru i włączonej opcji Automatyczne wypełnianie adresu w kasie kasa otwiera się również z adresem punktu jako adresem dostawy. Kupujący nadal może go zmienić. Storefront API punktów odbioru nie zmienia adresu dostawy.

Gdy Shopify tworzy zamówienie, Globe odczytuje atrybuty koszyka i weryfikuje punkt w sieci przewoźnika. Dotyczy to każdego kanału, łącznie z widżetem koszyka w motywie.

WynikCo robi Globe
Punkt istnieje i jest aktywnyZastępuje nazwę, adres i współrzędne punktu danymi przewoźnika, zapisuje punkt w zamówieniu (metafield Globe.PickupPoint) i stosuje tagi, atrybuty zamówienia i notatkę przewoźnika
Punkt nie został znaleziony, jest nieaktywny, znajduje się w innym kraju, należy do przewoźnika nieprzypisanego do metody wysyłki zamówienia albo metoda wysyłki nie jest stawką do punktu odbioruNie zapisuje punktu. Zamówienie otrzymuje tag Brak punktu odbioru (domyślnie point_unselected), jeśli go ustawisz, i działa zwykły proces przypomnień
Nie można połączyć się z przewoźnikiemZachowuje punkt z globe_PickupPointData koszyka bez zmian
Koszyk miał tylko globe_PickupPointId i Globe nie mógł go zweryfikować (zawsze u przewoźników, których Globe odpytuje na żywo, na przykład GLS lub DHL)Nie zapisuje punktu i stosuje tag braku punktu

Etykiety, eksporty oraz integracje ERP i WMS widzą te same pola co w zamówieniach z Twojego sklepu internetowego. Zobacz Metafield punktu odbioru.


Strona pokazuje komunikat „Wybór punktu odbioru nie jest włączony w tym sklepie.” Włącz stronę w Ustawienia → Aplikacje headless i mobilne. Jeśli ta sekcja pokazuje tylko Poproś o dostęp, wybór punktu w trybie headless nie jest jeszcze włączony dla Twojego sklepu. Napisz do nas na czacie wsparcia.

Storefront API punktów odbioru odpowiada 403 access_required z komunikatem „Headless pickup is not enabled for this shop.” Funkcja jest włączana dla każdego sklepu osobno. Napisz do nas na czacie wsparcia. Klucz utworzony wcześniej zacznie działać, gdy tylko funkcja zostanie włączona.

Strona pokazuje komunikat „Ten koszyk już nie istnieje.” Koszyk wygasł, został już zamieniony w zamówienie albo należy do innego sklepu. Utwórz nowy koszyk i otwórz stronę ponownie.

Strona pokazuje komunikat „Ten adres powrotu nie jest dozwolony dla tego sklepu.” return_url nie zaczyna się od żadnego z Twoich adresów powrotu. Sprawdź schemat, host i ścieżkę. Subdomeny nie są dopasowywane.

Strona pokazuje komunikat „Wybór punktu odbioru jest chwilowo niedostępny.” Globe nie ma aktywnego planu albo uprawnienia do koszyka sklepu nie zostały zatwierdzone. Otwórz Globe z panelu administracyjnego Shopify.

Strona prosi o hasło. Sklep internetowy jest chroniony hasłem, tak jak sklepy deweloperskie. Wprowadź raz hasło do sklepu w tym samym WebView lub w tej samej przeglądarce.

Zamówienie nie ma punktu odbioru. Sprawdź, czy wśród tagów zamówienia jest Twój tag braku punktu. Następnie sprawdź, czy koszyk miał globe_PickupPointData przed przejściem do kasy, czy kupujący wybrał stawkę do punktu odbioru tego samego przewoźnika i czy kraj dostawy zgadza się z krajem punktu.

API odpowiada 403 origin_not_allowed. Dodaj źródło strony internetowej w sekcji Dozwolone źródła internetowe albo usuń wszystkie źródła, aby dopuścić każdą stronę.

API odpowiada 429 rate_limited dla każdego kupującego. Twój serwer wywołuje API dla wszystkich kupujących z jednego adresu IP. Wywołuj je zamiast tego z urządzenia lub przeglądarki kupującego. Zobacz Limity zapytań.

Kasa pokazuje stawki do punktów odbioru innych przewoźników. Włącz Dostosowanie dostawy w kasie w Ustawienia → Widget koszyka i upewnij się, że koszyk ma globe_PickupPointData, a nie tylko ID.