Interfața REST

Pe scurt

Interfața REST se află la /api/v1 și răspunde doar la GET. Orice altceva primește 405 înainte ca serverul să se uite la cheie.

Accesul se dovedește prin antet; consultați Prezentare.

Apeluri

Endpoint	Domeniu	Ce returnează
GET /account/connection	stores:read	Diagnosticul acestei conexiuni: aplicația, cine și când a acordat accesul, permisiunile acordate și lipsă pe domenii, magazinele și modul de scriere prin AI.
GET /account/entitlements	account:read	Tariful clientului, funcțiile și limitele cu utilizarea actuală.
GET /affiliate/articles/:key	affiliate:read	Un articol de ajutor cu formularea (HTML) în toate limbile sau într-una singură; variabilele necompletate.
GET /affiliate/articles	affiliate:read	Articolele de ajutor ale portalului partenerilor: cheie, implicit/propriu, activare, ordine, stare pe limbi (titlu, adresă, completat, identic cu cel implicit).
GET /affiliate/campaigns/:campaignId	affiliate:read	O campanie a programului de parteneriat.
GET /affiliate/campaigns	affiliate:read	Campaniile programului de parteneriat ale magazinului online, cu recompensă, disponibilitate și numere.
GET /affiliate/code-requests	affiliate:read	Cererile partenerilor pentru un cod de reducere propriu, cu stare și motiv; cele în așteptare primele.
GET /affiliate/conversions/:conversionId	affiliate:read	Detaliul unei conversii: sume, comision, starea comisionului cu motiv, starea comenzii în magazinul online, notă de credit, plată.
GET /affiliate/conversions	affiliate:read	Conversiile programului de parteneriat ale magazinului online: baza comisionului și întreaga comandă cu TVA, comision, starea comisionului cu motiv, starea comenzii în magazinul online, legătura cu plata.
GET /affiliate/discount-codes	affiliate:read	Codurile de reducere ale partenerilor în magazinul online, cu numărul de utilizări și cifra de afaceri.
GET /affiliate/documents/:key/content	affiliate:read	Un document juridic al programului, cu formularea pe limbi (text salvat, formulare publică, versiune, amprente, sursă, metadate PDF) și ciornele deschise.
GET /affiliate/documents	affiliate:read	Documentele programului (condiții, acorduri): politica de confirmare, copia semnată, anexa la e-mail, versiunile pe limbi, pregătirea și numărul de confirmări.
GET /affiliate/email-templates	affiliate:read	Șabloanele e-mailurilor către parteneri pe limbi (subiect, activare, cu eveniment și corpul) și anexele automate ale e-mailului Cont aprobat.
GET /affiliate/links/generate	affiliate:read	Un link de partener urmărit către pagina principală, un produs sau o categorie a magazinului online al campaniei; după clic păstrează atribuirea către partener.
GET /affiliate/partners/:partnerId	affiliate:read	Un partener al programului, cu campaniile pe care le are la dispoziție.
GET /affiliate/partners	affiliate:read	Partenerii programului cu stare, performanță și comisioane; contactul doar cu date personale.
GET /affiliate/payouts	affiliate:read	Plățile comisioanelor către parteneri, cu stare; fără date bancare și de facturare.
GET /affiliate/portal	affiliate:read	Portalul public al partenerului: adresele pe magazine online, deschiderea înregistrării cu motiv, domenii proprii, persoana de contact, aspectul și starea textelor pe limbi.
GET /affiliate/settings	affiliate:read	Setarea programului de parteneriat: comisioane, clicuri, minimul plății, recomandare.
GET /affiliate/signatures/:signatureId	affiliate:read	O semnătură electronică, cu formularea semnată și instantaneul valorilor; înregistrare nemodificabilă, PDF-ul se compune în aplicație.
GET /affiliate/signatures	affiliate:read	Documentele semnate electronic de parteneri (cine, document, versiune, limbă, magazin online, oră, mod, verificare, amprente, stare) și partenerii cărora le lipsește semnătura; doar citire, semnătura apare exclusiv în portal.
GET /affiliate/statistics	affiliate:read	Statistica programului de parteneriat: evoluția pe zile, sursele atribuirii, clasamentul partenerilor.
GET /affiliate/summary	affiliate:read	Prezentarea programului de parteneriat al magazinului online pentru o perioadă: clicuri, conversii, comisioane, parteneri.
GET /affiliate/variables	affiliate:read	Registrul variabilelor de conținut și de e-mail ale programului de parteneriat: nume canonice, aliasuri, tip, suprafețe, exemplu; verificare opțională a textului pentru variabile necunoscute.
GET /analytics/advertising	reports:read	Publicitate: cheltuieli, buget, ROAS, PNO, CPA, valoarea medie a comenzii și MER cu comparație; Google Ads și Meta Ads, clicuri din GA4, 6 luni.
GET /analytics/channels	analytics:read	Repartizarea vizitelor, comenzilor și cifrei de afaceri pe canale de marketing.
GET /analytics/comparison	reports:read	Cifra de afaceri comparată: cifră de afaceri, comenzi, AOV, vizite, CR și AI/LLM față de perioada anterioară sau anul trecut.
GET /analytics/monthly	reports:read	Cifra de afaceri, comenzi și vizite pe luni (cel mult 24), de exemplu an la an.
GET /analytics/order-coverage	analytics:read	Acoperirea comenzilor și a cifrei de afaceri prin măsurarea din analitică.
GET /analytics/order-heatmap	reports:read	Când vin comenzile: ziua săptămânii × ora, cea mai puternică zi și oră.
GET /analytics/overview	analytics:read	Vizite, comenzi, cifră de afaceri, rata de conversie și ponderea AI/LLM pentru o perioadă.
GET /analytics/revenue-sources	reports:read	De unde a venit cifra de afaceri: canale, totaluri AI/LLM, MitoOps și Affiliate, achiziție după GA4.
GET /analytics/seo	analytics:read	Search Console: clicuri, afișări, CTR și poziție după interogări sau pagini.
GET /automations/catalog	automations:read	Catalogul automatizărilor: declanșatori, condiții, operatori, acțiuni, șabloane; catalogVersion pentru propuneri.
GET /automations/:workflowId	automations:read	O automatizare, cu DSL și rezultatul validării.
GET /automations	automations:read	Automatizările clientului, cu stare și domeniul magazinelor online.
GET /automations/options	automations:read	Nomenclatorul pentru un câmp al automatizării (stări, transporturi, plăți, șabloane, reclamații…): value pentru DSL și denumire.
GET /automations/:workflowId/runs	automations:read	Istoricul rulărilor unei automatizări.
GET /automations/templates	automations:read	Șabloane gata făcute de automatizări, cu DSL.
GET /chatbot/conversations/:sessionId	chatbot-conversations:read	Transcrierea unei conversații cu chatbotul web, inclusiv sursele răspunsurilor botului.
GET /chatbot/conversations	chatbot-conversations:read	Conversațiile clienților cu chatbotul web, de la cea activă cel mai recent, cu prima întrebare; cursor.
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	Statistica chatbotului web pentru o perioadă: pâlnia bulei, deschideri, conversații, rezultate, evaluări.
GET /chatbot/topics	chatbot:read	Despre ce au fost conversațiile: ponderile subiectelor, produse, tipul paginii de început și candidați pentru o lacună în cunoștințe.
GET /claims/config-drafts/:draftId	claims-settings:read	Starea propunerii de modificare a setărilor reclamațiilor (în așteptare, scrisă, respinsă).
GET /claims/configuration	claims-settings:read	Setările reclamațiilor: etichete, câmpuri, transport retur, formularul din magazinul online, tipurile formularului.
GET /claims/:code	claims:read	Un caz cu articole și legături: comandă, notă de credit, colet retur, mișcare de stoc.
GET /claims	claims:read	Reclamațiile și retururile unui magazin online, de la cea mai nouă.
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	Rambursări pentru reclamații: mod, conturi bancare cu eligibilitate pentru ordine de plată (mascate), cont implicit și manual.
GET /claims/routes	claims-settings:read	Transport retur pentru reclamații: rute, adrese, profiluri de curier cu ID și suport pentru retur, tipuri de caz.
GET /claims/settings	claims:read	Procesele reclamațiilor cu ID-uri și denumiri (tipuri, pași, stări, termene), etichete; setările modulului cu domeniul claims-settings:read.
GET /claims/statistics	claims:read	Statistica reclamațiilor și retururilor pentru o perioadă: numere, timpi de soluționare, tipuri, evaluări, motive.
GET /claims/templates	claims-settings:read	Șabloanele de e-mail (subiect, text, când și dacă se trimit automat) și de procese-verbale ale reclamațiilor.
GET /content/articles	products:read	Articolele blogului magazinului online, cu adresa de pe site și imaginea de previzualizare.
GET /coupons/activation-link	coupons:read	Un link care aplică clientului în coș un cupon EXISTENT. Nu creează cupoane.
GET /coupons/activation-status	coupons:read	Dacă un cupon poate fi folosit în magazinul online prin linkul de activare: oglinda cuponului + starea codului de pe site.
GET /coupons/capabilities	coupons:read	Ce știe platforma magazinului online respectiv despre cupoane. Citiți înainte de creare.
GET /coupons/:code	coupons:read	Un cupon din evidența MitoOps. Când nu se află în ea, răspunsul este „nu s-a găsit”.
GET /coupons	coupons:read	Cupoanele de reducere ale magazinului online, cu tipul și valoarea reducerii, valabilitatea și starea derivată.
GET /customers/:customerKey	customers:read	Un client din director: identitate, magazine online, bani LIFETIME și, opțional, PERIOD, defalcare pe magazine online.
GET /customers	customers:read	Directorul clienților: identitate (cu mascarea datelor personale), magazine online, limbă, numere LIFETIME și cifră de afaceri pe monede; filtru opțional al activității de cumpărare în perioadă.
GET /customers/performance	reports:read	Clienții ca pseudonime: număr de comenzi, cifră de afaceri, prima și ultima comandă, recumpărare, LTV.
GET /credit-notes	invoices:read	Căutare în notele de credit.
GET /documents	invoices:read	Documente contabile de un singur tip (facturi, facturi proforma, note de credit) pe pagini, cu ciclu de viață, stare în sursă, filtru de valabilitate și disponibilitatea PDF.
GET /documents/:documentType/:code/pdf	invoices:read	PDF-ul unei facturi, facturi proforma sau note de credit (base64 și SHA-256), aceiași octeți ca pe ecran.
GET /invoices/:invoiceCode	invoices:read	O factură cu articole, sume, note de credit și facturile proforma aferente.
GET /invoices	invoices:read	Căutare în facturi.
GET /inventory/movements	inventory:read	Istoricul mișcărilor de stoc: când, ce, cu cât, de ce și din ce sursă.
GET /inventory/availability	inventory:read	Stocul pentru mai multe articole deodată.
GET /inventory/stock	inventory:read	Stocul unui articol, inclusiv sursa valorii.
GET /orders/:orderCode	orders:read	O comandă salvată, inclusiv articolele.
GET /orders	orders:read	Comenzile salvate ale unui magazin online, de la cea mai nouă.
GET /availabilities/drafts/:draftId	products:read	Starea propunerii de modificare a nomenclatorului de disponibilități: așteaptă aprobarea, scrisă cu rezultat, respinsă, expirată.
GET /availabilities	products:read	Nomenclatorul de disponibilități al magazinului online: denumire, descriere, reaprovizionare, livrare, semnificația pentru Google, culoare, rol implicit.
GET /catalog/category-content-drafts/:draftId	category-content:read	Starea unei propuneri de texte pentru categorii: așteaptă aprobarea, scrisă, respinsă, expirată.
GET /categories/:guid/content	category-content:read	Textele unei categorii (descriere de sus și de jos, titlu și descriere SEO) cu amprentă și posibilitate de scriere.
GET /categories	products:read	Categoriile magazinului online, cu numărul de produse.
GET /catalog/product-content-drafts/:draftId	product-content:read	Starea unei propuneri de texte pentru produse: așteaptă aprobarea, scrisă cu avertismente ale magazinului, respinsă, expirată.
GET /products/:code/content	product-content:read	Textele unui produs din magazin (descriere, descriere scurtă, titlu și descriere SEO) cu amprentă și posibilitate de scriere.
GET /product-content/policy	product-content:read	Politica de conținut a magazinului fără apel către magazin: ce poate citi și propune acest acces, ce câmpuri scrie platforma, modul de aprobare și scrierea autonomă, limite și amprente.
GET /products/:code	products:read	Un produs după cod, inclusiv încadrarea și prețul din fișă.
GET /products	products:read	Căutarea produselor după denumire, cod, EAN sau PLU.
GET /reports/financial-summary	reports:read	Rezumatul financiar al perioadei: cifră de afaceri, TVA, comenzi, AOV; cu drepturi și achiziția, profitul brut, costurile și rezultatul.
GET /sales/order-performance	reports:read	Cifra de afaceri pe comenzi în EUR, cu totaluri pentru întreaga perioadă; cu drept și achiziția, profitul brut și marja pe comandă.
GET /sales/product-performance	reports:read	Vânzări pe produse din documente; cu drept și prețul de achiziție din momentul vânzării și marja.
GET /search-console/query	search-console:read	Search Console pe zile, interogări, pagini, țări și dispozitive, cu paginare și hash al conținutului.
GET /search-console/status	search-console:read	Starea Search Console a magazinului: conexiune, proprietate, permisiune, sincronizare și întinderea arhivei.
GET /shipping/carriers	shipping:read	Curierii conectați și profilurile lor, fără date de acces.
GET /shipping/shipments/:shipmentId	shipping:read	O expediere cu toate evenimentele de urmărire.
GET /shipping/shipments	shipping:read	Expedierile unui magazin online, cu curier, țară și orele de predare și livrare.
GET /shipping/stats	shipping:read	Statistici de livrare pe curieri: numere, rata de succes, mediana și p90 a timpului de livrare, țări.
GET /stores/integration-status	stores:read	Starea codului MitoOps de pe site pe magazine online: instalat, versiune, module, pregătirea cuponului din adresă.
GET /stores	stores:read	Lista magazinelor online ale clientului, cu codul lor.
GET /suppliers/:supplierId	purchasing:read	Un furnizor cu ofertele de produse și componentele de cost.
GET /suppliers	purchasing:read	Furnizorii clientului, cu numărul de oferte și de produse asociate.
GET /webhooks/endpoints/:endpointId/deliveries	webhooks:read	Jurnalul livrărilor unui endpoint, fără corp.
GET /webhooks/endpoints/:endpointId	webhooks:read	Un endpoint webhook, cu numărul de livrări în așteptare.
GET /webhooks/endpoints	webhooks:read	Endpointurile webhook ale clientului, fără secrete, și starea cozii.
GET /webhooks/events	webhooks:read	Catalogul evenimentelor webhookurilor de ieșire, plicul și semnătura.

