REST API: feedy dodavatelů | Dokumentace pro vývojáře SHOPZI

Feedy dodavatelů jsou přes REST jen ke čtení: katalog dodavatelů, odběry, běhy synchronizace, frontu ke schválení, produkty z feedů a cenová pravidla čte klíč s oprávněním products:read, dropship objednávky u dodavatelů klíč s orders:read. Zapisuje se přes MCP.

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/supplier-subscriptions`

Odebírané feedy dodavatelů: stav odběru, míra automatizace, filtr položek a poslední synchronizace s případnou chybou. Odběr se zakládá a mění přes MCP, ne přes REST.

Oprávnění: products:read, u klíče „Katalog: produkty, kategorie, dodavatelé (č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.

curl -s "https://muj-eshop.cz/api/v1/supplier-subscriptions?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

id (UUID)
feed_id (UUID): Feed v katalogu dodavatelů platformy.
catalog_supplier_id (UUID)
status (jedna z hodnot active a paused)
trust_level (jedna z hodnot review_all, review_exceptions a autopilot): Míra automatizace odběru.
auto_publish (true nebo false)
oos_behaviour (jedna z hodnot hide a show_unavailable)
ai_policy (jedna z hodnot off, review a auto_apply)
price_change_threshold_pct (celé číslo)
filter (objekt s libovolnými klíči): Které položky feedu obchod bere.
last_synced_at (čas ISO 8601 nebo null)
last_error (text nebo null)
created_at (čas ISO 8601)
updated_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á.

`GET /api/v1/supplier-approvals`

Fronta ke schválení ze synchronizace feedů: nové produkty, změny cen a textů a prodej pod nákupní cenou, s živou a navrženou hodnotou. Rozhoduje se v administraci nebo přes MCP.

Oprávnění: products:read, u klíče „Katalog: produkty, kategorie, dodavatelé (č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.

curl -s "https://muj-eshop.cz/api/v1/supplier-approvals?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 +.
status (jedna z hodnot pending, approved, rejected, expired a failed; nepovinný): Stav položky.
kind (jedna z hodnot product_create, price_change, below_cost, delist, content_change, ai_text, supplier_order a unmapped_category; nepovinný): Druh návrhu.

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)
subscription_id (UUID nebo null)
kind (jedna z hodnot product_create, price_change, below_cost, delist, content_change, ai_text, supplier_order a unmapped_category)
status (jedna z hodnot pending, approved, rejected, expired a failed)
product_id (UUID nebo null)
variant_id (UUID nebo null)
field (text nebo null)
current_value (libovolná hodnota): Živá hodnota v okamžiku návrhu. Ceny v haléřích.
proposed_value (libovolná hodnota): Navržená hodnota. Ceny v haléřích.
reason (text nebo null)
decided_via (text nebo null)
decided_at (čas ISO 8601 nebo null)
created_at (čas ISO 8601)
updated_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á.

`GET /api/v1/product-source-links`

Které produkty pocházejí z feedu dodavatele, z jaké položky katalogu, která pole si obchod převzal a co skryla synchronizace.

Oprávnění: products:read, u klíče „Katalog: produkty, kategorie, dodavatelé (č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í zápis synchronizace nebo změna zámků.

curl -s "https://muj-eshop.cz/api/v1/product-source-links?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

id (UUID)
product_id (UUID)
variant_id (UUID)
subscription_id (UUID)
catalog_item_id (UUID): Položka v katalogu dodavatele.
locked_fields (pole, položka: text): Pole, která obchod převzal; feed je nepřepíše.
hidden_by_sync (true nebo false): Produkt skryla synchronizace (vyprodáno, zmizelo, pod nákupní cenou).
updated_at (čas ISO 8601): Poslední zápis synchronizace nebo změna zámků.

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á.

`GET /api/v1/pricing-rules`

Cenová pravidla feedů: přirážka k nákupní ceně, minimální marže, zaokrouhlení a ceník, na který pravidlo platí.

Oprávnění: products:read, u klíče „Katalog: produkty, kategorie, dodavatelé (č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.

curl -s "https://muj-eshop.cz/api/v1/pricing-rules?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

id (UUID)
subscription_id (UUID nebo null): null = platí pro všechny odběry.
scope (jedna z hodnot all, category a brand)
scope_value (text nebo null)
markup_pct (číslo)
min_margin_minor (celé číslo): Minimální marže v haléřích.
rounding (jedna z hodnot none, whole, x9, x90 a x99)
target (jedna z hodnot catalog a wholesale)
priority (celé číslo)
is_active (true nebo false)
updated_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á.

`GET /api/v1/catalog-items`

Položky katalogu dodavatelů, které obchod smí vidět: kód, EAN, texty, fotky, parametry, sklad a doporučená i minimální cena. Nákupní cena jen u vlastního feedu, otevřeného dodavatele nebo po schváleném přístupu; tarif Free dostane 402.

Oprávnění: products:read, u klíče „Katalog: produkty, kategorie, dodavatelé (č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.

curl -s "https://muj-eshop.cz/api/v1/catalog-items?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 +.
feed_id (UUID; nepovinný): Jen položky jednoho feedu.
include_gone (jedna z hodnot true a false; nepovinný): I položky, které z feedu zmizely (výchozí false).

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)
feed_id (UUID)
external_id (text): Kód položky u dodavatele.
group_id (text nebo null): Skupina variant (velikosti, barvy jednoho produktu).
ean (text nebo null)
sku (text nebo null)
title (text)
description (text nebo null)
brand (text nebo null)
category_path (pole, položka: text)
images (pole, položka: text)
params (objekt s libovolnými klíči, hodnota: text)
cost_minor (celé číslo nebo null): Nákupní cena v měně feedu. Null, dokud obchod nemá u dodavatele schválený přístup.
cost_includes_vat (true nebo false)
retail_price_minor (celé číslo nebo null): Doporučená prodejní cena dodavatele.
min_price_minor (celé číslo nebo null): Nejnižší povolená prodejní cena (MAP), kterou dodavatel vyžaduje.
currency_code (text se vzorem ^[A-Z]{3}$): Kód měny podle ISO 4217, dnes vždy CZK.
vat_rate (celé číslo od 0 do 100 nebo null)
stock (celé číslo nebo null)
availability (jedna z hodnot in_stock, out_of_stock, preorder a unknown)
lead_days (celé číslo nebo null)
gone_at (čas ISO 8601 nebo null): Kdy položka z feedu zmizela; null = ve feedu je.
created_at (čas ISO 8601)
updated_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.
402 plan_required: Tarif obchodu feedy dodavatelů nezahrnuje, takže katalog dodavatelů se neotevře. Otevře ho tarif Basic a vyšší; ostatní cesty feedů vracejí, co obchod už má uložené.
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á.

`GET /api/v1/supplier-sync-runs`

Běhy synchronizace odběrů: kdy začaly a skončily, kolik produktů přibylo, změnilo se, skrylo a čeká na schválení, a chyba, pokud běh selhal.

Oprávnění: products:read, u klíče „Katalog: produkty, kategorie, dodavatelé (č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: Konec běhu, u běžícího jeho začátek.

curl -s "https://muj-eshop.cz/api/v1/supplier-sync-runs?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 +.
subscription_id (UUID; nepovinný): Jen běhy jednoho odběru.

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)
subscription_id (UUID)
trigger (jedna z hodnot feed, manual, subscribe a rules)
status (jedna z hodnot running, succeeded, partial a failed)
started_at (čas ISO 8601)
finished_at (čas ISO 8601 nebo null)
items_seen (celé číslo)
created (celé číslo)
updated (celé číslo)
hidden (celé číslo)
unhidden (celé číslo)
held (celé číslo)
skipped (celé číslo)
errors (celé číslo)
error (text nebo null)
created_at (čas ISO 8601): Začátek běhu.
updated_at (čas ISO 8601): Konec běhu, u běžícího jeho začátek.

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á.

`GET /api/v1/supplier-orders`

Části objednávek poslané dodavatelům k přímému odeslání zákazníkovi: stav u dodavatele, číslo zásilky a nákupní hodnota bez DPH. Adresa zákazníka je v objednávce, ne tady.

Oprávnění: orders:read, u klíče „Objednávky (č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.

curl -s "https://muj-eshop.cz/api/v1/supplier-orders?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

id (UUID)
order_id (UUID)
catalog_supplier_id (UUID)
status (jedna z hodnot draft, awaiting_approval, sent, confirmed, shipped, rejected, cancelled a failed)
tracking_number (text nebo null)
carrier (text nebo null)
total_cost_minor (celé číslo): Nákupní hodnota části objednávky bez DPH, v haléřích.
currency_code (text)
sent_at (čas ISO 8601 nebo null)
shipped_at (čas ISO 8601 nebo null)
created_at (čas ISO 8601)
updated_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á.