API

Pozor! Prepojenie prostredníctvom Užívateľského API patrí medzi príplatkové služby. Výnimkou sú Partnerské API prepojenia prostredníctvom doplnkov označených štítkom "Overené," ktoré sú zadarmo.

Čo je Upgates API

API je aplikačné programovacie rozhranie, ktoré sa používa na odovzdávanie údajov medzi Upgates a inými aplikáciami formalizovaným spôsobom. Upgates ponúka verejné API, ktoré umožňuje komukoľvek odovzdávať obsah do služby alebo zo služby.

Veľké množstvo ponúkaných doplnkov sa spravuje a priebežne pripája prostredníctvom API. Veľkou výhodou tejto technológie je neustála aktualizácia údajov, ktoré môžu byť synchronizované na dvoch alebo viacerých miestach súčasne.

Vďaka API môžete pracovať s údajmi v systéme (vkladať, aktualizovať, čítať, mazať) v reálnom čase a prepojiť napr. účtovníctvo, ERP alebo iný systém s Upgates. Takže keď aktualizujete napr. hodnotu zásob v systéme Upgates, aplikácia vytvorí požiadavku API na zmenu stavu v inom systéme.

Užívateľské API

Slúži klientom Upgates na prepojenie vlastného nástroja, alebo 3. strany, ktorá aktuálne nie je súčasťou Upgates partnerského programu a nemá svoj overený doplnok.
Táto časť API je platená podľa aktuálneho cenníka. Pokiaľ si prajete využívať neplatené API, je nutné 3. stranu / váš nástroj prepracovať do Partnerského api a overený doplnok.

Ako Používateľské API aktivovať