Adresă	Domeniu	Ce returnează
GET /capabilities	—	ce are voie să apeleze această cheie
GET /openapi.json	—	descrierea interfeței, care poate fi citită automat

GET /capabilities este cel mai rapid mod de a afla ce deschide cheia: returnează exact ceea ce i-au permis domeniile, nu întregul catalog. Parametrii exacți și câmpurile răspunsului fiecărui apel sunt în openapi.json.

Forma răspunsului

Fiecare răspuns are două părți: data și meta.

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

meta.requestId este identificatorul apelului. Dacă ceva nu merge, este informația care îi spune asistenței despre ce apel a fost vorba.

La liste, meta mai conține:

Câmp	Semnificație
count	câte înregistrări sunt în acest răspuns
hasMore	true când există pagina următoare
nextCursor	valoarea cu care cereți pagina următoare; null când nu există niciuna

La rezumate (statistici, prezentare generală, rezumat financiar), întregul răspuns se află în data, ca un singur obiect.

Paginare

Pagina următoare o cereți trimițând înapoi nextCursor din răspuns în parametrul cursor:

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

Trei lucruri pe care se bazează:

• Ceilalți parametri trebuie să rămână aceiași. Cursorul aparține interogării cu care a apărut. Cu un magazin online, o perioadă sau un filtru schimbat, interfața îl refuză (400): a continua într-o ordine care nu mai este valabilă ar returna pe tăcute o secțiune incoerentă.
• Sfârșitul îl recunoașteți după hasMore, nu după număr. Răspunsul poate avea exact atâtea înregistrări câte ați cerut, iar pagina următoare poate totuși să existe.
• Un cursor nevalid este o eroare, nu un rezultat gol. Un răspuns gol ar arăta ca sfârșitul datelor, iar exportul s-ar scurta pe tăcute.

