# REST API: dopravní metody

> Referenční popis cesty dopravních metod: dopravci, základní cena a sazby podle hmotnosti a hodnoty objednávky, doprava zdarma, dobírka a limity balíku, s chybami.

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

---

Pro ERP a expediční software: jakou dopravu obchod nabízí, za kolik a s jakými limity balíku. Přístupové údaje k dopravcům ani platebním bránám nikdy nevrací.

Cesty odpovídají na `GET`, `POST`, `PUT`, `PATCH` a `DELETE` 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`, `rest_write_disabled`, `rest_write_not_enabled`, `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/shipping-methods` [#get-api-v1-shipping-methods]

Dopravní metody, jak je nabízí pokladna: dopravce, základní cena a všechny sazby podle hmotnosti a hodnoty objednávky, hranice dopravy zdarma, dobírka a limity balíku. Přístupové údaje k dopravcům ven nejdou.

* **Oprávnění:** `settings:read`, u klíče „Nastavení, doprava, platby, vzhled, přístupy a zabezpečení účtu (č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í uložení metody. Sazby se přepisují jen spolu s ní, takže změnu ceny pošle i `updated_since`.

```bash
curl -s "https://muj-eshop.cz/api/v1/shipping-methods?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)
* `name` (text)
* `carrier_code` (jedna z hodnot `packeta`, `personal`, `balikovna`, `cp`, `ppl`, `dpd`, `gls` a `printify`): Dopravce, který balík veze. `personal` = vlastní rozvoz nebo osobní odběr.
* `delivery_type` (jedna z hodnot `shipping`, `pickup_point` a `personal_pickup`)
* `is_active` (`true` nebo `false`): Metoda se nabízí v pokladně.
* `position` (celé číslo): Pořadí v pokladně.
* `currency_code` (text se vzorem `^[A-Z]{3}$`): Kód měny podle ISO 4217, dnes vždy CZK.
* `price_minor` (celé číslo nebo `null`): Základní cena v haléřích s DPH: sazba bez horní hranice hmotnosti, kterou ukazuje administrace. `null`, když ji metoda nemá a cenu určují jen sazby v `rates`.
* `price_on_request` (`true` nebo `false`): Cena dle dohody: dopravu obchod vyúčtuje až po objednání. Nula v `price_minor` tu neznamená dopravu zdarma.
* `free_shipping_threshold_minor` (celé číslo nebo `null`): Od jaké hodnoty objednávky je doprava zdarma, v haléřích. `null` = nikdy.
* `vat_rate` (celé číslo od 0 do 100): Sazba DPH dopravy v celých procentech.
* `cod_allowed` (`true` nebo `false`): Jde zaplatit dobírkou.
* `cod_max_amount_minor` (celé číslo nebo `null`): Nejvyšší dobírka v haléřích, `null` = bez stropu.
* `requires_pickup_point` (`true` nebo `false`): Zákazník v pokladně vybírá výdejní místo.
* `postcode_prefixes` (pole, položka: text): Začátky PSČ, kam metoda doručuje. Prázdné pole = celá zóna.
* `limits` (objekt): Limity balíku. Balík, který některý z nich přesáhne, pokladna ukáže jako nedostupný.
* `limits.max_weight_grams` (celé číslo nebo `null`): Nejvyšší hmotnost balíku v gramech, `null` = bez limitu.
* `limits.max_length_mm` (celé číslo nebo `null`): Nejvyšší délka v milimetrech, `null` = bez limitu.
* `limits.max_width_mm` (celé číslo nebo `null`): Nejvyšší šířka v milimetrech, `null` = bez limitu.
* `limits.max_height_mm` (celé číslo nebo `null`): Nejvyšší výška v milimetrech, `null` = bez limitu.
* `limits.max_longest_side_mm` (celé číslo nebo `null`): Nejdelší strana v milimetrech, `null` = bez limitu.
* `limits.max_dimension_sum_mm` (celé číslo nebo `null`): Součet všech tří stran v milimetrech, `null` = bez limitu.
* `rates` (pole objektů): Všechny sazby metody od nejlevnější. Pokladna použije nejlevnější sazbu, do jejíchž mezí spadá balík i objednávka.
* `rates[].countries` (pole, položka: text): Země zóny sazby, ISO 3166-1 alpha-2.
* `rates[].min_weight_grams` (celé číslo)
* `rates[].max_weight_grams` (celé číslo nebo `null`): Sazba platí do této hmotnosti, `null` = bez hranice.
* `rates[].max_longest_side_mm` (celé číslo nebo `null`)
* `rates[].max_dimension_sum_mm` (celé číslo nebo `null`)
* `rates[].min_order_minor` (celé číslo nebo `null`): Sazba platí od této hodnoty objednávky, v haléřích.
* `rates[].max_order_minor` (celé číslo nebo `null`): Sazba platí do této hodnoty objednávky, v haléřích.
* `rates[].price_minor` (celé číslo): Cena v haléřích s DPH.
* `rates[].currency_code` (text se vzorem `^[A-Z]{3}$`): Kód měny podle ISO 4217, dnes vždy CZK.
* `created_at` (čas ISO 8601)
* `updated_at` (čas ISO 8601): Poslední uložení metody. Sazby se přepisují jen spolu s ní, takže změnu ceny pošle 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á.