1. Podpora
  2. Pro vývojáře
  3. Doplňky
  4. Vytváření doplňku

Vývoj doplňku

Průvodce propojením vaší služby s Upgates

REST API JSON Webhooks HTTPS (povinné)

Než začnete vyvíjet

Pokud si v něčem nejste jisti, projděte s Technickou podporou Upgates chování doplňku (aktivaci, běžný provoz, výpadky, pozdější úpravy i ukončení služby). Včasná konzultace předchází problémům při schvalování. (Případně můžete využít Discord)

Architektura doplňku

Upgates komunikuje s veřejně dostupnými HTTPS endpointy vaší služby. Doplněk následně pracuje s konkrétním e-shopem prostřednictvím REST API v2 a průběžné změny přijímá pomocí webhooků.

01 Životní cyklus

Upgates volá instalační, otevírací, odinstalační a případně verzovací endpoint vaší služby.

02 Práce s daty

Backend doplňku čte nebo mění data e-shopu pomocí REST API v2.

03 Průběžné změny

Nové a upravené záznamy backend zpracovává primárně na základě webhooků.

Základní adresa REST API

URL adresu dostanete v rámci úvodní incializace doplňku. Běžný tvar adresy:
https://NAZEV-ESHOPU.admin.ZNACKA-SERVERU.upgates.com/api/v2

Bezpečnostní požadavek

Všechny endpointy doplňku musí být veřejně dostupné přes HTTPS. Přístupové údaje a podpisový token ukládejte pouze na serveru. Nikdy je nezobrazujte uživateli ani neposílejte do klientského kódu.

Nastavení v Marketplace

V detailu doplňku otevřete záložku Vývoj doplňku.

ENDPOINTY

Sekce Endpointy se skládá ze dvou částí API nastavení a API přístupy.

Pozor! Pro správné fungování doplňku (aktivaci) je nutné vyplnit obě tyto sekce.

API nastavení

V sekci API nastavení zadejte veřejně dostupné HTTPS endpointy, které bude Upgates volat během jednotlivých částí životního cyklu doplňku.

INSTALL
Instalační endpoint

Spustí aktivaci, založení nebo spárování účtu a počáteční konfiguraci doplňku.
Dokumentace

Povinný
OPEN
Otevírací endpoint

Ověří uživatele a vrátí adresu prostředí doplňku, které lze otevřít v administraci Upgates pomocí iframe.
Dokumentace

Dle řešení
UNINSTALL
Odinstalační endpoint

Informuje o deaktivaci doplňku a zneplatnění jeho API přístupů. Zastavte související úlohy a ukončete propojení.
Dokumentace

Povinný
VERSION
Verzovací endpoint

Zpracuje přechod zákazníka na novou verzi a provede potřebné změny konfigurace, webhooků nebo uživatelského rozhraní.
Dokumentace

Při verzování
Signature token

signature_token je tajný identifikátor doplňku používaný k ověření podpisu požadavků životního cyklu. Neukládejte jej do klientského kódu ani do veřejně dostupných logů.

API přístupy

Požadujte jen oprávnění, která doplněk skutečně používá. U každého přístupu popište účel, očekávanou frekvenci a zda se volání spouští při instalaci, změně dat nebo na základě webhooku.

Pozor! Dbejte prosím na správný a detailní popis frekvence provolávání a popisu účelu proč daný API přístup zakládáte.

Aktivace doplňku

Aktivace doplňku je stav, kdy klient v administraci Upgates klikne v seznamu doplňku na tlačítko Aktivovat.
Request body, Response, Podpisový a více najdete zde.

  1. Ověřit podpis (více zde)
  2. Uložit přístupy
  3. Načíst /owner
  4. Založit účet / Spárovat existující
  5. Vytvořit webhooky, a stáhnout / založit potřebné data podle fungování doplňku

Aktivaci spouští přihlášený uživatel v Upgates, takže ji lze považovat za autorizovaný požadavek. Implementace ale musí bezpečně zvládnout opakované volání i aktivaci již aktivního doplňku.

  • Každá aktivace má vlastní samostatný API přístup (URL adresa zůstává stejná).
  • URL adresa se může v průběhu fungování doplňku měnit (změna identifikace serveru). Pokud zjistíte, že při provolávání URL adresa vrací redirect, uložte si novou URL adresu a starou zahoďte.

