Tovább a tartalomhoz
Ez az útmutató fejlesztőknek készült.

Átvételi pontok headless webáruházakban és mobilalkalmazásokban

A Globe kosár widgetje egy Shopify-témában fut. A Storefront API-ra épülő natív mobilalkalmazásnak vagy a headless webáruháznak (például Hydrogen- vagy Next.js-alapúnak) nincs témája, ahová a widget bekerülhetne. Ez az útmutató bemutatja, hogyan választhatnak átvételi pontot ezeknek az alkalmazásoknak a vásárlói, mielőtt a Shopify-pénztárba érnek.

Mindkét alábbi lehetőség kosárattribútumokként menti a pontot a Storefront API-n létrehozott kosárba. Innentől a pénztár és a rendelésfeldolgozás pontosan úgy kezeli a pontot, mint a kosár widgetben választottat.


A: Hosztolt kiválasztó oldalB: Átvételi pont Storefront API
Mit kell elkészítenieEgy URL megnyitását WebView-ban, felugró ablakban vagy iframe-benSaját térképet vagy listát az alkalmazása felületén
FelületA Globe térképe, listája, keresője, helymeghatározása és futárszolgálat-szűrőjeAz Öné
Ki írja a kosaratA GlobeAz Ön alkalmazása, a cartAttributesUpdate segítségével
HitelesítésNincs. Az oldal a webáruháza domainjén futPublikálható kulcs (glb_pk_…)
Mit kezel az alkalmazásaAz oldal megnyitását és az eredmény kiolvasásátA helymeghatározást, a keresést, a pontlistát és a kosár írását

Kezdje az A lehetőséggel, ha gyorsan működő megoldást szeretne. A B lehetőséget akkor válassza, ha a választónak natív megjelenésűnek és működésűnek kell lennie. Később is válthat: mindkettő ugyanazokat a kosárattribútumokat írja.


  • A Globe telepítve van, aktív előfizetéssel.
  • A headless átvétel be van kapcsolva a webáruházában. Webáruházanként kapcsoljuk be: kérje az alkalmazáson belüli ügyfélszolgálati chaten. Addig a Beállítások → Headless és mobilalkalmazások oldalon csak a Hozzáférés kérése gomb látható, a kiválasztó oldal és az Átvételi pont Storefront API pedig azt válaszolja, hogy a funkció nincs bekapcsolva.
  • Legalább egy átvételi pontos futárszolgálat be van állítva és szállítási módokhoz van rendelve. Lásd: Csomagátvételi pont futárszolgálatok hozzáadása.
  • Az alkalmazása a Storefront API-val hozza létre a kosarakat, és a kosár checkoutUrl címére küldi a vásárlókat.

A Globe adminfelületén lépjen a Beállítások → Headless és mobilalkalmazások oldalra.

  1. Az Átvételi pont kiválasztó oldal alatt kattintson a Bekapcsolás gombra.
  2. A Visszatérési URL-ek alatt kattintson a Visszatérési URL hozzáadása gombra, és adjon hozzá minden címet, ahová az oldal visszaküldheti a vásárlókat:
    • alkalmazás deep linket, például myapp://pickup,
    • universal linket vagy Android App Linket, például https://app.example.com/pickup,
    • a headless webáruháza webcímét, például https://shop.example.com/cart.
  3. Kattintson a mentési sávban a Mentés gombra.

A visszatérési URL-ek nem kötelezők, ha az alkalmazása csak natív hídon (native bridge) vagy postMessage üzeneten keresztül olvassa ki az eredményt. Átirányításhoz viszont kötelezők, és a postMessage webes eredetei is a https visszatérési URL-ekből származnak. Lásd: Visszatérési URL-ek.

Ha a kártya azt jelzi, hogy a Globe-nak szüksége van a storefront kosárengedélyekre, nyissa meg egyszer a Globe-ot a Shopify adminisztrációjából, és hagyja jóvá a frissített engedélyeket. Addig az oldal azt mutatja, hogy a választás nem érhető el.

  1. Az Átvételi pont Storefront API alatt kattintson a Kulcs létrehozása gombra, és másolja ki a publikálható kulcsot.
  2. Nem kötelező: az Engedélyezett webes eredetek alatt kattintson az Eredet hozzáadása gombra, és adja meg a webes áruháza eredeteit, például https://shop.example.com. Ha nincs megadva eredet, bármely webhely használhatja a kulcsot. A natív alkalmazásokat ez soha nem érinti.
  3. Kattintson a mentési sávban a Mentés gombra.

