REST rozhranie

Overenéoverené 2026-09-03

V skratke

REST rozhranie je na /api/v1 a odpovedá iba na GET. Čokoľvek iné dostane 405 skôr, než sa server pozrie na kľúč.

Prístup sa preukazuje hlavičkou — viď Prehľad.

Volania

Adresa	Rozsah	Čo vráti
`GET /account/entitlements`	`account:read`	Tarifa klienta, funkcie a limity s aktuálnym využitím.
`GET /affiliate/articles/:key`	`affiliate:read`	Jeden článok nápovedy so znením (HTML) vo všetkých alebo v jednom jazyku; premenné nedosadené.
`GET /affiliate/articles`	`affiliate:read`	Články nápovedy partnerského portálu: kľúč, predvolený/vlastný, zapnutie, poradie, stav po jazykoch (názov, adresa, vyplnené, totožné s predvoleným).
`GET /affiliate/campaigns/:campaignId`	`affiliate:read`	Jedna kampaň partnerského programu.
`GET /affiliate/campaigns`	`affiliate:read`	Kampane partnerského programu e-shopu s odmenou, dostupnosťou a počtami.
`GET /affiliate/code-requests`	`affiliate:read`	Žiadosti partnerov o vlastný zľavový kód so stavom a dôvodom; čakajúce prvé.
`GET /affiliate/conversions`	`affiliate:read`	Konverzie partnerského programu e-shopu s províziou, stavom a väzbou na výplatu.
`GET /affiliate/discount-codes`	`affiliate:read`	Zľavové kódy partnerov na e-shope s počtom použití a obratom.
`GET /affiliate/documents`	`affiliate:read`	Dokumenty programu (podmienky, dohody): politika potvrdenia, podpísaná kópia, príloha e-mailu, verzie po jazykoch, pripravenosť a počty potvrdení.
`GET /affiliate/email-templates`	`affiliate:read`	Šablóny e-mailov partnerom po jazykoch (predmet, zapnutie, s udalosťou aj telo) a automatické prílohy e-mailu Účet schválený.
`GET /affiliate/links/generate`	`affiliate:read`	Sledovaný partnerský odkaz na domov, produkt alebo kategóriu e-shopu kampane; po kliknutí zachová priradenie partnerovi.
`GET /affiliate/partners/:partnerId`	`affiliate:read`	Jeden partner programu s kampaňami, ktoré má k dispozícii.
`GET /affiliate/partners`	`affiliate:read`	Partneri programu so stavom, výkonom a províziami; kontakt iba s osobnými údajmi.
`GET /affiliate/payouts`	`affiliate:read`	Výplaty provízií partnerom so stavom; bez bankových a fakturačných údajov.
`GET /affiliate/portal`	`affiliate:read`	Verejný portál partnera: adresy po e-shopoch, otvorenosť registrácie s dôvodom, vlastné domény, kontaktná osoba, vzhľad a stav textov po jazykoch.
`GET /affiliate/settings`	`affiliate:read`	Nastavenie partnerského programu: provízie, kliky, minimum výplaty, privedenie.
`GET /affiliate/statistics`	`affiliate:read`	Štatistika partnerského programu: vývoj po dňoch, zdroje priradenia, rebríček partnerov.
`GET /affiliate/summary`	`affiliate:read`	Prehľad partnerského programu e-shopu za obdobie: kliky, konverzie, provízie, partneri.
`GET /analytics/channels`	`analytics:read`	Rozloženie návštev, objednávok a obratu podľa marketingových kanálov.
`GET /analytics/order-coverage`	`analytics:read`	Pokrytie objednávok a obratu meraním v analytike.
`GET /analytics/overview`	`analytics:read`	Návštevy, objednávky, obrat, konverzný pomer a AI/LLM podiel za obdobie.
`GET /analytics/seo`	`analytics:read`	Search Console: kliknutia, zobrazenia, CTR a pozícia podľa dopytov alebo stránok.
`GET /automations/catalog`	`automations:read`	Katalóg automatizácií: spúšťače, podmienky, operátory, akcie, šablóny; catalogVersion pre návrhy.
`GET /automations/:workflowId`	`automations:read`	Jedna automatizácia s DSL a výsledkom validácie.
`GET /automations`	`automations:read`	Automatizácie klienta so stavom a rozsahom e-shopov.
`GET /automations/:workflowId/runs`	`automations:read`	História behov jednej automatizácie.
`GET /automations/templates`	`automations:read`	Hotové vzory automatizácií s DSL.
`GET /claims/:code`	`claims:read`	Jeden prípad s položkami a väzbami: objednávka, dobropis, spätná zásielka, skladový pohyb.
`GET /claims`	`claims:read`	Reklamácie a vrátenia jedného e-shopu od najnovšieho.
`GET /claims/settings`	`claims:read`	Procesy reklamácií (typy, kroky, stavy, lehoty); nastavenia modulu iba s právom na ne.
`GET /claims/statistics`	`claims:read`	Štatistika reklamácií a vrátení za obdobie: počty, časy vybavenia, typy, hodnotenia, dôvody.
`GET /content/articles`	`products:read`	Články blogu e-shopu s adresou na webe a náhľadovým obrázkom.
`GET /coupons/activation-link`	`coupons:read`	Odkaz, ktorý zákazníkovi uplatní EXISTUJÚCI kupón v košíku. Kupón nevytvára.
`GET /coupons/activation-status`	`coupons:read`	Dá sa kupón na e-shope použiť cez aktivačný odkaz: zrkadlo kupónu + stav kódu na webe.
`GET /coupons/capabilities`	`coupons:read`	Čo o kupónoch vie platforma daného e-shopu. Čítajte pred zakladaním.
`GET /coupons/:code`	`coupons:read`	Jeden kupón z evidencie MitoOps. Keď v nej nie je, odpoveď je „nenašlo sa“.
`GET /coupons`	`coupons:read`	Zľavové kupóny e-shopu s typom a výškou zľavy, platnosťou a odvodeným stavom.
`GET /customers/:customerKey`	`customers:read`	Jeden zákazník z adresára — identita, e-shopy, LIFETIME aj voliteľné PERIOD peniaze, rozpis podľa e-shopu.
`GET /customers`	`customers:read`	Adresár zákazníkov: identita (s PII maskovaním), e-shopy, jazyk, LIFETIME počty a obrat po menách; voliteľný filter nákupnej aktivity v období.
`GET /customers/performance`	`reports:read`	Zákazníci ako pseudonymy: počet objednávok, obrat, prvá a posledná objednávka, opakovaný nákup, LTV.
`GET /credit-notes`	`invoices:read`	Hľadanie v dobropisoch.
`GET /invoices/:invoiceCode`	`invoices:read`	Jedna faktúra s položkami, sumami, dobropismi a zálohovými faktúrami k nej.
`GET /invoices`	`invoices:read`	Hľadanie vo faktúrach.
`GET /inventory/movements`	`inventory:read`	História skladových pohybov: kedy, čo, o koľko, prečo a z akého zdroja.
`GET /inventory/availability`	`inventory:read`	Stav zásoby pre viac položiek naraz.
`GET /inventory/stock`	`inventory:read`	Stav zásoby jednej položky aj so zdrojom hodnoty.
`GET /orders/:orderCode`	`orders:read`	Jedna uložená objednávka vrátane položiek.
`GET /orders`	`orders:read`	Uložené objednávky jedného e-shopu, od najnovšej.
`GET /categories`	`products:read`	Kategórie e-shopu s počtom produktov.
`GET /products/:code`	`products:read`	Jeden produkt podľa kódu vrátane zaradenia a ceny z karty.
`GET /products`	`products:read`	Hľadanie produktov podľa názvu, kódu, EAN alebo PLU.
`GET /reports/financial-summary`	`reports:read`	Finančný súhrn obdobia: obrat, DPH, objednávky, AOV; s právami aj nákup, hrubý zisk, náklady a výsledok.
`GET /sales/order-performance`	`reports:read`	Obrat po objednávkach v EUR so súčtami za celé obdobie; s právom aj nákup, hrubý zisk a marža na objednávku.
`GET /sales/product-performance`	`reports:read`	Predaje po produktoch z dokladov; s právom aj nákupná cena v čase predaja a marža.
`GET /shipping/carriers`	`shipping:read`	Pripojení dopravcovia a ich profily, bez prístupových údajov.
`GET /shipping/shipments/:shipmentId`	`shipping:read`	Jedna zásielka so všetkými udalosťami sledovania.
`GET /shipping/shipments`	`shipping:read`	Zásielky jedného e-shopu s dopravcom, krajinou a časmi odovzdania a doručenia.
`GET /shipping/stats`	`shipping:read`	Štatistiky doručovania podľa dopravcov: počty, úspešnosť, medián a p90 času doručenia, krajiny.
`GET /stores/integration-status`	`stores:read`	Stav MitoOps kódu na webe po e-shopoch: nainštalované, verzia, moduly, pripravenosť kupónu z adresy.
`GET /stores`	`stores:read`	Zoznam e-shopov klienta aj s ich kódom.
`GET /suppliers/:supplierId`	`purchasing:read`	Jeden dodávateľ s ponukami produktov a nákladovými zložkami.
`GET /suppliers`	`purchasing:read`	Dodávatelia klienta s počtom ponúk a napárovaných produktov.
`GET /webhooks/endpoints/:endpointId/deliveries`	`webhooks:read`	Denník doručení jedného endpointu bez tela.
`GET /webhooks/endpoints/:endpointId`	`webhooks:read`	Jeden webhook endpoint s počtom čakajúcich doručení.
`GET /webhooks/endpoints`	`webhooks:read`	Webhook endpointy klienta bez tajomstiev a stav fronty.
`GET /webhooks/events`	`webhooks:read`	Katalóg udalostí odchádzajúcich webhookov, obálka a podpis.

