API

Pozor! Propojení prostřednictvím uživatelského API patří mezi příplatkové služby. Výjimkou jsou partnerská API propojení prostřednictvím doplňků označených štítkem "Ověřeno", která jsou zdarma.

Co je to Upgates API

API je aplikační programové rozhraní, které slouží k předávání dat mezi Upgates a dalšími aplikacemi formalizovaným způsobem. Upgates nabízí veřejné API, díky nimž může kdokoli do služby předávat obsah nebo ho z ní odebírat.

Prostřednictvím rozhraní API je řízeno a kontinuálně propojeno velké množství nabízených doplňků. Velkou výhodou této technologie je neustálá aktualizace dat, které je možné mít stále synchronizované na dvou a více místech najednou.

Díky API můžete pracovat s daty v systému (vkládání, aktualizace, čtení, mazání) v reálném čase a propojit např. váš účetní, ERP, nebo jiný systém s Upgates. Když tak aktualizujete například hodnotu zásob skladu v Upgates, aplikace vytvoří požadavek API na změnu stavu v jiném systému.

Uživatelské vs. Partnerské API

API se dělí na dvě části Uživatelské a Partnerské.

Uživatelské API

Slouží klientům Upgates k propojení vlastního nástroje, anebo 3. strany, která aktuálně není součástí Upgates partnerského programu a nemá svůj ověřený doplněk.
Tato část API je placená dle aktuálního ceníku. Pokud si přejete využívat neplacené API, je nutné 3. stranu / váš nástroj přepracovat do Partnerského api a ověřený doplněk.

Omezení API (Limity)

Uživatelské API se řídí nastavenými limity. Každý klient Upgates má e-shop v určitém tarifu dle aktuálního ceníku. Každý tarif má svůj API limit, který limituje počet volání daného API. Jakmile je limit vyčerpán API nebude pro nějaký čas fungovat. Seznam těchto limitů najdete v naší APIary dokumentaci.

Co dělat, když vám limity nestačí?

Pokud vám základní limity v API nestačí a potřebujete více, doporučujeme se nejdříve podívat, zda-li by vaše API napojení nešlo optimalizovat.
Best Practices pro používání API, jsme přehledně vypsali níže v Omezení počtu požadavků a pro vaše vývojáře i v APIary dokumentaci. Pokud byste si s optimalizací vašeho API nevěděli rady a chcete vědět co ve vašem napojení zlepšit, neváhejte se obrátit na naši technickou podporu prostřednictvím ticketovacího systému ve svých administracích.

Pokud jste na své straně API optimalizovali, avšak váš e-shop je natolik velký, že i přes optimalizaci dosahujete základních limitů. Můžete dané limity navýšit.
Navýšení můžete provádět ve své administraci v sekci Doplňky / API - Omezení a ceny.
Zde v sekci Limity požadavků si pomocí "+" a "-" nastavíte počet balíčků, které vám daný limit zvednout. Následně jakmile budete mít počet balíčku nastaven, potvrďte svůj výběr tlačítkem Uložit.

Pokud limit překračujete a nevíte si rady, kolik přesně byste v daném limitu požadavků měli mít nastaveno, můžete využít tlačítka Nastavit doporučený limit v hlášce, která vás na překročení limitu upozorňuje. Systém automaticky nastaví doporučený limit tak, abyste měli dostatečný prostor na fungování přes vaše uživatelské API.
Maximální počet balíčků je 60, což odpovídá 60 000 požadavků za den. Do tohoto limitu by se mělo vejít 99% všech e-shopů.

Pokud máte dodatečné otázky, můžete se podívat na nejčastější řešené situace s API v našem článku.

Partnerské API

Je určeno pro agentury, které chtějí svůj doplněk nabízet klientům Upgates. Na partnerské API se nevztahuje placená část API.
Klienti využívající napojení přes ověřený doplněk agentury mají propojení přes API zdarma.
Pokud jste agentura a máte zájem o ověřený doplněk, více se o tomto můžete dozvědět v naší sekci pro vývojáře.

Jak poznat ověřený doplněk v administraci?

Zobrazení ověřeného doplňku v Administraci

Zobrazení ověřeného doplňku v Marketplace

Omezení počtu požadavků

Počty požadavků jsou sestaveny ze základního limitu podle vybraného tarifu z obchodního modelu (viz ceník). a individuálního limitu, který si každý klient může sám určit (přikoupit).

Jak to tedy funguje?

• Každý limit je tvořen hodinovým a denním počtem požadavků.
• Jakmile je hodinový limit vyčerpán, čerpá se z dodatečného denního limitu.
• Jakmile je hodinový i denní limit vyčerpán, s dalšími požadavky je vždy zapotřebí počkat do začátku další hodiny, kdy se vám počet požadavků za hodinu resetuje.
• O aktuálním stavu počtu požadavku v jednotlivých limitech (za den a hodinu) je váš vývojář informován v odpovědi API komunikace. Jakmile se limity vyčerpaní API komunikace nebude fungovat a vašemu vývojáři bude API vracet hlášku, ve které jej upozorní na překročení limitu.