Prin cursor se paginează comenzile, documentele, catalogul și expedierile. Numerotarea paginilor lipsește intenționat din interfață: când între două apeluri apare o înregistrare, „pagina 2” arată în altă parte decât înainte; cursorul poartă ultima înregistrare văzută, deci nimic nu se repetă și nimic nu se omite.

Listare și căutare

La produse, facturi și note de credit sunt două moduri ale aceleiași adrese:

Cum apelați	Ce primiți
fără query	listare pe pagini, de la cea mai nouă; se poate pagina și restrânge la o perioadă
cu query	căutare ordonată după potrivire; returnează cel mult limit înregistrări

Căutarea nu se paginează și nu se restrânge la o perioadă: ordinea după potrivire se schimbă între apeluri, iar un cursor peste ea ar sări înregistrări. Combinația query cu cursor, from sau to se încheie de aceea cu 400, nu cu un filtru ignorat pe tăcute.

Pentru citirea întregii evidențe folosiți listarea fără query.

Perioada

Comenzile, documentele, expedierile, statisticile, analitica și rapoartele pot fi restrânse cu parametrii from și to în forma YYYY-MM-DD.

• Ambele limite sunt incluse. to=2026-08-05 include întreaga zi de 5 august, nu miezul nopții de la începutul ei.
• Ziua se ia așa cum o înregistrează aplicația: comenzile în fusul orar al magazinului online, expedierile și rapoartele așa cum le vede operatorul pe ecran.
• Comenzile se ordonează după data creării comenzii, expedierile după data creării expedierii.
• Facturile și notele de credit după data fiscală; când documentul nu o are completată, după data emiterii. Ce valoare a încadrat documentul se vede în câmpul businessDate.
• Vânzările pe produse după data documentului; aici perioada este obligatorie.
• Cea mai lungă perioadă este de 366 de zile. Una mai lungă se refuză; un istoric mai lung parcurgeți-l pe ani.
• O perioadă inversată este o eroare, nu un rezultat gol: altfel o greșeală de tastare ar arăta ca o perioadă fără documente.
• Fără perioadă, expedierile și statisticile returnează ultimele 30 de zile, analitica și rezumatul financiar luna curentă. Răspunsul afișează întotdeauna perioada.