A publikálható kulcs csak a futárszolgálatai átvételi pontjai között keres, ezért biztonságosan beépíthető egy alkalmazásba vagy egy böngészős bundle-be. Lásd: Hitelesítés.


„A” lehetőség: hosztolt kiválasztó oldal

Szekció neve “„A” lehetőség: hosztolt kiválasztó oldal”
  1. Hozza létre vagy töltse be a vásárló kosarát a Storefront API-val, és jegyezze meg az id értékét.

  2. Nyissa meg ezt az URL-t a webáruháza domainjén:

    https://{shop domain}/apps/appfleece-globe/select?cart={URL-encoded cart id}&return_url={allowlisted URL}&state={your value}
  3. A vásárló kiválaszt egy pontot. A Globe ellenőrzi a futárszolgálatnál, és beírja a kosárattribútumokat.

  4. Az alkalmazása megkapja az eredményt: átirányítást a return_url címre, natív hídüzenetet vagy postMessage üzenetet.

  5. Kérdezze le újra a kosarat, és irányítsa tovább a vásárlót a checkoutUrl címre.

A teljes paraméterlista, az eredményüzenetek, valamint az iOS, Android, React Native és Hydrogen kódpéldák a Hosted selection page oldalon találhatók.

„B” lehetőség: Átvételi pont Storefront API

Szekció neve “„B” lehetőség: Átvételi pont Storefront API”
  1. Kérje le a vásárló tartózkodási helyét, vagy hagyja, hogy a térképet mozgassa.
  2. Keresés: GET https://api-globe.appfleece.app/v1/storefront/pickup-points?country=CZ&latitude=…&longitude=… az X-Globe-Publishable-Key fejléccel.
  3. Jelenítse meg a pontokat. Amikor a vásárló kiválaszt egyet, vegye át annak cart_attributes értékét.
  4. Egyesítse ezeket a kosár meglévő attribútumaival, és írja be a listát a Storefront API cartAttributesUpdate mutációjával.
  5. Irányítsa tovább a vásárlót a checkoutUrl címre.

A végpontok, valamint a curl, Swift, Kotlin, TypeScript és Hydrogen kódpéldák a Storefront pickup API oldalon találhatók.


Mindkét lehetőség végén ezek az attribútumok kerülnek a kosárra:

KulcsÉrték
globe_PickupPointIdA pont azonosítója
globe_PickupPointNameA pont neve
globe_PickupPointAddressA cím egy sorban
globe_PickupPointDataA teljes pont JSON-karakterláncként
globe_DeliveryMethodpickup
globe_PickupPointCustomerIdA DHL Postnummer, egyébként üres

A teljes cart_attributes értéket pontosan úgy írja be, ahogy az Átvételi pont Storefront API visszaadja. A Globe a globe_PickupPointId értéket önmagában csak tartalékként fogadja el, és csak azoknál a futárszolgálati hálózatoknál, amelyeket maga tárol. Azoknál a futárszolgálatoknál, amelyeket a Globe élőben kérdez le (például GLS vagy DHL), egy azonosító önmagában nem ellenőrizhető, és a pont nem kerül a rendelésre.

Ha a vásárló házhozszállításra vált, távolítsa el a pont kulcsait a kosárból. A Cart attributes oldalon megtalálja a teljes szerződést, a csak azonosítót használó tartalékot, és azt is, hogy házhozszállításnál mit kell beírni.


A pénztár a Globe szállítás-testreszabásán keresztül olvassa ki a kosárattribútumokat, ha bekapcsolta a Beállítások → Kosár widget → Pénztár szállítás testreszabás alatt:

  • Csak a kiválasztott pont futárszolgálatának szállítási díjai maradnak láthatók.
  • Ha ott beállította a díjak átnevezését, a díj a pont nevét mutatja.
  • Ha a vásárló a pénztárban olyan szállítási országra vált, amelyben a pont nincs, a pénztár a szokásos módon minden díjat megjelenít.

A hosztolt kiválasztó oldallal és bekapcsolt Pénztár cím előzetes kitöltése beállítással a pénztár úgy nyílik meg, hogy a szállítási cím a pont címe. A vásárló ezt továbbra is módosíthatja. Az Átvételi pont Storefront API nem nyúl a szállítási címhez.

Mi történik a rendelés létrehozásakor

Szekció neve “Mi történik a rendelés létrehozásakor”

