REST rozhraní

Ověřenoověřeno 2026-09-03

Stručně

REST rozhraní je na /api/v1 a odpovídá jen na GET. Cokoli jiného dostane 405 dřív, než se server podívá na klíč.

Přístup se prokazuje hlavičkou — viz Přehled.

Volání

Adresa	Rozsah	Co vrátí
`GET /account/entitlements`	`account:read`	Tarif klienta, funkce a limity s aktuálním využitím.
`GET /affiliate/articles/:key`	`affiliate:read`	Jeden článek nápovědy se zněním (HTML) ve všech nebo v jednom jazyce; proměnné nedosazené.
`GET /affiliate/articles`	`affiliate:read`	Články nápovědy partnerského portálu: klíč, výchozí/vlastní, zapnutí, pořadí, stav po jazycích.
`GET /affiliate/campaigns/:campaignId`	`affiliate:read`	Jedna kampaň partnerského programu.
`GET /affiliate/campaigns`	`affiliate:read`	Kampaně partnerského programu e-shopu s odměnou, dostupností a počty.
`GET /affiliate/code-requests`	`affiliate:read`	Žádosti partnerů o vlastní slevový kód se stavem a důvodem; čekající první.
`GET /affiliate/conversions`	`affiliate:read`	Konverze partnerského programu e-shopu s provizí, stavem a vazbou na výplatu.
`GET /affiliate/discount-codes`	`affiliate:read`	Slevové kódy partnerů na e-shopu s počtem použití a obratem.
`GET /affiliate/documents`	`affiliate:read`	Dokumenty programu (podmínky, dohody): politika potvrzení, podepsaná kopie, příloha e-mailu, verze po jazycích, připravenost a počty potvrzení.
`GET /affiliate/email-templates`	`affiliate:read`	Šablony e-mailů partnerům po jazycích (předmět, zapnutí, s událostí i tělo) a automatické přílohy e-mailu Účet schválen.
`GET /affiliate/links/generate`	`affiliate:read`	Sledovaný partnerský odkaz na domov, produkt nebo kategorii e-shopu kampaně; po kliknutí zachová přiřazení partnerovi.
`GET /affiliate/partners/:partnerId`	`affiliate:read`	Jeden partner programu s kampaněmi, které má k dispozici.
`GET /affiliate/partners`	`affiliate:read`	Partneři programu se stavem, výkonem a provizemi; kontakt jen s osobními údaji.
`GET /affiliate/payouts`	`affiliate:read`	Výplaty provizí partnerům se stavem; bez bankovních a fakturačních údajů.
`GET /affiliate/portal`	`affiliate:read`	Veřejný portál partnera: adresy po e-shopech, otevřenost registrace s důvodem, vlastní domény, kontaktní osoba, vzhled a stav textů po jazycích.
`GET /affiliate/settings`	`affiliate:read`	Nastavení partnerského programu: provize, kliky, minimum výplaty, přivedení.
`GET /affiliate/statistics`	`affiliate:read`	Statistika partnerského programu: vývoj po dnech, zdroje přiřazení, žebříček partnerů.
`GET /affiliate/summary`	`affiliate:read`	Přehled partnerského programu e-shopu za období: kliky, konverze, provize, partneři.
`GET /analytics/channels`	`analytics:read`	Kanály návštěvnosti včetně ChatGPT a dalších AI zdrojů.
`GET /analytics/order-coverage`	`analytics:read`	Pokrytí objednávek měřením.
`GET /analytics/overview`	`analytics:read`	Návštěvy, objednávky, obrat, konverzní poměr, AOV, podíl AI zdrojů.
`GET /analytics/seo`	`analytics:read`	Search Console podle dotazů nebo stránek.
`GET /automations/catalog`	`automations:read`	Katalog automatizací: spouštěče, pole podmínek, operátory, akce, šablony a `catalogVersion`.
`GET /automations/:workflowId`	`automations:read`	Jedna automatizace s DSL a výsledkem validace.
`GET /automations`	`automations:read`	Automatizace klienta se stavem a rozsahem e-shopů.
`GET /automations/:workflowId/runs`	`automations:read`	Historie běhů jedné automatizace.
`GET /automations/templates`	`automations:read`	Hotové vzory automatizací s DSL.
`GET /claims/:code`	`claims:read`	Jedna reklamace s položkami, refundacemi a zpětnými zásilkami.
`GET /claims`	`claims:read`	Reklamace a vrácení jednoho e-shopu s vazbami na objednávku.
`GET /claims/settings`	`claims:read`	Procesy reklamací (typy, kroky, stavy, lhůty); nastavení modulu jen s právem na ně.
`GET /claims/statistics`	`claims:read`	Statistika reklamací a vrácení za období: počty, doby vyřízení, typy, hodnocení, důvody.
`GET /content/articles`	`products:read`	Články blogu a obsah e-shopu z canonical zrcadla podle názvu nebo textu.
`GET /coupons/activation-link`	`coupons:read`	Odkaz, který zákazníkovi uplatní EXISTUJÍCÍ kupón v košíku. Kupón nevytváří.
`GET /coupons/activation-status`	`coupons:read`	Dá se kupón na e-shopu použít přes aktivační odkaz: zrcadlo kupónu + stav kódu na webu.
`GET /coupons/capabilities`	`coupons:read`	Co o kupónech umí platforma daného e-shopu. Čtěte před zakládáním.
`GET /coupons/:code`	`coupons:read`	Jeden kupón podle kódu.
`GET /coupons`	`coupons:read`	Slevové kupóny e-shopu s typem a výší slevy, platností a odvozeným stavem.
`GET /customers/:customerKey`	`customers:read`	Jeden zákazník z adresáře — identita, e-shopy, celoživotní i volitelné peníze za období, rozpis podle e-shopu.
`GET /customers`	`customers:read`	Adresář zákazníků: identita (s maskováním osobních údajů), e-shopy, jazyk, celoživotní počty a obrat po měnách; volitelný filtr nákupní aktivity v období.
`GET /customers/performance`	`reports:read`	Zákazníci jako pseudonymy: objednávky, obrat, LTV, noví a opakovaní.
`GET /credit-notes`	`invoices:read`	Hledání v dobropisech.
`GET /invoices/:invoiceCode`	`invoices:read`	Jedna faktura s položkami dokladu, dobropisy, zálohovými fakturami a číslem objednávky.
`GET /invoices`	`invoices:read`	Hledání ve fakturách.
`GET /inventory/movements`	`inventory:read`	Historie skladových pohybů: kdy, co, o kolik, druh, původ, objednávka.
`GET /inventory/availability`	`inventory:read`	Stav zásoby více položek najednou.
`GET /inventory/stock`	`inventory:read`	Stav zásoby jedné položky i se zdrojem hodnoty.
`GET /orders/:orderCode`	`orders:read`	Jedna uložená objednávka včetně položek.
`GET /orders`	`orders:read`	Uložené objednávky jednoho e-shopu, od nejnovější.
`GET /categories`	`products:read`	Kategorie e-shopu s počtem produktů.
`GET /products/:code`	`products:read`	Jeden produkt podle kódu včetně zařazení a ceny z karty.
`GET /products`	`products:read`	Hledání produktů podle názvu, kódu, EAN nebo PLU.
`GET /reports/financial-summary`	`reports:read`	Finanční souhrn období; s `purchase-prices:read` i nákup, hrubý zisk a marže.
`GET /sales/order-performance`	`reports:read`	Obrat po objednávkách se součty za celé období; s `purchase-prices:read` i nákup, zisk a marže.
`GET /sales/product-performance`	`reports:read`	Prodeje po produktech se součty za celé období.
`GET /shipping/carriers`	`shipping:read`	Připojení dopravci a profily, bez přístupových údajů.
`GET /shipping/shipments/:shipmentId`	`shipping:read`	Jedna zásilka se všemi událostmi sledování.
`GET /shipping/shipments`	`shipping:read`	Zásilky s dopravcem, zemí, časem předání a doručení, po stránkách.
`GET /shipping/stats`	`shipping:read`	Statistiky doručování po dopravcích: počty, úspěšnost, medián a p90 doručení, země.
`GET /stores/integration-status`	`stores:read`	Stav MitoOps kódu na webu po e-shopech: nainstalováno, verze, moduly, připravenost kupónu z odkazu.
`GET /stores`	`stores:read`	Seznam e-shopů klienta i s jejich kódem.
`GET /suppliers/:supplierId`	`purchasing:read`	Jeden dodavatel s nabídkami a nákladovými složkami.
`GET /suppliers`	`purchasing:read`	Dodavatelé s nabídkami a nákladovými složkami.
`GET /webhooks/endpoints/:endpointId/deliveries`	`webhooks:read`	Deník doručení jednoho endpointu bez těla.
`GET /webhooks/endpoints/:endpointId`	`webhooks:read`	Jeden webhook endpoint s počtem čekajících doručení.
`GET /webhooks/endpoints`	`webhooks:read`	Webhook endpointy klienta bez tajemství a stav fronty.
`GET /webhooks/events`	`webhooks:read`	Katalog událostí odchozích webhooků, obálka a podpis.

