REST sučelje

Provjerenoprovjereno 2026-09-20

Ukratko

REST sučelje nalazi se na /api/v1 i odgovara samo na GET. Sve ostalo dobiva 405 prije nego što poslužitelj uopće pogleda ključ.

Pristup se dokazuje zaglavljem: pogledajte Pregled.

Pozivi

Krajnja točka	Opseg	Što vraća
`GET /account/connection`	`stores:read`	Dijagnostika ove veze: aplikacija, tko je i kada odobrio pristup, odobrena i nedostajuća dopuštenja po područjima, trgovine i način upisa putem AI.
`GET /account/entitlements`	`account:read`	Tarifa klijenta, funkcije i ograničenja s trenutačnom iskorištenošću.
`GET /affiliate/articles/:key`	`affiliate:read`	Jedan članak pomoći s tekstom (HTML) na svim ili na jednom jeziku; varijable nisu umetnute.
`GET /affiliate/articles`	`affiliate:read`	Članci pomoći partnerskog portala: ključ, zadani/vlastiti, uključenost, redoslijed, stanje po jezicima (naziv, adresa, ispunjeno, isto kao zadano).
`GET /affiliate/campaigns/:campaignId`	`affiliate:read`	Jedna kampanja partnerskog programa.
`GET /affiliate/campaigns`	`affiliate:read`	Kampanje partnerskog programa web trgovine s nagradom, dostupnošću i brojevima.
`GET /affiliate/code-requests`	`affiliate:read`	Zahtjevi partnera za vlastiti kod za popust sa stanjem i razlogom; najprije oni koji čekaju.
`GET /affiliate/conversions/:conversionId`	`affiliate:read`	Detalj jedne konverzije: iznosi, provizija, stanje provizije s razlogom, status narudžbe u web trgovini, odobrenje, isplata.
`GET /affiliate/conversions`	`affiliate:read`	Konverzije partnerskog programa web trgovine: osnovica provizije i cijela narudžba s PDV-om, provizija, stanje provizije s razlogom, status narudžbe u web trgovini, veza na isplatu.
`GET /affiliate/discount-codes`	`affiliate:read`	Kodovi za popust partnera na web trgovini s brojem korištenja i prometom.
`GET /affiliate/documents/:key/content`	`affiliate:read`	Jedan pravni dokument programa s tekstom po jezicima (spremljeni tekst, javni tekst, verzija, otisci, izvor, PDF metapodaci) i otvorenim konceptima.
`GET /affiliate/documents`	`affiliate:read`	Dokumenti programa (uvjeti, sporazumi): pravila potvrde, potpisana kopija, privitak e-poruke, verzije po jezicima, spremnost i broj potvrda.
`GET /affiliate/email-templates`	`affiliate:read`	Predlošci e-poruka partnerima po jezicima (predmet, uključenost, s događajem i tijelo) i automatski prilozi e-poruke Račun odobren.
`GET /affiliate/links/generate`	`affiliate:read`	Praćena partnerska poveznica na početnu stranicu, proizvod ili kategoriju web trgovine kampanje; nakon klika zadržava dodjelu partneru.
`GET /affiliate/partners/:partnerId`	`affiliate:read`	Jedan partner programa s kampanjama koje ima na raspolaganju.
`GET /affiliate/partners`	`affiliate:read`	Partneri programa sa stanjem, učinkom i provizijama; kontakt samo s osobnim podacima.
`GET /affiliate/payouts`	`affiliate:read`	Isplate provizija partnerima sa stanjem; bez bankovnih podataka i podataka za naplatu.
`GET /affiliate/portal`	`affiliate:read`	Javni portal partnera: adrese po web trgovinama, otvorenost registracije s razlogom, vlastite domene, kontaktna osoba, izgled i stanje tekstova po jezicima.
`GET /affiliate/settings`	`affiliate:read`	Postavke partnerskog programa: provizije, klikovi, minimum isplate, dovođenje.
`GET /affiliate/signatures/:signatureId`	`affiliate:read`	Jedan elektronički potpis s potpisanim tekstom i snimkom vrijednosti; nepromjenjiv zapis, PDF se slaže u aplikaciji.
`GET /affiliate/signatures`	`affiliate:read`	Elektronički potpisani dokumenti partnera (tko, dokument, verzija, jezik, web trgovina, vrijeme, način, provjera, otisci, stanje) i partneri kojima potpis nedostaje; samo čitanje: potpis nastaje isključivo u portalu.
`GET /affiliate/statistics`	`affiliate:read`	Statistika partnerskog programa: kretanje po danima, izvori dodjele, ljestvica partnera.
`GET /affiliate/summary`	`affiliate:read`	Pregled partnerskog programa web trgovine za razdoblje: klikovi, konverzije, provizije, partneri.
`GET /affiliate/variables`	`affiliate:read`	Registar varijabli sadržaja i e-poruka partnerskog programa: kanonski nazivi, aliasi, vrsta, površine, primjer; neobavezna provjera teksta na nepoznate varijable.
`GET /analytics/advertising`	`reports:read`	Oglašavanje: troškovi, proračun, ROAS, udio troška u prihodu, CPA, prosječna narudžba i MER s usporedbom; Google Ads i Meta Ads, klikovi iz GA4, 6 mjeseci.
`GET /analytics/channels`	`analytics:read`	Raspodjela posjeta, narudžbi i prometa prema marketinškim kanalima.
`GET /analytics/comparison`	`reports:read`	Promet s usporedbom: promet, narudžbe, AOV, posjeti, CR i AI/LLM u odnosu na prethodno razdoblje ili godinu.
`GET /analytics/monthly`	`reports:read`	Promet, narudžbe i posjeti po mjesecima (najviše 24), na primjer godina na godinu.
`GET /analytics/order-coverage`	`analytics:read`	Pokrivenost narudžbi i prometa mjerenjem u analitici.
`GET /analytics/order-heatmap`	`reports:read`	Kada stižu narudžbe: dan u tjednu × sat, najjači dan i sat.
`GET /analytics/overview`	`analytics:read`	Posjete, narudžbe, promet, stopa konverzije i AI/LLM udio za razdoblje.
`GET /analytics/revenue-sources`	`reports:read`	Odakle je došao promet: kanali, zbrojevi za AI/LLM, MitoOps i Affiliate, akvizicija prema GA4.
`GET /analytics/seo`	`analytics:read`	Search Console: klikovi, prikazi, CTR i pozicija prema upitima ili stranicama.
`GET /automations/catalog`	`automations:read`	Katalog automatizacija: okidači, uvjeti, operatori, radnje, predlošci; catalogVersion za nacrte.
`GET /automations/:workflowId`	`automations:read`	Jedna automatizacija s DSL-om i rezultatom validacije.
`GET /automations`	`automations:read`	Automatizacije klijenta sa stanjem i opsegom web trgovina.
`GET /automations/options`	`automations:read`	Šifrarnik za polje automatizacije (statusi, dostave, plaćanja, predlošci, reklamacije…): value za DSL i naziv.
`GET /automations/:workflowId/runs`	`automations:read`	Povijest pokretanja jedne automatizacije.
`GET /automations/templates`	`automations:read`	Gotovi predlošci automatizacija s DSL-om.
`GET /chatbot/conversations/:sessionId`	`chatbot-conversations:read`	Prijepis jednog razgovora s web chatbotom, uključujući izvore odgovora bota.
`GET /chatbot/conversations`	`chatbot-conversations:read`	Razgovori kupaca s web chatbotom od posljednjeg aktivnog, s prvim pitanjem; kursor.
`GET /chatbot/outcomes`	`chatbot:read`	How web chatbot conversations ended: since when the outcome is measured, measured and unmeasured conversations, known and unknown outcome, resolved, unresolved, bot error and resolution rate with its denominator; N/A with a reason when the denominator is zero. Totals only.
`GET /chatbot/stats`	`chatbot:read`	Statistika web chatbota za razdoblje: lijevak oblačića, otvaranja, razgovori, rezultati, ocjene.
`GET /chatbot/topics`	`chatbot:read`	O čemu su bili razgovori: udjeli tema, proizvodi, vrsta početne stranice i kandidati za prazninu u znanju.
`GET /claims/config-drafts/:draftId`	`claims-settings:read`	Stanje nacrta promjene postavki reklamacija (čeka, zapisan, odbijen).
`GET /claims/configuration`	`claims-settings:read`	Postavke reklamacija: oznake, polja, povratni prijevoz, obrazac na web trgovini, vrste obrasca.
`GET /claims/:code`	`claims:read`	Jedan predmet sa stavkama i vezama: narudžba, odobrenje, povratna pošiljka, skladišno kretanje.
`GET /claims`	`claims:read`	Reklamacije i povrati jedne web trgovine od najnovijeg.
`GET /claims/refund-options`	`claims-settings:read`	Refunds: variable symbol source, refund coupon validity, coupon in the form, when the form asks for an account number.
`GET /claims/:code/refund-readiness`	`claims:read`	Claim before a refund: what the customer requests, masked account, variable symbol, mode and whether the claim can be deleted.
`GET /claims/refund-settings`	`claims-settings:read`	Povrati po reklamacijama: način, bankovni računi s prikladnošću za platni nalog (maskirani), zadani i ručni račun.
`GET /claims/routes`	`claims-settings:read`	Povratni prijevoz reklamacija: rute, adrese, profili prijevoznika s ID-jevima i podrškom za povrat, vrste slučajeva.
`GET /claims/settings`	`claims:read`	Procesi reklamacija s ID-ovima i nazivima (vrste, koraci, stanja, rokovi), oznake; postavke modula s opsegom claims-settings:read.
`GET /claims/statistics`	`claims:read`	Statistika reklamacija i povrata za razdoblje: brojevi, vremena rješavanja, vrste, ocjene, razlozi.
`GET /claims/templates`	`claims-settings:read`	Predlošci e-poruka (predmet, tekst, kada i šalju li se automatski) i zapisnika reklamacija.
`GET /content/articles`	`products:read`	Članci bloga web trgovine s adresom na webu i slikom za pregled.
`GET /coupons/activation-link`	`coupons:read`	Poveznica koja kupcu primjenjuje POSTOJEĆI kupon u košarici. Ne izrađuje kupon.
`GET /coupons/activation-status`	`coupons:read`	Može li se kupon na web trgovini koristiti putem aktivacijske poveznice: zrcalo kupona + stanje koda na webu.
`GET /coupons/capabilities`	`coupons:read`	Što platforma te web trgovine zna o kuponima. Pročitajte prije otvaranja.
`GET /coupons/:code`	`coupons:read`	Jedan kupon iz evidencije MitoOps. Kada ga u njoj nema, odgovor je „nije pronađeno“.
`GET /coupons`	`coupons:read`	Kuponi za popust web trgovine s vrstom i iznosom popusta, valjanošću i izvedenim stanjem.
`GET /customers/:customerKey`	`customers:read`	Jedan kupac iz imenika: identitet, web trgovine, LIFETIME i neobavezni PERIOD novac, raščlamba po web trgovini.
`GET /customers`	`customers:read`	Imenik kupaca: identitet (s maskiranjem PII), web trgovine, jezik, LIFETIME brojevi i promet po valutama; neobavezni filtar kupovne aktivnosti u razdoblju.
`GET /customers/performance`	`reports:read`	Kupci kao pseudonimi: broj narudžbi, promet, prva i posljednja narudžba, ponovna kupnja, LTV.
`GET /credit-notes`	`invoices:read`	Pretraživanje odobrenja.
`GET /documents`	`invoices:read`	Računovodstveni dokumenti jedne vrste (računi, predračuni, odobrenja) po stranicama sa životnim ciklusom, stanjem u izvoru, filtrom valjanosti i dostupnošću PDF-a.
`GET /documents/:documentType/:code/pdf`	`invoices:read`	PDF računa, predračuna ili odobrenja (base64 i SHA-256), isti bajtovi kao na zaslonu.
`GET /invoices/:invoiceCode`	`invoices:read`	Jedan račun sa stavkama, iznosima, odobrenjima i predračunima uz njega.
`GET /invoices`	`invoices:read`	Pretraživanje računa.
`GET /inventory/movements`	`inventory:read`	Povijest skladišnih kretanja: kada, što, za koliko, zašto i iz kojeg izvora.
`GET /inventory/availability`	`inventory:read`	Stanje zalihe za više stavki odjednom.
`GET /inventory/stock`	`inventory:read`	Stanje zalihe jedne stavke, uključujući izvor vrijednosti.
`GET /orders/:orderCode`	`orders:read`	Jedna spremljena narudžba, uključujući stavke.
`GET /orders`	`orders:read`	Spremljene narudžbe jedne web trgovine, od najnovije.
`GET /availabilities/drafts/:draftId`	`products:read`	Stanje nacrta izmjene šifrarnika dostupnosti: čeka odobrenje, zapisan s rezultatom, odbijen, istekao.
`GET /availabilities`	`products:read`	Šifrarnik dostupnosti web trgovine: naziv, opis, uskladištenje, dostava, značenje za Google, boja, zadana uloga.
`GET /catalog/category-content-drafts/:draftId`	`category-content:read`	Stanje prijedloga tekstova kategorija: čeka odobrenje, upisan, odbijen, istekao.
`GET /categories/:guid/content`	`category-content:read`	Tekstovi kategorije (gornji i donji opis, SEO naslov i opis) s otiskom i mogućnošću upisa.
`GET /categories`	`products:read`	Kategorije web trgovine s brojem proizvoda.
`GET /catalog/product-content-drafts/:draftId`	`product-content:read`	Stanje prijedloga tekstova proizvoda: čeka odobrenje, upisan s upozorenjima web trgovine, odbijen, istekao.
`GET /products/:code/content`	`product-content:read`	Tekstovi proizvoda iz web trgovine (opis, kratki opis, SEO naslov i opis) s otiskom i mogućnošću upisa.
`GET /product-content/policy`	`product-content:read`	Pravila sadržaja web trgovine bez poziva web trgovini: što ovaj pristup smije čitati i predlagati, koja polja platforma upisuje, način odobravanja i autonomni upis, ograničenja i otisci.
`GET /products/:code`	`products:read`	Jedan proizvod prema šifri, uključujući razvrstavanje i cijenu s kartice.
`GET /products`	`products:read`	Pretraživanje proizvoda prema nazivu, šifri, EAN-u ili PLU-u.
`GET /reports/financial-summary`	`reports:read`	Financijski sažetak razdoblja: promet, PDV, narudžbe, AOV; s pravima i nabava, bruto dobit, troškovi i rezultat.
`GET /sales/order-performance`	`reports:read`	Promet po narudžbama u EUR sa zbrojevima za cijelo razdoblje; s pravom i nabava, bruto dobit i marža po narudžbi.
`GET /sales/product-performance`	`reports:read`	Prodaja po proizvodima iz dokumenata; s pravom i nabavna cijena u trenutku prodaje i marža.
`GET /search-console/query`	`search-console:read`	Search Console po danima, upitima, stranicama, zemljama i uređajima, sa straničenjem i sažetkom sadržaja.
`GET /search-console/status`	`search-console:read`	Stanje Search Consolea trgovine: veza, svojstvo, dopuštenje, sinkronizacija i opseg arhiva.
`GET /shipping/carriers`	`shipping:read`	Povezane dostavne službe i njihovi profili, bez pristupnih podataka.
`GET /shipping/shipments/:shipmentId`	`shipping:read`	Jedna pošiljka sa svim događajima praćenja.
`GET /shipping/shipments`	`shipping:read`	Pošiljke jedne web trgovine s dostavnom službom, zemljom i vremenima predaje i dostave.
`GET /shipping/stats`	`shipping:read`	Statistike dostave prema dostavnim službama: brojevi, uspješnost, medijan i p90 vremena dostave, zemlje.
`GET /stores/integration-status`	`stores:read`	Stanje MitoOps koda na webu po web trgovinama: instalirano, verzija, moduli, spremnost kupona iz adrese.
`GET /stores`	`stores:read`	Popis web trgovina klijenta, uključujući njihov kod.
`GET /suppliers/:supplierId`	`purchasing:read`	Jedan dobavljač s ponudama proizvoda i troškovnim sastavnicama.
`GET /suppliers`	`purchasing:read`	Dobavljači klijenta s brojem ponuda i uparenih proizvoda.
`GET /webhooks/endpoints/:endpointId/deliveries`	`webhooks:read`	Dnevnik dostava jednog endpointa bez tijela.
`GET /webhooks/endpoints/:endpointId`	`webhooks:read`	Jedan webhook endpoint s brojem dostava koje čekaju.
`GET /webhooks/endpoints`	`webhooks:read`	Webhook endpointi klijenta bez tajni i stanje reda čekanja.
`GET /webhooks/events`	`webhooks:read`	Katalog događaja odlaznih webhookova, omotnica i potpis.

