Vývoj doplnku

Sprievodca prepojením vašej služby s Upgates

REST API JSON Webhooks HTTPS (povinné)

Skôr než začnete vyvíjať

Ak si v niečom nie ste istí, prejdite s Technickou podporou Upgates správanie doplnku (aktiváciu, bežnú prevádzku, výpadky, neskoršie úpravy aj ukončenie služby). Včasná konzultácia predchádza problémom pri schvaľovaní. (Prípadne môžete využiť Discord)

Architektúra doplnku

Upgates komunikuje s verejne dostupnými HTTPS endpointmi vašej služby. Doplnok následne pracuje s konkrétnym e-shopom prostredníctvom REST API v2 a priebežné zmeny prijíma pomocou webhookov.

01 Životný cyklus

Upgates volá inštalačný, otvárací, odinštalačný a prípadne verzovací endpoint vašej služby.

02 Práca s dátami

Backend doplnku číta alebo mení dáta e-shopu pomocou REST API v2.

03 Priebežné zmeny

Nové a upravené záznamy backend spracúva primárne na základe webhookov.

Základná adresa REST API

URL adresu dostanete v rámci úvodnej inicializácie doplnku. Bežný tvar adresy:
https://NAZEV-ESHOPU.admin.ZNACKA-SERVERU.upgates.com/api/v2

Bezpečnostná požiadavka

Všetky endpointy doplnku musia byť verejne dostupné cez HTTPS. Prístupové údaje a podpisový token ukladajte iba na serveri. Nikdy ich nezobrazujte používateľovi ani neposielajte do klientského kódu.

Nastavenie v Marketplace

V detaile doplnku otvorte záložku Vývoj doplnku.

ENDPOINTY

Sekcia Endpointy sa skladá z dvoch častí API nastavenie a API prístupy.

Pozor! Pre správne fungovanie doplnku (aktiváciu) je potrebné vyplniť obe tieto sekcie.

API nastavenie

V sekcii API nastavenie zadajte verejne dostupné HTTPS endpointy, ktoré bude Upgates volať počas jednotlivých častí životného cyklu doplnku.

INSTALL
Inštalačný endpoint

Spustí aktiváciu, založenie alebo spárovanie účtu a počiatočnú konfiguráciu doplnku.
Dokumentácia

Povinný
OPEN
Otvárací endpoint

Overí používateľa a vráti adresu prostredia doplnku, ktoré možno otvoriť v administrácii Upgates pomocou iframe.
Dokumentácia

Podľa riešenia
UNINSTALL
Odinštalačný endpoint

Informuje o deaktivácii doplnku a zneplatnení jeho API prístupov. Zastavte súvisiace úlohy a ukončite prepojenie.
Dokumentácia

Povinný
VERSION
Verzovací endpoint

Spracuje prechod zákazníka na novú verziu a vykoná potrebné zmeny konfigurácie, webhookov alebo používateľského rozhrania.
Dokumentácia

Pri verzovaní
Signature token

signature_token je tajný identifikátor doplnku používaný na overenie podpisu požiadaviek životného cyklu. Neukladajte ho do klientského kódu ani do verejne dostupných logov.

API prístupy

Požadujte iba oprávnenia, ktoré doplnok skutočne používa. Pri každom prístupe opíšte účel, očakávanú frekvenciu a či sa volanie spúšťa pri inštalácii, zmene dát alebo na základe webhooku.

Pozor! Dbajte, prosím, na správny a detailný opis frekvencie volania a účelu, prečo daný API prístup vytvárate.

Aktivácia doplnku

Aktivácia doplnku je stav, keď klient v administrácii Upgates klikne v zozname doplnku na tlačidlo Aktivovať.
Request body, Response, podpis a ďalšie informácie nájdete tu.

  1. Overiť podpis (viac tu)
  2. Uložiť prístupy
  3. Načítať /owner
  4. Založiť účet / Spárovať existujúci
  5. Vytvoriť webhooky a stiahnuť / založiť potrebné dáta podľa fungovania doplnku

Aktiváciu spúšťa prihlásený používateľ v Upgates, takže ju možno považovať za autorizovanú požiadavku. Implementácia však musí bezpečne zvládnuť opakované volanie aj aktiváciu už aktívneho doplnku.

  • Každá aktivácia má vlastný samostatný API prístup (URL adresa zostáva rovnaká).
  • URL adresa sa môže počas fungovania doplnku meniť (zmena identifikácie servera). Ak zistíte, že pri volaní URL adresa vracia redirect, uložte si novú URL adresu a starú zahoďte.

