API

Napojte SHOPZI na to, co už používáte

Programově a na doméně vašeho obchodu: objednávky, vratky a zásilky, produkty a kategorie, zásoby a skladové pohyby, zákazníci a doklady s PDF a ISDOC. Každý endpoint je tady vypsaný i s tím, jaké oprávnění chce, co vrací a čím se filtruje, a celé rozhraní si stáhnete jako OpenAPI.

Porovnat tarify Seznam endpointů

Hotové, a jen ke čtení

API běží na doméně vašeho obchodu a všechny jeho cesty jsou vypsané níž i s tím, co vrací a čím se dají zúžit. Stáhnete si přes ně objednávky, vratky a zásilky, produkty a kategorie, zásoby a skladové pohyby, zákazníci a doklady s PDF a ISDOC, a celé rozhraní je popsané i strojově ve formátu OpenAPI. Měnit se přes ně nedá nic, a není to nedodělek: cizí systém, který zapisuje do objednávek a skladu, potřebuje vlastní řešení idempotence, validace a auditu, a to postavíme pořádně, nebo vůbec. Zapnete si ho sami v administraci v Nastavení → API a MCP, když má obchod aktivní placený tarif. Poprvé potvrdíte, že za nástroj, kterému vydáte klíč, odpovídáte vy, protože se jím k datům obchodu dostane někdo další. Klíč a jeho rozsah pak spravujete sami, v protokolu vidíte jeho volání a zneplatnit ho jde okamžitě.

01Rozhraní

24 endpointů, a tohle jsou všechny

Cesta, oprávnění, co vrátí a čím se to dá zúžit. Vypsané z kódu, který to obsluhuje, ne přepsané rukou.

