Copy page

API

Základní informace

Upgates API slouží jako rozhraní pro přístup do e-shopů Upgates. Díky Upgates 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.

• Pokud vytváříte vlastní napojení, zvažte použití již hotových doplňků, nebo si přečtěte tipy pro vlastní napojení
• Pro komunikaci s API budete potřebovat vytvořit přístup. To můžete udělat v administraci e-shopu v sekci Doplňky / API.
• API je dostupné na URL adrese: https://NAZEV-ESHOPU.admin.ZNACKA-SERVERU.upgates.com/api/v2 Přesný tvar URL adresy najdete v administraci e-shopu v sekci Doplňky / API.
• Každý požadavek, který má v těle JSON, by měl obsahovat hlavičku Content-Type: application/json.
• V případě chyby vrací API JSON s textem zprávy a odpovídající stavový kód.
• API pracuje v kódování UTF-8, tzn. obsah všech požadavků musí být v tomto kódování.
• Většina endpointů vrací chybové hlášky (pole messages). Je to pole objektů, kde je informace o tom ve kterém objektu a které property je jaká chyba. Usnadňuje to odhalení chyby při nevalidním formátu JSON požadavku.

Autentizace

• Autentizace probíhá pomocí HTTP Basic authentication.
• Musíte si v administraci založit přístup do API (Administrace / Doplňky - API).
• Každému API uživateli je možné omezit přístupová práva na jednotlivé API endpointy. Konkrétní seznam včetně přístupových práv lze získat pomocí endpointu Stav API, který je vždy povolen pro všechny uživatele API.
• Každý API přístup je přiřazen do skupiny, skupiny se přiřazují automaticky a slouží pro Rate limiting
• Po 5-ti špatných pokusech se API zablokuje a vrací chybovou hlášku 403 (viz. Omezení přihlášení).

Stavové kódy

Kód	Název	Popis
200	OK	úspěšně zpracovaný požadavek, ve většině případů vrací JSON (viz. popis konkrétních endpointů)
301	Moved Permanently	e-shop byl přesunut na jiný server. V tomto případě server vrací hlavičku Location, kde je nová adresa. Adresu si u sebe musíte změnit na novou.
400	Bad Request	špatný požadavek, nevalidní JSON v těle požadavku. Pokud požadavek vyžaduje JSON, musí to být JSON Object
401	Unauthorized	chyba při autentizaci, chybějící hlavička pro autentizaci nebo špatné přihlašovací údaje
403	Forbidden	API uživatel není aktivní, nebo byl překročen maximální počet pokusů o přihlášení. Případně uživatel nemá práva na endpoint nebo metodu endpointu
404	Not Found	špatná URL adresa požadavku
405	Method Not Allowed	nepodporovaná metoda API nebo metoda konkrétního endpointu není implementována
413	Payload Too Large	překročena velikost PUT požadavku - počet položek v JSONu (viz. Rate Limiting)
429	Too Many Requests	překročen maximální počet požadavků (viz. Rate Limiting)
500	Internal Server Error	chyba serveru. Pokud nastane, kontaktujte technickou podporu Upgates
501	Not Implemented	metoda není implementována

HTTP metody

• API podporuje 4 základní HTTP metody: POST, GET, PUT, DELETE. Bližší popis je u každého endpointu.
• Pro přepsání HTTP metody můžete použít hlavičku X-HTTP-Method-Override. Požadavek může být např. POST, ale v pokud bude v požadavku tato hlavička s hodnotou DELETE, vyhodnotí se jako DELETE.

Stránkování

Většina endpointů podporujících metodu GET nevrací kompletní seznam položek, ale pouze jejich první stranu. Pomocí parametru page lze určit konkrétní stranu, která se ve výpisu zobrazí. Odpověď pak obsahuje ještě další parametry, pomocí kterých můžete stránkovat.

• current_page - aktuální strana
• current_page_items - počet položek na aktuální straně
• number_of_pages - celkový počet stran
• number_of_items - celkový počet položek

Obrázky

• platí pouze pro vytvoření a aktualizaci produktů a kategorií

Přidání obrázku

• přidání existujícího obrázku posláním parametru file_id (soubor musí už existovat)
• přidání nového obrázku
  • pomocí URL adresy - obrázek nebude stažen ze zadané URL adresy v průběhu zpracovávání požadavku, ale později na pozadí
  • posláním obsahu souboru - bude vytvořen nový soubor a bude přiřazen (zatím pouze u produktu)

Duplicitní obrázky

• systém řeší duplicitní soubory při jejich nahrávání přes API a to tak že porovnává jejich obsah a URL adresu ze které pochází
• pokud nahrávám obrázek z URL adresy, pokusí se vyhledat obrázek který pochází ze stejné URL adresy (u každého obrázku se pamatuje adresa ze které byl stažen), pokud ho najde použije se.
• při nahrávání obsahu souboru se kontroluje obsah souboru (systém porovnává hash obsahu souboru), pokud najde v databázi stejný hash, použije se soubor s tímto hashem.

Jak na API napojení (rady a tipy)

Pro maximální optimalizaci API propojení doporučujeme tyto postupy:

• Většina endpointů má možnost filtrovat položky podle času poslední změny, jazyka a dalších parametrů. Tzn. že si můžete vytáhnout např. produkty od času posledního volání API a tím ušetřit čas i množství požadavků na stahování produktů.
• V PUT a POST požadavku je možné posílat až 100 položek. Tím se zakládání nebo aktualizace výrazně zrychlí a není nutné volat API pouze s jednou položkou.
• Zvažte, jak často je třeba API volat. Mnohokrát se stává, že voláte API zbytečně často. Většinou se jedná o GET požadavek pro objednávky.
• Zvažte jestli u sebe pro data která se tak často nemění (seznamy číselníků jako jsou stavy objednávek atd.) nepoužívat cache.
• Používejte webhooky (dokumentace).
• Pro každé napojení si vytvořte zvláštní přístup (uživatele), kterému omezíte přístup pouze na potřebné služby. V budoucnu je poté jednodušší takové napojení deaktivovat nebo zrušit.

Testování

Pro testování API můžete použít:

• Postman
• Rozšíření RESTED pro Mozilla Firefox
• Upgates API client - jednoduchý API klient v PHP

Discord fórum

Discord fórum slouží vývojářům, kteří pracují s API a mají dotaz na naše developery. Zároveň prosíme o pochopení, že se nejedná o žádný online chat a může se stát, že nedostanete odpověď ihned. Děkujeme za pochopení. Discord pozvánka na fórum.