La comenzi rămâne și todayOnly. Nu poate fi combinat cu from/to: sunt două răspunsuri la aceeași întrebare, iar unul dintre ele ar câștiga pe tăcute.

Ce înseamnă câmpurile financiare

• purchasePriceWithoutVat la un articol al comenzii este prețul de achiziție din momentul comenzii, așa cum l-a salvat magazinul online. Nu este prețul din fișa de azi a produsului: acela se află în products/{code} ca purchasePrice.
• cogs din rezumatul financiar este achiziția mărfii pentru perioadă, din toate comenzile; null înseamnă că prețurile de achiziție nu sunt cunoscute pentru suficiente rânduri (cogsCoverage). Atunci nu se afișează nici profitul brut: mai bine nimic decât o cifră greșită.
• grossProfit este cifra de afaceri fără TVA minus achiziția mărfii, grossMargin același lucru în procente. resultAfterCosts este profitul brut minus transportul minus costurile firmei: o cifră managerială, nu profitul contabil.
• În vânzările pe produse, purchaseCostWithoutVat este prețul de achiziție din momentul documentului, conform asocierii cu catalogul; unmappedLines spune câte rânduri nu s-au asociat.
• Toate sumele rapoartelor și ale analiticii sunt în EUR (câmpul currency), convertite la cursul din momentul sincronizării. Comenzile și documentele poartă propria monedă.