Adresa	Opseg	Što vraća
`GET /capabilities`	nije potreban	što ovaj ključ smije pozvati
`GET /openapi.json`	nije potreban	strojno čitljiv opis sučelja

GET /capabilities najbrži je način da saznate što ključ otvara: vraća točno ono što su mu opsezi dopustili, a ne cijeli katalog. Točni parametri i polja odgovora svakog poziva nalaze se u openapi.json.

Oblik odgovora

Svaki odgovor ima dva dijela: data i meta.

{
  "data": [ { "market": "sk", "name": "Moja web trgovina" } ],
  "meta": { "requestId": "…", "count": 1 }
}

meta.requestId je identifikator poziva. Ako nešto pođe po zlu, to je podatak koji podršci kaže o kojem je pozivu riječ.

Kod ispisa meta dodatno nosi:

Polje	Značenje
`count`	koliko je zapisa u ovom odgovoru
`hasMore`	`true`, kada sljedeća stranica postoji
`nextCursor`	vrijednost kojom tražite sljedeću stranicu; `null`, kada je nema

Kod sažetaka (statistike, pregled, financijski sažetak) cijeli je odgovor u data kao jedan objekt.

Straničenje

Sljedeću stranicu tražite tako da nextCursor iz odgovora pošaljete natrag u parametru cursor:

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

