Doplňky - Vývoj doplňku (technická dokumentace)

Rozcestník:

• Vytváření a správa doplňku
  • Vývoj doplňku
    • Verifikace doplňku
    • Aktivace doplňku
    • Otevření doplňku
      • Iframe doplňku
    • Deaktivace doplňku
    • Testování doplňku
    • Verzování doplňku (změna fungování)
  • API dokumentace (jak propojit produkty, kategorie, objednávky, atd.)
    • Automatická kontrola a Omezení API doplňku
  • Pravidla a Best Practices
    • Obecné pravidla
    • Aktivace doplňku
    • Otevření doplňku
    • Fungování doplňku
    • Základní očekávané funkce doplňku
  • Webhooky
  • Discord Developer forum (Chcete vědět co se chystá, anebo jen potřebujete poradit?)

Vývoj doplňku

Vývojová část doplňku (záložka Vývoj doplňku) slouží pro napojení doplňku do Upgates administrace a je rozdělena na dvě sekce.

TIP! Než začnete doplněk vytvářet, ikdyž jste prošli úvodní online konzultací, neváhejte hned ze startu založit ticket z vašeho vývojového projektu (případně napište na Discord) a proberme krok za krokem jak by se měl doplněk chovat od aktivace, přes běžný provoz až po speciální případy jako například co dělat s doplňkem, když klient přestave vaši službu platit. Raději vždy pomůžeme v průběhu vývoje samotného doplňku, než abychom narazili na překážky ve schválení doplňku až při samotném testování.

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í najdete endpointy, které musíte na své straně vytvořit. Z naší strany na ně budou chodit požadavky týkající se funkce doplňku.

Endpointy musí být veřejně dostupné a vyžadujeme SSL certifikát na všech API endpointech.

(screen z Marketplace / Moje doplňky - Váš doplněk - Vývoj doplňku)

• Instalační endpoint: Slouží při aktivaci doplňku ze strany klienta.
• Otevírací endpoint: Slouží pro otevření Iframe části doplňku. Z naší strany posíláme informaci Klient X, s tokenem Y chce otevřít váš doplněk. Z vaší strany vracíte v těle požadavku adresu daného iframu.
• Odinstalační endpoint: Slouží při při deaktivaci doplňku. Z naší strany posíláme informaci, že klient doplněk deaktivoval a mažou se API přístupy. Není zapotřebí vaše odpověď.
• Verzovácí endpoint: Slouží k případům kdy zákazník bude přecházet na novou verzi doplňu, na tuto adresu se následně zasílá informace na jakou verzi přechází, abyste mu mohli vrátit správné informace například do iframu / založit konverzní kód, atd.
• Signature_token: Jedinečný identifikátor k vašemu doplňku, sloužící k sestavení podpisu (viz Aktivace, Otevření, Změna verze a Deaktivace)

API přístupy

Tyto API přístupy je nutné navolit podle toho, jak váš doplněk pracuje.
Například: Pokud potřebujete stahovat objednávky, založíte Typ přístupu Objednávky, část GET Objednávky, a nastavíte frekvenci v jaké budete GET provolávat.

Popis účelu využití API přístupu:  Slouží pro nás jako informace o tom, proč API přístup potřebujete a jakou u vás plní funkci.
Frekvence volání: slouží při automatické kontrole vašeho doplňku. Automatická kontrola vyhodnocuje zda-li se váš doplněk drží v nastavených mezích. Tato kontrola je pro nás důležitá, aby pravidelně nebylo přetěžováno API a nefunguje jinak, než způsobem, který jsme si řekli v konzultaci, anebo při testování z naší strany.

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.

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ářů.

Využívejte vždy aktuální loga Upgates.

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.

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 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.

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.