Amikor a Shopify létrehozza a rendelést, a Globe kiolvassa a kosárattribútumokat, és ellenőrzi a pontot a futárszolgálat hálózatában. Ez minden értékesítési csatornára vonatkozik, a téma kosár widgetjét is beleértve.

EredményMit tesz a Globe
A pont létezik és aktívA pont nevét, címét és koordinátáit a futárszolgálat adataira cseréli, menti a rendelésre (Globe.PickupPoint metamező), és alkalmazza a futárszolgálat rendeléscímkéit, rendelési attribútumait és megjegyzését
A pont nem található, inaktív, más országban van, olyan futárszolgálathoz tartozik, amely nincs a rendelés szállítási módjához rendelve, vagy a szállítási mód nem átvételi pontos díjNem ment pontot. A rendelés megkapja a Hiányzó átvételi pont rendeléscímkét (alapértelmezés: point_unselected), ha beállított ilyet, és a szokásos emlékeztető folyamat indul
A futárszolgálat nem érhető elVáltozatlanul megtartja a pontot a kosár globe_PickupPointData attribútumából
A kosárban csak globe_PickupPointId szerepelt, és a Globe nem tudta ellenőrizni (az élőben lekérdezett futárszolgálatoknál, például a GLS-nél vagy a DHL-nél, ez mindig így van)Nem ment pontot, és alkalmazza a hiányzó pont rendeléscímkéjét

A címkék, az exportok és az ERP- vagy WMS-integrációk ugyanazokat a mezőket látják, mint az online áruházából érkező rendeléseknél. Lásd: Pont metamező.


Az oldalon ez áll: „Az átvételi pont választása nincs bekapcsolva ennél a boltnál.” Kapcsolja be az oldalt a Beállítások → Headless és mobilalkalmazások alatt. Ha ez a szakasz csak a Hozzáférés kérése gombot mutatja, a headless átvétel még nincs bekapcsolva a webáruházában. Kérje tőlünk az ügyfélszolgálati chaten.

Az Átvételi pont Storefront API 403 access_required hibával és a „Headless pickup is not enabled for this shop.” üzenettel válaszol. A funkciót webáruházanként kapcsoljuk be. Kérje tőlünk az ügyfélszolgálati chaten. A korábban létrehozott kulcs a bekapcsolás után működni kezd.

Az oldalon ez áll: „Ez a kosár már nem létezik.” A kosár lejárt, már rendeléssé alakult, vagy egy másik webáruházhoz tartozik. Hozzon létre új kosarat, és nyissa meg újra az oldalt.

Az oldalon ez áll: „Ez a visszatérési cím nem engedélyezett ennél a boltnál.” A return_url nem az Ön egyik visszatérési URL-jével kezdődik. Ellenőrizze a sémát, a hosztot és az útvonalat. Az aldomainek nem számítanak egyezésnek.

Az oldalon ez áll: „Az átvételi pont választása átmenetileg nem érhető el.” A Globe-nak nincs aktív előfizetése, vagy a storefront kosárengedélyeket nem hagyták jóvá. Nyissa meg a Globe-ot a Shopify adminisztrációjából.

Az oldal jelszót kér. Az online áruház jelszóval védett, ahogy a fejlesztői áruházak is. Adja meg egyszer a webáruház jelszavát ugyanabban a WebView-ban vagy böngészőben.

A rendelésen nincs átvételi pont. Nézze meg, hogy a rendelés címkéi között szerepel-e a hiányzó pont rendeléscímkéje. Ezután ellenőrizze, hogy a kosárban a pénztár előtt szerepelt-e globe_PickupPointData, hogy a vásárló ugyanannak a futárszolgálatnak az átvételi pontos díját választotta-e, és hogy a szállítási ország megegyezik-e a pont országával.

Az API 403 origin_not_allowed hibával válaszol. Adja hozzá a webhely eredetét az Engedélyezett webes eredetek alatt, vagy távolítson el minden eredetet, hogy bármely webhely használhassa a kulcsot.

Az API minden vásárlónak 429 rate_limited hibával válaszol. A szervere egyetlen IP-címről hívja az API-t az összes vásárló nevében. Ehelyett a vásárló eszközéről vagy böngészőjéből hívja. Lásd: Sebességkorlátok.

A pénztár más futárszolgálatok átvételi pontos díjait is mutatja. Kapcsolja be a Pénztár szállítás testreszabás opciót a Beállítások → Kosár widget alatt, és győződjön meg arról, hogy a kosárban globe_PickupPointData szerepel, nem csak az azonosító.