Shoptet API 2026: Private API token, Premium a první volání

Shoptet API je REST rozhraní na adrese https://api.myshoptet.com. Pro majitele e-shopu je přímý přístup (Private API) dostupný jen u tarifu Shoptet Premium. Token vytvoříte v administraci v Propojení → Private API, do požadavků ho posíláte v hlavičce Shoptet-Private-API-Token a ověříte ho například voláním GET /api/eshop. Partnerští vývojáři doplňků používají jiný režim (OAuth). Webhooky jsou samostatný kanál událostí — doplněk API, ne náhrada. Postupy níže vycházejí z developers.shoptet.com a api.docs.shoptet.com ověřených 27. 10. 2026.

Ve zkratce

• Private API = Premium; token až 10×, header Shoptet-Private-API-Token.
• Partner / doplněk = OAuth + dočasný Shoptet-Access-Token.
• Webhooky = push událostí (order:create…); k API se vážou, ale neřeší čtení katalogu.
• Rate limit: max. 3 souběžné spojení na token, 50 na IP; při překročení HTTP 429.
• Originální prvek: rozhodovací strom Private API vs doplněk vs webhook + checklist oprávnění tokenu.

Navazuje na Shoptet Premium 2026: cena, co obsahuje a pro koho a na Shoptet webhooky s daty 2026. Profil platformy je v katalogu Shoptet.

Co Shoptet API umí a co od něj nečekejte

API vrací a přijímá JSON. Společné endpointy slouží jak Premium (Private API), tak partnerům (doplňky). Liší se autentizace:

Private API neřeší „magické napojení bez programování“. Potřebujete někoho, kdo umí HTTP požadavky (vlastní skript, Make/Zapier přes HTTP, nebo vývojáře). Pokud stačí hotový doplněk z katalogu, API sami nepotřebujete — viz Shoptet doplňky 2026.

Kdy stačí doplněk, kdy webhook a kdy Private API

Doplněk z katalogu zvolte, když existuje hotová integrace (účetnictví, doprava, chat, mailing). Instalace je v administraci, OAuth řeší partner.

Webhook zvolte, když potřebujete okamžitě vědět, že se něco stalo (nová objednávka, změna skladu), a data si případně dočtete API. Od září 2025 umí vybrané webhooky nést payload — detaily v článku o webhookách s daty.

Private API zvolte, když:

• ☐ potřebujete pravidelně číst/zapisovat větší objemy (produkty, objednávky, sklady) vlastním systémem,
• ☐ doplněk neexistuje nebo nevyhovuje právům a limitu dat,
• ☐ máte (nebo plánujete) Shoptet Premium a interní kapacitu na údržbu tokenů.

Bez Premium Private API token v administraci nevytvoříte. Partner API přes doplněk Premium nevyžaduje na straně e-shopu stejným způsobem — doplněk si OAuth řeší sám.

Cena kontextu: Premium a Private REST API

Podle shoptet.cz/cenik k 27. 10. 2026 (ceny bez DPH 21 %):

Orientační ceny nižších tarifů z katalogu biztools (k 30. 9. 2026, bez DPH): Basic 440 Kč, Business 1 490 Kč, Profi 2 490 Kč, Enterprise 4 690 Kč. Konkrétní nabídku Premium vždy ověřte u Shoptetu — „od 12 000 Kč“ je spodní hranice z veřejného ceníku.

Postup: Private API token a první volání

1. Ověřte tarif Premium v administraci (nebo u obchodního zástupce Shoptetu). Bez Premium sekce Private API nebude k dispozici.
2. Otevřete Propojení → Private API (v anglické dokumentaci Connections → Private API).
3. Klikněte na Přidat, zadejte popis tokenu (např. „ERP Pohoda – jen čtení objednávek“). Můžete mít až 10 tokenů; platnost není časově omezená.
4. Token se po vytvoření zobrazí celý jen po opětovném zadání hesla administrace. Uložte ho do správce tajemství (1Password, Bitwarden, secrets ve CI) — nikdy do veřejného repozitáře ani do frontendu e-shopu.
5. V detailu tokenu upravte skupiny endpointů (read / write / read+write). Nový token má ve výchozím stavu všechna oprávnění; odeberte, co integrace nepotřebuje.
6. Ověřte volání:

Příklad ověření v terminálu (curl): metoda GET na https://api.myshoptet.com/api/eshop, hlavička Shoptet-Private-API-Token s vaším tokenem a Content-Type: application/json. Úspěch poznáte podle stavového kódu 200 a JSON odpovědi s kontaktem e-shopu.

Úspěch = HTTP 200 a JSON s data.contactInformation (název e-shopu, URL, kontakty). Do logu si uložte metadata.requestId — Shoptet ho chce při ticketu na podporu.

Oprávnění, chyby a rate limiting

403 invalid-token-no-rights znamená, že token nemá skupinu pro daný endpoint. Doplňte oprávnění v administraci, nebo použijte jiný token.

401 u partnerských (dočasných) tokenů obvykle znamená expiraci — Private tokeny dle dokumentace časově neexpirují, ale smazaný nebo špatně zkopírovaný token se chová stejně jako neplatný.

429 = překročen limit souběžných spojení (max. 3 na token, 50 z jedné IP). Snižte paralelismus. Header X-RateLimit-Bucket-Filling a případně Retry-After pomáhají s „leaky bucket“ limity u náročných integrací.

423 Locked = stejný zápis běžel paralelně; počkejte a neopakujte dvojité POST/PUT.

Stránkování: parametry page a itemsPerPage. Velké exporty řešte snapshot / asynchronními joby a webhookem job:finished — bez registrace tohoto webhooku asynchronní job nepřijme (403).

Bezpečnost tokenu v praxi

• ☐ Oddělený token pro každou službu (ERP, BI, staging).
• ☐ Minimum oprávnění (jen read, pokud zápis nepotřebujete).
• ☐ Rotace při podezření na únik: smazat starý token, vytvořit nový, aktualizovat integraci.
• ☐ Token jen na serveru / v secrets; nikdy v HTML šabloně Shoptetu ani v prohlížeči zákazníka.
• ☐ Logujte requestId, nelogujte celý token.

AI funkce v administraci (přehled AI ve Shoptetu) API nenahrazují — slouží copywritingu a rutinně v adminu, ne pro napojení skladů.

Typické use-cases Private API

1. ERP a účetnictví — objednávky, faktury, sklady do POHODA nebo jiného systému, pokud nestačí hotový doplněk (viz i Shoptet Pohoda 2026).
2. Vlastní WMS / fulfillment — pohyb skladu a dostupnost; u skladových procesů navazuje série Sklad.
3. BI a reporty — noční dump objednávek do skladu dat.
4. B2B portál — čtení ceníků a zápis objednávek mimo standardní košík.
5. Migrace a čištění dat — jednorázové skripty místo ručních CSV.

Pro běžné napojení dopravců a srovnávačů stačí vestavěné funkce a XML feedy — API je zbytečně drahé, pokud Premium berete jen kvůli jednomu exportu týdně.

Checklist před spuštěním integrace

• ☐ Máte Premium (nebo jasný termín přechodu).
• ☐ Popis tokenu a seznam endpointů schválený interně.
• ☐ Secrets management a kdo token smí rotovat.
• ☐ Test na sandboxu Premium (ceník sandbox uvádí) před produkcí.
• ☐ Monitoring 401/403/429 a alert při výpadku.
• ☐ Plán, co se stane při smazání tokenu (runbook).
• ☐ Webhook job:finished, pokud používáte asynchronní endpointy.
• ☐ Dokumentace mapování polí (SKU, DPH, stavy objednávek) mezi Shoptetem a cílovým systémem.

Časté chyby

1. Volání API z frontendu e-shopu — token unikne.
2. Jeden „god token“ pro vše — při úniku ohrozíte celý obchod.
3. Ignorování stránkování — zpracujete jen první stránku produktů.
4. Paralelní zápisy stejné entity → 423 a nekonzistence.
5. Očekávání Private API na tarifech Basic–Enterprise bez Premium.
6. Záměna Private API s partnerským OAuth (špatný header).

Příklad minimální integrace (čtení objednávek)

Po úspěšném GET /api/eshop obvykle následuje seznam objednávek. Endpointy a přesné parametry filtrů berte vždy z aktuální OpenAPI dokumentace — názvy polí se mezi verzemi můžou doplňovat. Praktický postup:

1. Zavolejte stránkovaný seznam objednávek (typicky /api/orders s page a itemsPerPage).
2. Pro každou novou objednávku si uložte code / identifikátor a stav.
3. Detail objednávky stáhněte jen pro záznamy, které ještě nemáte v ERP (šetříte bucket i čas).
4. Stav „zaplaceno“ raději ověřujte i přes webhook order:paid, ať nečekáte jen na polling.

Kombinace webhook (signál) + API (dočtení) je u Shoptetu obvykle stabilnější než čistý polling každých 30 sekund.

Vztah k administraci a správcům

Token Private API není vázaný na konkrétního správce e-shopu jako přihlášení do adminu, ale správa tokenů vyžaduje přístup do sekce Propojení. Oprávnění správců a 2FA řeší článek Shoptet administrace 2026 — vhodné je, aby tokeny zakládal jen účet s vysokými právy a aby změna hesla admina spouštěla kontrolu, kdo má přístup k secrets.

Pokud agentura drží token za vás, smluvně určete:

• ☐ kdo smí token vytvořit a smazat,
• ☐ kam se ukládá,
• ☐ jak rychle rotujete po odchodu konzultanta,
• ☐ jestli agentura smí mít write práva, nebo jen read.

Kdy Premium kvůli API nedává smysl

Private API samo o sobě neospravedlní Premium, pokud:

• objednávky exportujete jednou týdně přes CSV,
• stačí vám oficiální doplněk,
• nemáte vývojáře ani rozpočet na údržbu,
• řešíte jen e-mailing nebo feedy (na to API nepotřebujete).

V takových případech zůstaňte na Enterprise/Profi a použijte doplňky, XML feedy nebo Make. Premium zvažte, až máte konkrétní seznam endpointů a odhad hodin vývoje.

Při změně majitele e-shopu zneplatněte API tokeny a partnerské přístupy, viz Prodej e-shopu na Shoptetu 2026: převod, data a checklist.

FAQ

Potřebuji Shoptet API, když už mám doplněk Pohoda?

Ne nutně. Doplněk řeší běžnou synchronizaci. Private API přidejte, když potřebujete vlastní logiku mimo doplněk.

Funguje Private API bez Premium?

Podle oficiální dokumentace developers.shoptet.com je přímý přístup k datům e-shopu přes Private API určen pro Premium. Bez něj token v administraci nevytvoříte.

Jaký je rozdíl mezi webhookem a API?

Webhook vás informuje o události. API data čte a zapisuje na vyžádání. Často se kombinují.

Kolik tokenů můžu mít?

Až 10 Private API tokenů na e-shop (dle Private tokens maintenance).

Kde je kompletní seznam endpointů?

V referenční dokumentaci na api.docs.shoptet.com a v Postman kolekci Shoptet Public API Workspace.

Co dělat při 403 invalid-token-no-rights?

V administraci u tokenu doplňte skupinu endpointů s právem read nebo write pro danou oblast.

Co si připravit po stránce firmy, než napíšete vývojáři

Než objednáte napojení, sepište jednu stránku zadání v češtině (i když vývojář mluví anglicky — API dokumentace je anglicky, byznys pravidla musíte dodat vy):

1. Která data tečou kam — např. „nové objednávky ze Shoptetu do účetního systému každou hodinu“.
2. Mapování stavů — co znamená ve Shoptetu „odesláno“ a co v ERP.
3. Výjimky — dobírka, předobjednávka, balíček dárků, slevový kupón.
4. Kdo hlídá chyby — e-mail nebo Slack kanál, když API vrátí 5xx nebo 429.
5. Testovací scénář — jedna testovací objednávka, jeden testovací produkt, postup rollbacku.

Bez tohoto zadání vzniká „napojení, které umí všechno a v praxi nic“. Private API je jen trubka; pravidla patří vám.

Provozní hygiena po spuštění

První měsíc po startu integrace:

• ☐ Denní pohled na počet chyb 401/403/429.
• ☐ Týdenní kontrola, že počet objednávek v ERP sedí s exportem ze Shoptetu (tolerance např. zpoždění webhooku).
• ☐ Po každé změně tarifu nebo správců ověřit, že sekce Private API je stále dostupná a tokeny existují.
• ☐ Záloha mapovací tabulky SKU (když dodavatel změní kódy, API jen poslušně přenese špatná data).

Když se e-shop rozroste o marketplace kanály, znovu zvažte, zda má být zdrojem pravdy Shoptet, nebo ERP — API umí oba směry, ale dvojí zápis bez pravidel = rozbitý sklad.