Adresa	Rozsah	Co vrátí
`GET /capabilities`	—	co tento klíč smí zavolat
`GET /openapi.json`	—	strojově čitelný popis rozhraní

GET /capabilities je nejrychlejší způsob, jak zjistit, co klíč otevírá — vrací přesně to, co mu rozsahy dovolily, ne celý katalog. Přesné parametry a pole odpovědi každého volání jsou v openapi.json.

Tvar odpovědi

Každá odpověď má dvě části: data a meta.

{
  "data": [ { "market": "cz", "name": "Můj e-shop" } ],
  "meta": { "requestId": "…", "count": 1 }
}

meta.requestId je identifikátor volání. Když se něco pokazí, je to údaj, který podpoře řekne, o které volání šlo.

U výpisů nese meta navíc count (kolik záznamů je v této odpovědi), hasMore (true, když další strana existuje) a nextCursor (hodnota, kterou si o další stranu řeknete; null, když žádná není).

Stránkování

Další stranu si vyžádáte tak, že nextCursor z odpovědi pošlete zpět v parametru cursor. Ostatní parametry musí zůstat stejné — kurzor patří k dotazu, se kterým vznikl, a se změněným e-shopem či obdobím ho rozhraní odmítne (400). Konec poznáte podle hasMore, ne podle počtu záznamů. Neplatný kurzor je chyba, ne prázdný výsledek: prázdná odpověď by vypadala jako konec dat a export by se tiše zkrátil.

