Založte si e-shop zdarma a získejte 10 000 AI kreditů na start. Bez karty, bez závazku.E-shop zdarma + 10 000 AI kreditů na start

Začít zdarma
Přeskočit na obsah
Přihlásit seVyzkoušet zdarma
Obsah dokumentace

REST API: zásoby a skladové pohyby

Referenční popis cest skladu, tedy zásob po variantách a knihy skladových pohybů: parametry, pole odpovědi, synchronizace, chyby a ukázka volání.

Ověřeno 16. 9. 2026Markdown verze

Pro externí sklad nebo WMS: kolik kusů které varianty leží na skladě a který pohyb to změnil.

Cesty odpovídají na GET na doméně vašeho obchodu, například https://muj-eshop.cz/api/v1/…, a klíč se posílá v hlavičce Authorization: Bearer nebo x-api-key. Parametry, pole i chyby na téhle stránce se generují ze smlouvy, podle které API odpovídá, takže platí pro build, na kterém stránka běží. Každá cesta může navíc vrátit chyby společné všem cestám: invalid_api_key, missing_api_key, external_access_disabled, external_access_not_enabled, external_access_suspended, key_surface_mismatch, plan_required, shop_unavailable, shop_not_found, rate_limited a server_error. Co znamenají, popisuje článek Chybové odpovědi, klíč a oprávnění Autentizace a oprávnění a průchod výpisem Stránkování a filtry.

GET /api/v1/stock

Zásoby po variantě, sečtené přes sklady, i s názvem varianty z hodnot jejích voleb (například velikost a barva). Obchod s vypnutým modulem Sklad tenhle endpoint neotevírá.

  • Oprávnění: stock:read, u klíče „Sklad, pohyby a nákup (čtení)“.
  • Odpověď: stránka výpisu, záznamy jsou v data a jak otevřít další stránku, říká seznam Obálka odpovědi.
  • Synchronizace: s updated_since se výpis řadí podle pole updated_at od nejstarší změny, bez něj od nejnovějšího záznamu. Pole updated_at: Poslední změna zásoby, varianty (například SKU) nebo názvu produktu.
curl -s "https://muj-eshop.cz/api/v1/stock?limit=100" \
  -H "Authorization: Bearer $SHOPZI_API_KEY"

Parametry dotazu

  • limit (celé číslo od 1 do 100, výchozí 25; nepovinný): Počet řádků na stránku, výchozí 25. Vyšší hodnota se ořízne na 100, nesmysl spadne na výchozí.
  • cursor (text; nepovinný): Hodnota next_cursor z předchozí stránky, beze změny. Platí jen pro tentýž dotaz.
  • updated_since (čas ISO 8601; nepovinný): ISO 8601 se zónou Z nebo s číselným posunem (+02:00). Vrátí záznamy změněné od té chvíle včetně, seřazené od nejstarší změny, a stránkuje stabilně: řádek změněný během průchodu se v něm neopakuje a přijde v příštím. Hodnota next_updated_since jde do adresy vložit bez kódování; + z nezakódované adresy se čte jako +.

Obálka odpovědi

  • data (pole záznamů): Záznamy stránky, jejich pole popisuje seznam Pole záznamu.
  • next_cursor (text nebo null): Kurzor další stránky, null = tohle je poslední stránka.
  • next_updated_since (čas ISO 8601): Hodnota updated_since pro příští průchod: začátek tohoto průchodu mínus 5 minut. Na všech stránkách jednoho průchodu je stejná a do adresy jde vložit bez kódování.

Pole záznamu

  • variant_id (UUID)
  • product_id (UUID)
  • sku (text nebo null)
  • title (text): Název produktu. Kterou variantu řádek nese, říká variant.
  • variant (text nebo null): Název varianty z hodnot jejích voleb v pořadí voleb produktu, oddělených lomítkem, například Černá / 42. null, když varianta žádné volby nemá (jednoduchý produkt).
  • on_hand (číslo): Fyzicky na skladě, sečteno přes sklady.
  • available (číslo): Kolik jde prodat. Dnes totéž co on_hand, obchod nerezervuje.
  • updated_at (čas ISO 8601): Poslední změna zásoby, varianty (například SKU) nebo názvu produktu.
  • created_at (čas ISO 8601)