Adresa	Rozsah	Čo vráti
`GET /capabilities`	—	čo tento kľúč smie zavolať
`GET /openapi.json`	—	strojovo čitateľný popis rozhrania

GET /capabilities je najrýchlejší spôsob, ako zistiť, čo kľúč otvára — vracia presne to, čo mu rozsahy dovolili, nie celý katalóg. Presné parametre a polia odpovede každého volania sú v openapi.json.

Tvar odpovede

Každá odpoveď má dve časti: data a meta.

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

meta.requestId je identifikátor volania. Ak sa niečo pokazí, je to údaj, ktorý podpore povie, o ktoré volanie išlo.

Pri výpisoch nesie meta navyše:

Pole	Význam
`count`	koľko záznamov je v tejto odpovedi
`hasMore`	`true`, keď ďalšia strana existuje
`nextCursor`	hodnota, ktorou si o ďalšiu stranu poviete; `null`, keď žiadna nie je

Pri súhrnoch (štatistiky, prehľad, finančný súhrn) je celá odpoveď v data ako jeden objekt.

Stránkovanie

Ďalšiu stranu si vypýtate tak, že nextCursor z odpovede pošlete späť v parametri cursor:

curl -H "Authorization: Bearer <váš kľúč>" \
  "https://<vaša adresa>/api/v1/shipping/shipments?market=sk&from=2026-08-01&to=2026-08-31&limit=50&cursor=<nextCursor>"