Shrnutí pro majitele e-shopu bez technického týmu

Pokud nemáte vlastní vývojáře, berte Private API jako službu, kterou kupujete spolu s Premium a s implementací. Spočítejte si, kolik hodin měsíčně dnes ztrácíte ručním přepisováním objednávek a skladů. Až když tahle ruční práce dává smysl převést do automatizace a máte partnera, který to udrží, má Premium kvůli rozhraní ekonomické opodstatnění. Jinak zůstaňte u hotových doplňků a běžných exportů. Rozhraní samo o sobě tržby nezvedne — zvedne je spolehlivý provoz bez přepisování čísel.

Často stačí začít menším krokem: nechat si od partnera připravit jednosměrné čtení objednávek do účetnictví a teprve později přidat zápis skladů. Čím míň směrů data tečou, tím míň překvapení při inventuře a reklamacích. První měsíc po spuštění počítejte s tím, že budete kontrolovat rozdíly ručně — automatizace bez kontroly jen zrychlí chyby.

Časté otázky majitelů před podpisem Premium

Než přejdete na vyšší tarif kvůli rozhraní, zeptejte se dodavatele implementace na tři věci: jak dlouho potrvá první užitečný přenos dat, kdo platí opravy po změně ze strany Shoptetu a jak poznáte, že se data rozcházejí. Bez jasných odpovědí riskujete, že budete platit vyšší měsíční částku a stejně přepisovat tabulky ručně. Raději odložte start o měsíc a připravte čistá data produktů a stavů objednávek — špatný číselník žádné rozhraní nezachrání.

Jak poznat, že už narazíte na strop bez Premium

Typické signály přicházejí postupně. Nejdřív účetní žádá každý den export, který někdo ručně upravuje v tabulce. Pak sklad hlásí, že se stavy „rozcházejí“, i když nikdo vědomě nic neměnil. Nakonec marketing spustí kampaň a objednávky se ve špičce nestíhají propsat do fakturace. V tu chvíli už nejde o pohodlí, ale o riziko špatně odchozích dokladů a špatně drženého skladu.

Než sáhnete po vyšším tarifu, spočítejte si počet ručních zásahů za týden a kolik stojí hodina člověka, který je dělá. Porovnejte to s měsíční cenou Premium a s jednorázovým nákladem na implementaci. Když vychází návratnost v jednotkách měsíců a máte stabilního partnera, dává smysl pokračovat. Když vychází návratnost v letech, nejdřív zjednodušte procesy — často stačí lepší stavy objednávek a kázeň u importů.

Spolupráce s agenturou a předání

Agentura by měla odevzdat nejen funkční skript, ale i krátký provozní manuál: kde leží přístupové údaje, jak se obnoví spojení po výpadku a koho volat, když odpověď serveru hlásí zakázaný přístup. Bez manuálu skončíte po půl roce s černou skříňkou. Do smlouvy uveďte, že po ukončení spolupráce dostanete všechny přístupy a že agentura tokeny smaže ze svých zařízení.

Propojení s doplňky a marketplace

Private API není konkurencí ke katalogu doplňků — spíš poslední vrstva, když doplněk nestačí. Marketplace napojení (Allegro, Heureka a další) řešte nejdřív oficiálními propojeními. Vlastní zápis přes rozhraní do marketplace kanálů bez znalosti jejich pravidel snadno poruší dostupnost nebo cenu. Stejně tak dopravní štítky nechte na Balících nebo doplňku dopravce; rozhraní používejte spíš na data, která nikde jinde nedostanete v potřebném tvaru.

Závěr

Shoptet API dává smysl tam, kde Premium a vlastní integrace ušetří ruční práci nebo nahradí chybějící doplněk. Začněte jedním tokenem s minimem práv, ověřte GET /api/eshop a teprve potom napojujte objednávky a sklady. Cenu Premium berte z aktuálního ceníku (od 12 000 Kč/měs. bez DPH k 27. 10. 2026) a rozhodněte, jestli objem dat tu investici unese.

Zdroje

• Private API – Shoptet Developers (ověřeno 27. 10. 2026)
• Private API tokens maintenance
• Shoptet API reference
• Ceník Shoptet — ceny bez DPH 21 %, k 27. 10. 2026
• Shoptet Premium 2026 na biztools
• Shoptet webhooky s daty 2026