Chyby této cesty

  • 400 invalid_query: Parametr dotazu má neplatnou hodnotu: čas v updated_since bez časového posunu, nebo hodnota filtru, kterou výčet nezná. Zpráva jmenuje parametr, u filtru i povolené hodnoty.
  • 400 invalid_cursor: Kurzor je poškozený, nebo patří k jinému dotazu (jiná cesta, jiný filtr nebo jiné updated_since). Začněte průchod znovu bez cursor.
  • 403 insufficient_scope: Klíč je platný, ale nemá oprávnění, které cesta vyžaduje. Zpráva vypíše, co klíči chybí a co má.
  • 403 inventory_disabled: Obchod má vypnutý modul Sklad, takže skladová data neotevírá nikomu.

GET /api/v1/stock/movements

Skladové pohyby jako neměnná kniha: varianta, sklad, změna množství, důvod a to, k čemu pohyb patří. Nákupní cena ani poznámka k pohybu ven nejdou a s vypnutým modulem Sklad je cesta zavřená.

  • Oprávnění: stock:read, u klíče „Sklad, pohyby a nákup (čtení)“.
  • Odpověď: stránka výpisu, záznamy jsou v data a jak otevřít další stránku, říká seznam Obálka odpovědi.
  • Synchronizace: s updated_since se výpis řadí podle pole created_at od nejstarší změny, bez něj od nejnovějšího záznamu. Pole created_at: Kdy pohyb vznikl. Pohyb se nemění, takže podle něj stránkuje i updated_since.
curl -s "https://muj-eshop.cz/api/v1/stock/movements?limit=100" \
  -H "Authorization: Bearer $SHOPZI_API_KEY"

Parametry dotazu

  • limit (celé číslo od 1 do 100, výchozí 25; nepovinný): Počet řádků na stránku, výchozí 25. Vyšší hodnota se ořízne na 100, nesmysl spadne na výchozí.
  • cursor (text; nepovinný): Hodnota next_cursor z předchozí stránky, beze změny. Platí jen pro tentýž dotaz.
  • updated_since (čas ISO 8601; nepovinný): ISO 8601 se zónou Z nebo s číselným posunem (+02:00). Vrátí záznamy změněné od té chvíle včetně, seřazené od nejstarší změny, a stránkuje stabilně: řádek změněný během průchodu se v něm neopakuje a přijde v příštím. Hodnota next_updated_since jde do adresy vložit bez kódování; + z nezakódované adresy se čte jako +.
  • type (jedna z hodnot receipt, usage, writeoff, correction, return, transfer a stocktake_adjustment; nepovinný): Druh pohybu.

Obálka odpovědi

  • data (pole záznamů): Záznamy stránky, jejich pole popisuje seznam Pole záznamu.
  • next_cursor (text nebo null): Kurzor další stránky, null = tohle je poslední stránka.
  • next_updated_since (čas ISO 8601): Hodnota updated_since pro příští průchod: začátek tohoto průchodu mínus 5 minut. Na všech stránkách jednoho průchodu je stejná a do adresy jde vložit bez kódování.

Pole záznamu

  • id (UUID)
  • variant_id (UUID): Varianta, které se pohyb týká. SKU, produkt a název varianty čtěte z /stock: mění se, kdežto pohyb je neměnný a znovu by nepřišel.
  • location_id (UUID nebo null): Sklad, null u pohybu na zrušeném skladě. Zrušení skladu pohyb znovu nepošle.
  • type (jedna z hodnot receipt, usage, writeoff, correction, return, transfer a stocktake_adjustment)
  • quantity_change (číslo): Změna množství: kladná přidává, záporná ubírá.
  • quantity_before (číslo)
  • quantity_after (číslo)
  • reason (text nebo null): Důvod odpisu, jinak null.
  • reference (objekt)
  • reference.type (text nebo null): K čemu pohyb patří, například order nebo purchase_order.
  • reference.id (UUID nebo null)
  • created_at (čas ISO 8601): Kdy pohyb vznikl. Pohyb se nemění, takže podle něj stránkuje i updated_since.

Chyby této cesty

  • 400 invalid_query: Parametr dotazu má neplatnou hodnotu: čas v updated_since bez časového posunu, nebo hodnota filtru, kterou výčet nezná. Zpráva jmenuje parametr, u filtru i povolené hodnoty.
  • 400 invalid_cursor: Kurzor je poškozený, nebo patří k jinému dotazu (jiná cesta, jiný filtr nebo jiné updated_since). Začněte průchod znovu bez cursor.
  • 403 insufficient_scope: Klíč je platný, ale nemá oprávnění, které cesta vyžaduje. Zpráva vypíše, co klíči chybí a co má.
  • 403 inventory_disabled: Obchod má vypnutý modul Sklad, takže skladová data neotevírá nikomu.