Po aktivaci doplňku vytvořte nebo propojte zákaznický účet bez zbytečných mezikroků.

  • Získejte informace o provozovateli e-shopu pomocí /owner.
  • Automaticky vytvořte nový účet nebo propojte již existující.
  • Po dokončení přiveďte uživatele rovnou do funkčního prostředí.
  • Opakovaný aktivační požadavek zpracujte bezpečně a idempotentně.

Nechtějte další ověření

Aktivaci provedl přihlášený uživatel v Upgates, proto ho nezatěžujte dalším ručním ověřováním.

  • Nevyžadujte ruční kopírování propojovacích tokenů.
  • Neposílejte další potvrzovací nebo ověřovací kód e-mailem.
  • Nevyžadujte opětovné vyplnění údajů, které již poskytlo API.
  • Nezobrazujte zákazníkovi API přístupové údaje ani podpisový token.

Ověření přes Upgates OAuth

V přípravě

Upgates OAuth umožňuje bezpečně ověřit uživatele bez předání jeho přihlašovacích údajů externí aplikaci. Vlastní OAuth aplikaci pro službu třetí strany zatím nelze samostatně založit; podpora se počítá jako budoucí rozšíření a její dokončení se bude řídit konkrétními případy použití a zájmem vývojářů. Pokud chcete OAuth využít ve svém doplňku, ozvěte se nám s popisem zamýšleného propojení.

Otevření doplňku

Pokud doplněk používá iframe, otevírací endpoint po ověření požadavku vrátí URL konkrétní relace. Nastavení zpřístupněte přímo v administraci Upgates, kdykoli je to možné. Pokud je registrace i spárování plně automatické a doplněk vlastní rozhraní nepotřebuje, iframe není povinný. (Více zde)

Request body, Response, Podpisový a více najdete zde.

Deaktivace doplňku

Při deaktivaci Upgates odešle požadavek na odinstalační endpoint doplňku. Vaše služba musí ukončit synchronizaci, zneplatnit uložené přístupy a bezpečně uzavřít propojení s e-shopem.
Více v naší dokumentaci zde.

  1. Ověřit podpis
  2. Zastavit synchronizaci
  3. Upgates deaktivuje
    • API přístupy
    • Konverzní kódy (pokud jste je vložili přes API doplňku)

Deaktivace uživatele z vaší strany

Pokud uživatel přestane vaše služby platit / je v prodlení nebo nastane jiná situace, která u vás ovlivní deaktivaci účtu musíte vyřešit deaktivaci webhooků.
Na své straně z důvodu ukončení / pozastavení služeb deaktivujete webhooky. Upgates však o tomto nemá možnost se dozvědět a tedy bude posílat informace na webhooky dál a ty budou padat na chybě. V těchto případech tedy přes PUT deaktivujte webhooky, anebo je prozatím rovnou smažte pomocí DELETE. Po reaktivaci je nezapomeňte zase zpět aktivovat / založit.

Verzování doplňku

Novou verzi použijte ve chvíli, kdy se mění fungování doplňku, požadovaná oprávnění nebo konfigurace. Přechod zákazníka musí být bezproblémový a bezpečný.
Více se dozvíte zde.

Synchronizace dat

Stránkování a dávky

GET seznamů stránkujte. Maximální počet položek bývá 100. Pro POST a PUT lze v podporovaných endpointech posílat až 100 položek najednou.

Jazyky a více domén

Jedna administrace může obsahovat více jazyků i domén. Jeden produkt má společné ID, ale jeho obsah se může lišit podle jazykové mutace. Při běžné synchronizaci načítejte objekt jako celek a rozdělení mutací řešte až ve vlastní aplikaci. Jazyk filtrujte jen v případě, kdy potřebujete stahovat pouze konkrétní jazyky, anebo GET trvá příliš dlouho z důvodu množství produktů, variant a jazykových mutací.

Produkty a varianty

Pokud se setkáte s tím, že projekt má spoustu produktů a GET tvrá příliš dlouho, anebo padá přímo na chybě. Může vyzkoušet snížit počet produktů na stránku current_page_items.

Pokud se setkáte s tím, že projekt má spoustu variant a buď je nepotřebujete, anebo GET trvá příliš dlouho, anebo padá na chybě. Můžete vyzkoušet varianty odebrat variants_yn a stáhnout je poté za pomocí separátního endpointu /products/variants

Webhooky