Tri veci, na ktorých to stojí:

Ostatné parametre musia zostať rovnaké. Kurzor patrí k dopytu, s ktorým vznikol. So zmeneným e-shopom, obdobím alebo filtrom ho rozhranie odmietne (400) — pokračovať v poradí, ktoré už neplatí, by ticho vrátilo nesúvislý výrez.
Koniec spoznáte podľa hasMore, nie podľa počtu. Odpoveď môže mať presne toľko záznamov, koľko ste pýtali, a ďalšia strana napriek tomu existovať.
Neplatný kurzor je chyba, nie prázdny výsledok. Prázdna odpoveď by vyzerala ako koniec dát a export by sa ticho skrátil.

Kurzorom sa stránkujú objednávky, doklady, katalóg a zásielky. Číslovanie strán rozhranie nemá zámerne: keď medzi dvoma volaniami pribudne záznam, „strana 2“ ukazuje inam než pred chvíľou; kurzor nesie posledný videný záznam, takže sa nič nezopakuje ani nevynechá.

Výpis a hľadanie

Pri produktoch, faktúrach a dobropisoch sú to dva režimy jednej adresy:

Ako voláte	Čo dostanete
bez `query`	výpis po stranách, od najnovšieho; dá sa stránkovať a obmedziť obdobím
s `query`	hľadanie zoradené podľa zhody; vráti najviac `limit` záznamov

Hľadanie sa nestránkuje a neobmedzuje obdobím — poradie podľa zhody sa medzi volaniami mení a kurzor nad ním by záznamy preskakoval. Kombinácia query s cursor, from alebo to preto skončí ako 400, nie ako ticho ignorovaný filter.

Na vyčítanie celej evidencie použite výpis bez query.

Obdobie