Nevyžadujte ďalšie overenie

Aktiváciu vykonal prihlásený používateľ v Upgates, preto ho nezaťažujte ďalším ručným overovaním.

  • Nevyžadujte ručné kopírovanie prepojovacích tokenov.
  • Neposielajte ďalší potvrdzovací alebo overovací kód e-mailom.
  • Nevyžadujte opätovné vyplnenie údajov, ktoré už poskytlo API.
  • Nezobrazujte zákazníkovi API prístupové údaje ani podpisový token.

Overenie cez Upgates OAuth

V príprave

Upgates OAuth umožňuje bezpečne overiť používateľa bez odovzdania jeho prihlasovacích údajov externej aplikácii. Vlastnú OAuth aplikáciu pre službu tretej strany zatiaľ nie je možné samostatne založiť; podpora sa plánuje ako budúce rozšírenie a jej dokončenie sa bude riadiť konkrétnymi prípadmi použitia a záujmom vývojárov. Ak chcete OAuth využiť vo svojom doplnku, ozvite sa nám s opisom zamýšľaného prepojenia.

Otvorenie doplnku

Ak doplnok používa iframe, otvárací endpoint po overení požiadavky vráti URL konkrétnej relácie. Nastavenie sprístupnite priamo v administrácii Upgates vždy, keď je to možné. Ak sú registrácia aj spárovanie plne automatické a doplnok vlastné rozhranie nepotrebuje, iframe nie je povinný. (Viac tu)

Request body, Response, podpis a ďalšie informácie nájdete tu.

Deaktivácia doplnku

Pri deaktivácii Upgates odošle požiadavku na odinštalačný endpoint doplnku. Vaša služba musí ukončiť synchronizáciu, zneplatniť uložené prístupy a bezpečne uzavrieť prepojenie s e-shopom.
Viac v našej dokumentácii tu.

  1. Overiť podpis
  2. Zastaviť synchronizáciu
  3. Upgates deaktivuje
    • API prístupy
    • Konverzné kódy (ak ste ich vložili cez API doplnku)

Deaktivácia používateľa z vašej strany

Ak používateľ prestane vaše služby platiť / je v omeškaní alebo nastane iná situácia, ktorá u vás ovplyvní deaktiváciu účtu, musíte vyriešiť deaktiváciu webhookov.
Na svojej strane z dôvodu ukončenia / pozastavenia služieb deaktivujete webhooky. Upgates sa však o tom nemá ako dozvedieť, a preto bude informácie na webhooky posielať ďalej a tie budú končiť chybou. V týchto prípadoch teda cez PUT deaktivujte webhooky alebo ich zatiaľ rovno zmažte pomocou DELETE. Po reaktivácii ich nezabudnite znova aktivovať / založiť.

Verzovanie doplnku

Novú verziu použite vtedy, keď sa mení fungovanie doplnku, požadované oprávnenia alebo konfigurácia. Prechod zákazníka musí byť bezproblémový a bezpečný.
Viac sa dozviete tu.

Synchronizácia dát

Stránkovanie a dávky

GET zoznamov stránkujte. Maximálny počet položiek býva 100. Pre POST a PUT možno v podporovaných endpointoch posielať až 100 položiek naraz.

Jazyky a viac domén

Jedna administrácia môže obsahovať viac jazykov aj domén. Jeden produkt má spoločné ID, ale jeho obsah sa môže líšiť podľa jazykovej mutácie. Pri bežnej synchronizácii načítavajte objekt ako celok a rozdelenie mutácií riešte až vo vlastnej aplikácii. Jazyk filtrujte iba v prípade, keď potrebujete sťahovať len konkrétne jazyky alebo GET trvá príliš dlho z dôvodu množstva produktov, variantov a jazykových mutácií.

Produkty a varianty

Ak sa stretnete s tým, že projekt má veľa produktov a GET trvá príliš dlho alebo končí priamo chybou, môžete skúsiť znížiť počet produktov na stránku current_page_items.

Ak sa stretnete s tým, že projekt má veľa variantov a buď ich nepotrebujete, alebo GET trvá príliš dlho, prípadne končí chybou, môžete skúsiť varianty odobrať pomocou variants_yn a následne ich stiahnuť pomocou samostatného endpointu /products/variants