Po úvodním stažení dat reagujte na změny pomocí webhooků. Pravidelné kompletní stahování objednávek nebo produktů zvyšuje zátěž, spotřebovává limity a může být důvodem k neschválení doplňku.

POST https://domenaprojektu.com/v2/webhooks JSON

{
    "name": "addonName",
    "url": "addonWebhookUrl",
    "event": "Orders.update"
}

Best practices

Dodržujte následující doporučení, aby byl doplněk bezpečný, spolehlivý a zbytečně nezatěžoval API ani připojené e-shopy.

Automatizujte

Cílem je klientům přinést co největší automatizaci a komfort při zřizování doplňku. Vyhněte se ručnímu zakládání účtu, vyplňování údajů, atd.

Více projektů na jednom serveru

Rozdělte časování fungování během celého dne. Nestahujte data pouze během noci v přesně v 0:00, atd. Doporučujeme si rozdělení například eshop ABC 0:03, DEF 0:07

Počítejte s opakovaným požadavkem

Aktivace, deaktivace i webhook mohou dorazit opakovaně nebo v nečekaném pořadí. Zpracování proto navrhněte idempotentně.

Využívejte Webhooky

Absence webhooků může způsobit neschválení doplňku, popřípadě jeho blokaci, pokud by se absence vyskytla po schválení.

Testujte svůj doplněk

Hlavním atributem doplňků je uživatelská přívětivost a optimalizované využívání API. Vyhněte se duplicitním a zbytečným požadavkům. Doplněk před odesláním ke schválení správně otestujte (více zde).

Detailní Pravidla a Best practices

Základním cílem ověřeného doplňku je přinést klientům co největší automatizaci v propojení bez zbytečných klikání a vyplňování formulářů.

Pravidla pro implementaci AI

Obecné

  • Doplněk funguje díky komunikaci přes API. Základní BestPractices v používání API najdete zde.
  • V případě práce s API více e-shopů na jednom serveru je potřeba vytížení rozdělit časově během celého dne, a nestahovat data např. pouze během noci nebo v 00:00 apod.
    • Např. si rozdělit pool e-shopů a přidávat offsety po hodinách nebo jiných větších časových úsecích:
      • 2 e-shopy v 00:00
      • 2 e-shopy v 01:00
        atd.
  • Brát v úvahu, že Upgates umožňuje multijazyčnost a multidoménovost.
    • Co to pro vás znamená?
      Je zapotřebí se připravit na to, že produkty, kategorie, články, a další sekce jsou ve více jazycích pod více doménami, ale pouze pod jednou administrací.
      Tedy například produkt "Tričko" může být v jazyce CZ, SK, EN, může mít pro každou mutaci vlastní doménu, ale stále bude v jedné administraci pod jedním jedinečným ID.
      Dále může být produkt "Bunda", který bude v jazyce pouze SK, ale stále bude spadat pod tu jednu samou administraci jako produkt "Tričko".
    • Pokud řešíte multijazyčnost u produkt, kategorií atd. Stahujte je jako celek (bez omezení URL na jazyky).
       Rozdělení na samotné jazyky vyřešte až na své straně. Stahování konkrétních jazyků byste měli využít například v moment, kdy řešíte věc týkající se konkrétní jazykové mutace. Například reakci na webhook languages.create - kdy vzniká nová jazyková mutace.
  • Využívejte webhooky - Porušení může způsobit neschválení doplňku, popřípadě pozdější blokaci pokud je zjištěno automatickou kontrolou.
  • Testování doplňku:
    • Hlavním atributem při testování doplňků z vaší strany, by měla být uživatelská přívětivost. Než nám doplněk předáte k testování, prosím ověřte si, že dokážete váš doplněk obsluhovat jako běžný zákazník (správně se vytvoří uživatelský účet, funguje odhlášení a opětovné přihlášení do vašeho prostředí, atd.). Ulehčí se tím celkový proces schvalování doplňku.
    • Hlavním cílem při kontrole z naší strany vašeho doplňku, bude zajistit co nejlepší používání API.
    • Nepoužívejte tlačítko "Synchronizovat". Pokud jej pro fungování opravdu potřebujete, nastavte u něj ochranu opakovaného klikání, a také aby nebylo možné tlačítko stisknout znovu, pokud běží ještě původní proces synchronizace.
    • Plánované úlohy provažte s webhooky. Není nutné každý den stahovat všechny objednávky, zvláště v případě, kdy nevznikla žádná nová objednávky / neproběhla žádná změna.
    • Více o tomto tématu v naší nápovědě.