Endpoint	Oprávnění	Vrací	Parametry
GET`/api/v1/catalog-items`	`products:read` Navíc 400 invalid_cursor, 400 invalid_query, 402 plan_required	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. Stránka v data[], kurzor v next_cursor `id` `feed_id` `external_id` `group_id` `ean` `sku` `title` `description` `brand` `category_path[]` `images[]` `params{}` `cost_minor` `cost_includes_vat` `retail_price_minor` `min_price_minor` `currency_code` `vat_rate` `stock` `availability` `lead_days` `gone_at` `created_at` `updated_at`	`feed_id` `include_gone` `updated_since` Stránkování: limit, cursor
GET`/api/v1/categories`	`products:read` Navíc 400 invalid_cursor, 400 invalid_query	Strom kategorií jako plochý výpis: nadřazená kategorie, hloubka, pořadí, celá cesta ze slugů a to, jestli je kategorie na obchodě vidět. Stránka v data[], kurzor v next_cursor `id` `parent_id` `name` `slug` `full_path` `depth` `position` `is_active` `show_in_menu` `created_at` `updated_at`	`updated_since` Stránkování: limit, cursor
GET`/api/v1/customers`	`customers:read` Navíc 400 invalid_cursor, 400 invalid_query	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. Stránka v data[], kurzor v next_cursor `id` `type` `name` `company_name` `ico` `dic` `email` `phone` `billing_address{}` `delivery_address{}` `marketing_consent` `marketing_consent_at` `customer_group{}` `created_at` `updated_at`	`updated_since` Stránkování: limit, cursor
GET`/api/v1/customers/{id}`	`customers:read` Navíc 404 not_found	Jeden zákazník, týmž povoleným seznamem polí jako ve výpisu. Jeden objekt v data `id` `type` `name` `company_name` `ico` `dic` `email` `phone` `billing_address{}` `delivery_address{}` `marketing_consent` `marketing_consent_at` `customer_group{}` `created_at` `updated_at`	Bez parametrů
GET`/api/v1/documents`	`documents:read` Navíc 400 invalid_cursor, 400 invalid_query	Vystavené doklady: druh, číslo, datum vystavení a DUZP, částka a IČO a DIČ odběratele. Doklad se nemění, proto tu updated_since stránkuje podle vzniku dokladu. Stránka v data[], kurzor v next_cursor `id` `doc_type` `doc_number` `order_id` `issued_at` `duzp` `total_minor` `currency_code` `tax_regime` `customer_ico` `customer_dic` `created_at`	`doc_type` `updated_since` Stránkování: limit, cursor
GET`/api/v1/documents/{id}`	`documents:read` Navíc 404 not_found, 422 unsupported_document_type	Faktura, proforma nebo dobropis celý: položky, dodavatel a odběratel s IČO a DIČ a rekapitulace DPH po sazbách v haléřích. Objednávka, cenová nabídka a účtenka daňový detail nemají. Jeden objekt v data `id` `doc_type` `doc_number` `order_id` `order_number` `issued_at` `issue_date` `duzp` `due_date` `currency_code` `tax_regime` `is_vat_payer` `payment_method` `variable_symbol` `is_paid` `supplier{}` `customer{}` `lines[]` `shipping_gross_minor` `shipping_vat_rate` `discount_total_minor` `rounding_minor` `vat_breakdown[]` `total_base_minor` `total_vat_minor` `total_gross_minor` `original_doc_number` `correction_reason` `created_at`	Bez parametrů
GET`/api/v1/documents/{id}/isdoc`	`documents:read` Navíc 404 not_found, 422 isdoc_invalid, 422 unsupported_document_type	Doklad ve formátu ISDOC 6.0.2 k importu do účetního programu, například do POHODY, Money, ABRY nebo iDokladu. Soubor ke stažení (application/vnd.isdoc+xml)	Bez parametrů
GET`/api/v1/documents/{id}/pdf`	`documents:read` Navíc 404 not_found, 422 unsupported_document_type, 502 pdf_unavailable, 503 pdf_busy	Doklad jako PDF, týž soubor, jaký stahuje administrace. Neukládá se do žádné sdílené mezipaměti. Soubor ke stažení (application/pdf)	Bez parametrů
GET`/api/v1/orders`	`orders:read` Navíc 400 invalid_cursor, 400 invalid_query	Objednávky s částkami v haléřích, bez updated_since od nejnovější, s ním od nejstarší změny. Nákupní ceny, marže, interní poznámky ani identifikátory platby ven nejdou. Stránka v data[], kurzor v next_cursor `id` `order_number` `status` `payment_status` `payment_method` `fulfillment_status` `currency_code` `subtotal_minor` `discount_total_minor` `shipping_price_minor` `total_minor` `email` `phone` `is_quotation` `placed_at` `created_at` `updated_at`	`payment_status` `status` `updated_since` Stránkování: limit, cursor
GET`/api/v1/orders/{id}`	`orders:read` Navíc 404 not_found	Jedna objednávka i s položkami, fakturační a doručovací adresou a variabilním symbolem. Jeden objekt v data `id` `order_number` `status` `payment_status` `payment_method` `fulfillment_status` `currency_code` `subtotal_minor` `discount_total_minor` `shipping_price_minor` `total_minor` `email` `phone` `is_quotation` `placed_at` `created_at` `updated_at` `billing{}` `shipping{}` `variable_symbol` `notes` `lines[]`	Bez parametrů
GET`/api/v1/ping`	libovolný platný klíč	Ověření klíče, než postavíte scénář: vrátí jen identitu klíče a jeho oprávnění, žádná data obchodu. Stačí mu libovolný platný klíč, takže rozliší neplatný klíč od chybějícího oprávnění. Odpověď bez obálky `ok` `key_id` `scopes[]` `api_version`	Bez parametrů
GET`/api/v1/pricing-rules`	`products:read` Navíc 400 invalid_cursor, 400 invalid_query	Cenová pravidla feedů: přirážka k nákupní ceně, minimální marže, zaokrouhlení a ceník, na který pravidlo platí. Stránka v data[], kurzor v next_cursor `id` `subscription_id` `scope` `scope_value` `markup_pct` `min_margin_minor` `rounding` `target` `priority` `is_active` `updated_at`	`updated_since` Stránkování: limit, cursor
GET`/api/v1/product-source-links`	`products:read` Navíc 400 invalid_cursor, 400 invalid_query	Které produkty pocházejí z feedu dodavatele, z jaké položky katalogu, která pole si obchod převzal a co skryla synchronizace. Stránka v data[], kurzor v next_cursor `id` `product_id` `variant_id` `subscription_id` `catalog_item_id` `locked_fields[]` `hidden_by_sync` `updated_at`	`updated_since` Stránkování: limit, cursor
GET`/api/v1/products`	`products:read` Navíc 400 invalid_cursor, 400 invalid_query	Katalog, bez updated_since od nejnovějšího produktu. Cena je běžná koncová z ceníku pro maloobchod, velkoobchodní ceny se přes API neposílají. Stránka v data[], kurzor v next_cursor `id` `slug` `title` `status` `product_type` `brand` `price_minor` `currency_code` `image_url` `stock` `created_at` `updated_at`	`status` `updated_since` Stránkování: limit, cursor
GET`/api/v1/products/{id}`	`products:read` Navíc 404 not_found	Jeden produkt i s variantami, jejich názvy, cenami a dostupností a se zařazením do kategorií. Jeden objekt v data `id` `slug` `title` `status` `product_type` `brand` `price_minor` `currency_code` `image_url` `stock` `created_at` `updated_at` `subtitle` `description` `meta_title` `meta_description` `published_at` `variants[]` `categories[]` `primary_category_id`	Bez parametrů
GET`/api/v1/returns`	`orders:read` Navíc 400 invalid_cursor, 400 invalid_query	Vratky a reklamace i s položkami, důvodem a stavem vrácení peněz v haléřích, s odkazem na objednávku a na vystavený dobropis. Stránka v data[], kurzor v next_cursor `id` `return_number` `order_id` `order_number` `regime` `status` `reason` `refund{}` `credit_note_id` `credit_note_number` `deadline_at` `items[]` `created_at` `updated_at`	`status` `updated_since` Stránkování: limit, cursor
GET`/api/v1/returns/{id}`	`orders:read` Navíc 404 not_found	Jedna vratka nebo reklamace, v témže tvaru jako ve výpisu. Jeden objekt v data `id` `return_number` `order_id` `order_number` `regime` `status` `reason` `refund{}` `credit_note_id` `credit_note_number` `deadline_at` `items[]` `created_at` `updated_at`	Bez parametrů
GET`/api/v1/shipments`	`orders:read` Navíc 400 invalid_cursor, 400 invalid_query	Zásilky objednávek: dopravce, způsob dopravy, číslo a odkaz pro sledování, stav a položky v zásilce. Štítek ani chybová hlášení dopravce ven nejdou. Stránka v data[], kurzor v next_cursor `id` `order_id` `order_number` `carrier` `service` `delivery_type` `status` `tracking_number` `tracking_url` `pickup_point_id` `parcel_count` `weight_grams` `currency_code` `cod_amount_minor` `handed_over_at` `delivered_at` `items[]` `created_at` `updated_at`	`status` `updated_since` Stránkování: limit, cursor
GET`/api/v1/stock`	`stock:read` Navíc 400 invalid_cursor, 400 invalid_query, 403 inventory_disabled	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á. Stránka v data[], kurzor v next_cursor `variant_id` `product_id` `sku` `title` `variant` `on_hand` `available` `updated_at` `created_at`	`updated_since` Stránkování: limit, cursor
GET`/api/v1/stock/movements`	`stock:read` Navíc 400 invalid_cursor, 400 invalid_query, 403 inventory_disabled	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á. Stránka v data[], kurzor v next_cursor `id` `variant_id` `location_id` `type` `quantity_change` `quantity_before` `quantity_after` `reason` `reference{}` `created_at`	`type` `updated_since` Stránkování: limit, cursor
GET`/api/v1/supplier-approvals`	`products:read` Navíc 400 invalid_cursor, 400 invalid_query	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. Stránka v data[], kurzor v next_cursor `id` `subscription_id` `kind` `status` `product_id` `variant_id` `field` `current_value` `proposed_value` `reason` `decided_via` `decided_at` `created_at` `updated_at`	`kind` `status` `updated_since` Stránkování: limit, cursor
GET`/api/v1/supplier-orders`	`orders:read` Navíc 400 invalid_cursor, 400 invalid_query	Čá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. Stránka v data[], kurzor v next_cursor `id` `order_id` `catalog_supplier_id` `status` `tracking_number` `carrier` `total_cost_minor` `currency_code` `sent_at` `shipped_at` `created_at` `updated_at`	`updated_since` Stránkování: limit, cursor
GET`/api/v1/supplier-subscriptions`	`products:read` Navíc 400 invalid_cursor, 400 invalid_query	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. Stránka v data[], kurzor v next_cursor `id` `feed_id` `catalog_supplier_id` `status` `trust_level` `auto_publish` `oos_behaviour` `ai_policy` `price_change_threshold_pct` `filter{}` `last_synced_at` `last_error` `created_at` `updated_at`	`updated_since` Stránkování: limit, cursor
GET`/api/v1/supplier-sync-runs`	`products:read` Navíc 400 invalid_cursor, 400 invalid_query	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. Stránka v data[], kurzor v next_cursor `id` `subscription_id` `trigger` `status` `started_at` `finished_at` `items_seen` `created` `updated` `hidden` `unhidden` `held` `skipped` `errors` `error` `created_at` `updated_at`	`subscription_id` `updated_since` Stránkování: limit, cursor