Webhooky

Po úvodnom stiahnutí dát reagujte na zmeny pomocou webhookov. Pravidelné kompletné sťahovanie objednávok alebo produktov zvyšuje záťaž, spotrebúva limity a môže byť dôvodom na neschválenie doplnku.

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

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

Best practices

Dodržiavajte nasledujúce odporúčania, aby bol doplnok bezpečný, spoľahlivý a zbytočne nezaťažoval API ani pripojené e-shopy.

Automatizujte

Cieľom je priniesť klientom čo najväčšiu automatizáciu a komfort pri zriaďovaní doplnku. Vyhnite sa ručnému zakladaniu účtu, vypĺňaniu údajov atď.

Viac projektov na jednom serveri

Rozdeľte časovanie fungovania počas celého dňa. Nesťahujte dáta iba počas noci presne o 0:00 atď. Odporúčame rozdeliť ich napríklad takto: e-shop ABC 0:03, DEF 0:07

Počítajte s opakovanou požiadavkou

Aktivácia, deaktivácia aj webhook môžu prísť opakovane alebo v neočakávanom poradí. Spracovanie preto navrhnite idempotentne.

Využívajte Webhooky

Absencia webhookov môže spôsobiť neschválenie doplnku, prípadne jeho zablokovanie, ak by sa absencia zistila po schválení.

Testujte svoj doplnok

Hlavným atribútom doplnkov je používateľská prívetivosť a optimalizované využívanie API. Vyhnite sa duplicitným a zbytočným požiadavkám. Doplnok pred odoslaním na schválenie správne otestujte (viac tu).

Detailné Pravidlá a Best practices

Základným cieľom overeného doplnku je priniesť klientom čo najväčšiu automatizáciu v prepojení bez zbytočného klikania a vypĺňania formulárov.

Pravidlá pre implementáciu AI

Všeobecné

  • Doplnok funguje vďaka komunikácii cez API. Základné Best Practices pri používaní API nájdete tu.
  • V prípade práce s API viacerých e-shopov na jednom serveri je potrebné rozložiť zaťaženie časovo počas celého dňa a nesťahovať dáta napríklad iba počas noci alebo o 00:00 a pod.
    • Napríklad rozdeliť pool e-shopov a pridávať offsety po hodinách alebo iných väčších časových úsekoch:
      • 2 e-shopy o 00:00
      • 2 e-shopy o 01:00
        atď.
  • Berte do úvahy, že Upgates umožňuje viacjazyčnosť a multidoménovosť.
    • Čo to pre vás znamená?
      Je potrebné pripraviť sa na to, že produkty, kategórie, články a ďalšie sekcie sú vo viacerých jazykoch pod viacerými doménami, ale iba v rámci jednej administrácie.
      Napríklad produkt "Tričko" môže byť v jazykoch CZ, SK, EN, môže mať pre každú mutáciu vlastnú doménu, ale stále bude v jednej administrácii pod jedným jedinečným ID.
      Ďalej môže existovať produkt "Bunda", ktorý bude iba v jazyku SK, ale stále bude patriť do tej istej administrácie ako produkt "Tričko".
    • Ak riešite viacjazyčnosť pri produktoch, kategóriách atď., sťahujte ich ako celok (bez obmedzenia URL na jazyky).
      Rozdelenie na jednotlivé jazyky vyriešte až na svojej strane. Sťahovanie konkrétnych jazykov by ste mali využiť napríklad vtedy, keď riešite vec týkajúcu sa konkrétnej jazykovej mutácie. Napríklad reakciu na webhook languages.create – keď vzniká nová jazyková mutácia.
  • Využívajte webhooky - Porušenie môže spôsobiť neschválenie doplnku, prípadne neskoršiu blokáciu, ak sa zistí automatickou kontrolou.
  • Testovanie doplnku:
    • Hlavným atribútom pri testovaní doplnkov z vašej strany by mala byť používateľská prívetivosť. Skôr než nám doplnok odovzdáte na testovanie, overte si, prosím, že dokážete svoj doplnok obsluhovať ako bežný zákazník (správne sa vytvorí používateľský účet, funguje odhlásenie a opätovné prihlásenie do vášho prostredia atď.). Uľahčí sa tým celý proces schvaľovania doplnku.
    • Hlavným cieľom pri kontrole vášho doplnku z našej strany bude zabezpečiť čo najlepšie používanie API.
    • Nepoužívajte tlačidlo "Synchronizovať". Ak ho na fungovanie skutočne potrebujete, nastavte pri ňom ochranu proti opakovanému klikaniu a tiež zabezpečte, aby nebolo možné tlačidlo stlačiť znova, ak ešte prebieha pôvodný proces synchronizácie.
    • Plánované úlohy prepojte s webhookmi. Nie je potrebné každý deň sťahovať všetky objednávky, najmä v prípade, keď nevznikla žiadna nová objednávka / neprebehla žiadna zmena.
    • Viac o tejto téme v našej nápovede.