Číslování stran rozhraní záměrně nemá: když mezi dvěma voláními přibude záznam, „strana 2“ ukazuje jinam než před chvílí.

Výpis a hledání

U produktů, faktur a dobropisů jsou to dva režimy jedné adresy: bez query dostanete výpis po stranách od nejnovějšího (dá se stránkovat a omezit obdobím), s query hledání seřazené podle shody (nejvýš limit záznamů). Hledání se nestránkuje ani neomezuje obdobím — kombinace query s cursor, from nebo to skončí jako 400, ne jako tiše ignorovaný filtr. Na vyčtení celé evidence použijte výpis bez query.

Období

Objednávky, doklady, zásilky, statistiky, analytika i výkazy lze omezit parametry from a to ve tvaru YYYY-MM-DD.

Obě hranice jsou včetně. to=2026-08-05 zahrnuje celý 5. srpen, ne půlnoc na jeho začátku.
Den se bere tak, jak ho poslal e-shop — v jeho časovém pásmu, tedy stejně, jak ho vidí obsluha v aplikaci.
Objednávky se řadí podle data vzniku objednávky, zásilky podle data vzniku zásilky.
Faktury a dobropisy podle daňového data; když ho doklad nemá vyplněné, podle data vystavení. Je to tatáž sémantika, jakou se doklady zařazují do období v aplikaci. Která hodnota doklad zařadila, je vidět v poli businessDate.
Prodeje po produktech podle data dokladu; zde je období povinné.
Nejdelší období je 366 dní. Delší se odmítne.
Bez období vrátí zásilky a statistiky posledních 30 dní, analytika a finanční souhrn aktuální měsíc. Odpověď období vždy vypíše.
Obrácené období je chyba, ne prázdný výsledek — jinak by překlep vypadal jako období bez dokladů.