Objednávky, doklady, zásielky, štatistiky, analytika aj výkazy sa dajú obmedziť parametrami from a to v tvare YYYY-MM-DD.

Obe hranice sú vrátane. to=2026-08-05 zahŕňa celý 5. august, nie polnoc na jeho začiatku.
Deň sa berie tak, ako ho eviduje aplikácia — objednávky v pásme e-shopu, zásielky a výkazy tak, ako ich vidí obsluha na obrazovke.
Objednávky sa radia podľa dátumu vzniku objednávky, zásielky podľa dátumu vzniku zásielky.
Faktúry a dobropisy podľa daňového dátumu; keď ho doklad nemá vyplnený, podľa dátumu vystavenia. Ktorá hodnota doklad zaradila, vidno v poli businessDate.
Predaje po produktoch podľa dátumu dokladu; tu je obdobie povinné.
Najdlhšie obdobie je 366 dní. Dlhšie sa odmietne; dlhšiu históriu prejdite po rokoch.
Obrátené obdobie je chyba, nie prázdny výsledok — inak by preklep vyzeral ako obdobie bez dokladov.
Bez obdobia vrátia zásielky a štatistiky posledných 30 dní, analytika a finančný súhrn aktuálny mesiac. Odpoveď obdobie vždy vypíše.

Pri objednávkach zostáva aj todayOnly. S from/to sa nedá spojiť: sú to dve odpovede na tú istú otázku a jedna z nich by ticho vyhrala.

Čo znamenajú finančné polia

purchasePriceWithoutVat pri položke objednávky je nákupná cena v čase objednávky, tak ako ju uložil e-shop. Nie je to cena z dnešnej karty produktu — tá je v products/{code} ako purchasePrice.
cogs vo finančnom súhrne je nákup tovaru za obdobie zo všetkých objednávok; null znamená, že nákupné ceny nie sú známe pre dosť riadkov (cogsCoverage). Vtedy sa neukáže ani hrubý zisk — radšej nič než nesprávne číslo.
grossProfit je obrat bez DPH mínus nákup tovaru, grossMargin to isté v percentách. resultAfterCosts je hrubý zisk mínus doprava mínus náklady firmy — manažérske číslo, nie účtovný zisk.
V predajoch po produktoch je purchaseCostWithoutVat nákupná cena v čase dokladu podľa spárovania s katalógom; unmappedLines hovorí, koľko riadkov sa nespárovalo.
Všetky sumy výkazov a analytiky sú v EUR (pole currency), prepočítané kurzom v čase synchronizácie. Objednávky a doklady nesú vlastnú menu.

Bez rozsahu purchase-prices:read tieto polia v odpovedi nie sú — nie sú nulové, chýbajú.

Čas doručenia

Štatistiky doručovania (shipping/stats) merajú čas od odovzdania dopravcovi po prvú udalosť doručenia z udalostí sledovania. Z dátumu objednávky sa nepočíta nič. Zásielka, ktorá nemá oba body, sa do mediánu nezapočíta; koľko sa ich započítalo, hovorí delivery.measured. Tie isté dva časy nesie každá zásielka v poliach handedOverAt a deliveredAt.

deliveryRate je podiel doručených z tých, ktorých osud sa už skončil (doručené, vrátené, chybné). Zásielka na ceste ešte nie je ani úspech, ani neúspech; zrušená zásielka je váš úkon, nie zlyhanie dopravcu, a neráta sa vôbec.

Stav zásob

inventory/stock vracia quantity a source — z ktorého evidenčného modelu hodnota pochádza (varianty, bilancia e-shopu, karta produktu). Keď e-shop vedie bilanciu, sú k dispozícii aj physical, available (dostupné na predaj) a reserved (rezervované v objednávkach); inak sú null. Rozhranie nevymýšľa žiadny „stav na sklade“, ktorý aplikácia neeviduje.

Adresár zákazníkov

Zákazníci majú dve rôzne čítania a mýliť si ich znamená čítať iné číslo, než čakáte:

/customers a /customers/{customerKey} (rozsah customers:read) sú adresár: tá istá projekcia, akú vidí obsluha na obrazovke Zákazníci a aká ide do exportu — identita, e-shopy, krajina, jazyk, počty a dátumy.
/customers/performance (rozsah reports:read) je analytika nad surovými objednávkami: zákazník je iba pseudonym, meno ani kontakt v nej nie sú vôbec.