Aktivácia doplnku

  • Pri návrhu doplnku by ste mali počítať s tým, že z našej strany, aj keď nie cielene, môže prísť viac požiadaviek na aktiváciu už aktivovaného doplnku alebo aj požiadavka na deaktiváciu aktuálne neaktívneho doplnku.
  • Aktiváciu (prípadne následnú registráciu) možno považovať za už overenú (autorizovanú). Vykonáva ju totiž vždy používateľ v Upgates.

Založenie účtu

  • Na založenie alebo spárovanie účtu môžete využiť /owner.
  • Založenie účtu plne automatizujte. Nevyžadujte od klienta vyplnenie špeciálneho formulára na vašich stránkach. Klient je overený z našej strany, takže registráciu priamo u vás možno realizovať bez zbytočných prieťahov.
    • Ak z /owner a ďalších endpointov nezískate všetky potrebné údaje na registráciu, vyriešte to pomocou iframe okna.
    • Hneď ako získate informácie z owner, založte zákazníkovi účet tak, aby sa dostal priamo do vášho prostredia bez zbytočných prieťahov. Nevyžadujte od zákazníka dodatočné kopírovanie overovacích kódov z e-mailov, kopírovanie prepojovacích tokenov atď.
  • Ak vaše prostredie vyžaduje uviesť, že účet je prepojený s platformou Upgates, musí sa tak stať počas zakladania účtu. Nevyžadujte od zákazníka dodatočnú aktiváciu prepojenia na svojej strane.
  • Používateľ nesmie mať prístup k API prístupovým údajom, ktoré sa vám cez doplnok odosielajú. Tieto komunikačné údaje slúžia iba vám a klient by ich nemal mať možnosť nijako zistiť ani ďalej používať.

Otvorenie doplnku

  • Riadi sa pravidlami používania iframe doplnku.
  • Ak všetko v rámci spárovania existujúceho zákazníka a registrácie nového prebieha automaticky, nie je potrebné iframe používať.
  • (Odporúčame) Cez iframe môžete klientovi poskytnúť nastavenie vašej aplikácie tak, aby vôbec nemusel opustiť administráciu Upgates a všetko preňho bolo pohodlnejšie a rýchlejšie.

Fungovanie doplnku

  • Tlačidlo Synchronizovať / Aktualizovať
    Ak potrebujete mať vo svojom doplnku tlačidlo na sťahovanie aktuálnych dát (napríklad objednávok), myslite najskôr na povinnosť mať webhooky. Ak musí byť dané tlačidlo skutočne uvedené, odporúčame ho nastaviť tak, aby ho nebolo možné používať opakovane počas niekoľkých sekúnd. Použitie musí byť minimálne podmienené tak, aby sa dalo aktivovať až po dokončení predchádzajúceho sťahovania + napríklad po určitom intervale.
    Ak pred X sekundami prebehlo stiahnutie zmien, tlačidlo na aktualizáciu by nemalo znova volať API.
  • Webhooky (dokumentácia tu)
    • Webhooky nesmú byť vo vašom prostredí používateľsky obíditeľné!
    • Ak zákazníkovi ponúkate možnosť nastavovať synchronizáciu opakovane napríklad v intervaloch niekoľkých minút, tieto časové spúšťače sa musia vykonávať na vašej strane a kontrolovať, či počas daného intervalu neprišla notifikácia z webhooku. Nie je možné volať jednotlivé sekcie napríklad každú minútu a takto obchádzať webhooky.
  • Myslite aj na neplatiaceho klienta
    Ak sa klientsky účet u vás dostane do stavu, keď jeho dáta nespracúvate, je potrebné deaktivovať webhooky v prepojení doplnku. V opačnom prípade bude projekt zbytočne logovať chyby spôsobené nesprávnou odpoveďou na notifikáciu z webhooku.