U objednávek zůstává i todayOnly. S from/to se spojit nedá: jsou to dvě odpovědi na tutéž otázku.

Co znamenají finanční pole

purchasePriceWithoutVat u položky objednávky je nákupní cena v čase objednávky, tak jak ji uložil e-shop. Není to cena z dnešní karty produktu — ta je v products/{code} jako purchasePrice.
cogs ve finančním souhrnu je nákup zboží za období ze všech objednávek; null znamená, že nákupní ceny nejsou známé pro dost řádků (cogsCoverage). Tehdy se neukáže ani hrubý zisk — raději nic než nesprávné číslo.
grossProfit je obrat bez DPH minus nákup zboží, grossMargin totéž v procentech. resultAfterCosts je hrubý zisk minus doprava minus náklady firmy — manažerské číslo, ne účetní zisk.
V prodejích po produktech je purchaseCostWithoutVat nákupní cena v čase dokladu podle spárování s katalogem; unmappedLines říká, kolik řádků se nespárovalo.
Všechny částky výkazů a analytiky jsou v EUR (pole currency), přepočtené kurzem v čase synchronizace. Objednávky a doklady nesou vlastní měnu.

Bez rozsahu purchase-prices:read tato pole v odpovědi nejsou — nejsou nulová, chybějí.

Čas doručení

Statistiky doručování (shipping/stats) měří čas od předání dopravci po první událost doručení z událostí sledování. Z data objednávky se nepočítá nic. Zásilka, která nemá oba body, se do mediánu nezapočítá; kolik se jich započítalo, říká delivery.measured. Tytéž dva časy nese každá zásilka v polích handedOverAt a deliveredAt.

deliveryRate je podíl doručených z těch, jejichž osud se už skončil (doručené, vrácené, chybné). Zásilka na cestě ještě není ani úspěch, ani neúspěch; zrušená zásilka je váš úkon, ne selhání dopravce, a nepočítá se vůbec.

Stav zásob

inventory/stock vrací quantity a source — z kterého evidenčního modelu hodnota pochází (varianty, bilance e-shopu, karta produktu). Když e-shop vede bilanci, jsou k dispozici i physical, available (dostupné k prodeji) a reserved (rezervované v objednávkách); jinak jsou null. Rozhraní nevymýšlí žádný „stav na skladě“, který aplikace neeviduje.

Adresář zákazníků

Zákazníci mají dvě různá čtení a zaměnit je znamená číst jiné číslo, než čekáte:

/customers a /customers/{customerKey} (rozsah customers:read) jsou adresář: tatáž projekce, jakou vidí obsluha na obrazovce Zákazníci a jaká jde do exportu — identita, e-shopy, země, jazyk, počty a data.
/customers/performance (rozsah reports:read) je analytika nad surovými objednávkami: zákazník je jen pseudonym, jméno ani kontakt v ní nejsou vůbec.

Zvenčí je market u obou povinný. Bez něj by se četlo přes všechny e-shopy klienta, tedy i přes ty, které přístupu nepatří.

