1. Produkt
  2. Pro vývojáře
  3. Doplňky
  4. API dokumentace - Doplňky

API dokumentace - Doplňky

Slouží pro napojení doplňku do administrace Upgates e-shopů. Jakmile klient požádá o aktivaci, deaktivaci nebo otevření daného doplňku, systém vyhodnotí odpověď na požadavek zaslaný na endpoint doplňku. Následně zobrazí klientovi výsledek (úspěšný nebo neúspěšný).

  • Vyžadujeme SSL certifikát na všech API endpointech.

Rozcestník:

Podepisování

Data podepisujeme privátním klíčem a vy si je můžete zkontrolovat veřejným klíčem metodou OPENSSL_ALGO_SHA256. Podpis můžete nalézt v každém těle požadavku pod klíčem signature. Dle požadavků se podepisují příslušná data.

  • Z podepisovaných dat je vyjmut current_admin_language.
  • Jednotlivá podepisovaná data nalezenete u každého endpointu.
  • Doporučujeme vždy načítat aktuální veřejný klíč při ověřování podpisu a neukládat jej u sebe pro pozdější použití. Důvodem je možnost změny klíčů.

Testování

Během žádosti o implementaci doplňku v administraci jste vyplňovali testovací projekt/e-shop. V případě schválení techniky Upgates bude možné vidět váš doplněk pouze v administraci tohoto konkrétního projektu, v seznamu doplňků. Budete mít možnost si jej aktivovat, deaktivovat a případně zobrazit/přejít na jeho detail.

Příklad ověření podpisu v PHP

<?php
$data = implode(";",[...]);
$signature = 'a0e0a3e7689bd4c80e4d6ffcccb05235b864e1d0';
$signaturePublicKey = file_get_contents("https://files.upgates.com/addons/signature/api.signature.pub.key");
$verify = openssl_verify($data, base64_decode($signature), $signaturePublicKey, OPENSSL_ALGO_SHA256);

Best practices

Obecné

  • 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.
  • 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.
  • 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.
  • Dbát při implementaci na nepřetěžování serveru(využívat webhooky) - porušení může způsobit blokaci API přístupů doplňku na všechny eshopy.
  • Hlavním cílem při kontrole z naší strany vašeho doplňku, bude zajistit co nejlepší používání API.
    • Místo opakovaných dotazů (například na stavy objednávek, jazyky, majitel, atd.) využívejte co nejvíce cache
    • 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 stiknout znovu, pokud běží ještě původní proces synchronizace.

Aktivace doplňku

Založení účtu

  • Pro založení nebo spárování účtu můžete využít /owner
  • Založení účtu doporučujeme finalizovat v iframe okně v administraci například tlačíky "Stávající zákazník", "Nový zákazník s emailem /owner", "Nový zákazník".
    (Je to tak z důvodu, že uživatel může mít více ownerů dle jazyků, a vy můžete spravovat mutace / domény v 1 účtu a nevíte na jaký finálně založit účet).
  • Jakmile získáte informace z owner, založte zákazníkovi účet tak, aby hned získal přihlašovací údaje do svého účtu ve vašem prostředí a měl tak možnost se odhlásit a přihlásit kdykoli bude potřebovat.
  • 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

Zpracování dat / Dodatečná finalizace aktivace propojení

  • Pokud aktivace doplňku u vás podléhá nějakému zpracování, je nutné uvést do iframe doplňku přesný odkrokovaný proces zpracování žádosti a postupně měnit aktuální stav tak, aby zákazník vždy věděl, v jakém stavu je jeho zpracování aktivace. Zároveň také musí být uveden telefon a email na vaší společnost, aby se zákazník na vás mohl obrátit.

Sestavení doplňku

Products

  • Varianty je možné posílat v jednom požadavku, není nutné každou variantu posílat zvlášť.
  • Pokud potřebujete produkty aktualizovat, aktualizujte pouze takové sekce, které potřebujete. Pokud budete například vkládat pouze překlady, nemusíte k tomu posílat váhu, zda-li má být produkt vložitelný do košíku, atd.

Orders

  • Pokud potřebujete mít ve svém doplňku tlačítko na stahování aktuálních objednávek, myslete nejdříve na 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.

Orders, Products, Customers, Categories

  • Místo stahování všech objednávek, využívejte nejlépe webhooky. V nejzažším případě můžete použít last_update_time na aktuální den, kterým si nové produkty stáhnete.

Owner, languages

  • Tyto sekce nepotřebují pravidelné stahování. Využívejte cache

FAQ

Často kladené otázky.

Chci pracovat s informacemi o aktuálně přihlášeném uživateli při otevření doplňku?

Bude možné využít nový endpoint pro stažení informací o uživatelích, na kterém aktuálně pracujeme. V endpointu pro otevření doplňku přibude informace s indentifikátorem uživatele. Je nutno vyžádat si a zdůvodnit si přístup pro tento nový endpoint při žádosti o založení doplňků.

Další článek
Aktivace doplňku