1. Prihláste sa do svojej administrácie Upgates,
2. Prejdite do sekcie Doplnky,
3. Vyhľadajte vo vyhľadávacom poli API,
4. Kliknite na Aktivovať,
5. V detaile doplnku, ktorý sa vám po aktivácii otvorí, kliknite na tlačidlo +Nové,
6. Vo vyskakovacom okne pomenujte API prístupy (najlepšie podľa toho komu ich udeľujete),
7. Navoľte sekcie, do ktorých chcete 3. strane udeliť prístup,
8. Uložte,
9. Po vytvorení odovzdajte 3. strane:
   • URL adresu (nájdete pod tabuľkou s vytvoreným API prístupom adresa je v tvare https://vasprojekt.admin.server.upgates.com/api/v2)
   • Hodnoty zo stĺpcov LOGIN a KĽÚČ API (ten si najskôr zobrazte).

Pozor! Pre každú 3. stranu využívajte vždy jedinečný prístup. Nikdy neoznamujte jeden login a heslo viacerým 3. stranám.

Obmedzenie API (LImity)

Užívateľské API sa riadi nastavenými limitmi. Každý klient Upgates má e-shop v určitej tarife podľa aktuálneho cenníka. Každá tarifa má svoj API limit, ktorý limituje počet volaní daného API. Akonáhle je limit vyčerpaný API nebude pre nejaký čas fungovať. Zoznam týchto limitov nájdete v našej APIary dokumentácii.

Čo robiť, keď vám limity nestačia?

Pokiaľ vám základné limity v API nestačia a potrebujete viac, doporučujeme sa najskôr pozrieť, či by vaše API napojenie nešlo optimalizovať.
Best Practices pre používanie API, sme prehľadne vypísali v našej APIary dokumentáciu. Pokiaľ by ste si s optimalizáciou vášho API nevedeli rady a chcete vedieť čo vo vašom napojení zlepšiť, neváhajte sa obrátiť na našu technickú podporu prostredníctvom ticketovacieho systému vo svojich administráciách.

Pokiaľ ste na svojej strane API optimalizovali, avšak váš e-shop je natoľko veľký, že aj napriek optimalizácii dosahujete základné limity. Môžete dané limity navýšiť.
Navýšenie môžete vykonávať vo svojej administrácii v sekcii Doplnky / API - Obmedzenia a ceny.
Tu v sekcii Limity požiadaviek si pomocou "+" a "-" nastavíte počet balíčkov, ktoré vám daný limit zdvihnú. Následne akonáhle budete mať počet balíčka nastavený, potvrďte svoj výber tlačidlom Uložiť.

Pokiaľ limit prekračujete a neviete si rady, koľko presne by ste v danom limite požiadaviek mali mať nastavené, môžete využiť tlačidlá Nastaviť odporúčaný limit v hláške, ktorá vás na prekročenie limitu upozorňuje. Systém automaticky nastaví odporúčaný limit tak, aby ste mali dostatočný priestor na fungovanie cez vaše užívateľské API.
Maximálny počet balíčkov je 60, čo zodpovedá 60 000 požiadaviek za deň. Do tohto limitu by sa mal vliesť 99% všetkých e-shopov.

Ak máte dodatočné otázky, môžete sa pozrieť na najčastejšie riešené situácie s API v našom článku.

Partnerské API

Je určené pre agentúry, ktoré chcú svoj doplnok ponúkať klientom Upgates. Na partnerské API sa nevzťahuje platená časť API.
Klienti využívajúci napojenie cez overený doplnok agentruy majú prepojenie cez API zadarmo.
Pokiaľ ste agentúra a máte záujem o overený doplnok, viac sa o tomto môžete dozvedieť v našej sekcii pre vývojárov.

Ako spoznať overený doplnok v administrácii?

Zobrazenie overeného doplnku v Administrácii

Zobrazenie overeného doplnku v Marketplace

Obmedzenie počtu požiadaviek

Počet požiadaviek sa skladá zo základného limitu podľa zvolenej tarify z obchodného modelu (cenník) a individuálneho limitu, ktorý si môže každý klient určiť (pridať).

Ako to teda funguje?

• Každý limit sa skladá z hodinového a denného počtu požiadaviek.
• Po vyčerpaní hodinového limitu sa čerpá dodatočný denný limit.
• Po vyčerpaní hodinového a denného limitu musíte s ďalšími požiadavkami vždy počkať do začiatku nasledujúcej hodiny, kedy sa počet požiadaviek za hodinu vynuluje.
• Váš vývojár je informovaný o aktuálnom stave počtu požiadaviek v každom limite (za deň a hodinu) v odpovedi na komunikáciu API. Po vyčerpaní limitov nebude komunikácia API fungovať a API vráti vášmu vývojárovi správu s upozornením, že limit bol prekročený.

* Hodinou sa rozumie interval od prvej sekundy po poslednú sekundu hodiny.
** Deň je interval začínajúci prvou sekundou a končiaci poslednou sekundou daného dňa.

Počet požiadaviek základného limitu:

Počet jednotlivých žiadostí o limit:

Tento individuálny limit sa skladá zo samostatných "balíkov", z ktorých každý pozostáva z 1000 požiadaviek. Týchto 1000 požiadaviek je rozdelených medzi denný a hodinový limit.

25 požiadaviek za hodinu a 400 za deň.

Celkom 600(25 požiadavky x 24hodin) + 400den = 1000

Maximálny počet balíkov, ktoré je možné zakúpiť, je 60. To zodpovedá 60 000 požiadavkám za deň. Ak potrebujete ešte vyšší limit, kontaktujte technickú podporu.

Najčastejšie chyby v API prepojení

Limity jednotlivých verzií sú nastavené s veľmi dostatočnou rezervou. V 99% prípadov nie je potrebné sa k tomuto limitu vôbec priblížiť.

Nižšie uvádzame niekoľko prípadov najčastejších chýb:

1. Pravidelné a opakované otázky namiesto využitia Webhookov.
   Ak na eshope neprebiehajú zmeny, je zbytočné sa opakovane opýtať aké zmeny na eshope prebehli. Webhooky zo strany Upgates zasielajú notifikáciu cez API o tom, že prebehlo založenie, úprava alebo zmazanie určitej sekcie (produktov, kategórií, atď.). Až potom môže prebehnúť otázka na dané zmeny.
   Tým pádom napríklad namiesto 24 otázok za deň, či náhodou nie je nový produkt, nemusí prebehnúť ani jedna otázka, pretože za daný deň žiadny produkt nevznikol.
   Webhooky navyše vo svojej správe uvádza aké konkrétne produkty, kategórie, atď. sa zmenili. teda je možné stiahnuť napríklad len jeden produkt a nie je nutné sťahovať všetky.
2. Sťahovanie veľkého množstva dát
   Chápeme, že využívanie Webhookov (pozri vyššie bod 1) môže byť finančne náročnejšie. Avšak existujú cesty ako aj tak znížiť záťaž a počet záznamov, s ktorými musia obe strany pracovať. Pokiaľ sa chcete opýtať napríklad na nové objednávky / produkty, použite vždy parameter "last_update_time_from" alebo jemu podobný. Takýto parameter vo vašom dotaze môže ovplyvniť počet výsledkov, ktoré musí Upgates prechádzať a vy naopak na svojej strane spracovávať. Napríklad namiesto toho, aby ste sťahovali všetky objednávky a potom u vás zisťovali, ktoré sú nové. Jednoducho použite tento parameter a stiahnite záznamy iba od určitého dátumu. Teda napríklad posledné 2 hodiny. Tým pádom namiesto sťahovania objednávok za 5 rokov histórie vášho eshopu, je možné stiahnuť len tie nové.
3. Sťahovanie po jednom zázname
   Každá sekcia má možnosť sťahovať zoznamy tzv. stránkovane. Stránka obsahuje vždy určitý počet záznamov. Teda namiesto 100 otázok na 100 produktov, je možné poslať len 2 otázky na 2 stránky obsahujúce 100 produktov.
4. Otázka na Stav API
   Otázka na Stav API (/status) nie je nutné posielať pred každým dotazom. Ak API nie je aktívna, vami poslaný dotaz neprejde a API vráti chybu. Stačí teda len s takými správami pracovať a prispôsobiť tomu dané posielanie dát.
5. Ignorovanie chybových hlášok
   Každá otázka na stranu Upgates vracia aj odpoveď (response). V tejto časti sa objavujú chybové hlášky a ďalšie dôležité informácie. Ak v tejto odpovedi prichádza napríklad správa o tom, že bol dovŕšený limit požiadaviek, riešením by nemalo byť opakovane posielať dotaz a zisťovať kedy prejde. Je potrebné pozastaviť komunikáciu a počkať na ubehnutie časového intervalu.
6. Zostávajúci počet požiadaviek
   Každý API dotaz vracia v odpovedi Aktuálne nastavený hodinový / denný limit a to vrátane počtu zostávajúcich požiadaviek za hodinu / deň. S týmito informáciami môžete pracovať a prispôsobiť tomu svoju komunikáciu, aby práve nedošlo k tomu, že časový limit vyčerpáte.
7. Aktualizácia dát
   Pokiaľ nejakú časť eshopu aktualizujete, nie je nutné ju posielať po určitých záznamoch. Napríklad, ak upravíte na svojej strane 10 produktov, nie je nutné ich cez API do Upgates posielať ako 10 požiadaviek. Môžete ich spojiť do jedného. Tým pádom namiesto 10 požiadaviek máte iba jeden.

Dokumentácia

Konkrétne možnosti API nájdete vo verejne dostupnej dokumentácii.

Upgates API spĺňa princípy RESTu.Do API Upgates je možné sa pripojiť pomocou unikátneho prístupu. Ide o bezpečnostnú poistku, aby nemohol vaše dáta čerpať niekto neoprávnený.