REST rozhraní

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/connection	stores:read	Diagnostika tohoto připojení: aplikace, kdo a kdy přístup povolil, udělená a neudělená oprávnění po oblastech, e-shopy a režim zápisu přes AI.
GET /account/entitlements	account:read	Tarif klienta, funkce a limity s aktuálním využitím.
GET /account/team	team:read	Tým klienta: jména, role, aktivní účty, poslední přihlášení a kdo koho vede; e-mail jen s oprávněním na osobní údaje.
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/:conversionId	affiliate:read	Detail jedné konverze: částky, provize, stav provize s důvodem, stav objednávky v e-shopu, dobropis, výplata.
GET /affiliate/conversions	affiliate:read	Konverze partnerského programu e-shopu: základ provize a celá objednávka s DPH, provize, stav provize s důvodem, stav objednávky v e-shopu, vazba 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/:key/content	affiliate:read	Jeden právní dokument programu se zněním po jazycích (uložený text, veřejné znění, verze, otisky, zdroj, PDF metadata) a otevřenými koncepty.
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/signatures/:signatureId	affiliate:read	Jeden elektronický podpis s podepsaným zněním a snímkem hodnot; neměnný záznam, PDF se skládá v aplikaci.
GET /affiliate/signatures	affiliate:read	Elektronicky podepsané dokumenty partnerů (kdo, dokument, verze, jazyk, e-shop, čas, způsob, ověření, otisky, stav) a partneři, kterým podpis chybí; jen čtení — podpis vzniká výhradně v portálu.
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 /affiliate/variables	affiliate:read	Registr proměnných obsahu a e-mailů partnerského programu: kanonická jména, aliasy, typ, plochy, příklad; volitelná kontrola textu na neznámé proměnné.
GET /analytics/advertising	reports:read	Reklama: výdaje, rozpočet, ROAS, PNO, CPA, průměrná objednávka a MER se srovnáním; Google Ads, Meta Ads a OpenAI Ads, prokliky z GA4, 6 měsíců.
GET /analytics/channels	analytics:read	Kanály návštěvnosti včetně ChatGPT a dalších AI zdrojů.
GET /analytics/comparison	reports:read	Obraty se srovnáním: obrat, objednávky, AOV, návštěvy, CR a AI/LLM proti předchozímu období nebo roku.
GET /analytics/daily	reports:read	Obrat a objednávky po dnech (nejvýše 92 dní), součet za e-shopy nebo jeden e-shop.
GET /analytics/funnels/catalog	analytics-funnels:read	Události, parametry a vlastnosti uživatele z GA4 e-shopu pro nastavení trychtýře.
GET /analytics/funnels/:id	analytics-funnels:read	Trychtýř za období: návštěvníci kroků z GA4, nákupy a obrat z objednávek, rozdělení podle kanálů, srovnání.
GET /analytics/funnels	analytics-funnels:read	Trychtýře z GA4 (například kvíz na webu): kroky, značka návštěvníka, stav a poslední načtení.
GET /analytics/monthly	reports:read	Obrat, objednávky a návštěvy po měsících (nejvýše 24), například rok k roku.
GET /analytics/order-coverage	analytics:read	Pokrytí objednávek měřením; bez e-shopu součet za e-shopy a rozpis po e-shopech.
GET /analytics/order-heatmap	reports:read	Kdy přicházejí objednávky: den v týdnu × hodina, nejsilnější den a hodina.
GET /analytics/overview	analytics:read	Návštěvy, objednávky, obrat, konverzní poměr, AOV, podíl AI zdrojů.
GET /analytics/revenue-sources	reports:read	Odkud přišly tržby: kanály, součty AI/LLM, MitoOps a Affiliate, rozpad akvizice podle GA4.
GET /analytics/seo	analytics:read	Search Console podle dotazů nebo stránek.
GET /approvals/pending	approvals:read	Co čeká na schválení člověkem: kroky AI v Deníku AI změn a Návrhy od AI.
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/options	automations:read	Číselník pro pole automatizace (stavy, dopravy, platby, šablony, reklamace…): hodnota do DSL a název.
GET /automations/:workflowId/runs	automations:read	Historie běhů jedné automatizace.
GET /automations/templates	automations:read	Hotové vzory automatizací s DSL.
GET /campaigns/discount-compute	campaign-rules:read	Skutečná sleva z plné ceny při akci a kódu (násobí se), nebo dopočet druhé části k cílové slevě; porovnání s limitem e-shopu.
GET /campaigns/discount-rules	campaign-rules:read	Pravidla slev e-shopů: zda je limit zapnutý, nejvyšší souhrnná sleva z plné ceny, rozsah, režim a provize partnerů.
GET /chatbot/conversations/:sessionId	chatbot-conversations:read	Přepis jednoho rozhovoru s webovým chatbotem i se zdroji odpovědí bota.
GET /chatbot/conversations	chatbot-conversations:read	Rozhovory zákazníků s webovým chatbotem od naposledy aktivního, s první otázkou; kurzor.
GET /chatbot/outcomes	chatbot:read	Jak dopadly rozhovory s webovým chatbotem: odkdy se výsledek měří, měřené a neměřené rozhovory, známý a neznámý výsledek, vyřešené, nevyřešené, chyba bota a míra vyřešení se jmenovatelem; při nulovém jmenovateli N/A s důvodem. Jen součty.
GET /chatbot/stats	chatbot:read	Statistika webového chatbota za období: trychtýř bublinky z jednoho měření (starší počty jdou vedle jako historické), míra otevření chatu, rozhovory, výsledek na úrovni rozhovoru, hodnocení.
GET /chatbot/topics	chatbot:read	O čem byly rozhovory: podíly témat z uzavřené taxonomie, míra vyřešení a kandidáti na mezeru ve znalostech podle tématu, nejčastější produkty, typ stránky začátku a vývoj po dnech. Součet podílů se počítá ze zanalyzovaných rozhovorů a ten počet jde ven také. Jen součty.
GET /claims/config-drafts/:draftId	claims-settings:read	Stav návrhu změny nastavení reklamací (čeká, zapsaný, zamítnutý).
GET /claims/configuration	claims-settings:read	Nastavení reklamací: štítky, pole, zpětná doprava, formulář na e-shopu, typy formuláře.
GET /claims/deadlines	claims:read	Otevřené reklamace podle lhůty: po lhůtě a blízko lhůty, od nejnaléhavější, s počty po e-shopech.
GET /claims/:code	claims:read	Jedna reklamace s položkami, refundacemi, zpětnými zásilkami, štítky, časovou osou a odeslanými e-maily.
GET /claims	claims:read	Reklamace a vrácení jednoho e-shopu s vazbami na objednávku.
GET /claims/refund-options	claims-settings:read	Vrácení peněz: zdroj variabilního symbolu, platnost refundačního kuponu, kupon ve formuláři, kdy formulář žádá číslo účtu.
GET /claims/:code/refund-readiness	claims:read	Případ před refundací: co zákazník žádá, maskovaný účet, variabilní symbol, režim a zda lze případ smazat.
GET /claims/refund-settings	claims-settings:read	Refundace reklamací: režim, bankovní účty se způsobilostí pro platební příkaz (maskované), výchozí a ruční účet.
GET /claims/routes	claims-settings:read	Zpětná doprava reklamací: trasy, adresy, profily dopravců s ID a podporou vratky, typy případů.
GET /claims/settings	claims:read	Procesy reklamací s ID a názvy (typy, kroky, stavy, lhůty), štítky; nastavení modulu s rozsahem claims-settings:read.
GET /claims/statistics	claims:read	Statistika reklamací a vrácení za období: počty, doby vyřízení, typy, hodnocení, důvody.
GET /claims/templates	claims-settings:read	Šablony e-mailů (předmět, text, kdy a zda se posílají automaticky) a protokolů reklamací.
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 /coupons/web-box	coupons:read	Rámečky s cenou po zadání kódu u produktů na e-shopu: hlavní vypínač, kupóny, nastavení a stav.
GET /coupons/web-box/stats	coupons:read	Zobrazení rámečku, kopie kódu a uplatnění v košíku podle kupónu a produktu.
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 /documents	invoices:read	Účetní doklady jednoho druhu (faktury, zálohové faktury, dobropisy) po stránkách s životním cyklem, stavem ve zdroji, filtrem platnosti a dostupností PDF.
GET /documents/:documentType/:code/pdf	invoices:read	PDF faktury, zálohové faktury nebo dobropisu (base64 a SHA-256), tytéž bajty jako na obrazovce.
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; filtr úhrady (zaplacené, nezaplacené, po splatnosti) s počtem a součtem po e-shopech.
GET /payments/matching	payments:read	Párování přijatých plateb s objednávkami: počty podle výsledku a nespárované, nejednoznačné a chybné platby.
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/product-statistics	inventory:read	Po produktech za období: stav skladu, prodané, reklamované a vrácené kusy, míra reklamací.
GET /inventory/stock	inventory:read	Stav zásoby jedné položky i se zdrojem hodnoty.
GET /inventory/sync-status	stock-sync:read	Stav synchronizace skladu mezi e-shopy: fronta, konflikty, poslední běh a kontrola shody, mapování, zdraví spojení.
GET /inventory/valuation	inventory:read	Hodnota skladu jako obrazovka: nákupní a prodejní hodnota, hrubý a čistý potenciál, pod minimem, záporné, největší položky; bez sad a balíčků.
GET /messaging/deliveries	messaging:read	Doručení e-mailů k zásilkám, objednávkám, reklamacím a partnerům: souhrn, stavy a chyby (odražené, spam, zablokované).
GET /notifications	notifications:read	Upozornění ze zvonečku: co hlásí moduly, závažnost, stav, počet nepřečtených a obrazovka, která to řeší.
GET /orders/:orderCode	orders:read	Jedna uložená objednávka včetně položek.
GET /orders/:orderCode/line-discounts	orders:read	Historické ceny a slevy po položkách objednávky: původní cena, sleva, kupon, zaplacená hodnota a spolehlivost.
GET /orders	orders:read	Uložené objednávky, od nejnovější; filtr stavu, hledání, úhrada, období a úplný počet ve filtru.
GET /orders/packing-queue	orders:read	Fronta balení podle stavů, které si klient nastavil jako připravené k zabalení: počet a objednávky po e-shopech.
GET /availabilities/drafts/:draftId	products:read	Stav návrhu změny číselníku dostupností: čeká na schválení, zapsaný s výsledkem, zamítnutý, vypršelý.
GET /availabilities/history	products:read	Historie synchronizace dostupností: co se z kterého e-shopu přeneslo kam a s jakým výsledkem; období, kurzor.
GET /availabilities	products:read	Číselník dostupností e-shopu: název, popis, naskladnění, doručení, význam pro Google, barva, výchozí role.
GET /availabilities/pairing	products:read	Párování dostupností mezi e-shopy: řádky s položkou každého e-shopu, návrhy, nespárované, stav synchronizace.
GET /availabilities/pairing-drafts/:draftId	products:read	Stav návrhu změny párování dostupností: čeká na schválení, uložený, zamítnutý, vypršelý.
GET /catalog/category-content-drafts/:draftId	category-content:read	Stav návrhu textů kategorií: čeká na schválení, zapsaný, zamítnutý, vypršelý.
GET /categories/:guid/content	category-content:read	Texty kategorie (horní a dolní popis, SEO titulek a popis) s otiskem a zapisovatelností pole.
GET /categories/:guid	category-content:read	Jedna kategorie s živým stavem z e-shopu včetně viditelnosti (true/false, null = platforma ji nevede) a plánů od–do.
GET /categories	products:read	Kategorie e-shopu s počtem produktů, po stránkách s úplným počtem.
GET /categories/:guid/products	products:read	Produkty zařazené v kategorii, stránkovaně, živě z e-shopu (při výpadku ze zrcadla s označením zdroje).
GET /categories/visibility-plans	category-content:read	Plány zobrazení kategorií od–do: čas, stav, původní viditelnost, poslední zápis a chyba.
GET /product-logistics/:code	product-logistics:read	Hmotnost a rozměry prodejního balení varianty živě z e-shopu (kg, cm), zděděná pole, revize a poslední zápisy.
GET /product-logistics/missing	product-logistics:read	Kódy e-shopu bez hmotnosti nebo rozměrů (nebo s neověřenými jednotkami); s codes hodnoty z kopie se zdrojem a jistotou.
GET /products/:code/categories	products:read	Všechny kategorie produktu po e-shopech živě z e-shopu: hlavní a další zařazení včetně skrytých kategorií.
GET /products/changes	products:read	Deník změn karty produktu: pole, e-shop, kdy, odkud a náhled staré a nové hodnoty; ceny jen s oprávněním.
GET /catalog/product-content-drafts/:draftId	product-content:read	Stav návrhu textů produktů: čeká na schválení, zapsaný s upozorněními e-shopu, zamítnutý, vypršelý.
GET /products/:code/content	product-content:read	Texty produktu z e-shopu (popis, krátký popis, SEO titulek a popis) s otiskem a zapisovatelností pole.
GET /product-content/policy	product-content:read	Politika obsahu na e-shopu bez volání e-shopu: co tento přístup smí číst a navrhovat, která pole platforma zapíše, režim schvalování a autonomní zápis, limity a otisky.
GET /products/:code	products:read	Jeden produkt podle kódu včetně zařazení a ceny z karty.
GET /products/:code/offer	products:read	Nabídka produktu v e-shopu: zda ho e-shop ještě má, viditelnost, objednatelnost, dostupnost a cena s měnou, DPH a cenou v prodejní měně e-shopu.
GET /products	products:read	Hledání produktů podle názvu, kódu, EAN nebo PLU; filtr kategorie, aktivity a pod minimem s úplným počtem; stav v e-shopu, produkty smazané v e-shopu jen na vyžádání.
GET /products/:code/visibility	products:read	Živý stav produktu po e-shopech: viditelnost (i surový stav platformy), objednatelnost a indexovatelnost ke čtení, běžící plán od–do.
GET /catalog/products/visibility-plans	products:read	Plány viditelnosti produktů od–do: čas, stav, původní stav e-shopu, poslední zápis, chyba a poslední kolo plánovače.
GET /reports/cost-groups	reports:read	Kategorie a štítky nákladů a rozložení skupin v Nákladech.
GET /reports/costs	reports:read	Ruční i automatické náklady s částkou, která se započte do období; firemní i po e-shopech.
GET /reports/financial-summary	reports:read	Finanční souhrn období; s purchase-prices:read i nákup, hrubý zisk a marže.
GET /reports/history/:runId	reports:read	Stav jednoho exportu a jeho soubory s adresou ke stažení přes REST.
GET /reports/history	reports:read	Historie vygenerovaných reportů se soubory, velikostí a SHA256.
GET /reports/layout	reports:read	Rozložení exportu reportu: obálka, pořadí a zapnutí listů a sekcí, zlomy stran.
GET /reports/notes	reports:read	Poznámka k reportům, která jde do výkazu ve Wordu a PDF.
GET /reports/order-status-rules	reports:read	Které stavy objednávek se počítají do obratu, po e-shopech, s počtem a obratem ve stavu.
GET /reports/summary-all	reports:read	Souhrn více e-shopů jako u „Všechny“: celek, rozpad po e-shopech, firemní náklady jednou, computedAt a dataAsOf.
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 /reviews/:kind/:reviewId	reviews:read	Jedna recenze s historií odpovědí, jazykem, tónem a podpisem e-shopu a čekajícím návrhem odpovědi.
GET /reviews	reviews:read	Recenze obchodu a produktů jednoho e-shopu: hvězdičky, text, produkt, odpověď e-shopu, čekající návrh; filtry a období.
GET /reviews/reply-drafts/:draftId	reviews:read	Stav návrhu odpovědi na recenzi: čeká na schválení, zveřejněný, zamítnutý, vypršelý.
GET /reviews/statistics	reviews:read	Statistika recenzí e-shopu za období: počet, bez odpovědi, průměr, počet podle hvězdiček a po druzích.
GET /reviews/web-display	reviews:read	Blok recenzí na stránce produktu (skript na webu): zda je zapnutý, podpora platformy a nastavení.
GET /search-console/query	search-console:read	Search Console po dnech, dotazech, stránkách, zemích a zařízeních, se stránkováním a otiskem obsahu.
GET /search-console/status	search-console:read	Stav Search Console e-shopu: připojení, property, oprávnění, synchronizace a rozsah archivu.
GET /shipping/carriers	shipping:read	Připojení dopravci a profily, bez přístupových údajů.
GET /shipping/overview	shipping:read	Přehled expedice: k zabalení, čeká na předání, na cestě, chyby dopravce, dobírky, s rozpisem po e-shopech.
GET /shipping/packing-performance	shipping:read	Výkon balení podle lidí: počet zabalených objednávek, čas balení (průměr a medián), čas do zabalení a do předání, srovnání s týmem.
GET /shipping/pickups	shipping:read	Svoz po dopravcích: do kdy objednat, do kdy převzetí, co čeká na svoz a objednané svozy.
GET /shipping/returns	shipping:read	Zpětné zásilky (vratky) se stavem a reklamací, součty na cestě a nevyřízené po e-shopech.
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 /purchasing/advisor	purchasing:read	Nákupní návrh: co doobjednat a kolik, naléhavost, stav, minimum a odhad potřeby; globálně za jeden sklad.
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, po stránkách s úplným počtem.
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.

