Přeskočit na obsah
Tento průvodce je určen speciálně pro vývojáře.

Výdejní místa v headless obchodech a mobilních aplikacích

Widget košíku od Globe je součástí šablony Shopify. Nativní mobilní aplikace postavená na Storefront API nebo headless webový obchod, například Hydrogen nebo Next.js, šablonu nemá, takže widget není kam vložit. Tento průvodce ukazuje, jak si zákazníci v takových aplikacích vyberou výdejní místo dřív, než se dostanou do pokladny Shopify.

Obě níže popsané možnosti ukládají místo do košíku Storefront API jako atributy košíku. Od té chvíle s ním pokladna i zpracování objednávky zacházejí úplně stejně jako s místem vybraným ve widgetu košíku.


A: Hostovaná stránka pro výběrB: Storefront API pro výdejní místa
Co vytváříteOtevřete URL ve WebView, vyskakovacím okně nebo iframuVlastní mapu nebo seznam v rozhraní vaší aplikace
RozhraníMapa, seznam, vyhledávání, geolokace a filtr dopravců od GlobeVaše vlastní
Kdo zapisuje do košíkuGlobeVaše aplikace, pomocí cartAttributesUpdate
Přihlašovací údajŽádný. Stránka běží na doméně vašeho obchoduVeřejný klíč (glb_pk_…)
Co řeší vaše aplikaceOtevření stránky a přečtení výsledkuPolohu, vyhledávání, seznam míst a zápis do košíku

Pokud to chcete mít rychle hotové, začněte možností A. Možnost B zvolte, když výběr musí vypadat a chovat se nativně. Později můžete přejít na druhou možnost: obě zapisují stejné atributy košíku.


  • Globe je nainstalovaný a má aktivní tarif.
  • Headless výběr je pro váš obchod zapnutý. Zapínáme ho pro každý obchod zvlášť: napište nám do chatu podpory v aplikaci. Do té doby se v Nastavení → Headless a mobilní aplikace zobrazuje jen tlačítko Požádat o přístup a stránka pro výběr i Storefront API pro výdejní místa odpovídají, že funkce není zapnutá.
  • Máte nastaveného alespoň jednoho dopravce výdejních míst, který je namapovaný na dopravní metody. Viz Přidání výdejních míst.
  • Vaše aplikace vytváří košíky přes Storefront API a posílá zákazníky na checkoutUrl košíku.

V administraci Globe přejděte do Nastavení → Headless a mobilní aplikace.

Pro hostovanou stránku pro výběr

Sekce “Pro hostovanou stránku pro výběr”
  1. V části Stránka pro výběr výdejního místa klikněte na Zapnout.
  2. V části Návratové adresy klikněte na Přidat návratovou adresu a přidejte všechny adresy, na které může stránka zákazníky vracet:
    • deep link aplikace, například myapp://pickup,
    • universal link nebo Android App Link, například https://app.example.com/pickup,
    • webovou adresu vašeho headless obchodu, například https://shop.example.com/cart.
  3. Klikněte na Uložit v liště pro uložení.

Návratové adresy jsou volitelné, pokud vaše aplikace čte výsledek jen přes nativní most nebo postMessage. Pro přesměrování jsou povinné a webové domény pro postMessage se berou z návratových adres s https. Viz Return URLs.

Pokud karta hlásí, že Globe potřebuje oprávnění ke košíkům obchodu, otevřete jednou Globe ze Shopify administrace a schvalte aktualizovaná oprávnění. Do té doby stránka zobrazuje, že výběr není dostupný.

Pro Storefront API pro výdejní místa

Sekce “Pro Storefront API pro výdejní místa”
  1. V části Storefront API pro výdejní místa klikněte na Vytvořit klíč a zkopírujte veřejný klíč.
  2. Volitelně: v části Povolené webové domény klikněte na Přidat doménu a přidejte domény svého webového obchodu, například https://shop.example.com. Když žádnou doménu nezadáte, klíč může použít jakýkoli web. Nativních aplikací se to nikdy netýká.
  3. Klikněte na Uložit v liště pro uložení.

Veřejný klíč umí jen hledat výdejní místa vašich dopravců, takže ho můžete bezpečně vložit do aplikace nebo do kódu, který běží v prohlížeči. Viz Authentication.


Možnost A: hostovaná stránka pro výběr

Sekce “Možnost A: hostovaná stránka pro výběr”
  1. Vytvořte nebo načtěte košík zákazníka přes Storefront API a uložte si jeho id.

  2. Otevřete tuto URL na doméně svého obchodu:

    https://{shop domain}/apps/appfleece-globe/select?cart={URL-encoded cart id}&return_url={allowlisted URL}&state={your value}
  3. Zákazník vybere místo. Globe ho ověří u dopravce a zapíše atributy košíku.

  4. Vaše aplikace dostane výsledek: přesměrování na return_url, zprávu přes nativní most, nebo postMessage.

  5. Načtěte košík znovu a pokračujte na checkoutUrl.

Všechny parametry, zprávy s výsledkem a kód pro iOS, Android, React Native a Hydrogen najdete na stránce Hosted selection page.

Možnost B: Storefront API pro výdejní místa

Sekce “Možnost B: Storefront API pro výdejní místa”
  1. Požádejte zákazníka o polohu, nebo ho nechte posouvat mapou.
  2. Vyhledávejte: GET https://api-globe.appfleece.app/v1/storefront/pickup-points?country=CZ&latitude=…&longitude=… s hlavičkou X-Globe-Publishable-Key.
  3. Zobrazte místa. Když zákazník jedno vybere, vezměte jeho cart_attributes.
  4. Slučte je se stávajícími atributy košíku a seznam zapište mutací Storefront API cartAttributesUpdate.
  5. Pokračujte na checkoutUrl.