Tri stvari na kojima to počiva:

Ostali parametri moraju ostati isti. Kursor pripada upitu s kojim je nastao. S promijenjenom web trgovinom, razdobljem ili filtrom sučelje ga odbija (400): nastavak u redoslijedu koji više ne vrijedi tiho bi vratio nepovezani isječak.
Kraj prepoznajete prema hasMore, a ne prema broju. Odgovor može imati točno onoliko zapisa koliko ste tražili, a sljedeća stranica ipak postoji.
Nevažeći kursor je greška, a ne prazan rezultat. Prazan odgovor izgledao bi kao kraj podataka i izvoz bi se tiho skratio.

Kursorom se stranice narudžbe, dokumenti, katalog i pošiljke. Numeriranje stranica sučelje namjerno nema: kada između dva poziva pristigne zapis, „stranica 2“ pokazuje drugamo nego maloprije; kursor nosi posljednji viđeni zapis, pa se ništa ne ponavlja ni ne preskače.

Ispis i pretraživanje

Kod proizvoda, računa i odobrenja to su dva načina rada iste adrese:

Kako pozivate	Što dobivate
bez `query`	ispis po stranicama, od najnovijeg; može se straničiti i ograničiti razdobljem
s `query`	pretraživanje poredano prema podudarnosti; vraća najviše `limit` zapisa