Aktivace doplňku

  • Při návrhu doplňku byste měli počítat s tím, že z naší strany, i když ne přímo cíleně, může přijít více požadavku na aktivaci, již aktivovaného doplňku nebo také požadavek na deaktivaci, aktuálně neaktivního doplňku.
  • Aktivaci (popřípadě následnou registraci) je možné brát jako již ověřenou (autorizovanou). Provádí jí totiž vždy uživatel v Upgates.

Založení účtu

  • Pro založení nebo spárování účtu můžete využít /owner.
  • Založení účtu plně automatizujte. Nevyžadujte po klientovi vyplnění speciálního formuláře na vašich stránkách. Klient je ověřen z naší strany, tedy registraci přímo u vás je možné realizovat, bez zbytečných průtahů.
    • Pokud z /owner a dalších endpointů nezískáte všechny potřebné údaje pro registraci vyřešte pomocí iframe okna.
    • Jakmile získáte informace z owner, založte zákazníkovi účet tak, aby se dostal rovnou do vašeho prostředí bez zbytečných průtahů. Nevyžadujte po zákazníkovi dodatečné kopírování ověřovacích kódů z e-mailů, kopírování propojovacích tokenů, atd..
  • Pokud vaše prostředí vyžaduje uvést, že účet je propojen s danou platformou Upgates, musí se tak stát během zakládání účtu. Nevyžadujte po zákazníkovi dodatečnou aktivaci propojení na své straně.
  • Uživatel nesmí mít přístup k API přístupovým údajům, které se vám přes doplněk zasílají. Tyto komunikační údaje slouží jenom pro vás a klient by je neměl mít možnost nijak zjistit a dále používat.

Otevření doplňku

  • Řídí se pravidly používání iframe doplňku.
  • Pokud vše v rámci spárování stávajícího zákazníka a registrace nevého probíhá automaticky, není nutné iframe používat.
  • (Doporučujeme) Přes iframe můžete poskytnout nastavení vaší aplikace klientovi tak, aby vůbec nemusel opustit administraci Upgates a bylo tak pro něj vše komfortnější a rychlejší.

Fungování doplňku

  • Tlačítko Synchronizovat / Aktualizovat
    Pokud potřebujete mít ve svém doplňku tlačítko na stahování aktuálních dat (například objednávek), myslete nejdříve na povinnost mít webhooky. Pokud dané tlačítko musí být skutečně uvedeno, doporučujeme jej nastavit tak, aby nebylo možné používat opakovaně během pár sekund. Použití musí být podmíněno minimálně vždy tak, aby se dalo aktivovat až po dokončení předchozího stahování + například nějaký interval.
    Pokud před X sekundami proběhlo stažení změn, nemělo by tlačítko pro aktualizaci provolávat znovu API.
  • Webhooky (dokumentace zde)
    • Webhooky nesmí jít ve vašem prostředí uživatelsky obejít!
    • Pokud zákazníkovi nabízíte možnost nastavení synchronizace opakovaně například v řádech jednotek minut. Musí se tyto časové spouštěče provádět na vaší straně a kontrolovat, zda-li během tohoto intervalu nedorazila notifikace z webhooku. Není možné provolávat jednotlivé sekce například co minutu a obcházet takto webhooky.
  • Myslete i na neplatícího klienta
    Pokud se klientský účet u vás dostane do stavu, kdy jeho data nezpracováváte, je nutné deaktivovat webhooky v propojení doplňku. V opačném případě, bude projekt zbytečně logovat chyby se špatnou odpovědí na notifikaci z webhooku.

Typy jednotlivých doplňků