Endpointy a kód pro curl, Swift, Kotlin, TypeScript a Hydrogen najdete na stránce Storefront pickup API.


Formát atributů košíku

Sekce “Formát atributů košíku”

Po obou možnostech má košík tyto atributy:

KlíčHodnota
globe_PickupPointIdID místa
globe_PickupPointNameNázev místa
globe_PickupPointAddressAdresa na jednom řádku
globe_PickupPointDataCelé místo jako řetězec JSON
globe_DeliveryMethodpickup
globe_PickupPointCustomerIdDHL Postnummer, jinak prázdné

Zapište celé cart_attributes přesně tak, jak je Storefront API pro výdejní místa vrací. Samotné globe_PickupPointId Globe přijme jen jako náhradní řešení, a to jen u sítí dopravců, které si Globe ukládá sám: u dopravců, jejichž místa Globe načítá živě, například GLS nebo DHL, samotné ID ověřit nelze a místo se do objednávky neuloží.

Když zákazník přepne na doručení na adresu, odeberte klíče místa z košíku. Kompletní popis formátu, náhradní řešení jen s ID a to, co se má zapsat při doručení na adresu, najdete na stránce Cart attributes.


Pokladna čte atributy košíku přes přizpůsobení doručení od Globe, pokud jste ho zapnuli v Nastavení → Widget košíku → Přizpůsobení doručení v pokladně:

  • Viditelné zůstanou jen dodací sazby dopravce vybraného místa.
  • Pokud jste tam nastavili přejmenování sazeb, zobrazí se u sazby název místa.
  • Pokud zákazník v pokladně změní zemi doručení na zemi, ve které místo není, pokladna zobrazí všechny sazby jako obvykle.

S hostovanou stránkou pro výběr a se zapnutým Předvyplnění adresy v checkoutu se pokladna navíc otevře s adresou místa jako doručovací adresou. Zákazník ji může změnit. Storefront API pro výdejní místa doručovací adresu nemění.

Co se děje při vytvoření objednávky

Sekce “Co se děje při vytvoření objednávky”

Když Shopify vytvoří objednávku, Globe přečte atributy košíku a ověří místo v síti dopravce. To platí pro všechny kanály, včetně widgetu košíku v šabloně.

VýsledekCo Globe udělá
Místo existuje a je aktivníNahradí název, adresu a souřadnice místa údaji dopravce, uloží ho do objednávky (metapole Globe.PickupPoint) a použije tagy, atributy objednávky a poznámku dopravce
Místo nebylo nalezeno, není aktivní, je z jiné země, patří dopravci, který není namapovaný na dopravní metodu objednávky, nebo dopravní metoda není sazba s výdejním místemNeuloží žádné místo. Objednávka dostane tag Chybějící výdejní místo (výchozí point_unselected), pokud ho máte nastavený, a platí obvyklý postup s připomínkami
Dopravce není dostupnýPonechá místo z globe_PickupPointData košíku tak, jak je
Košík měl jen globe_PickupPointId a Globe ho nedokázal ověřit (u dopravců, jejichž místa Globe načítá živě, například GLS nebo DHL, je to tak vždy)Neuloží žádné místo a použije tag pro chybějící místo

Štítky, exporty a integrace ERP nebo WMS vidí stejná pole jako u objednávek z vašeho online obchodu. Viz Metafield pro výdejní místo.


Stránka hlásí „Výběr výdejního místa není pro tento obchod zapnutý.“ Zapněte stránku v Nastavení → Headless a mobilní aplikace. Pokud se v této sekci zobrazuje jen Požádat o přístup, headless výběr pro váš obchod ještě není zapnutý. Napište nám do chatu podpory.

Storefront API pro výdejní místa odpovídá 403 access_required se zprávou „Headless pickup is not enabled for this shop.“ Funkci zapínáme pro každý obchod zvlášť. Napište nám do chatu podpory. Klíč vytvořený dříve začne fungovat, jakmile funkci zapneme.

Stránka hlásí „Tento košík už neexistuje.“ Platnost košíku vypršela, košík už byl převeden na objednávku, nebo patří jinému obchodu. Vytvořte nový košík a otevřete stránku znovu.

Stránka hlásí „Tato návratová adresa není pro obchod povolená.“ return_url nezačíná žádnou z vašich návratových adres. Zkontrolujte schéma, doménu a cestu. Subdomény se za shodu nepovažují.

Stránka hlásí „Výběr výdejního místa je dočasně nedostupný.“ Globe nemá aktivní tarif, nebo nebyla schválena oprávnění ke košíkům obchodu. Otevřete Globe ze Shopify administrace.

Stránka vyžaduje heslo. Online obchod je chráněný heslem, jako je tomu u vývojových obchodů. Zadejte heslo obchodu jednou ve stejném WebView nebo prohlížeči.

Objednávka nemá výdejní místo. Podívejte se, jestli tagy objednávky obsahují váš tag pro chybějící místo. Pak ověřte, že košík měl před pokladnou globe_PickupPointData, že zákazník zvolil sazbu s výdejním místem téhož dopravce a že země doručení odpovídá zemi místa.

API odpovídá 403 origin_not_allowed. Přidejte doménu webu do seznamu Povolené webové domény, nebo odeberte všechny domény, aby klíč mohl použít jakýkoli web.

API odpovídá 429 rate_limited pro všechny zákazníky. Váš server volá API za všechny zákazníky z jedné IP adresy. Volejte ho místo toho ze zařízení nebo prohlížeče zákazníka. Viz Rate limits.

Pokladna zobrazuje sazby s výdejními místy jiných dopravců. Zapněte Přizpůsobení doručení v pokladně v Nastavení → Widget košíku a ujistěte se, že košík má globe_PickupPointData, ne jen ID.