Pretraživanje se ne stranici i ne ograničava razdobljem: redoslijed prema podudarnosti mijenja se između poziva i kursor nad njim preskakao bi zapise. Kombinacija query s cursor, from ili to zato završava kao 400, a ne kao tiho zanemaren filtar.

Za čitanje cijele evidencije koristite ispis bez query.

Razdoblje

Narudžbe, dokumenti, pošiljke, statistike, analitika i izvještaji mogu se ograničiti parametrima from i to u obliku YYYY-MM-DD.

Obje su granice uključene. to=2026-08-05 obuhvaća cijeli 5. kolovoza, a ne ponoć na njegovu početku.
Dan se uzima onako kako ga evidentira aplikacija: narudžbe u vremenskoj zoni web trgovine, pošiljke i izvještaji onako kako ih osoblje vidi na zaslonu.
Narudžbe se razvrstavaju prema datumu nastanka narudžbe, a pošiljke prema datumu nastanka pošiljke.
Računi i odobrenja prema datumu oporezivanja; kada ga dokument nema ispunjenog, prema datumu izdavanja. Koja je vrijednost razvrstala dokument, vidi se u polju businessDate.
Prodaja po proizvodima prema datumu dokumenta; ovdje je razdoblje obavezno.
Najdulje razdoblje je 366 dana. Dulje se odbija; dulju povijest prođite po godinama.
Obrnuto razdoblje je greška, a ne prazan rezultat: inače bi tipfeler izgledao kao razdoblje bez dokumenata.
Bez razdoblja pošiljke i statistike vraćaju posljednjih 30 dana, a analitika i financijski sažetak tekući mjesec. Odgovor razdoblje uvijek ispisuje.