V tomto odstavci se pokusíme popsat základní očekávané využití API a fungování jednotlivých typů doplňků. Pokud zde nenajdete popis svého doplňku, neváhejte nás informovat a společně můžeme ideální stav fungování doplňku probrat na online schůzce.

  • API přístupy
    • Objednávky
      • GET - Možné jednorázové stažení k určitému datu zpětně při aktivaci (stahování přes ?page=), následně reagovat vždy na webhooky (create, update).
        • Nastavení API přístupu v marketplace:
          • Frekvence: Jen při instalaci a vlastní
          • Počet opakování: Vlastní -> Na základě webhooku
          • Webhooky: ANO
      • PUT - Vrácení změny stavu objednávky, trasovacího kódu zásilky (vlastní počet opakování - podle změn v objednávkách na vaší straně)
        • Nastavení API přístupu v marketplace:
          • Frekvence: Vlastní
          • Počet opakování: Vlastní
      • Stavy objednávek
        • GET - Možné jednorázové stažení při aktivaci doplňku, následně reagovat vždy na webhooky
          • Nastavení API přístupu v marketplace:
            • Frekvence: Jen při instalaci a vlastní
            • Počet opakování: Vlastní -> Na základě webhooku
            • Webhooky: ANO
    • Produkty
      • GET - Pokud pracujete i s produkty možné jednorázové stažení při aktivaci (stahování přes ?page=), následně reagovat vždy na webhooky (create, update).
        • Nastavení API přístupu v marketplace:
          • Frekvence: Jen pnstalaci a vlastní
          • Počet opakování: Vlastní -> Na základě webhooku
          • Webhooky: ANO
      • PUT - Pozor na skladové hospodářství produktů. Objednávky v Upgates automaticky vyskladňují produkty na základě provedené objednávky. Produkty byste tedy neměli opětovně vyskladňovat na základě příchozí objednávky k vám do systému.
        • Nastavení API přístupu v marketplace:
          • Frekvence: Vlastní
          • Počet opakování: Vlastní
    • Doprava a platba
      • GET - Při aktivaci doplňku by mělo proběhnout jednorázové stažení doprav, které použijete pro párování dopravců. Následně reagovat vždy na webhooky.
        • Nastavení API přístupu v marketplace:
          • Frekvence: Při instalaci a vlastní
          • Počet opakování: Vlastní -> Na základě webhooku
          • Webhooky: ANO
    • Majitel (provozovatel e-shopu)
      • GET - Při aktivaci doplňku pro spárování / založení účtu ve vašem prostředí
        • Nastavení API přístupu v marketplace:
          • Frekvence: Jen při instalaci
    • Webhooky
      • GET - Kontrola před POST (v rámci aktivace / přechodu na novou verzi)
        • Nastavení API přístupu v marketplace:
          • Frekvence: Vlastní / Jen při instalaci a vlastní
          • Počet opakování: Vlastní -> Při instalaci doplňku a přechodu na novou verzi
      • POST - Založení webhooků na nejdůležitější sekce Objednávky, Produkty, Stavy objednávek, Doprava a Platba
        • Nastavení API přístupu v marketplace:
          • Frekvence: Vlastní / Jen při instalaci a vlastní
          • Počet opakování: Vlastní -> Při instalaci doplňku a přechodu na novou verzi
  • Informace o doplňku - Služby
    • V detailu doplňku pro Marketplace musí být napárované pouze takové služby, které jste schopni zákazníkovi v rámci fungování dodat. Je potřeba brát ohled na takové dopravce, které zákazník ve své administraci nedokáže nastavit (například stahování poboček dopravce, kterého Upgates nepodporuje a nelze tedy pro něj stáhnout konkrétní pobočky (FAN Courier)).

  • API přístupy
    • Objednávky
      • GET - Možné jednorázové stažení k určitému datu zpětně při aktivaci (stahování přes ?page=), následně reagovat vždy na webhooky (create, update).
        • Nastavení API přístupu v marketplace:
          • Frekvence: Jen při instalaci a vlastní
          • Počet opakování: Vlastní -> Na základě webhooku
          • Webhooky: ANO
      • PUT - Vrácení změny stavu objednávky, trasovacího kódu zásilky (vlastní počet opakování - podle změn v objednávkách na vaší straně)
        • Nastavení API přístupu v marketplace:
          • Frekvence: Vlastní
          • Počet opakování: Vlastní
      • Stavy objednávek
        • GET - Možné jednorázové stažení při aktivaci doplňku, následně reagovat vždy na webhooky
          • Nastavení API přístupu v marketplace:
            • Frekvence: Jen při instalaci a vlastní
            • Počet opakování: Vlastní -> Na základě webhooku
            • Webhooky: ANO
    • Produkty
      • GET - Pokud pracujete i s produkty možné jednorázové stažení při aktivaci (stahování přes ?page=), následně reagovat vždy na webhooky (create, update).
        • Nastavení API přístupu v marketplace:
          • Frekvence: Jen pnstalaci a vlastní
          • Počet opakování: Vlastní -> Na základě webhooku
          • Webhooky: ANO
      • PUT - Pozor na skladové hospodářství produktů. Objednávky v Upgates automaticky vyskladňují produkty na základě provedené objednávky. Produkty byste tedy neměli opětovně vyskladňovat na základě příchozí objednávky k vám do systému.
        • Nastavení API přístupu v marketplace:
          • Frekvence: Vlastní
          • Počet opakování: Vlastní
      • Parametry a Suvisející
        • GET - Stažení parametrů z produktu
          • Nastavení API přístupu v marketplace:
            • Frekvence: Jen při instalaci a vlastní
            • Počet opakování: Vlastní -> Na základě webhooku (Products.create, Products.update)
            • Webhooky: ANO
    • Doprava a platba
      • GET - Při aktivaci doplňku by mělo proběhnout jednorázové stažení doprav, které použijete pro párování dopravců. Následně reagovat vždy na webhooky.
        • Nastavení API přístupu v marketplace:
          • Frekvence: Jen při instalaci a vlastní
          • Počet opakování: Vlastní -> Na základě webhooku
          • Webhooky: ANO
    • Majitel (provozovatel e-shopu)
      • GET - Při aktivaci doplňku pro spárování / založení účtu ve vašem prostředí
        • Nastavení API přístupu v marketplace:
          • Frekvence: Jen při instalaci
    • Webhooky
      • GET - Kontrola před POST (v rámci aktivace / přechodu na novou verzi)
        • Nastavení API přístupu v marketplace:
          • Frekvence: Vlastní / Jen při instalaci a vlastní
          • Počet opakování: Vlastní -> Při instalaci doplňku a přechodu na novou verzi
      • POST - Založení webhooků na nejdůležitější sekce Objednávky, Produkty, Stavy objednávek, Doprava a Platba
        • Nastavení API přístupu v marketplace:
          • Frekvence: Vlastní / Jen při instalaci a vlastní
          • Počet opakování: Vlastní -> Při instalaci doplňku a přechodu na novou verzi

  • Obecné
    • Mailingové doplňky, musí podporovat oboustrannou synchronizaci kontaktů.
      • Nejdůležitějším bodem synchronizace je určitě zda-li zákazník akceptuje newsletter. Pokud o zákazníkovi ukládáte i jiné údaje (jméno, telefon, adresy), je nutné propojit zpětně i tyto údaje.
      • Pokud odběratel existuje ve SmartEmailingu, ale není v Upgates, mělo by proběhnout jeho založení do Upgates, aby zbytečně nedocházelo ke zbytečným kolizím v budoucnu.
  • API přístupy
    • Objednávky
      • GET - Možné jednorázové stažení k určitému datu zpětně při aktivaci (stahování přes ?page=), následně reagovat vždy na webhooky (create, update).
        • Nastavení API přístupu v marketplace:
          • Frekvence: Jen při instalaci a vlastní
          • Počet opakování: Vlastní -> Na základě webhooku
          • Webhooky: ANO
        • Doporučujeme zahrnout také možnost propojení na hodnocení produktu.
    • Produkty
      • GET - Pokud pracujete i s produkty je vhodnéjednorázové stažení při aktivaci (stahování přes ?page=), následně reagovat vždy na webhooky (create, update).
        • Nastavení API přístupu v marketplace:
          • Frekvence: Jen při instalaci a vlastní
          • Počet opakování: Vlastní -> Na základě webhooku
          • Webhooky: ANO
      • PUT - Pozor na skladové hospodářství produktů. Objednávky v Upgates automaticky vyskladňují produkty na základě provedené objednávky. Produkty byste tedy neměli opětovně vyskladňovat na základě příchozí objednávky k vám do systému.
        • Nastavení API přístupu v marketplace:
          • Frekvence: Vlastní
          • Počet opakování: Vlastní
    • Kategorie
      • GET - Pokud pracujete i s kategoriemi je vhodné jednorázové stažení při aktivaci (stahování přes ?page=), následně reagovat vždy na webhooky (create, update).
        • Nastavení API přístupu v marketplace:
          • Frekvence: Jen při instalaci a vlastní
          • Počet opakování: Vlastní -> Na základě webhooku
          • Webhooky: ANO
    • Zákazníci
      • GET - Jednorázové stažení při aktivaci (stahování přes ?page=), následně reagovat vždy na webhooky (create, update).
        • Nastavení API přístupu v marketplace:
          • Frekvence: Jen při instalaci a vlastní
          • Počet opakování: Vlastní -> Na základě webhooku
          • Webhooky: ANO
      • PUT - Zpětná synchronizace zákazníka na základě změny ve vašem systému (odhlášení z newsletteru, změna jména, atd.)
        • Nastavení API přístupu v marketplace:
          • Frekvence: Vlastní
          • Počet opakování: Vlastní
    • Konverzní kódy
      • GET - Kontrola před POST (v rámci aktivace / přechodu na novou verzi)
        • Nastavení API přístupu v marketplace:
          • Frekvence: Vlastní / Jen při instalaci a vlastní
          • Počet opakování: Vlastní -> Při instalaci doplňku a přechodu na novou verzi
      • POST - Založení konverzního kódu
        • Nastavení API přístupu v marketplace:
          • Frekvence: Vlastní / Jen při instalaci a vlastní
          • Počet opakování: Vlastní -> Při instalaci doplňku a přechodu na novou verzi
      • DELETE - Smazání konverzního kódu
        • Nastavení API přístupu v marketplace:
          • Frekvence: Vlastní / Jen při instalaci a vlastní
          • Počet opakování: Vlastní -> Při instalaci doplňku a přechodu na novou verzi
    • Slevové kupóny
      • GET - Pokud s kupóny pracujete například v email kampaních
        • Nastavení API přístupu v marketplace:
          • Frekvence: Jen při instalaci a vlastní
          • Počet opakování: Vlastní / 1x za den (?active_yn / ?date_from + ?page)
      • POST - Založení Slevového kupónu
        • Nastavení API přístupu v marketplace:
          • Frekvence: Vlastní
          • Počet opakování: Vlastní -> Při nastavení blahopřání k svátku, atd. u vás v systému
      • DELETE - Smazání Slevového kupónu
        • Nastavení API přístupu v marketplace:
          • Frekvence: Vlastní
          • Počet opakování: Vlastní -> Kupóny můžete nechat expirovat, anebo je rovnou smazat
    • Jazyky
      • GET - Při aktivaci doplňku pro správné nastavení profilu zákazníka u vás v systému
        • Nastavení API přístupu v marketplace:
          • Frekvence: Jen při instalaci a vlastní
          • Počet opakování: Vlastní -> Při reakci na webhook
          • Webhook: ANO
    • Majitel (provozovatel e-shopu)
      • GET - Při aktivaci doplňku pro spárování / založení účtu ve vašem prostředí
        • Nastavení API přístupu v marketplace:
          • Frekvence: Jen při instalaci
    • Webhooky
      • GET - Kontrola před POST (v rámci aktivace / přechodu na novou verzi)
        • Nastavení API přístupu v marketplace:
          • Frekvence: Vlastní / Jen při instalaci a vlastní
          • Počet opakování: Vlastní -> Při instalaci doplňku a přechodu na novou verzi
      • POST - Založení webhooků na nejdůležitější sekce Objednávky, Produkty, Jazyky, Doprava a Platba
        • Nastavení API přístupu v marketplace:
          • Frekvence: Vlastní / Jen při instalaci a vlastní
          • Počet opakování: Vlastní -> Při instalaci doplňku a přechodu na novou verzi

