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). Pro zobrazení těchto údajů se stačí opětovně prokliknout do sekce Uživatelé a práva a následně pak na API klienta.

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ě Swagger. 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

Níže příklad z programu Postman:

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"

Níže příklad z programu Postman:

Token je nutné vložit do "Headers" u HTTP GET požadavku.

Použití

Návodný popis jak využít funkcionalitu dostupnou skrze AlzaTrade API.

Objednávky

GET endpoint/orders slouží k získání stránkované kolekce objednávek s podporou filtrování a řazení prostřednictvím query parametrů.

Pomocí GET endpointu /orders/unshipped si můžete stáhnout své neodeslané objednávky. Výsledná data lze filtrovat pomocí času odeslání zásilky od-do. Použití filtru je nepovinné, v případě nevyplnění budou vráceny všechny neodeslané objednávky.

Listování

Skupina endpointů/listings slouží pro operace k listování produktů. Aktuálně obsahuje endpointy k získání dat pro kategorie a jejich šablony, podle kterých lze zalistovat produkt.

Pro získání dostupných kategorií lze využít dvou endpointů.

• /listings/categories - navrácená data kategorií jako jedna kolekce
• /listings/categories/tree - navrácené kategorie ve stromové struktuře stejně tak, jako jsou vidět i v portále Alza Trade

Seznam výrobců získáte zavoláním/listings/manufacturers. Zde se žádný filtr nepoužívá, jedná se o číselník.

Pokud chcete získat šablonu pro vybranou kategorii na základě jejího ID, je nejjednodušším způsobem zavolat endpoint/listings/templates a do parametru přidat požadované ID kategorie (1 nebo více ID najednou). Použijte tento endpoint v případě, že se chystáte získat data pro nízký počet kategorií (maximálně do 50). Opakované nebo paralelní volání může vést k překročení rate limitu a vrácení HTTP kódu 429 - Too many requests.

Pokud potřebujete data pro větší počet kategorií nebo rovnou všechny, využijte kombinaci endpointů, ze kterých lze šablonu kategorie poskládat. Jedná se o:

• /listings/parameters - parametry s vazbou na kategorie
• /listings/parameters - kolekce SEO prefixů s vazbou na kategorie

Zmíněné endpointy lze zavolat s nebo bez filtru kategorie. Pokud filtr nepoužijete, jsou stažena data pro všechny kategorie. Tyto operace můžou trvat delší dobu.

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 - 11.03.2026
  • Vytvořen nový GET endpoint/orders se shodnou strukturou dat jako /orders/unshipped pro získání kolekce objednávek nezávisle na jejich stavu s možností filtrace a řazení
  • Do endpointu /orders/unshipped přidána hodnota state
• v2 - 12.11.2025
  • Do endpointu /orders/unshipped přidána hodnota packageSortingGroup
• v2 - 29.05.2025
  • Umožnění volání endpointu /orders/unshipped také pro partnery s výběrem napojení jiným než AlzaTrade
• v2 - 23.01.2025
  • Do endpointu /orders/unshipped 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 odstraněna 11.03.2026
  • Přidána skupina endpointů /order