Dokumentace API - Základní informace

Základní informace

  • Pro komuninaci s API budete potřebovat vytvořit přístup, to můžete udělat v administraci na Propojení > API.
  • API je na adrese: https://NAZEV-PROJEKTU.admin.ZNACKA-SERVERU.upgates.com/api/v2.
  • Každý požadavek, který má v těle JSON, by měl mít 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í.

Autentizace

  • Musíte si v administraci založit přístup do API.
  • Autentizace probíhá pomocí HTTP Basic authentication.
  • Každý požadavek musí mít hlavičku Authorization. Hodnotou této hlavičky je Basic a v base64 zakodované login:heslo.
  • Celá hlavička může vypadat např. takto: Authorization: Basic dGVzdDp0ZXN0
  • Po 5-ti špatných pokusech se API zablokuje a vrací 403

Stavové kódy

  • 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 nevrací hlavičku Location, pouze v těle požadavku vrací JSON s novou adresou { "api_url": "https://NAZEV-PROJEKTU.admin.ZNACKA-SERVERU.upgates.com/api/v2" }. Je potřeba ji změnit na všech místech, kde je použita původní adresa.
  • 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í, 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

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. API podporuje následující HTTP metody:

  • POST - vytvoření
  • PUT - aktualizace
  • DELETE - smazání
  • GET - získání dat

Datové typy

Položky které jsou v popisech jednotlivých endpointů tučně jsou povinné, datový typ je uveden v závorce u každé položky v popisu jednotlivých API.

  • bool - true / false, 1 / 0
  • string - standardní řetězec znaků v UTF-8
  • int - celé číslo
  • float - desetinné číslo, jako oddělovač desetinných míst používejte tečku
  • array - pole hodnot
  • object - JSON Object
  • email - validní emailová adresa
  • date - datum zapsané jako řeťezec znaků dle ISO 8601
  • language - kód jazyka dle ISO 639-1
  • currency - kód měny dle ISO 4217
  • country - kód země dle ISO 3166-1 alpha-2

Rate Limiting (Omezení provozu)

Aby nedošlo, ať už neúmyslně špatným návrhem, nebo úmyslně k přílišnému zahlcení API požadavky, je API omezeno.

Omezení přihlášení

  • Je omezen počet pokusů o přihlášení, tzn, že můžete udělat pouze 5 špatných přihlášení za 1 hodinu na jednu IP adresu. Potom API zablokuje přístup a vrací stav 403. Opět se používá Floating Time Window.

Omezení velikosti požadavku

  • Je omezena velikost PUT požadavku, tzn. že v JSONu může být maximálně 100 položek. Pokud je tento počet překročen, neprovede žádná operace (API veškerá data zahodí) a vrací stav 413.

Souběžné požadavky

  • Na API je možno provádět pouze 3 souběžné požadavky, pokud je toto překročeno vrací stav 429.

Jak na API napojení (rady a tipy)

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

  • většina endpointů má možnost filtrovat položky podle času poslední změny, tzn. že si můžete vytáhnout (např. produkty) od času posledního volání API a tím ušetřit čas a 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 zakladání nebo aktualizace výrazně zrychlí a není nutné volat API 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, nejčastěji GET požadavek pro objednávky
  • pro každé napojení si vytvořte zvláštní přístup (uživatele), kterému omezíte přístup pouze na ty služby které potřebuje, v budoucnu je pak jednodušší takové napojení deaktivovat nebo zrušit

Testování

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

Na této stránce

Další zdroje informací

Facebook poradna

Výměna zkušeností, rady a tipy mezi provozovateli e-shopů na systému UPgates.

Přejít do poradny

Akademie

Získejte znalosti od našich specialistů na marketing, obchod, právo a podnikání.

Přejít do akademie

Novinky z Blogu

Co nového jsme pro vás připravili nebo chystáme najdete na blogu.

Přejít do blogu

Nepodařilo se Vám najít tu správnou odpověď?

Kontaktujte naši technickou podporu, která je tu pro vás od pondělí do pátku 8:00 až 16:00 hod.

Zákaznická podpora