Doplňky, které jsou tvořeny přes AI, anebo pro své fungování využívají AI jsou určitě dnešním trendem.

Tyto doplňky však nefungují podle zavedených pravidel (Best Practices) a ikdyž se AI dají jasné příkazy a podmínky, je velmi pravděpodobné, že i přesto bude AI schopeno vymyslet vlastní postup, aby zadaného cíle dostáhlo.

Abychom ochránili uživatelská data sepsali jsme pro vás základní body, které je nutné z vaší strany vyřešit:

  • Doplněk by měl výhradně fungovat přes API.
  • Doplněk (typicky řešený přes extensions prohlížeče) může pracovat s obsahem stránky stylem udělat například focus, anebo jinak zvýraznit hledanou sekci zákazníkem, ale neměl by sahat "fyzicky" do stránky administrace a měnit data, nebo přepínat nastavení za zákazníka.
  • Před úvodní konzultací a před posláním ke schválení je nutné důkladně sepsat jak pro nás tak pro klienty co doplněk je schopen udělat (K čemu všemu má přístup, a co je schopen zajistit: Překlady, vyhledávání, změny stavů objednávek, atd.)
    • V budoucnu bude zapotřebí vždy když se přidává nová funkce, kontaktovat naši technickou podporu a informovat nás o tom. I v případě, kdy se neprovádí žádné přidání / změna API endpointů
    • Tuto změna musíte zaznamenat v sekci Informace o doplňku a poslat k nám na schválení ještě předtím, než bude funkce nasazena a přístupná běžným klientům.
  • Důkladně zajistit optimalizované provolávání API
    • Volat seznamy stránkově a neumožnist stahovat všechny produktu jen tak.
    • Neumožnit obcházet Best Practices pokynem ze strany zákazníka.
    • Doplněk by si při aktivaci měl stáhnout seznam produktů, uložit si jej a následně pracovat s webhooky. Není možné aby doplněk provolával všechny produkty po každém dotazu zákazníka (například prostřednictvím chatu).
    • Zajistit ochranu před obecnými poždavky ze strany klienta. (například: Ke každému produktu do názvu přidej jeho výrobce). Doplněk by neměl najednou spustit provolávání 100 000 produktů formou samostatných požadavků, ale udělat sumář a postupovat dle pravidel API.
    • Doplněk by měl zajistit cache aktuálního a naposledy probíhajících chatů alespoň v rámci 1 hodiny. Nemělo by tedy docházet k tomu, že v jednom chatu si doplněk stáhne všechny produkty, kategorie, atd., vykonají se požadavky klienta, klient okno zavře a za minutu si vzpomene, že potřebuje ještě něco upravit a tak znovu otevře okno a znovu se stáhnou všechny produkty, kategorie, atd.
    • Pokud stále probíhá API komunikace (stále se stahují data, anebo posílájí do Upgates), doplněk by neměl příjmat další příkazy a tvořit tak nekonečnou frontu úkonů.
  • Ochrana dat zákazníka
    • Doplněk by vždy před každým úkonem měl provést validaci zadaného požadavku ze strany zákazníka a následně uvést viditelně: Co bude přesně dělat, nad kolika produkty (články, kategoriemi, parametry, atd.)
    • Doplněk by vždy po této validaci a upozornění se měl zeptat, zda-li to má skutečně provést. Nesmí dojít k tomu, že klient zadá obecný požadavek "změň dopravu DPD za PPL" a místo aby doplněk změnil název dopravy v seznamu doprav, začně měnit všechny objednávky i 10let zpětně protože mají dopravu DPD
    • Doplněk by měl odpovídat za zálohu dat, které edituje a maže, a poskytnout možnost vrátit se zpět do stavu, než změny proběhly.
    • Doplněk by měl brát v potaz všechny návazné funkce, které Upgates poskytuje. Tedy pokud byť i chybou začne měnit stavy všech objednávek, je potřeba počítat s tím, že se mohou odeslat emaily a SMS zákazníkům. Tedy provedení hromadných úkonů by se němělo dělat automaticky, ale vždy s plným informováním klienta a jeho potvrzením od klienta. Takové rozhodnutí se musí také u vás zalogovat.
  • Doplněk by měl být kompatibilní s aktuálními verzemi a nejpoužívanějšími systémy a prohlížeči
  • Doplněk musí zajistit informovanost zákazníka a uložení jeho souhlasu s tím, že poskytuje data (své a zákazníků) nejen vaší společnosti, ale také službám 3. stran (OpenAI, atd.), které s daty pracují a zpracovávájí je.
  • Při spuštění doplňku musí první krok obsahovat iframe, ve kterém klient odsouhlasí upozornění, že doplněk není nijak spojen se společností Upgates, je plně ve vlastnictví vaší společnosti (vyjmenovat kdo má přístup k datům) a Upgates nenese odpovědnost za změny dat, které na eshopu doplněk udělá ani nevzniká nárok data ze strany Upgates bezplatně vrátit. (včetně zalogování tohoto souhlasu)
Na této stránce

Další zdroje informací

Facebook Forum

Výměna zkušeností, rady a tipy mezi provozovateli e-shopů na systému Upgates.

Přejít do fóra

Akademie

Získejte znalosti od našich specialistů na marketing, obchod, právo a podnikání.

Přejít do akademie

Novinky z Blogu

Co nového jsme pro vás připravili nebo chystáme najdete na blogu.

Přejít do blogu

Nepodařilo se Vám najít tu správnou odpověď?

Kontaktujte naši technickou podporu, která je tu pro vás od pondělí do pátku 8:00 až 16:00 hod.

Zákaznická podpora