Fără domeniul purchase-prices:read, aceste câmpuri nu sunt în răspuns: nu sunt zero, lipsesc.

Timpul de livrare

Statisticile de livrare (shipping/stats) măsoară timpul de la predarea către curier până la primul eveniment de livrare din evenimentele de urmărire. Din data comenzii nu se calculează nimic. O expediere care nu are ambele puncte nu se include în mediană; câte au fost incluse spune delivery.measured. Aceleași două momente le poartă fiecare expediere în câmpurile handedOverAt și deliveredAt.

deliveryRate este proporția celor livrate din cele al căror deznodământ s-a încheiat deja (livrate, returnate, eronate). O expediere în tranzit nu este încă nici succes, nici eșec; o expediere anulată este acțiunea dumneavoastră, nu un eșec al curierului, și nu se ia deloc în calcul.

Starea stocurilor

inventory/stock returnează quantity și source: din ce model de evidență provine valoarea (variante, bilanțul magazinului online, fișa produsului). Când magazinul online ține bilanțul, sunt disponibile și physical, available (disponibil pentru vânzare) și reserved (rezervat în comenzi); altfel sunt null. Interfața nu inventează nicio „stare a stocului” pe care aplicația nu o înregistrează.

Starea stocurilor (inventory/stock și inventory/availability, domeniul inventory:read) spune câtă marfă există; nomenclatorul de disponibilități (/availabilities, domeniul products:read) sunt stările denumite pe care magazinul online le arată clientului la produs, de exemplu În stoc sau La comandă.