Adresa je vždycky doména vašeho obchodu, takže úplná cesta je například muj-eshop.cz/api/v1/orders. Peněžní částky chodí jako celá čísla v haléřích. Podrobná dokumentace endpointů popisuje obálku odpovědi, pole i to, jak se stránkuje kurzorem.

02Rozsah

5 datových oblastí

U klíče zaškrtnete jen ty, které vaše integrace potřebuje. Na co jste ho nezaškrtli, na to klíč nedosáhne a odpověď je 403.

Zákazníci, skupiny, recenze, zprávy, historie e-mailů a SMS a žádosti GDPR (čtení)

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.

Doklady: metadata, položky a stažení PDF/ISDOC (čtení)

Pro účetní software: co bylo vystaveno, komu, kdy a na kolik, i s rekapitulací DPH, PDF a ISDOC.

Objednávky (čtení)

Pro účetnictví, ERP a expedici: kdo co objednal, v jakém je to stavu, kolik to stálo, co se vrací a kde je zásilka.

Katalog: produkty, kategorie, dodavatelé (čtení)

Pro vlastní frontend, srovnávače a mobilní aplikaci: katalog s variantami, cenami, dostupností a stromem kategorií.

Sklad, pohyby a nákup (čtení)

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

03Parametry

Jak se s ním pracuje