Kdo uvidí co

customers:read sám vydá pseudonym (customerKey), e-shopy, zemi, jazyk, počty objednávek a data první a poslední objednávky. Navíc:

jméno, firma, e-mail, telefon a marketingové pohlaví jen s personal-data:read,
obrat, průměrná objednávka a LTV jen s reports:read.

Pole, na která nemáte rozsah, se odstraní, nikoli vynulují. null na místě e-mailu by znamenalo „zákazník e-mail nemá“, což není pravda — chybějící klíč znamená „nemáte na něj právo“.

customerKey je SHA-256 normalizovaného e-mailu. Je to tentýž pseudonym, jaký nesou doklady (customerEmailHash) i /customers/performance, takže se ty tři pohledy dají spojit, aniž by se kamkoli posílal e-mail.

Celý život versus období

Adresář má volitelný filtr purchaseFrom a purchaseTo (YYYY-MM-DD, obě hranice včetně). Znamená nákupní aktivitu v období: zákazník má v tom intervalu alespoň jednu objednávku. Není to filtr na datum prvního nebo posledního nákupu.

S obdobím přibudou pole periodFrom, periodTo, periodOrdersCount a periodRevenueByCurrency vedle celoživotních (ordersCount, revenue, lifetimeRevenue, firstOrderAt, lastOrderAt) — nikdy místo nich. Celoživotní hodnoty se obdobím nemění.

Peníze jsou vždy po měnách

Obrat, průměrná objednávka a LTV jsou pole po měnách, nikdy jedno číslo. Zákazník s objednávkami v EUR i v CZK má dvě položky; sečíst je do jednoho skaláru by znamenalo přičíst koruny k eurům. Totéž platí pro /customers/performance: řádek je dvojice (zákazník, měna) a součty filtru jsou totals.revenueByCurrency.

Jazyk a marketingové pohlaví

language je jazyk e-shopu, na kterém zákazník objednal (source: "store_locale"), ne jeho vlastní volba. Aplikace dnes výslovnou jazykovou preferenci zákazníka neeviduje.
marketingGender (male / female / unknown) je odhad z křestního jména, ne údaj, který by zákazník uvedl. Původ je vždy v genderSource — dnes výhradně name_inference nebo unknown — a spolehlivost v genderConfidence. Firemní zákazník pole nemá. Kdo ho zobrazuje dál, má říkat „odhad podle jména“, nikdy „zákazník uvedl“. Jde za personal-data:read stejně jako jméno samo.

E-shop

Volání nad údaji jednoho e-shopu si vyžádají jeho kód v parametru market. Seznam kódů vydá GET /stores.

Když klíč na daný e-shop rozsah nemá, odpověď je 403 — ne prázdný seznam. Prázdný seznam by se nedal odlišit od e-shopu bez objednávek. Záznam jiného e-shopu (například zásilka) je 404.

Chyby

Chybová odpověď má vždy stejný tvar a nese kód. Seznam stavů je v Přehledu.

Příklady

# Objednávky za období, po stránkách
curl -H "Authorization: Bearer <váš klíč>" \
  "https://<vaše adresa>/api/v1/orders?market=cz&from=2026-08-01&to=2026-08-31&limit=50"

# Statistiky doručování za srpen
curl -H "Authorization: Bearer <váš klíč>" \
  "https://<vaše adresa>/api/v1/shipping/stats?market=cz&from=2026-08-01&to=2026-08-31"

# Finanční souhrn srpna (s právem na nákupní ceny i hrubý zisk)
curl -H "Authorization: Bearer <váš klíč>" \
  "https://<vaše adresa>/api/v1/reports/financial-summary?market=cz&from=2026-08-01&to=2026-08-31"

# Stav zásoby tří položek
curl -H "Authorization: Bearer <váš klíč>" \
  "https://<vaše adresa>/api/v1/inventory/availability?market=cz&codes=A100,A101,A102"