Nomenclatorul de disponibilități

GET /availabilities?market=sk returnează în data intrările nomenclatorului unui singur magazin online: id, name, description, onStockHours, deliveryHours, meaning (semnificația pentru Google Shopping: in_stock, backorder, preorder, out_of_stock), color, system, defaultRoles (rolul implicit în magazinul online) și pairingRows (în câte rânduri de asociere a disponibilităților se află intrarea). meta poartă market, manageable și reason: dacă nomenclatorul poate fi modificat în MitoOps și, dacă nu, de ce (PLATFORMA, BEZ_ROZSIRENIA, PROSTREDIE).

Modificarea nomenclatorului prin REST nu este posibilă. O poate pregăti doar asistentul, prin MCP, și anume ca propunere, cu domeniul sensibil availabilities:draft; în magazinul online o scrie abia omul, prin aprobare în aplicație. Starea unei astfel de propuneri o citiți prin REST: GET /availabilities/drafts/:draftId returnează status (pending, writing, executed, partial, failed, rejected, expired), previzualizarea și, după aprobare, rezultatul pe intrări. Detalii în interfața MCP.

Directorul clienților

Clienții au două citiri diferite, iar a le confunda înseamnă a citi o altă cifră decât vă așteptați:

• /customers și /customers/{customerKey} (domeniul customers:read) sunt directorul: aceeași proiecție pe care o vede operatorul pe ecranul Clienți și care merge în export: identitate, magazine online, țară, limbă, numere și date.
• /customers/performance (domeniul reports:read) este analitica peste comenzile brute: clientul este doar un pseudonim, numele și contactul nu apar deloc în ea.

Din exterior, market este obligatoriu la ambele. Fără el, citirea s-ar face în toate magazinele online ale clientului, deci și în cele care nu aparțin accesului.

Cine vede ce

customers:read furnizează singur pseudonimul (customerKey), magazinele online, țara, limba, numărul de comenzi și datele primei și ultimei comenzi. În plus:

• numele, firma, e-mailul, telefonul și genul pentru marketing doar cu personal-data:read,
• cifra de afaceri, comanda medie și LTV doar cu reports:read.

Câmpurile pentru care nu aveți domeniu se elimină, nu se pun pe zero. null în locul e-mailului ar însemna „clientul nu are e-mail”, ceea ce nu este adevărat: o cheie lipsă înseamnă „nu aveți drept asupra ei”.

