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ákazníci

Referenční popis cest pro zákazníky obchodu: povolený seznam polí s osobními údaji, parametry, synchronizace přes updated_since, chyby a ukázka volání.

Ověřeno 16. 9. 2026Markdown verze

Pro CRM a e-mailový nástroj: kdo u vás nakupuje, jak ho zastihnout a jestli souhlasil s obchodními sděleními. Obsahuje osobní údaje.

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/customers

Zákazníci obchodu, jen vyjmenovaná pole: jméno, firma, IČO, DIČ, kontakt, fakturační a doručovací adresa, souhlas s obchodními sděleními a cenová skupina. Heslo, tokeny, pokusy o přihlášení ani interní poznámky ven nejdou.

  • Oprávnění: customers:read, u klíče „Zákazníci, skupiny, recenze, zprávy, historie e-mailů a SMS a žádosti GDPR (č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ákazníka, jeho adresy nebo jeho cenové skupiny.
curl -s "https://muj-eshop.cz/api/v1/customers?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)
  • type (jedna z hodnot person a company): company = zákazník nakupuje na firmu.
  • name (text nebo null): Jméno a příjmení.
  • company_name (text nebo null)
  • ico (text nebo null)
  • dic (text nebo null)
  • email (text)
  • phone (text nebo null)
  • billing_address (objekt nebo null): Adresa zákazníka.
  • billing_address.name (text nebo null): Jméno příjemce.
  • billing_address.company (text nebo null)
  • billing_address.street (text)
  • billing_address.house_number (text nebo null)
  • billing_address.city (text)
  • billing_address.postal_code (text)
  • billing_address.country (text): ISO 3166-1 alpha-2.
  • delivery_address (objekt nebo null): Adresa zákazníka.
  • delivery_address.name (text nebo null): Jméno příjemce.
  • delivery_address.company (text nebo null)
  • delivery_address.street (text)
  • delivery_address.house_number (text nebo null)
  • delivery_address.city (text)
  • delivery_address.postal_code (text)
  • delivery_address.country (text): ISO 3166-1 alpha-2.
  • marketing_consent (true nebo false): Souhlas se zasíláním obchodních sdělení e-mailem.
  • marketing_consent_at (čas ISO 8601 nebo null): Kdy byl platný souhlas udělen. null, když souhlas není.
  • customer_group (objekt nebo null): Cenová skupina zákazníka.
  • customer_group.id (UUID)
  • customer_group.code (text)
  • customer_group.name (text)
  • created_at (čas ISO 8601)
  • updated_at (čas ISO 8601): Poslední změna zákazníka, jeho adresy nebo jeho cenové skupiny.

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/customers/{id}

Jeden zákazník, týmž povoleným seznamem polí jako ve výpisu.

  • Oprávnění: customers:read, u klíče „Zákazníci, skupiny, recenze, zprávy, historie e-mailů a SMS a žádosti GDPR (čtení)“.
  • Odpověď: jeden záznam v data.
curl -s "https://muj-eshop.cz/api/v1/customers/$ID" \
  -H "Authorization: Bearer $SHOPZI_API_KEY"

Parametry v cestě

  • id (UUID; povinný): Identifikátor záznamu (UUID) z výpisu.

Obálka odpovědi

  • data (záznam): Jeho pole popisuje seznam Pole záznamu.

Pole záznamu

  • id (UUID)
  • type (jedna z hodnot person a company): company = zákazník nakupuje na firmu.
  • name (text nebo null): Jméno a příjmení.
  • company_name (text nebo null)
  • ico (text nebo null)
  • dic (text nebo null)
  • email (text)
  • phone (text nebo null)
  • billing_address (objekt nebo null): Adresa zákazníka.
  • billing_address.name (text nebo null): Jméno příjemce.
  • billing_address.company (text nebo null)
  • billing_address.street (text)
  • billing_address.house_number (text nebo null)
  • billing_address.city (text)
  • billing_address.postal_code (text)
  • billing_address.country (text): ISO 3166-1 alpha-2.
  • delivery_address (objekt nebo null): Adresa zákazníka.
  • delivery_address.name (text nebo null): Jméno příjemce.
  • delivery_address.company (text nebo null)
  • delivery_address.street (text)
  • delivery_address.house_number (text nebo null)
  • delivery_address.city (text)
  • delivery_address.postal_code (text)
  • delivery_address.country (text): ISO 3166-1 alpha-2.
  • marketing_consent (true nebo false): Souhlas se zasíláním obchodních sdělení e-mailem.
  • marketing_consent_at (čas ISO 8601 nebo null): Kdy byl platný souhlas udělen. null, když souhlas není.
  • customer_group (objekt nebo null): Cenová skupina zákazníka.
  • customer_group.id (UUID)
  • customer_group.code (text)
  • customer_group.name (text)
  • created_at (čas ISO 8601)
  • updated_at (čas ISO 8601): Poslední změna zákazníka, jeho adresy nebo jeho cenové skupiny.

Chyby této cesty

  • 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á.
  • 404 not_found: Záznam s tímhle identifikátorem v obchodě není.