Kod narudžbi ostaje i todayOnly. S from/to ne može se kombinirati: to su dva odgovora na isto pitanje i jedan bi od njih tiho pobijedio.

Što znače financijska polja

purchasePriceWithoutVat kod stavke narudžbe nabavna je cijena u trenutku narudžbe, onako kako ju je spremila web trgovina. To nije cijena s današnje kartice proizvoda: ona je u products/{code} kao purchasePrice.
cogs u financijskom sažetku nabava je robe za razdoblje iz svih narudžbi; null znači da nabavne cijene nisu poznate za dovoljno redaka (cogsCoverage). Tada se ne prikazuje ni bruto dobit: bolje ništa nego pogrešan broj.
grossProfit je promet bez PDV-a umanjen za nabavu robe, a grossMargin isto u postocima. resultAfterCosts je bruto dobit umanjena za dostavu i troškove tvrtke: menadžerska brojka, a ne računovodstvena dobit.
U prodaji po proizvodima purchaseCostWithoutVat nabavna je cijena u trenutku dokumenta prema uparivanju s katalogom; unmappedLines govori koliko se redaka nije uparilo.
Svi iznosi izvještaja i analitike su u EUR (polje currency), preračunati tečajem u trenutku sinkronizacije. Narudžbe i dokumenti nose vlastitu valutu.