Protokol: REST a JSON přes HTTPS
Adresa: Na doméně vašeho obchodu, cesta /api/v1
Endpointy: 24 cest, všechny jen ke čtení
Autentizace: Klíč shopzi_sk_… v hlavičce authorization nebo x-api-key
Oprávnění: 5 oblastí, vybíráte je u klíče
Stránkování: Kurzorem, výchozích 25 položek, nejvýš 100; s updated_since jen změny od minulého průchodu
Popis: OpenAPI 3.1.0 v souboru /openapi-v1.json na doméně obchodu
Chyby: 13 sdílených kódů, strojově čitelné
Verzování: Verze v cestě, změny nikdy zpětně

04Synchronizace

Jen změny od minulého běhu

Průběžná synchronizace přes updated_since, která se nerozejde s tím, co se v obchodě mezitím mění, a strojový popis celého rozhraní.

Jen změny od minulého běhu

Parametr updated_since přijme čas ISO 8601 se zónou Z nebo s posunem a vrátí záznamy změněné od té chvíle, seřazené od nejstarší změny. Doklady a skladové pohyby se nemění, u nich rozhoduje čas vzniku.

Průchod, který se nerozejde

Kurzor drží pořadí i při souběžných změnách: řádek změněný během průchodu se v něm neopakuje a přijde v příštím. Platí jen pro dotaz, který ho vydal; se změněným filtrem přijde odpověď 400 invalid_cursor.