Typy jednotlivých doplnkov

V tomto odseku sa pokúsime opísať základné očakávané využitie API a fungovanie jednotlivých typov doplnkov. Ak tu nenájdete opis svojho doplnku, neváhajte nás informovať a spoločne môžeme ideálny spôsob fungovania doplnku prebrať na online stretnutí.

  • API prístupy
    • Objednávky
      • GET - Možné jednorazové stiahnutie k určitému dátumu spätne pri aktivácii (sťahovanie cez ?page=), následne vždy reagovať na webhooky (create, update).
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Len pri inštalácii a vlastná
          • Počet opakovaní: Vlastný -> Na základe webhooku
          • Webhooky: ÁNO
      • PUT - Vrátenie zmeny stavu objednávky, trasovacieho kódu zásielky (vlastný počet opakovaní – podľa zmien v objednávkach na vašej strane)
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Vlastná
          • Počet opakovaní: Vlastná
      • Stavy objednávok
        • GET - Možné jednorazové stiahnutie pri aktivácii doplnku, následne vždy reagovať na webhooky
          • Nastavenie API prístupu v Marketplace:
            • Frekvencia: Len pri inštalácii a vlastná
            • Počet opakovaní: Vlastný -> Na základe webhooku
            • Webhooky: ÁNO
    • Produkty
      • GET - Ak pracujete aj s produktmi, je možné jednorazové stiahnutie pri aktivácii (sťahovanie cez ?page=), následne vždy reagovať na webhooky (create, update).
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Len pri inštalácii a vlastná
          • Počet opakovaní: Vlastný -> Na základe webhooku
          • Webhooky: ÁNO
      • PUT - Pozor na skladové hospodárstvo produktov. Objednávky v Upgates automaticky vyskladňujú produkty na základe vykonanej objednávky. Produkty by ste teda nemali opätovne vyskladňovať na základe prichádzajúcej objednávky do vášho systému.
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Vlastná
          • Počet opakovaní: Vlastná
    • Doprava a platba
      • GET - Pri aktivácii doplnku by malo prebehnúť jednorazové stiahnutie dopráv, ktoré použijete na párovanie dopravcov. Následne vždy reagovať na webhooky.
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Pri inštalácii a vlastná
          • Počet opakovaní: Vlastný -> Na základe webhooku
          • Webhooky: ÁNO
    • Majiteľ (prevádzkovateľ e-shopu)
      • GET - Pri aktivácii doplnku na spárovanie / založenie účtu vo vašom prostredí
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Len pri inštalácii
    • Webhooky
      • GET - Kontrola pred POST (v rámci aktivácie / prechodu na novú verziu)
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Vlastná / Len pri inštalácii a vlastná
          • Počet opakovaní: Vlastný -> Pri inštalácii doplnku a prechode na novú verziu
      • POST - Založenie webhookov pre najdôležitejšie sekcie Objednávky, Produkty, Stavy objednávok, Doprava a Platba
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Vlastná / Len pri inštalácii a vlastná
          • Počet opakovaní: Vlastný -> Pri inštalácii doplnku a prechode na novú verziu
  • Informácie o doplnku - Služby
    • V detaile doplnku pre Marketplace musia byť spárované iba také služby, ktoré ste schopní zákazníkovi v rámci fungovania poskytnúť. Je potrebné brať ohľad na dopravcov, ktorých zákazník vo svojej administrácii nedokáže nastaviť (napríklad sťahovanie pobočiek dopravcu, ktorého Upgates nepodporuje, a preto preň nemožno stiahnuť konkrétne pobočky (FAN Courier)).

  • API prístupy
    • Objednávky
      • GET - Možné jednorazové stiahnutie k určitému dátumu spätne pri aktivácii (sťahovanie cez ?page=), následne vždy reagovať na webhooky (create, update).
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Len pri inštalácii a vlastná
          • Počet opakovaní: Vlastný -> Na základe webhooku
          • Webhooky: ÁNO
      • PUT - Vrátenie zmeny stavu objednávky, trasovacieho kódu zásielky (vlastný počet opakovaní – podľa zmien v objednávkach na vašej strane)
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Vlastná
          • Počet opakovaní: Vlastná
      • Stavy objednávok
        • GET - Možné jednorazové stiahnutie pri aktivácii doplnku, následne vždy reagovať na webhooky
          • Nastavenie API prístupu v Marketplace:
            • Frekvencia: Len pri inštalácii a vlastná
            • Počet opakovaní: Vlastný -> Na základe webhooku
            • Webhooky: ÁNO
    • Produkty
      • GET - Ak pracujete aj s produktmi, je možné jednorazové stiahnutie pri aktivácii (sťahovanie cez ?page=), následne vždy reagovať na webhooky (create, update).
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Len pri inštalácii a vlastná
          • Počet opakovaní: Vlastný -> Na základe webhooku
          • Webhooky: ÁNO
      • PUT - Pozor na skladové hospodárstvo produktov. Objednávky v Upgates automaticky vyskladňujú produkty na základe vykonanej objednávky. Produkty by ste teda nemali opätovne vyskladňovať na základe prichádzajúcej objednávky do vášho systému.
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Vlastná
          • Počet opakovaní: Vlastná
      • Parametre a Súvisiace
        • GET - Stiahnutie parametrov z produktu
          • Nastavenie API prístupu v Marketplace:
            • Frekvencia: Len pri inštalácii a vlastná
            • Počet opakovaní: Vlastný -> Na základe webhooku (Products.create, Products.update)
            • Webhooky: ÁNO
    • Doprava a platba
      • GET - Pri aktivácii doplnku by malo prebehnúť jednorazové stiahnutie dopráv, ktoré použijete na párovanie dopravcov. Následne vždy reagovať na webhooky.
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Len pri inštalácii a vlastná
          • Počet opakovaní: Vlastný -> Na základe webhooku
          • Webhooky: ÁNO
    • Majiteľ (prevádzkovateľ e-shopu)
      • GET - Pri aktivácii doplnku na spárovanie / založenie účtu vo vašom prostredí
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Len pri inštalácii
    • Webhooky
      • GET - Kontrola pred POST (v rámci aktivácie / prechodu na novú verziu)
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Vlastná / Len pri inštalácii a vlastná
          • Počet opakovaní: Vlastný -> Pri inštalácii doplnku a prechode na novú verziu
      • POST - Založenie webhookov pre najdôležitejšie sekcie Objednávky, Produkty, Stavy objednávok, Doprava a Platba
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Vlastná / Len pri inštalácii a vlastná
          • Počet opakovaní: Vlastný -> Pri inštalácii doplnku a prechode na novú verziu

  • Všeobecné
    • Mailingové doplnky, musia podporovať obojsmernú synchronizáciu kontaktov.
      • Najdôležitejším bodom synchronizácie je určite to, či zákazník akceptuje newsletter. Ak o zákazníkovi ukladáte aj iné údaje (meno, telefón, adresy), je potrebné spätne prepojiť aj tieto údaje.
      • Ak odberateľ existuje v SmartEmailingu, ale nie je v Upgates, malo by prebehnúť jeho založenie do Upgates, aby v budúcnosti zbytočne nevznikali kolízie.
  • API prístupy
    • Objednávky
      • GET - Možné jednorazové stiahnutie k určitému dátumu spätne pri aktivácii (sťahovanie cez ?page=), následne vždy reagovať na webhooky (create, update).
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Len pri inštalácii a vlastná
          • Počet opakovaní: Vlastný -> Na základe webhooku
          • Webhooky: ÁNO
        • Odporúčame zahrnúť aj možnosť prepojenia na hodnotenie produktu.
    • Produkty
      • GET - Ak pracujete aj s produktmi, je vhodné jednorazové stiahnutie pri aktivácii (sťahovanie cez ?page=), následne vždy reagovať na webhooky (create, update).
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Len pri inštalácii a vlastná
          • Počet opakovaní: Vlastný -> Na základe webhooku
          • Webhooky: ÁNO
      • PUT - Pozor na skladové hospodárstvo produktov. Objednávky v Upgates automaticky vyskladňujú produkty na základe vykonanej objednávky. Produkty by ste teda nemali opätovne vyskladňovať na základe prichádzajúcej objednávky do vášho systému.
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Vlastná
          • Počet opakovaní: Vlastná
    • Kategórie
      • GET - Ak pracujete aj s kategóriami, je vhodné jednorazové stiahnutie pri aktivácii (sťahovanie cez ?page=), následne vždy reagovať na webhooky (create, update).
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Len pri inštalácii a vlastná
          • Počet opakovaní: Vlastný -> Na základe webhooku
          • Webhooky: ÁNO
    • Zákazníci
      • GET - Jednorazové stiahnutie pri aktivácii (sťahovanie cez ?page=), následne vždy reagovať na webhooky (create, update).
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Len pri inštalácii a vlastná
          • Počet opakovaní: Vlastný -> Na základe webhooku
          • Webhooky: ÁNO
      • PUT - Spätná synchronizácia zákazníka na základe zmeny vo vašom systéme (odhlásenie z newslettera, zmena mena atď.)
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Vlastná
          • Počet opakovaní: Vlastná
    • Konverzné kódy
      • GET - Kontrola pred POST (v rámci aktivácie / prechodu na novú verziu)
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Vlastná / Len pri inštalácii a vlastná
          • Počet opakovaní: Vlastný -> Pri inštalácii doplnku a prechode na novú verziu
      • POST - Založenie konverzného kódu
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Vlastná / Len pri inštalácii a vlastná
          • Počet opakovaní: Vlastný -> Pri inštalácii doplnku a prechode na novú verziu
      • DELETE - Zmazanie konverzného kódu
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Vlastná / Len pri inštalácii a vlastná
          • Počet opakovaní: Vlastný -> Pri inštalácii doplnku a prechode na novú verziu
    • Zľavové kupóny
      • GET - Ak s kupónmi pracujete napríklad v e-mailových kampaniach
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Len pri inštalácii a vlastná
          • Počet opakovaní: Vlastná / 1x za deň (?active_yn / ?date_from + ?page)
      • POST - Založenie zľavového kupónu
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Vlastná
          • Počet opakovaní: Vlastný -> Pri nastavení blahoželania k sviatku atď. u vás v systéme
      • DELETE - Zmazanie zľavového kupónu
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Vlastná
          • Počet opakovaní: Vlastný -> Kupóny môžete nechať expirovať alebo ich rovno zmazať
    • Jazyky
      • GET - Pri aktivácii doplnku na správne nastavenie profilu zákazníka u vás v systéme
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Len pri inštalácii a vlastná
          • Počet opakovaní: Vlastný -> Pri reakcii na webhook
          • Webhook: ÁNO
    • Majiteľ (prevádzkovateľ e-shopu)
      • GET - Pri aktivácii doplnku na spárovanie / založenie účtu vo vašom prostredí
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Len pri inštalácii
    • Webhooky
      • GET - Kontrola pred POST (v rámci aktivácie / prechodu na novú verziu)
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Vlastná / Len pri inštalácii a vlastná
          • Počet opakovaní: Vlastný -> Pri inštalácii doplnku a prechode na novú verziu
      • POST - Založenie webhookov pre najdôležitejšie sekcie Objednávky, Produkty, Jazyky, Doprava a Platba
        • Nastavenie API prístupu v Marketplace:
          • Frekvencia: Vlastná / Len pri inštalácii a vlastná
          • Počet opakovaní: Vlastný -> Pri inštalácii doplnku a prechode na novú verziu