Bez opsega purchase-prices:read ta polja u odgovoru ne postoje: nisu nula, nego nedostaju.

Vrijeme dostave

Statistike dostave (shipping/stats) mjere vrijeme od predaje dostavnoj službi do prvog događaja dostave iz događaja praćenja. Iz datuma narudžbe ne računa se ništa. Pošiljka koja nema obje točke ne ubraja se u medijan; koliko ih je ubrojeno, govori delivery.measured. Ista dva vremena nosi svaka pošiljka u poljima handedOverAt i deliveredAt.

deliveryRate je udio dostavljenih među onima čija je sudbina već završena (dostavljene, vraćene, neuspjele). Pošiljka na putu još nije ni uspjeh ni neuspjeh; otkazana pošiljka Vaša je radnja, a ne neuspjeh dostavne službe, i uopće se ne broji.

Stanje zaliha

inventory/stock vraća quantity i source: iz kojeg evidencijskog modela vrijednost potječe (varijante, bilanca web trgovine, kartica proizvoda). Kada web trgovina vodi bilancu, dostupni su i physical, available (dostupno za prodaju) i reserved (rezervirano u narudžbama); inače su null. Sučelje ne izmišlja nikakvo „stanje na zalihi“ koje aplikacija ne evidentira.

Stanje zaliha (inventory/stock i inventory/availability, opseg inventory:read) govori koliko robe ima; šifrarnik dostupnosti (/availabilities, opseg products:read) su imenovana stanja koja web trgovina prikazuje kupcu uz proizvod, na primjer Na zalihi ili Po narudžbi.

Šifrarnik dostupnosti

GET /availabilities?market=sk u data vraća stavke šifrarnika jedne web trgovine: id, name, description, onStockHours, deliveryHours, meaning (značenje za Google Shopping: in_stock, backorder, preorder, out_of_stock), color, system, defaultRoles (zadana uloga u web trgovini) i pairingRows (u koliko se redaka uparivanja dostupnosti stavka nalazi). meta nosi market, manageable i reason: može li se šifrarnik mijenjati u MitoOps i, ako ne može, zašto (PLATFORMA, BEZ_ROZSIRENIA, PROSTREDIE).

Promjena šifrarnika putem REST-a nije moguća. Pripremiti je može samo asistent putem MCP-a, i to kao nacrt s osjetljivim opsegom availabilities:draft; u web trgovinu upisuje ga tek osoba odobrenjem u aplikaciji. Stanje takvog nacrta čitate putem REST-a: GET /availabilities/drafts/:draftId vraća status (pending, writing, executed, partial, failed, rejected, expired), pregled i nakon odobrenja rezultat po stavkama. Detaljno u MCP sučelju.

Imenik kupaca

Kupci imaju dva različita čitanja, a njihovo miješanje znači čitati drugi broj od očekivanog:

/customers i /customers/{customerKey} (opseg customers:read) su imenik: ista projekcija koju osoblje vidi na zaslonu Kupci i koja ide u izvoz: identitet, web trgovine, zemlja, jezik, brojevi i datumi.
/customers/performance (opseg reports:read) je analitika nad sirovim narudžbama: kupac je samo pseudonim, a ime ni kontakt u njoj uopće nisu.

Izvana je market obavezan kod oba. Bez njega bi se čitalo preko svih web trgovina klijenta, dakle i onih koje pristupu ne pripadaju.

Tko vidi što