customerKey este SHA-256 al e-mailului normalizat. Este același pseudonim pe care îl poartă documentele (customerEmailHash) și /customers/performance, astfel încât cele trei perspective pot fi unite fără ca e-mailul să fie trimis undeva.

Întreaga relație față de perioadă

Directorul are filtrul opțional purchaseFrom și purchaseTo (YYYY-MM-DD, ambele limite incluse). Înseamnă activitate de cumpărare în perioadă: clientul are în acel interval cel puțin o comandă. Nu este un filtru după data primei sau ultimei cumpărări.

Cu perioada apar câmpurile periodFrom, periodTo, periodOrdersCount și periodRevenueByCurrency lângă cele pentru întreaga relație (ordersCount, revenue, lifetimeRevenue, firstOrderAt, lastOrderAt), niciodată în locul lor. Valorile pentru întreaga relație nu se schimbă cu perioada.

Banii sunt întotdeauna pe monede

Cifra de afaceri, comanda medie și LTV sunt o listă pe monede, niciodată un singur număr. Un client cu comenzi în EUR și în CZK are două elemente; a le aduna într-un singur scalar ar însemna a aduna coroane la euro. Același lucru este valabil pentru /customers/performance: rândul este perechea (client, monedă), iar totalurile filtrului sunt totals.revenueByCurrency.

Limba și genul pentru marketing

• language este limba magazinului online în care a comandat clientul (source: "store_locale"), nu propria lui alegere. Aplicația nu înregistrează astăzi o preferință lingvistică explicită a clientului.
• marketingGender (male / female / unknown) este o estimare după prenume, nu o informație pe care clientul ar fi indicat-o. Originea este întotdeauna în genderSource (astăzi exclusiv name_inference sau unknown), iar fiabilitatea în genderConfidence. Un client persoană juridică nu are acest câmp. Cine îl afișează mai departe trebuie să spună „estimare după nume”, niciodată „indicat de client”. Se află în spatele personal-data:read, la fel ca numele însuși.

Magazinul online

Apelurile asupra datelor unui singur magazin online cer codul lui în parametrul market. Lista codurilor o furnizează GET /stores.

Când cheia nu are domeniu pentru magazinul online respectiv, răspunsul este 403, nu o listă goală. O listă goală nu ar putea fi deosebită de un magazin online fără comenzi. O înregistrare a altui magazin online (de exemplu o expediere) înseamnă 404.

Erori

Răspunsul de eroare are întotdeauna aceeași formă și poartă un cod. Lista stărilor și codurilor este în Prezentare.

Exemple

# Comenzi pentru o perioadă, pe pagini
curl -H "Authorization: Bearer <cheia dumneavoastră>" \
  "https://<adresa dumneavoastră>/api/v1/orders?market=sk&from=2026-08-01&to=2026-08-31&limit=50"

# Statistici de livrare pentru august
curl -H "Authorization: Bearer <cheia dumneavoastră>" \
  "https://<adresa dumneavoastră>/api/v1/shipping/stats?market=sk&from=2026-08-01&to=2026-08-31"

# Expedierile unui curier pentru august
curl -H "Authorization: Bearer <cheia dumneavoastră>" \
  "https://<adresa dumneavoastră>/api/v1/shipping/shipments?market=sk&from=2026-08-01&to=2026-08-31&carrier=dhl"

# Rezumatul financiar al lunii august (cu drept asupra prețurilor de achiziție și profitul brut)
curl -H "Authorization: Bearer <cheia dumneavoastră>" \
  "https://<adresa dumneavoastră>/api/v1/reports/financial-summary?market=sk&from=2026-08-01&to=2026-08-31"

# Stocul pentru trei articole
curl -H "Authorization: Bearer <cheia dumneavoastră>" \
  "https://<adresa dumneavoastră>/api/v1/inventory/availability?market=sk&codes=A100,A101,A102"

# Nomenclatorul de disponibilități al magazinului online
curl -H "Authorization: Bearer <cheia dumneavoastră>" \
  "https://<adresa dumneavoastră>/api/v1/availabilities?market=sk"

Legate

• Prezentare
• Interfața MCP