Hranice příštího běhu

Každá stránka průchodu nese next_updated_since, tedy začátek průchodu mínus 5 minut. Tu hodnotu pošlete při dalším běhu a do adresy ji vložíte bez kódování.

Popis OpenAPI 3.1.0

Soubor /openapi-v1.json na doméně obchodu popisuje každou cestu, parametr, tvar odpovědi i chybu. Generuje se ze stejné smlouvy, podle které API odpovídá, takže z něj vytvoříte klienta a v testech podle něj ověříte odpovědi.

Podrobně to popisují články Stránkování a filtry, OpenAPI popis REST API a Chybové odpovědi.

05Ukázka

Jak volání vypadá

Adresa v ukázkách je vaše vlastní doména i s cestou /api/v1 a klíč se čte z prostředí, protože přesně tak vypadá integrace, která se nikam neopíše.

Ověření klíče
curl -sS "$SHOPZI_API_URL/ping" \
  -H "Authorization: Bearer $SHOPZI_API_KEY"

# {"ok":true,"key_id":"…","scopes":["products:read"],"api_version":"v1"}
Seznam produktů
curl -sS "$SHOPZI_API_URL/products?limit=20&status=active" \
  -H "Authorization: Bearer $SHOPZI_API_KEY" \
  -H "Accept: application/json"