* Hodinou je myšlen interval počínající od první vteřiny do poslední vteřiny dané hodiny.
** Dnem je myšlen interval počínající od první vteřiny do poslední vteřiny daného dne.

Počet požadavků základního limitu:

Počet požadavků individuálního limitu:

Tento individuální limit je tvořen samostatnými "balíčky", které jsou tvořeny po 1000 požadavcích. Těchto 1000 požadavků je rozděleno mezi denní a hodinový limit.

25 požadavků za hodinu a 400 za den.

Celkem 600(25 požadavků x 24 hodin) + 400/den = 1000

Maximální počet balíčků, který lze dokoupit je 60. To odpovídá 60 000 požadavků za den. Pokud budete potřebovat limit ještě větší, prosím kontaktujte technickou podporu.

Nejčastější chyby v API propojení

Limity jednotlivých verzí jsou nastaveny s velmi dostatečnou rezervou. V 99% případů není potřeba se k tomuto limitu vůbec přiblížit.

Níže uvádíme několik případů nejčastějších chyb:

1. Pravidelné a opakované dotazy místo využití Webhooků.
   Pokud na eshopu neprobíhají změny, je zbytečné se opakovaně doptávat jaké změny na eshopu proběhly. Webhooky ze strany Upgates zasílájí notifikaci přes API o tom, že proběhlo založení, úprava anebo smazání určité sekce (produktů, kategorií, atd.). Teprve až poté může proběhnout dotaz na dané změny.
   Tím pádem například místo 24 dotazů za den, zda-li náhodou není nový produkt, nemusí proběhnout ani jeden dotaz, protože za daný den žádný produkt nevznikl.
   Webhooky navíc ve své zprávě uvádí jaké konkrétní produkty, kategorie, atd. se změnili. tedy je možné stáhnout například jen jeden produkt a není nutné stahovat všechny.
2. Stahování velkého množství dat
   Chápeme, že využívání Webhooků (viz výše bod 1) může být finančně náročnější. Nicméně existují cesty jak i tak snížit zátěž a počet záznamů, se kterými musí obě strany pracovat. Pokud se chcete doptávat například na nové objednávky / produkty, použijte vždy parametr "last_update_time_from" anebo jemu podobný. Takovýto parametr ve vašem dotazu může ovlivnit počet výsledků, které musí Upgates procházet a vy naopak na své straně zpracovávat. Například místo toho, abyste stahovali všechny objednávky a poté u vás zjišťovali, které jsou nové. Jednoduše použijte tento parametr a stáhněte záznamy pouze od určitého data. Tedy například poslední 2 hodiny. Tím pádem místo stahování objednávek za 5 let historie vašeho eshopu, lze stáhnout jen ty nové.
3. Stahování po jednom záznamu
   Každá sekce má možnost stahovat seznamy tzv. stránkovaně. Stránka obsahuje vždy určitý počet záznamů. Tedy místo 100 dotazů na 100 produktů, lze poslat jen 2 dotazy na 2 stránky obsahující 100 produktů.
4. Dotaz na Stav API
   Dotaz na Stav API (/status) není nutné posílat před každým dotazem. Pokud API není aktivní, vámi poslaný dotaz neprojde a API vrátí chybu. Stačí tedy jen s takovými zprávami pracovat a přizpůsobit tomu dané posílání dat.
5. Ignorování chybových hlášek
   Každý dotaz na stranu Upgates vrací i odpověď (response). V této části se objevují chybové hlášky a další důležité informace. Pokud v této odpovědi přichází například zpráva o tom, že byl dovršen limit požadavků, řešením by nemělo být opakovaně posílat dotaz a zjišťovat kdy projde. Je zapotřebí pozastavit komunikaci a vyčkat na uběhnutí časového intervalu.
6. Zbývající počet požadavků
   Každý API dotaz vrací v odpovědi Aktuálně nastavený hodinový / denní limit a to včetně počtu zbývajících požadavků za hodinu / den. S těmito informacemi můžete pracovat a přizpůsobit tomu svou komunikaci, aby právě nedošlo k tomu, že časový limit vyčerpáte.
7. Aktualizace dat
   Pokud nějakou část eshopu aktualizujete, není nutné jí posílat po určitých záznamech. Například pokud upravíte na své straně 10 produktů, není nutné je přes API do Upgates posílat jako 10 požadavků. Můžete je spojit do jednoho. Tím pádem místo 10 požadavků máte pouze jeden.

Dokumentace

Konkrétní možnosti API najdete ve veřejně dostupné dokumentaci.

Upgates API splňuje principy RESTu. Do API Upgates je možné se připojit pomocí unikátního přístupu. Jedná se o bezpečnostní pojistku, aby nemohl vaše data čerpat někdo neoprávněný.