Začínáme

Nejprve se, prosím, ujistěte, že AlzaTrade API je skutečně to, co chcete používat. Nejedná se totiž o Drop API. Drop API a AlzaTrade API jsou rozdílné služby a nesouvisí se sebou.

Chcete-li začít používat API AlzaTrade, je nutné si nejprve zažádat o aktivaci API klienta z Vašeho účtu v AlzaTrade. Jakmile je Váš požadavek vyřešen a API klient aktivován, v portálu se vám zobrazí vaše klientské ID (Client ID) a tajný klíč (Secret key).

Doporučujeme si vyzkoušet volání dostupných endpointů nejprve přes generovanou dokumentaci Swagger (více viz kapitola Dokumentace) a poté přejít k programové integraci.

Dokumentace

Dokumentaci API naleznete ve formě Swaggeru. Verzi API si můžete zvolit z výběru v pravém horním rohu, doporučujeme používat vždy nejaktuálnější verzi API, staré verze jsou po určité době postupně mazány.

Volání jednotlivých endpointů si můžete vyzkoušet přímo ve Swaggeru. Nejprve je nutné se přihlásit stisknutím tlačítka Authorize a vyplnit vaše Client ID a tajný klíč. Tyto údaje naleznete ve svém účtu v AlzaTrade. Následně je možné rozkliknout jakýkoliv endpoint, stisknout tlačítko Try it out, vyplnit parametry a tlačítkem Execute provést volání.

AlzaTrade API klient

Nejprve je nutné svého klienta autentizovat. Autentizace je řešena pomocí Bearer tokenu, který získáte POST requestem na URL https://identity.alza.cz/connect/token. V těle požadavku je potřeba poslat následující údaje:

• client_id: *vaše_client_id*
• client_secret: *váš_tajný_klíč*
• grant_type: client_credentials

Pokud Váš tajný klíč obsahuje speciální znaky (pro cURL např. &, ^, %), nezapomeňte je escapovat. Příklad získání tokenu pomocí cURL:

curl -X POST "https://identity.alza.cz/connect/token" -H "Content-Type: application/x-www-form-urlencoded" -d "client_id=ZDE_DOPLNIT&client_secret=ZDE_DOPLNIT&grant_type=client_credentials"

Token má platnost 1 hodinu (3600 vteřin). Po uplynutí této doby expiruje a je potřeba opět zavolat identity server pro nový token.

Důrazně doporučujeme, abyste při integraci svého klienta neposílali na identity server příliš mnoho požadavků, ale využívali získaný token opakovaně. V opačném případě budete automaticky zařazeni na blacklist a budete muset žádat o ruční odstranění. To stejné se stane, pokud pošlete opakovaně požadavek s nesprávnými přihlašovacími údaji.

Jakmile máte autorizační token, je nutné jej přidat do hlavičky (Headers) u každého requestu, který voláte na AlzaTrade API. Níže je uveden příklad pro zavolání endpointu na získání podporovaných jazyků pomocí cURL:

curl "https://portalapi.alza.cz/v2/languages" -H "Authorization: Bearer ZDE_DOPLNIT"

Verze a změny

Pokud používáte pro volání API URL https://marketplaceapi.alza.cz, změňte si ji prosím na https://portalapi.alza.cz. Stará URL bude časem zrušena.

• v2 - 29.05.2025
  umožnění volání endpointu v2/orders/unshipped  také pro partnery s výběrem napojení jiným než AlzaTrade
  
  
• v2 - 23.01.2025
  do skupiny endpointů /orders přidána hodnota parcelShopBranchCode (ID Alzaboxu)
  
  
• v1 - 23.01.2025
  do skupiny endpointů /order přidána hodnota parcelShopBranchCode (ID Alzaboxu)

• v2 - 04.12.2024
  • Skupina /order přejmenována na /orders
  • Změněna struktura odpovědi endpointu orders/unshipped - nově jsou items jako kolekce v hlavním objektu a v kolekci packages je struktura items změněna
  • Nově jsou hodnoty null v json odpovědi vynechány
  • Přidány skupiny endpointů /languages a /listings
    
    
• v1 - 11.04.2023 Verze bude odstraněna k 01.01.2026
  • Přidána skupina endpointů /order