Zvonku je market povinný pri oboch. Bez neho by sa čítalo cez všetky e-shopy klienta, teda aj cez tie, ktoré prístupu nepatria.

Kto uvidí čo

customers:read sám vydá pseudonym (customerKey), e-shopy, krajinu, jazyk, počty objednávok a dátumy prvej a poslednej objednávky. Navyše:

meno, firma, e-mail, telefón a marketingové pohlavie iba s personal-data:read,
obrat, priemerná objednávka a LTV iba s reports:read.

Polia, na ktoré nemáte rozsah, sa odstránia, nie vynulujú. null na mieste e-mailu by znamenalo „zákazník e-mail nemá“, čo nie je pravda — chýbajúci kľúč znamená „nemáte naň právo“.

customerKey je SHA-256 normalizovaného e-mailu. Je to ten istý pseudonym, aký nesú doklady (customerEmailHash) aj /customers/performance, takže sa tie tri pohľady dajú spojiť bez toho, aby sa niekde posielal e-mail.

Celý život verzus obdobie

Adresár má voliteľný filter purchaseFrom a purchaseTo (YYYY-MM-DD, obe hranice vrátane). Znamená nákupnú aktivitu v období: zákazník má v tom intervale aspoň jednu objednávku. Nie je to filter na dátum prvého alebo posledného nákupu.

S obdobím pribudnú polia periodFrom, periodTo, periodOrdersCount a periodRevenueByCurrency vedľa celoživotných (ordersCount, revenue, lifetimeRevenue, firstOrderAt, lastOrderAt) — nikdy namiesto nich. Celoživotné hodnoty sa obdobím nemenia.

Peniaze sú vždy po menách

Obrat, priemerná objednávka a LTV sú pole po menách, nikdy jedno číslo. Zákazník s objednávkami v EUR aj v CZK má dve položky; sčítať ich do jedného skalára by znamenalo pripočítať koruny k eurám. To isté platí pre /customers/performance: riadok je dvojica (zákazník, mena) a súčty filtra sú totals.revenueByCurrency.

Jazyk a marketingové pohlavie

language je jazyk e-shopu, na ktorom zákazník objednal (source: "store_locale"), nie jeho vlastná voľba. Aplikácia dnes explicitnú jazykovú preferenciu zákazníka neeviduje.
marketingGender (male / female / unknown) je odhad z krstného mena, nie údaj, ktorý by zákazník uviedol. Pôvod je vždy v genderSource — dnes výhradne name_inference alebo unknown — a spoľahlivosť v genderConfidence. Firemný zákazník pole nemá. Kto ho zobrazuje ďalej, má hovoriť „odhad podľa mena“, nikdy „zákazník uviedol“. Ide za personal-data:read rovnako ako meno samo.

E-shop

Volania nad údajmi jedného e-shopu si vypýtajú jeho kód v parametri market. Zoznam kódov vydá GET /stores.

Keď kľúč na daný e-shop nemá rozsah, odpoveď je 403 — nie prázdny zoznam. Prázdny zoznam by sa nedal odlíšiť od e-shopu bez objednávok. Záznam iného e-shopu (napríklad zásielka) je 404.

Chyby

Chybová odpoveď má vždy rovnaký tvar a nesie kód. Zoznam stavov a kódov je v Prehľade.

Príklady

# Objednávky za obdobie, po stranách
curl -H "Authorization: Bearer <váš kľúč>" \
  "https://<vaša adresa>/api/v1/orders?market=sk&from=2026-08-01&to=2026-08-31&limit=50"

# Štatistiky doručovania za august
curl -H "Authorization: Bearer <váš kľúč>" \
  "https://<vaša adresa>/api/v1/shipping/stats?market=sk&from=2026-08-01&to=2026-08-31"

# Zásielky jedného dopravcu za august
curl -H "Authorization: Bearer <váš kľúč>" \
  "https://<vaša adresa>/api/v1/shipping/shipments?market=sk&from=2026-08-01&to=2026-08-31&carrier=dhl"

# Finančný súhrn augusta (s právom na nákupné ceny aj hrubý zisk)
curl -H "Authorization: Bearer <váš kľúč>" \
  "https://<vaša adresa>/api/v1/reports/financial-summary?market=sk&from=2026-08-01&to=2026-08-31"

# Stav zásoby troch položiek
curl -H "Authorization: Bearer <váš kľúč>" \
  "https://<vaša adresa>/api/v1/inventory/availability?market=sk&codes=A100,A101,A102"