Stav zásob (inventory/stock a inventory/availability, rozsah inventory:read) říká, kolik zboží je; číselník dostupností (/availabilities, rozsah products:read) jsou pojmenované stavy, které e-shop ukazuje zákazníkovi u produktu, například Skladem nebo Na objednávku.

Statistika produktů

GET /inventory/product-statistics?market=sk&from=2026-01-01&to=2026-10-24 (rozsah inventory:read) vrátí v data produkty jednoho e-shopu: code, name, ean, active, stockQuantity a stockSource (jako inventory/stock), soldQty (prodané kusy, výdej k číslu objednávky) a s rozsahem claims:read i claimedQty (reklamované kusy), claimCases (počet případů), claimRatePercent (reklamované / prodané × 100, null bez prodeje), claimRateReliable (false pod 20 prodanými kusy), returnedQty (vrácené bez vady), claimedRestockedQty a claimedNotRestockedQty. meta.totals jsou za celý filtr a nesou navíc unmatchedClaimedQty a unmatchedReturnedQty, kusy případů, které se nepodařilo přiřadit k produktu.

Reklamovaný kus je položka případu typu reklamace nebo položka s důvodem vada či poškození při přepravě. Běžné odstoupení od smlouvy, vrácení a výměna bez vady jsou vrácené kusy. Zamítnutá položka se nepočítá, případ patří do období podle data založení. Bez rozsahu claims:read pole z reklamací v odpovědi nejsou (nejsou nulová) a filtr withClaimsOnly=true skončí chybou. Bez období platí aktuální rok, okno je nejvýše 366 dní; stránkuje se limit a cursor.

Číselník dostupností

GET /availabilities?market=cz vrátí v data položky číselníku jednoho e-shopu: id, name, description, onStockHours, deliveryHours, meaning (význam pro Google Nákupy: in_stock, backorder, preorder, out_of_stock), color, system, defaultRoles (výchozí role v e-shopu) a pairingRows (v kolika řádcích párování dostupností položka je). meta nese market, manageable a reason: zda se číselník dá v MitoOps měnit, a pokud ne, proč (PLATFORMA, BEZ_ROZSIRENIA, PROSTREDIE).

Změna číselníku přes REST nejde. Připravit ji umí jen asistent přes MCP, a to jako návrh s citlivým rozsahem availabilities:draft; do e-shopu ho zapíše až člověk schválením v aplikaci. Stav takového návrhu si přes REST přečtete: GET /availabilities/drafts/:draftId vrátí status (pending, writing, executed, partial, failed, rejected, expired), náhled a po schválení výsledek po položkách. Podrobně v MCP rozhraní.

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"

# Číselník dostupností e-shopu
curl -H "Authorization: Bearer <váš klíč>" \
  "https://<vaše adresa>/api/v1/availabilities?market=cz"

Související

• Přehled
• MCP rozhraní