Interfejs REST

Zweryfikowanezweryfikowano 2026-09-20

W skrócie

Interfejs REST znajduje się pod /api/v1 i odpowiada tylko na GET. Wszystko inne otrzymuje 405, zanim serwer w ogóle spojrzy na klucz.

Dostęp potwierdza się nagłówkiem; zobacz Przegląd.

Wywołania

Adres	Zakres	Co zwraca
`GET /account/connection`	`stores:read`	Diagnostyka tego połączenia: aplikacja, kto i kiedy udzielił dostępu, przyznane i brakujące uprawnienia według obszarów, e-sklepy i tryb zapisu przez AI.
`GET /account/entitlements`	`account:read`	Taryfa klienta, funkcje i limity z aktualnym wykorzystaniem.
`GET /affiliate/articles/:key`	`affiliate:read`	Jeden artykuł pomocy z treścią (HTML) we wszystkich językach lub w jednym; zmienne niepodstawione.
`GET /affiliate/articles`	`affiliate:read`	Artykuły pomocy portalu partnerskiego: klucz, domyślny/własny, włączenie, kolejność, stan według języków (tytuł, adres, wypełnione, zgodne z domyślnym).
`GET /affiliate/campaigns/:campaignId`	`affiliate:read`	Jedna kampania programu partnerskiego.
`GET /affiliate/campaigns`	`affiliate:read`	Kampanie programu partnerskiego e-shopu z wynagrodzeniem, dostępnością i liczbami.
`GET /affiliate/code-requests`	`affiliate:read`	Wnioski partnerów o własny kod rabatowy ze stanem i powodem; oczekujące najpierw.
`GET /affiliate/conversions/:conversionId`	`affiliate:read`	Szczegóły jednej konwersji: kwoty, prowizja, stan prowizji z powodem, status zamówienia w e-shopie, korekta, wypłata.
`GET /affiliate/conversions`	`affiliate:read`	Konwersje programu partnerskiego e-shopu: podstawa prowizji i całe zamówienie z VAT, prowizja, stan prowizji z powodem, status zamówienia w e-shopie, powiązanie z wypłatą.
`GET /affiliate/discount-codes`	`affiliate:read`	Kody rabatowe partnerów w e-shopie z liczbą użyć i obrotem.
`GET /affiliate/documents/:key/content`	`affiliate:read`	Jeden dokument prawny programu z treścią według języków (zapisany tekst, treść publiczna, wersja, odciski, źródło, metadane PDF) i otwartymi projektami.
`GET /affiliate/documents`	`affiliate:read`	Dokumenty programu (warunki, umowy): polityka potwierdzania, podpisana kopia, załącznik e-maila, wersje według języków, gotowość i liczby potwierdzeń.
`GET /affiliate/email-templates`	`affiliate:read`	Szablony e-maili do partnerów według języków (temat, włączenie, ze zdarzeniem także treść) i automatyczne załączniki e-maila Konto zatwierdzone.
`GET /affiliate/links/generate`	`affiliate:read`	Śledzony link partnerski do strony głównej, produktu lub kategorii e-shopu kampanii; po kliknięciu zachowuje przypisanie do partnera.
`GET /affiliate/partners/:partnerId`	`affiliate:read`	Jeden partner programu z kampaniami, które ma do dyspozycji.
`GET /affiliate/partners`	`affiliate:read`	Partnerzy programu ze stanem, wynikami i prowizjami; kontakt tylko z danymi osobowymi.
`GET /affiliate/payouts`	`affiliate:read`	Wypłaty prowizji partnerom ze stanem; bez danych bankowych i rozliczeniowych.
`GET /affiliate/portal`	`affiliate:read`	Publiczny portal partnera: adresy według e-shopów, otwartość rejestracji z powodem, własne domeny, osoba kontaktowa, wygląd i stan tekstów według języków.
`GET /affiliate/settings`	`affiliate:read`	Ustawienia programu partnerskiego: prowizje, kliknięcia, minimum wypłaty, polecenia.
`GET /affiliate/signatures/:signatureId`	`affiliate:read`	Jeden podpis elektroniczny z podpisaną treścią i migawką wartości; niezmienny rekord, PDF składa się w aplikacji.
`GET /affiliate/signatures`	`affiliate:read`	Dokumenty partnerów podpisane elektronicznie (kto, dokument, wersja, język, e-shop, czas, sposób, weryfikacja, odciski, stan) oraz partnerzy, którym brakuje podpisu; tylko odczyt, podpis powstaje wyłącznie w portalu.
`GET /affiliate/statistics`	`affiliate:read`	Statystyka programu partnerskiego: przebieg według dni, źródła przypisania, ranking partnerów.
`GET /affiliate/summary`	`affiliate:read`	Przegląd programu partnerskiego e-shopu za okres: kliknięcia, konwersje, prowizje, partnerzy.
`GET /affiliate/variables`	`affiliate:read`	Rejestr zmiennych treści i e-maili programu partnerskiego: nazwy kanoniczne, aliasy, typ, miejsca użycia, przykład; opcjonalna kontrola tekstu pod kątem nieznanych zmiennych.
`GET /analytics/advertising`	`reports:read`	Reklama: wydatki, budżet, ROAS, udział wydatków w obrocie, CPA, średnia wartość zamówienia i MER z porównaniem; Google Ads i Meta Ads, kliknięcia z GA4, 6 miesięcy.
`GET /analytics/channels`	`analytics:read`	Rozkład wizyt, zamówień i obrotu według kanałów marketingowych.
`GET /analytics/comparison`	`reports:read`	Obrót z porównaniem: obrót, zamówienia, AOV, wizyty, CR i AI/LLM wobec poprzedniego okresu lub roku.
`GET /analytics/monthly`	`reports:read`	Obrót, zamówienia i wizyty według miesięcy (maksymalnie 24), na przykład rok do roku.
`GET /analytics/order-coverage`	`analytics:read`	Pokrycie zamówień i obrotu pomiarem w analityce.
`GET /analytics/order-heatmap`	`reports:read`	Kiedy przychodzą zamówienia: dzień tygodnia × godzina, najsilniejszy dzień i godzina.
`GET /analytics/overview`	`analytics:read`	Wizyty, zamówienia, obrót, współczynnik konwersji i udział AI/LLM za okres.
`GET /analytics/revenue-sources`	`reports:read`	Skąd pochodzi obrót: kanały, sumy AI/LLM, MitoOps i Affiliate, pozyskanie według GA4.
`GET /analytics/seo`	`analytics:read`	Search Console: kliknięcia, wyświetlenia, CTR i pozycja według zapytań lub stron.
`GET /automations/catalog`	`automations:read`	Katalog automatyzacji: wyzwalacze, warunki, operatory, akcje, szablony; catalogVersion dla propozycji.
`GET /automations/:workflowId`	`automations:read`	Jedna automatyzacja z DSL i wynikiem walidacji.
`GET /automations`	`automations:read`	Automatyzacje klienta ze stanem i zakresem e-shopów.
`GET /automations/options`	`automations:read`	Słownik dla pola automatyzacji (statusy, metody dostawy, płatności, szablony, reklamacje…): value do DSL i nazwa.
`GET /automations/:workflowId/runs`	`automations:read`	Historia przebiegów jednej automatyzacji.
`GET /automations/templates`	`automations:read`	Gotowe wzory automatyzacji z DSL.
`GET /chatbot/conversations/:sessionId`	`chatbot-conversations:read`	Zapis jednej rozmowy z chatbotem internetowym wraz ze źródłami odpowiedzi bota.
`GET /chatbot/conversations`	`chatbot-conversations:read`	Rozmowy klientów z chatbotem internetowym od ostatnio aktywnej, z pierwszym pytaniem; 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`	Statystyka chatbota internetowego za okres: lejek dymka, otwarcia, rozmowy, wyniki, oceny.
`GET /chatbot/topics`	`chatbot:read`	O czym były rozmowy: udziały tematów, produkty, typ strony początkowej i kandydaci na lukę w wiedzy.
`GET /claims/config-drafts/:draftId`	`claims-settings:read`	Stan propozycji zmiany ustawień reklamacji (czeka, zapisana, odrzucona).
`GET /claims/configuration`	`claims-settings:read`	Ustawienia reklamacji: etykiety, pola, transport zwrotny, formularz w e-shopie, typy formularza.
`GET /claims/:code`	`claims:read`	Jedno zgłoszenie z pozycjami i powiązaniami: zamówienie, korekta, przesyłka zwrotna, ruch magazynowy.
`GET /claims`	`claims:read`	Reklamacje i zwroty jednego e-shopu od najnowszego.
`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`	Zwroty reklamacji: tryb, konta bankowe z przydatnością do poleceń przelewu (zamaskowane), konto domyślne i ręczne.
`GET /claims/routes`	`claims-settings:read`	Transport zwrotny reklamacji: trasy, adresy, profile przewoźników z ID i obsługą zwrotów, typy zgłoszeń.
`GET /claims/settings`	`claims:read`	Procesy reklamacji z ID i nazwami (typy, kroki, statusy, terminy), etykiety; ustawienia modułu z zakresem claims-settings:read.
`GET /claims/statistics`	`claims:read`	Statystyka reklamacji i zwrotów za okres: liczby, czasy obsługi, typy, oceny, powody.
`GET /claims/templates`	`claims-settings:read`	Szablony e-maili (temat, tekst, kiedy i czy są wysyłane automatycznie) oraz protokołów reklamacji.
`GET /content/articles`	`products:read`	Artykuły bloga e-shopu z adresem na stronie i obrazkiem podglądu.
`GET /coupons/activation-link`	`coupons:read`	Link, który zastosuje klientowi ISTNIEJĄCY kupon w koszyku. Kuponu nie tworzy.
`GET /coupons/activation-status`	`coupons:read`	Czy kupon w e-shopie można użyć przez link aktywacyjny: lustro kuponu + stan kodu na stronie.
`GET /coupons/capabilities`	`coupons:read`	Co o kuponach potrafi platforma danego e-shopu. Warto odczytać przed zakładaniem.
`GET /coupons/:code`	`coupons:read`	Jeden kupon z ewidencji MitoOps. Gdy go w niej nie ma, odpowiedź to „nie znaleziono”.
`GET /coupons`	`coupons:read`	Kupony rabatowe e-shopu z typem i wysokością rabatu, ważnością i wyprowadzonym stanem.
`GET /customers/:customerKey`	`customers:read`	Jeden klient z katalogu: tożsamość, e-shopy, kwoty LIFETIME i opcjonalnie PERIOD, rozbicie według e-shopów.
`GET /customers`	`customers:read`	Katalog klientów: tożsamość (z maskowaniem PII), e-shopy, język, liczby LIFETIME i obrót według walut; opcjonalny filtr aktywności zakupowej w okresie.
`GET /customers/performance`	`reports:read`	Klienci jako pseudonimy: liczba zamówień, obrót, pierwsze i ostatnie zamówienie, ponowny zakup, LTV.
`GET /credit-notes`	`invoices:read`	Wyszukiwanie w korektach.
`GET /documents`	`invoices:read`	Dokumenty księgowe jednego rodzaju (faktury, faktury zaliczkowe, korekty) stronami z cyklem życia, stanem w źródle, filtrem ważności i dostępnością PDF.
`GET /documents/:documentType/:code/pdf`	`invoices:read`	PDF faktury, faktury zaliczkowej lub korekty (base64 i SHA-256), te same bajty co na ekranie.
`GET /invoices/:invoiceCode`	`invoices:read`	Jedna faktura z pozycjami, kwotami, korektami i fakturami zaliczkowymi do niej.
`GET /invoices`	`invoices:read`	Wyszukiwanie w fakturach.
`GET /inventory/movements`	`inventory:read`	Historia ruchów magazynowych: kiedy, co, o ile, dlaczego i z jakiego źródła.
`GET /inventory/availability`	`inventory:read`	Stan zapasu dla wielu pozycji naraz.
`GET /inventory/stock`	`inventory:read`	Stan zapasu jednej pozycji wraz ze źródłem wartości.
`GET /orders/:orderCode`	`orders:read`	Jedno zapisane zamówienie łącznie z pozycjami.
`GET /orders`	`orders:read`	Zapisane zamówienia jednego e-shopu, od najnowszego.
`GET /availabilities/drafts/:draftId`	`products:read`	Stan propozycji zmiany słownika dostępności: czeka na zatwierdzenie, zapisana z wynikiem, odrzucona, wygasła.
`GET /availabilities`	`products:read`	Słownik dostępności e-shopu: nazwa, opis, zaopatrzenie, dostawa, znaczenie dla Google, kolor, rola domyślna.
`GET /catalog/category-content-drafts/:draftId`	`category-content:read`	Stan propozycji tekstów kategorii: czeka na zatwierdzenie, zapisana, odrzucona, wygasła.
`GET /categories/:guid/content`	`category-content:read`	Teksty kategorii (górny i dolny opis, tytuł i opis SEO) z odciskiem i możliwością zapisu pola.
`GET /categories`	`products:read`	Kategorie e-shopu z liczbą produktów.
`GET /catalog/product-content-drafts/:draftId`	`product-content:read`	Stan propozycji tekstów produktów: czeka na zatwierdzenie, zapisana z uwagami sklepu, odrzucona, wygasła.
`GET /products/:code/content`	`product-content:read`	Teksty produktu ze sklepu (opis, krótki opis, tytuł i opis SEO) z odciskiem i możliwością zapisu pola.
`GET /product-content/policy`	`product-content:read`	Zasady treści sklepu bez odpytywania sklepu: co ten dostęp może czytać i proponować, które pola platforma zapisze, tryb zatwierdzania i zapis autonomiczny, limity i odciski.
`GET /products/:code`	`products:read`	Jeden produkt według kodu łącznie z klasyfikacją i ceną z karty.
`GET /products`	`products:read`	Wyszukiwanie produktów według nazwy, kodu, EAN lub PLU.
`GET /reports/financial-summary`	`reports:read`	Podsumowanie finansowe okresu: obrót, VAT, zamówienia, AOV; z uprawnieniami także zakup, zysk brutto, koszty i wynik.
`GET /sales/order-performance`	`reports:read`	Obrót według zamówień w EUR z sumami za cały okres; z uprawnieniem także zakup, zysk brutto i marża na zamówienie.
`GET /sales/product-performance`	`reports:read`	Sprzedaż według produktów z dokumentów; z uprawnieniem także cena zakupu w czasie sprzedaży i marża.
`GET /search-console/query`	`search-console:read`	Search Console według dni, zapytań, stron, krajów i urządzeń, ze stronicowaniem i skrótem zawartości.
`GET /search-console/status`	`search-console:read`	Stan Search Console sklepu: połączenie, właściwość, uprawnienia, synchronizacja i zakres archiwum.
`GET /shipping/carriers`	`shipping:read`	Podłączeni przewoźnicy i ich profile, bez danych dostępowych.
`GET /shipping/shipments/:shipmentId`	`shipping:read`	Jedna przesyłka ze wszystkimi zdarzeniami śledzenia.
`GET /shipping/shipments`	`shipping:read`	Przesyłki jednego e-shopu z przewoźnikiem, krajem oraz czasami przekazania i doręczenia.
`GET /shipping/stats`	`shipping:read`	Statystyki doręczeń według przewoźników: liczby, skuteczność, mediana i p90 czasu doręczenia, kraje.
`GET /stores/integration-status`	`stores:read`	Stan kodu MitoOps na stronie według e-shopów: zainstalowany, wersja, moduły, gotowość kuponu z adresu.
`GET /stores`	`stores:read`	Lista e-shopów klienta wraz z ich kodem.
`GET /suppliers/:supplierId`	`purchasing:read`	Jeden dostawca z ofertami produktów i składnikami kosztów.
`GET /suppliers`	`purchasing:read`	Dostawcy klienta z liczbą ofert i powiązanych produktów.
`GET /webhooks/endpoints/:endpointId/deliveries`	`webhooks:read`	Dziennik doręczeń jednego endpointu bez treści.
`GET /webhooks/endpoints/:endpointId`	`webhooks:read`	Jeden endpoint webhooka z liczbą oczekujących doręczeń.
`GET /webhooks/endpoints`	`webhooks:read`	Endpointy webhooków klienta bez tajnych kluczy i stan kolejki.
`GET /webhooks/events`	`webhooks:read`	Katalog zdarzeń webhooków wychodzących, koperta i podpis.

Adres	Zakres	Co zwraca
`GET /capabilities`	brak	co ten klucz może wywołać
`GET /openapi.json`	brak	maszynowo czytelny opis interfejsu

GET /capabilities to najszybszy sposób, aby sprawdzić, co otwiera klucz: zwraca dokładnie to, na co pozwoliły mu zakresy, a nie cały katalog. Dokładne parametry i pola odpowiedzi każdego wywołania są w openapi.json.

Kształt odpowiedzi

Każda odpowiedź ma dwie części: data i meta.

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

meta.requestId to identyfikator wywołania. Jeśli coś pójdzie nie tak, jest to informacja, która pozwoli pomocy technicznej ustalić, o które wywołanie chodziło.

Przy listach meta zawiera dodatkowo:

Pole	Znaczenie
`count`	ile rekordów jest w tej odpowiedzi
`hasMore`	`true`, gdy istnieje kolejna strona
`nextCursor`	wartość, którą prosi się o kolejną stronę; `null`, gdy żadnej nie ma

Przy podsumowaniach (statystyki, przegląd, podsumowanie finansowe) cała odpowiedź jest w data jako jeden obiekt.

Stronicowanie

O kolejną stronę prosi się, wysyłając nextCursor z odpowiedzi z powrotem w parametrze cursor:

curl -H "Authorization: Bearer <klucz API>" \
  "https://<adres aplikacji>/api/v1/shipping/shipments?market=sk&from=2026-08-01&to=2026-08-31&limit=50&cursor=<nextCursor>"

Trzy rzeczy, na których to się opiera:

Pozostałe parametry muszą pozostać takie same. Kursor należy do zapytania, z którym powstał. Przy zmienionym e-shopie, okresie lub filtrze interfejs go odrzuci (400): kontynuowanie w kolejności, która już nie obowiązuje, zwróciłoby po cichu niespójny wycinek.
Koniec rozpoznaje się po hasMore, a nie po liczbie. Odpowiedź może mieć dokładnie tyle rekordów, ile zażądano, a kolejna strona mimo to istnieje.
Nieprawidłowy kursor to błąd, a nie pusty wynik. Pusta odpowiedź wyglądałaby jak koniec danych i eksport zostałby po cichu skrócony.

Kursorem stronicuje się zamówienia, dokumenty, katalog i przesyłki. Numerowania stron interfejs celowo nie ma: gdy między dwoma wywołaniami dojdzie rekord, „strona 2” wskazuje gdzie indziej niż przed chwilą; kursor niesie ostatni widziany rekord, więc nic się nie powtórzy ani nie zostanie pominięte.

Lista i wyszukiwanie

Przy produktach, fakturach i korektach są to dwa tryby jednego adresu:

Jak się wywołuje	Co się otrzymuje
bez `query`	lista według stron, od najnowszego; można ją stronicować i ograniczyć okresem
z `query`	wyszukiwanie uporządkowane według dopasowania; zwraca najwyżej `limit` rekordów

Wyszukiwanie nie jest stronicowane ani ograniczane okresem: kolejność według dopasowania zmienia się między wywołaniami, a kursor nad nią przeskakiwałby rekordy. Połączenie query z cursor, from lub to kończy się więc 400, a nie po cichu zignorowanym filtrem.

Do odczytania całej ewidencji należy użyć listy bez query.

Okres

Zamówienia, dokumenty, przesyłki, statystyki, analitykę i zestawienia można ograniczyć parametrami from i to w postaci YYYY-MM-DD.

Obie granice są włącznie. to=2026-08-05 obejmuje cały 5 sierpnia, a nie północ na jego początku.
Dzień jest brany tak, jak ewidencjonuje go aplikacja: zamówienia w strefie czasowej e-shopu, przesyłki i zestawienia tak, jak widzi je obsługa na ekranie.
Zamówienia są porządkowane według daty powstania zamówienia, przesyłki według daty powstania przesyłki.
Faktury i korekty według daty podatkowej; gdy dokument jej nie ma, według daty wystawienia. To, która wartość zaszeregowała dokument, widać w polu businessDate.
Sprzedaż według produktów według daty dokumentu; tutaj okres jest obowiązkowy.
Najdłuższy okres to 366 dni. Dłuższy zostanie odrzucony; dłuższą historię należy przejść według lat.
Odwrócony okres to błąd, a nie pusty wynik: inaczej literówka wyglądałaby jak okres bez dokumentów.
Bez okresu przesyłki i statystyki zwracają ostatnie 30 dni, analityka i podsumowanie finansowe bieżący miesiąc. Odpowiedź zawsze podaje okres.

Przy zamówieniach pozostaje też todayOnly. Nie można go łączyć z from/to: to dwie odpowiedzi na to samo pytanie i jedna z nich po cichu by wygrała.

Co oznaczają pola finansowe

purchasePriceWithoutVat przy pozycji zamówienia to cena zakupu w czasie zamówienia, tak jak zapisał ją e-shop. Nie jest to cena z dzisiejszej karty produktu; ta jest w products/{code} jako purchasePrice.
cogs w podsumowaniu finansowym to zakup towaru za okres ze wszystkich zamówień; null oznacza, że ceny zakupu nie są znane dla dostatecznej liczby wierszy (cogsCoverage). Wtedy nie pokazuje się też zysk brutto: lepiej nic niż nieprawidłowa liczba.
grossProfit to obrót bez VAT minus zakup towaru, grossMargin to samo w procentach. resultAfterCosts to zysk brutto minus transport minus koszty firmy: liczba zarządcza, a nie zysk księgowy.
W sprzedaży według produktów purchaseCostWithoutVat to cena zakupu w czasie dokumentu według sparowania z katalogiem; unmappedLines mówi, ile wierszy nie zostało sparowanych.
Wszystkie kwoty zestawień i analityki są w EUR (pole currency), przeliczone kursem z czasu synchronizacji. Zamówienia i dokumenty niosą własną walutę.

Bez zakresu purchase-prices:read tych pól w odpowiedzi nie ma: nie są zerowe, brakuje ich.

Czas doręczenia

Statystyki doręczeń (shipping/stats) mierzą czas od przekazania przewoźnikowi do pierwszego zdarzenia doręczenia ze zdarzeń śledzenia. Z daty zamówienia nic nie jest liczone. Przesyłka, która nie ma obu punktów, nie jest wliczana do mediany; ile zostało wliczonych, mówi delivery.measured. Te same dwa czasy niesie każda przesyłka w polach handedOverAt i deliveredAt.

deliveryRate to udział doręczonych spośród tych, których los już się zakończył (doręczone, zwrócone, błędne). Przesyłka w drodze nie jest jeszcze ani sukcesem, ani porażką; anulowana przesyłka to czynność sprzedawcy, a nie awaria przewoźnika, i w ogóle nie jest liczona.

Stan zapasów

inventory/stock zwraca quantity i source: z którego modelu ewidencji pochodzi wartość (warianty, bilans e-shopu, karta produktu). Gdy e-shop prowadzi bilans, dostępne są też physical, available (dostępne do sprzedaży) i reserved (zarezerwowane w zamówieniach); w przeciwnym razie są null. Interfejs nie wymyśla żadnego „stanu magazynowego”, którego aplikacja nie ewidencjonuje.

Stan zapasów (inventory/stock i inventory/availability, zakres inventory:read) mówi, ile towaru jest; słownik dostępności (/availabilities, zakres products:read) to nazwane stany, które e-shop pokazuje klientowi przy produkcie, na przykład Na stanie lub Na zamówienie.

Słownik dostępności

GET /availabilities?market=sk zwraca w data pozycje słownika jednego e-shopu: id, name, description, onStockHours, deliveryHours, meaning (znaczenie dla Google Shopping: in_stock, backorder, preorder, out_of_stock), color, system, defaultRoles (rola domyślna w e-shopie) i pairingRows (w ilu wierszach parowania dostępności jest pozycja). meta zawiera market, manageable i reason: czy słownik można zmieniać w MitoOps, a jeśli nie, dlaczego (PLATFORMA, BEZ_ROZSIRENIA, PROSTREDIE).

Zmiana słownika przez REST nie jest możliwa. Przygotować ją może tylko asystent przez MCP, i to jako propozycję z wrażliwym zakresem availabilities:draft; do e-shopu zapisuje ją dopiero człowiek, zatwierdzając w aplikacji. Stan takiej propozycji można odczytać przez REST: GET /availabilities/drafts/:draftId zwraca status (pending, writing, executed, partial, failed, rejected, expired), podgląd, a po zatwierdzeniu wynik według pozycji. Szczegóły w interfejsie MCP.

Katalog klientów

Klienci mają dwa różne odczyty, a ich pomylenie oznacza odczytanie innej liczby, niż się oczekuje:

/customers i /customers/{customerKey} (zakres customers:read) to katalog: ta sama projekcja, którą widzi obsługa na ekranie Klienci i która trafia do eksportu: tożsamość, e-shopy, kraj, język, liczby i daty.
/customers/performance (zakres reports:read) to analityka nad surowymi zamówieniami: klient jest tylko pseudonimem, imienia ani kontaktu w niej w ogóle nie ma.

Z zewnątrz market jest obowiązkowy w obu przypadkach. Bez niego odczyt obejmowałby wszystkie e-shopy klienta, a więc także te, które nie należą do dostępu.

Kto co zobaczy

customers:read sam wydaje pseudonim (customerKey), e-shopy, kraj, język, liczby zamówień i daty pierwszego i ostatniego zamówienia. Ponadto:

imię i nazwisko, firma, e-mail, telefon i płeć marketingowa tylko z personal-data:read,
obrót, średnia wartość zamówienia i LTV tylko z reports:read.

Pola, do których brak zakresu, są usuwane, a nie zerowane. null w miejscu e-maila oznaczałby „klient nie ma e-maila”, co nie jest prawdą; brakujący klucz oznacza „brak uprawnienia”.

customerKey to SHA-256 znormalizowanego e-maila. To ten sam pseudonim, który niosą dokumenty (customerEmailHash) i /customers/performance, więc te trzy widoki można połączyć bez wysyłania gdziekolwiek e-maila.

Całe życie a okres

Katalog ma opcjonalny filtr purchaseFrom i purchaseTo (YYYY-MM-DD, obie granice włącznie). Oznacza on aktywność zakupową w okresie: klient ma w tym przedziale co najmniej jedno zamówienie. Nie jest to filtr daty pierwszego lub ostatniego zakupu.

Z okresem dochodzą pola periodFrom, periodTo, periodOrdersCount i periodRevenueByCurrency obok pól z całego życia (ordersCount, revenue, lifetimeRevenue, firstOrderAt, lastOrderAt), nigdy zamiast nich. Wartości z całego życia nie zmieniają się wraz z okresem.

Pieniądze zawsze według walut

Obrót, średnia wartość zamówienia i LTV to pole według walut, nigdy jedna liczba. Klient z zamówieniami w EUR i w CZK ma dwie pozycje; zsumowanie ich w jeden skalar oznaczałoby dodanie koron do euro. To samo dotyczy /customers/performance: wiersz to para (klient, waluta), a sumy filtra to totals.revenueByCurrency.

Język i płeć marketingowa

language to język e-shopu, w którym klient zamówił (source: "store_locale"), a nie jego własny wybór. Aplikacja nie ewidencjonuje dziś jawnej preferencji językowej klienta.
marketingGender (male / female / unknown) to szacunek na podstawie imienia, a nie dana, którą podał klient. Pochodzenie jest zawsze w genderSource (dziś wyłącznie name_inference lub unknown), a wiarygodność w genderConfidence. Klient firmowy nie ma tego pola. Kto wyświetla je dalej, powinien mówić „szacunek według imienia”, nigdy „klient podał”. Wymaga personal-data:read, tak samo jak samo imię.

E-shop

Wywołania dotyczące danych jednego e-shopu wymagają jego kodu w parametrze market. Listę kodów zwraca GET /stores.

Gdy klucz nie ma zakresu dla danego e-shopu, odpowiedź to 403, a nie pusta lista. Pustej listy nie dałoby się odróżnić od e-shopu bez zamówień. Rekord innego e-shopu (na przykład przesyłka) to 404.

Błędy

Odpowiedź z błędem ma zawsze ten sam kształt i zawiera kod. Lista stanów i kodów jest w Przeglądzie.

Przykłady

# Zamówienia za okres, według stron
curl -H "Authorization: Bearer <klucz API>" \
  "https://<adres aplikacji>/api/v1/orders?market=sk&from=2026-08-01&to=2026-08-31&limit=50"

# Statystyki doręczeń za sierpień
curl -H "Authorization: Bearer <klucz API>" \
  "https://<adres aplikacji>/api/v1/shipping/stats?market=sk&from=2026-08-01&to=2026-08-31"

# Przesyłki jednego przewoźnika za sierpień
curl -H "Authorization: Bearer <klucz API>" \
  "https://<adres aplikacji>/api/v1/shipping/shipments?market=sk&from=2026-08-01&to=2026-08-31&carrier=dhl"

# Podsumowanie finansowe sierpnia (z uprawnieniem do cen zakupu także zysk brutto)
curl -H "Authorization: Bearer <klucz API>" \
  "https://<adres aplikacji>/api/v1/reports/financial-summary?market=sk&from=2026-08-01&to=2026-08-31"

# Stan zapasu trzech pozycji
curl -H "Authorization: Bearer <klucz API>" \
  "https://<adres aplikacji>/api/v1/inventory/availability?market=sk&codes=A100,A101,A102"

# Słownik dostępności e-shopu
curl -H "Authorization: Bearer <klucz API>" \
  "https://<adres aplikacji>/api/v1/availabilities?market=sk"