Doplnky, ktoré sú vytvorené pomocou AI alebo na svoje fungovanie využívajú AI, sú určite dnešným trendom.

Tieto doplnky však nefungujú podľa zavedených pravidiel (Best Practices) a aj keď AI dostane jasné príkazy a podmienky, je veľmi pravdepodobné, že aj napriek tomu dokáže vymyslieť vlastný postup, aby dosiahla zadaný cieľ.

Aby sme ochránili používateľské dáta, spísali sme pre vás základné body, ktoré je potrebné z vašej strany vyriešiť:

  • Doplnok by mal fungovať výhradne cez API.
  • Doplnok (typicky riešený cez rozšírenia prehliadača) môže pracovať s obsahom stránky napríklad tak, že nastaví focus alebo inak zvýrazní sekciu, ktorú zákazník hľadá, ale nemal by "fyzicky" zasahovať do stránky administrácie a meniť dáta alebo prepínať nastavenia za zákazníka.
  • Pred úvodnou konzultáciou a pred odoslaním na schválenie je potrebné dôkladne spísať pre nás aj pre klientov, čo je doplnok schopný urobiť (k čomu všetkému má prístup a čo dokáže zabezpečiť: preklady, vyhľadávanie, zmeny stavov objednávok atď.)
    • V budúcnosti bude potrebné vždy pri pridaní novej funkcie kontaktovať našu technickú podporu a informovať nás o tom. A to aj v prípade, keď sa nepridáva ani nemení žiadny API endpoint.
    • Túto zmenu musíte zaznamenať v sekcii Informácie o doplnku a odoslať nám ju na schválenie ešte predtým, ako bude funkcia nasadená a sprístupnená bežným klientom.
  • Dôkladne zabezpečte optimalizované volanie API
    • Volajte zoznamy stránkovane a neumožňujte len tak sťahovať všetky produkty.
    • Neumožnite obchádzať Best Practices pokynom zo strany zákazníka.
    • Doplnok by si mal pri aktivácii stiahnuť zoznam produktov, uložiť ho a následne pracovať s webhookmi. Nie je možné, aby doplnok volal všetky produkty pri každej požiadavke zákazníka (napríklad prostredníctvom chatu).
    • Zabezpečte ochranu pred všeobecnými požiadavkami zo strany klienta. (napríklad: Ku každému produktu pridaj do názvu jeho výrobcu). Doplnok by nemal naraz spustiť volanie 100 000 produktov formou samostatných požiadaviek, ale vytvoriť súhrn a postupovať podľa pravidiel API.
    • Doplnok by mal zabezpečiť cache aktuálneho a naposledy prebiehajúcich chatov aspoň v rámci 1 hodiny. Nemalo by teda dochádzať k tomu, že v jednom chate si doplnok stiahne všetky produkty, kategórie atď., vykonajú sa požiadavky klienta, klient okno zavrie a o minútu si spomenie, že potrebuje ešte niečo upraviť, takže okno znovu otvorí a opäť sa stiahnu všetky produkty, kategórie atď.
    • Ak stále prebieha API komunikácia (dáta sa stále sťahujú alebo odosielajú do Upgates), doplnok by nemal prijímať ďalšie príkazy a vytvárať tak nekonečný rad úkonov.
  • Ochrana dát zákazníka
    • Doplnok by mal pred každým úkonom vykonať validáciu zadanej požiadavky zo strany zákazníka a následne viditeľne uviesť: čo bude presne robiť a nad koľkými produktmi (článkami, kategóriami, parametrami atď.).
    • Doplnok by sa mal po tejto validácii a upozornení vždy opýtať, či to má skutočne vykonať. Nesmie dôjsť k tomu, že klient zadá všeobecnú požiadavku "zmeň dopravu DPD za PPL" a namiesto toho, aby doplnok zmenil názov dopravy v zozname dopráv, začne meniť všetky objednávky aj 10 rokov spätne, pretože majú dopravu DPD.
    • Doplnok by mal zodpovedať za zálohu dát, ktoré upravuje a maže, a poskytnúť možnosť vrátiť sa do stavu pred vykonaním zmien.
    • Doplnok by mal brať do úvahy všetky nadväzujúce funkcie, ktoré Upgates poskytuje. Ak teda hoci aj chybou začne meniť stavy všetkých objednávok, je potrebné počítať s tým, že sa môžu odoslať e-maily a SMS zákazníkom. Hromadné úkony by sa preto nemali vykonávať automaticky, ale vždy s úplným informovaním klienta a jeho potvrdením. Takéto rozhodnutie sa musí tiež u vás zalogovať.
  • Doplnok by mal byť kompatibilný s aktuálnymi verziami a najpoužívanejšími systémami a prehliadačmi
  • Doplnok musí zabezpečiť informovanie zákazníka a uloženie jeho súhlasu s tým, že poskytuje dáta (svoje aj zákazníkov) nielen vašej spoločnosti, ale aj službám tretích strán (OpenAI atď.), ktoré s dátami pracujú a spracúvajú ich.
  • Pri spustení doplnku musí prvý krok obsahovať iframe, v ktorom klient odsúhlasí upozornenie, že doplnok nie je nijako spojený so spoločnosťou Upgates, je plne vo vlastníctve vašej spoločnosti (uviesť, kto má prístup k dátam) a Upgates nenesie zodpovednosť za zmeny dát, ktoré doplnok v e-shope vykoná, ani nevzniká nárok na bezplatné vrátenie dát zo strany Upgates. (vrátane zalogovania tohto súhlasu)
Na tejto stránke

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