# 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í.

- Sekce: Pro vývojáře
- Stránka: https://shopzi.cz/dokumentace/vyvojari/rest-zakaznici
- Ověřeno: 2026-09-16

---

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](/dokumentace/vyvojari/chybove-odpovedi), klíč a oprávnění [Autentizace a oprávnění](/dokumentace/vyvojari/autentizace-a-opravneni) a průchod výpisem [Stránkování a filtry](/dokumentace/vyvojari/strankovani-a-filtry).

## `GET /api/v1/customers` [#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.

```bash
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}` [#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`.

```bash
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í.