Vývoj doplnku
Sprievodca prepojením vašej služby s Upgates
REST API JSON Webhooks HTTPS (povinné)
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.
Administrácia e-shopu
- aktivuje a deaktivuje doplnok,
- odovzdáva API prístupové údaje,
- otvára používateľské rozhranie doplnku,
- odosiela informácie o zmene verzie.
Backend doplnku
- overuje podpis prichádzajúcich požiadaviek,
- bezpečne ukladá API prístupy,
- komunikuje s REST API Upgates,
- spracúva udalosti z webhookov.
Upgates volá inštalačný, otvárací, odinštalačný a prípadne verzovací endpoint vašej služby.
Backend doplnku číta alebo mení dáta e-shopu pomocou REST API v2.
Nové a upravené záznamy backend spracúva primárne na základe webhookov.
URL adresu dostanete v rámci úvodnej inicializácie doplnku. Bežný tvar adresy:
https://NAZEV-ESHOPU.admin.ZNACKA-SERVERU.upgates.com/api/v2
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.
Spustí aktiváciu, založenie alebo spárovanie účtu a počiatočnú konfiguráciu doplnku.
Dokumentácia
Overí používateľa a vráti adresu prostredia doplnku, ktoré možno otvoriť v administrácii Upgates pomocou iframe.
Dokumentácia
Informuje o deaktivácii doplnku a zneplatnení jeho API prístupov. Zastavte súvisiace úlohy a ukončite prepojenie.
Dokumentácia
Spracuje prechod zákazníka na novú verziu a vykoná potrebné zmeny konfigurácie, webhookov alebo používateľského rozhrania.
Dokumentácia
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.
- Overiť podpis (viac tu)
- Uložiť prístupy
- Načítať /owner
- Založiť účet / Spárovať existujúci
- 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.
Aktiváciu automatizujte
Po aktivácii doplnku vytvorte alebo prepojte zákaznícky účet bez zbytočných medzikrokov.
- Získajte informácie o prevádzkovateľovi e-shopu pomocou
/owner. - Automaticky vytvorte nový účet alebo prepojte už existujúci.
- Po dokončení priveďte používateľa priamo do funkčného prostredia.
- Opakovanú aktivačnú požiadavku spracujte bezpečne a idempotentne.
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ípraveUpgates 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.
- Overiť podpis
- Zastaviť synchronizáciu
- 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.
{
"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ď.
Logá Upgates
Vždy používajte aktuálne logá Upgates
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.
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ď.
- Napríklad rozdeliť pool e-shopov a pridávať offsety po hodinách alebo iných väčších časových úsekoch:
- 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.
- Čo to pre vás znamená?
- 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í.
Doprava a logistika
Expedičné systémy
- 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
- Nastavenie API prístupu v Marketplace:
- 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á
- Nastavenie API prístupu v Marketplace:
- 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
- Nastavenie API prístupu v Marketplace:
- GET - Možné jednorazové stiahnutie pri aktivácii doplnku, následne vždy reagovať na webhooky
- GET - Možné jednorazové stiahnutie k určitému dátumu spätne pri aktivácii (sťahovanie cez
- 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
- Nastavenie API prístupu v Marketplace:
- 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á
- Nastavenie API prístupu v Marketplace:
- GET - Ak pracujete aj s produktmi, je možné jednorazové stiahnutie pri aktivácii (sťahovanie cez
- 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
- Nastavenie API prístupu v Marketplace:
- 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.
- 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
- Nastavenie API prístupu v Marketplace:
- GET - Pri aktivácii doplnku na spárovanie / založenie účtu vo vašom prostredí
- 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
- Nastavenie API prístupu v Marketplace:
- 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
- Nastavenie API prístupu v Marketplace:
- GET - Kontrola pred POST (v rámci aktivácie / prechodu na novú verziu)
- Objednávky
- 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)).
Fulfillment
- 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
- Nastavenie API prístupu v Marketplace:
- 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á
- Nastavenie API prístupu v Marketplace:
- 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
- Nastavenie API prístupu v Marketplace:
- GET - Možné jednorazové stiahnutie pri aktivácii doplnku, následne vždy reagovať na webhooky
- GET - Možné jednorazové stiahnutie k určitému dátumu spätne pri aktivácii (sťahovanie cez
- 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
- Nastavenie API prístupu v Marketplace:
- 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á
- Nastavenie API prístupu v Marketplace:
- 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
- Nastavenie API prístupu v Marketplace:
- GET - Stiahnutie parametrov z produktu
- GET - Ak pracujete aj s produktmi, je možné jednorazové stiahnutie pri aktivácii (sťahovanie cez
- 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
- Nastavenie API prístupu v Marketplace:
- 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.
- 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
- Nastavenie API prístupu v Marketplace:
- GET - Pri aktivácii doplnku na spárovanie / založenie účtu vo vašom prostredí
- 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
- Nastavenie API prístupu v Marketplace:
- 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
- Nastavenie API prístupu v Marketplace:
- GET - Kontrola pred POST (v rámci aktivácie / prechodu na novú verziu)
- Objednávky
Komunikácia
Emailing
- 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.
- Mailingové doplnky, musia podporovať obojsmernú synchronizáciu kontaktov.
- 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.
- Nastavenie API prístupu v Marketplace:
- GET - Možné jednorazové stiahnutie k určitému dátumu spätne pri aktivácii (sťahovanie cez
- 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
- Nastavenie API prístupu v Marketplace:
- 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á
- Nastavenie API prístupu v Marketplace:
- GET - Ak pracujete aj s produktmi, je vhodné jednorazové stiahnutie pri aktivácii (sťahovanie cez
- 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
- Nastavenie API prístupu v Marketplace:
- GET - Ak pracujete aj s kategóriami, je vhodné jednorazové stiahnutie pri aktivácii (sťahovanie cez
- 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
- Nastavenie API prístupu v Marketplace:
- 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á
- Nastavenie API prístupu v Marketplace:
- GET - Jednorazové stiahnutie pri aktivácii (sťahovanie cez
- 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
- Nastavenie API prístupu v Marketplace:
- 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
- Nastavenie API prístupu v Marketplace:
- 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
- Nastavenie API prístupu v Marketplace:
- GET - Kontrola pred POST (v rámci aktivácie / prechodu 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)
- Nastavenie API prístupu v Marketplace:
- 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
- Nastavenie API prístupu v Marketplace:
- 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ť
- Nastavenie API prístupu v Marketplace:
- GET - Ak s kupónmi pracujete napríklad v e-mailových kampaniach
- 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
- Nastavenie API prístupu v Marketplace:
- GET - Pri aktivácii doplnku na správne nastavenie profilu zákazníka u vás v systéme
- 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
- Nastavenie API prístupu v Marketplace:
- GET - Pri aktivácii doplnku na spárovanie / založenie účtu vo vašom prostredí
- 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
- Nastavenie API prístupu v Marketplace:
- 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
- Nastavenie API prístupu v Marketplace:
- GET - Kontrola pred POST (v rámci aktivácie / prechodu na novú verziu)
- Objednávky
AI - Umelá inteligencia
AI doplnky
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)