customers:read sam daje pseudonim (customerKey), web trgovine, zemlju, jezik, broj narudžbi i datume prve i posljednje narudžbe. Dodatno:

ime, tvrtka, e-pošta, telefon i marketinški spol samo s personal-data:read,
promet, prosječna narudžba i LTV samo s reports:read.

Polja za koja nemate opseg uklanjaju se, a ne poništavaju. null na mjestu e-pošte značio bi „kupac nema e-poštu“, što nije istina: ključ koji nedostaje znači „nemate pravo na njega“.

customerKey je SHA-256 normalizirane e-pošte. To je isti pseudonim koji nose dokumenti (customerEmailHash) i /customers/performance, pa se ta tri pogleda mogu povezati, a da se nigdje ne šalje e-pošta.

Cijeli životni vijek i razdoblje

Imenik ima neobavezni filtar purchaseFrom i purchaseTo (YYYY-MM-DD, obje granice uključene). Znači kupovnu aktivnost u razdoblju: kupac u tom intervalu ima barem jednu narudžbu. To nije filtar za datum prve ili posljednje kupnje.

S razdobljem se dodaju polja periodFrom, periodTo, periodOrdersCount i periodRevenueByCurrency uz vrijednosti za cijeli životni vijek (ordersCount, revenue, lifetimeRevenue, firstOrderAt, lastOrderAt), a nikada umjesto njih. Vrijednosti za cijeli životni vijek razdobljem se ne mijenjaju.

Novac je uvijek po valutama

Promet, prosječna narudžba i LTV su polje po valutama, nikada jedan broj. Kupac s narudžbama u EUR i u CZK ima dvije stavke; zbrajanje u jedan skalar značilo bi pribrojiti krune eurima. Isto vrijedi za /customers/performance: redak je par (kupac, valuta), a zbrojevi filtra su totals.revenueByCurrency.

Jezik i marketinški spol

language je jezik web trgovine na kojoj je kupac naručio (source: "store_locale"), a ne njegov vlastiti odabir. Aplikacija danas ne evidentira izričitu jezičnu preferenciju kupca.
marketingGender (male / female / unknown) je procjena iz imena, a ne podatak koji bi kupac naveo. Podrijetlo je uvijek u genderSource (danas isključivo name_inference ili unknown), a pouzdanost u genderConfidence. Poslovni kupac nema to polje. Tko ga prikazuje dalje, treba reći „procjena prema imenu“, nikada „kupac je naveo“. Ide iza personal-data:read jednako kao i samo ime.

Web trgovina

Pozivi nad podacima jedne web trgovine traže njezin kod u parametru market. Popis kodova daje GET /stores.

Kada ključ za tu web trgovinu nema opseg, odgovor je 403, a ne prazan popis. Prazan popis ne bi se mogao razlikovati od web trgovine bez narudžbi. Zapis druge web trgovine (na primjer pošiljka) je 404.

Greške

Odgovor s greškom uvijek ima isti oblik i nosi kod. Popis statusa i kodova nalazi se u Pregledu.

Primjeri

# Narudžbe za razdoblje, po stranicama
curl -H "Authorization: Bearer <vaš ključ>" \
  "https://<vaša adresa>/api/v1/orders?market=sk&from=2026-08-01&to=2026-08-31&limit=50"

# Statistike dostave za kolovoz
curl -H "Authorization: Bearer <vaš ključ>" \
  "https://<vaša adresa>/api/v1/shipping/stats?market=sk&from=2026-08-01&to=2026-08-31"

# Pošiljke jedne dostavne službe za kolovoz
curl -H "Authorization: Bearer <vaš ključ>" \
  "https://<vaša adresa>/api/v1/shipping/shipments?market=sk&from=2026-08-01&to=2026-08-31&carrier=dhl"

# Financijski sažetak kolovoza (s pravom na nabavne cijene i bruto dobit)
curl -H "Authorization: Bearer <vaš ključ>" \
  "https://<vaša adresa>/api/v1/reports/financial-summary?market=sk&from=2026-08-01&to=2026-08-31"

# Stanje zalihe triju stavki
curl -H "Authorization: Bearer <vaš ključ>" \
  "https://<vaša adresa>/api/v1/inventory/availability?market=sk&codes=A100,A101,A102"

# Šifrarnik dostupnosti web trgovine
curl -H "Authorization: Bearer <vaš ključ>" \
  "https://<vaša adresa>/api/v1/availabilities?market=sk"