Odpověď 200
{
  "data": [
    {
      "id": "b1f0c0de-8f4a-4f6e-9a1c-2d3e4f5a6b70",
      "slug": "lnena-kosile-nord",
      "title": "Lněná košile Nord",
      "status": "active",
      "product_type": "physical",
      "brand": "Nord",
      "price_minor": 129000,
      "currency_code": "CZK",
      "image_url": null,
      "stock": 4,
      "created_at": "2026-08-19T11:02:41.512000Z",
      "updated_at": "2026-08-19T11:04:10.230118Z"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJtIjoiciIsImEiOiIyMDI2LTA4LTE5VDExOjAyOjQxLjUxMjAwMFoiLCJpIjoiYjFmMGMwZGUtOGY0YS00ZjZlLTlhMWMtMmQzZTRmNWE2YjcwIiwiaCI6IjIwMjYtMDgtMTlUMTE6MDU6MDcuMDAwMDAwWiIsImYiOiIxb2tnYmVxIn0",
  "next_updated_since": "2026-08-19T11:00:07.000000Z"
}
Chyba
HTTP/1.1 403 Forbidden

{
  "error": {
    "code": "insufficient_scope",
    "message": "This key is missing the `orders:read` scope. It has: products:read."
  }
}

Čte a nezapisujeVšechny cesty odpovídají jen na GET. Když potřebujete, aby se v obchodě něco měnilo, je k tomu MCP server: zápis existuje tam, každou změnu, která něco přepisuje, napřed potvrdíte a téměř každou jde vrátit zpět.

06Opačný směr

Když má obchod zavolat vám

Koncový bod zaregistrujete v Nastavení → API a MCP v části Webhooky, vyberete u něj události a jedním tlačítkem si pošlete testovací zprávu. Na ní si ověříte podpis i to, že vaše fronta odpoví včas. Pak už chodí samy: jednotlivé změny objednávek, produktů, zákazníků a dokladů. Webhooky běží jen se zapnutým REST API.

order.createdObjednávka vytvořena
order.paidObjednávka zaplacena
order.fulfilledObjednávka vyřízena
order.shippedObjednávka odeslána
order.deliveredObjednávka doručena
order.cancelledObjednávka zrušena
order.refundedObjednávka refundována
product.createdProdukt vytvořen
product.updatedProdukt upraven
product.deletedProdukt smazán
customer.createdNový zákazník
stock.lowDocházející zásoba
document.issuedVystaven doklad
return.requestedŽádost o vrácení / reklamace
supplier_order.sentObjednávka odeslána dodavateli (dropship)
supplier_order.confirmedDodavatel objednávku potvrdil
supplier_order.shippedDodavatel odeslal zákazníkovi
supplier_order.rejectedDodavatel nemůže dodat
supplier_sync.completedSynchronizace feedu něco změnila
supplier_sync.failedSynchronizace feedu selhala
supplier_approval.pendingNové položky ke schválení z feedu
catalog_item.goneDodavatel vyřadil zboží z feedu
stock.changedZměna skladu z feedu (souhrn za běh)

Odchozí webhooky v administraci SHOPZI: koncové body pro n8n a Make, u každého odebírané události obchodu a tlačítko Odeslat test

Tělo požadavku
{
  "id": "3f8a1c94-7d2e-4b11-9c0a-5e6f7a8b9c01",
  "type": "order.created",
  "created_at": "2026-08-20T09:14:22.184Z",
  "data": {
    "order": {
      "id": "a71c22e8-0b19-4a2c-8f31-6c5d4e3b2a10",
      "order_number": "2026000431",
      "total_minor": 129900,
      "currency_code": "CZK",
      "status": "received",
      "payment_status": "pending"
    }
  }
}

Doručení opakujemeDokud nedostaneme odpověď 2xx, zprávu posíláme znovu. Stejné webhook-id proto smí dorazit vícekrát a příjem musí být idempotentní. Razítko starší než 5 minut zahoďte: jinak jde zachycený požadavek přehrát navždy.

Celou smlouvu příjemce, tedy podpis, toleranci razítka, rozvrh opakování a hotový kód na ověření, najdete v článku Webhooky: příjem událostí.

07Klíče

Zapnutí, klíče a přehled volání

Přístup i klíče spravuje vlastník obchodu sám a u každého klíče vidí, jak se používá.

Zapíná vlastník obchodu

REST API i server MCP se zapínají každé zvlášť v Nastavení → API a MCP, jen s placeným tarifem, nebo s jeho zkušebním obdobím a uloženou kartou. Poprvé vlastník potvrdí odpovědnost za napojený nástroj a krok ověří heslem nebo kódem z e-mailu. Vypnout jde okamžitě a bez ověření. Když placený tarif skončí, přístup se sám zavře a s obnoveným tarifem se znovu otevře se stejnými klíči.

Klíč pro jednu plochu, nebo pro obě

U každého klíče vyberete, kde platí: jen REST API, jen server MCP, nebo REST API i server MCP. Plochu klíči už nezměníte, pro jinou vydáte nový klíč.

Platnost s upozorněním předem

Nový klíč platí 90 dní. Při vytvoření jde zvolit i 30, 180 nebo 365 dní, anebo výslovně klíč bez expirace. Vlastníci obchodu dostanou upozornění 14 a 3 dny před koncem platnosti.

Výměna bez výpadku

Klíč vyměníte jedním kliknutím za nový se stejným názvem, oprávněními i plochou. Starý platí ještě nejvýš 24 hodin, takže integraci přepnete bez výpadku.

Přehled využití a protokol volání

Za zvolené období vidíte počet volání, chyb a odmítnutí, volání nad strop i utracené kredity, celkem i po jednotlivých klíčích. Protokol volání drží 30 dní a jen metadata, žádný obsah požadavků ani odpovědí.

Strop volání podle tarifu

Každý klíč má strop volání za minutu a za den podle tarifu obchodu. Odpovědi nesou hlavičky X-RateLimit a nad stropem přijde 429 s hlavičkou Retry-After, podle které integrace počká.

Nový API klíč v administraci SHOPZI: klíč jen pro REST API s platností 90 dní, rychlá volba oprávnění a zaškrtnuté čtení katalogu a skladu

Jak se klíčem prokázat a co který rozsah otevírá, popisuje článek Autentizace a oprávnění; jak vlastník přístup zapne a klíč vydá, pak uživatelská dokumentace v článku API a MCP.

08Na co

K čemu se používá nejčastěji

Když se váš záměr v seznamu nenajde, napište nám ho. Klidně vám řekneme, že na něj API nepotřebujete.

Účetnictví a ERP

Doklady a objednávky do systému, se kterým už účetní pracuje.

Skladový systém

Zásoby a pohyby proti externímu skladu nebo WMS.

Vlastní aplikace

Katalog a objednávky do mobilní nebo interní aplikace.

Reporting a BI

Data o prodejích do nástroje, ve kterém je vyhodnocujete.

Systém dodavatele

Předávání objednávek přímo k tomu, kdo je expeduje.

Vlastní frontend

Katalog za vlastním webem, když má výklad vzniknout jinde.

09Bezpečnost

Co klíč nesmí a co o něm víme

Klíč jen na to, co potřebujete

Oblasti zaškrtnete při vytvoření klíče a jinam se s ním nedostanete.

Klíč vidíte jen jednou

Ukládáme si z něj jen otisk, takže ho zpětně nepřečteme ani my.

Data oddělená databází

Izolace mezi obchody je vynucená databází, ne jen podmínkou v dotazu aplikace.

Citlivá čísla ven nejdou

Nákupní ceny, marže ani interní poznámky k objednávce API nikdy nevrací.

Podepsané webhooky

Každá zpráva nese podpis a časové razítko, takže se dá ověřit, že přišla od nás.

Zrušitelné kdykoliv

Klíč zneplatníte okamžitě, bez zásahu do zbytku obchodu.

10Postup

Od klíče k prvnímu volání

Zapněte API a vytvořte klíč
V Nastavení → API a MCP zapnete REST API a kliknete na Vytvořit klíč: pojmenujete ho, zvolíte, že platí pro REST API, a zaškrtnete oblasti, které smí číst. Obojí smí jen vlastník obchodu a obchod k tomu potřebuje aktivní placený tarif.
Zkopírujte si ho hned
Klíč se zobrazí jednou a naposledy. Ukládáme si z něj jen otisk, takže vám ho nedokážeme znovu přečíst.
Ověřte ho na /ping
První volání ať vede na ověřovací cestu. Vrátí oprávnění klíče, takže hned víte, jestli sedí, ještě než postavíte scénář.
Nepoužívaný klíč odvolejte
Klíč, který už nic nevolá, je jen riziko navíc. Odvolání je okamžité a zbytku obchodu se nedotkne.

Časté dotazy

Než začnete

Musím o klíč žádat?

Ne, o klíč ani o přístup. REST API si vlastník obchodu zapne sám v Nastavení → API a MCP a poprvé potvrdí, že za napojený nástroj odpovídá. Klíč si tamtéž vytvoří a hned u něj vybere, které oblasti smí číst. Celý klíč se ukáže jedinkrát při vytvoření: uložený u nás je jen jeho otisk, takže vám ho nedokážeme přečíst ani my. Když se ztratí, vytvoříte si nový a starý zrušíte. Externí přístup je součástí placených tarifů, včetně jejich zkušebního období s uloženou kartou.

Kdo v obchodě smí klíč vytvořit?

Jen vlastník obchodu, a každé vytvoření potvrdí heslem nebo kódem z e-mailu. Klíč čte objednávky a s nimi i osobní údaje zákazníků, takže to není nic, co by mělo jít mimo majitele obchodu. Manažer klíče vidí a smí je zrušit. U každého klíče vidíte, kdy byl naposledy použit a kolik volání dnes přišlo, a můžete ho okamžitě zrušit.

Proč se přes API nedá nic měnit?

Protože zápis zvenčí je jiná úloha než čtení. Cizí systém, který zakládá objednávky nebo hýbe skladem, potřebuje vlastní řešení idempotence (opakované volání nesmí nic zdvojit), validace a auditu, jinak se první výpadek sítě projeví jako dvě objednávky a nikdo nepozná proč. Dokud to nebude postavené pořádně, radši to neslíbíme. Když potřebujete, aby se v obchodě něco měnilo, podívejte se na MCP server: tam zápis existuje, každou změnu, která něco přepisuje, napřed potvrdíte a téměř každou jde vrátit zpět.

Co když integraci nepotřebuju, protože stačí hotová funkce?

Než začnete vyvíjet, projděte si, co už v systému hotové je: export do POHODY, feedy pro srovnávače, e-mailové automatizace nebo import katalogu. Když vám stačí, ušetříte si vývoj. A když si nejste jistí, jestli váš záměr API vůbec potřebuje, napište nám a řekneme vám to rovnou.

Kolik API stojí?

Je v ceně tarifu, neúčtujeme ho zvlášť ani za volání. Kolik klíčů váš tarif dovoluje, najdete v ceníku.

Jak často se dá volat?

Každý klíč má strop volání za minutu a za den podle tarifu obchodu a každá ověřená odpověď nese hlavičky X-RateLimit, podle kterých si integrace sama určí tempo. Nad strop přijde odpověď 429 s hlavičkou Retry-After, která říká, za kolik sekund pokračovat. Průběžná synchronizace přes updated_since stahuje jen změny od minulého běhu, takže se do stropu vejde i velký katalog.

Máte popis rozhraní ve formátu OpenAPI?

Ano. Soubor /openapi-v1.json na doméně vašeho obchodu popisuje ve formátu OpenAPI 3.1 každou cestu, parametr, tvar odpovědi i chybu. Generuje se ze stejné smlouvy, podle které API odpovídá, takže si z něj běžným generátorem vytvoříte klienta pro svůj jazyk a v testech podle něj ověříte odpovědi.

Zapnete si ho sami

REST API zapíná vlastník obchodu v Nastavení → API a MCP, jen s placeným tarifem, nebo s jeho zkušebním obdobím a uloženou kartou. Jak poslat první požadavek, popisuje dokumentace pro vývojáře.

Porovnat tarify Dokumentace pro vývojáře

Hotové, a jen ke čtení

24 endpointů, a tohle jsou všechny

5 datových oblastí

Zákazníci, skupiny, recenze, zprávy, historie e-mailů a SMS a žádosti GDPR (čtení)

Doklady: metadata, položky a stažení PDF/ISDOC (čtení)

Objednávky (čtení)

Katalog: produkty, kategorie, dodavatelé (čtení)

Sklad, pohyby a nákup (čtení)

Jak se s ním pracuje

Jen změny od minulého běhu

Jen změny od minulého běhu

Průchod, který se nerozejde

Hranice příštího běhu

Popis OpenAPI 3.1.0

Jak volání vypadá

Když má obchod zavolat vám

Zapnutí, klíče a přehled volání

Zapíná vlastník obchodu

Klíč pro jednu plochu, nebo pro obě

Platnost s upozorněním předem

Výměna bez výpadku

Přehled využití a protokol volání

Strop volání podle tarifu

K čemu se používá nejčastěji

Účetnictví a ERP

Skladový systém

Vlastní aplikace

Reporting a BI

Systém dodavatele

Vlastní frontend

Co klíč nesmí a co o něm víme

Klíč jen na to, co potřebujete

Klíč vidíte jen jednou

Data oddělená databází

Citlivá čísla ven nejdou

Podepsané webhooky

Zrušitelné kdykoliv

Od klíče k prvnímu volání

Zapněte API a vytvořte klíč

Zkopírujte si ho hned

Ověřte ho na /ping

Nepoužívaný klíč odvolejte

Než začnete

Zapnete si ho sami