Dostęp partnerski do API (/api/v1/external/*)
Ta strona opisuje partnerskie API HTTP platformy: osobną przestrzeń /api/v1/external/*. To
jedyna przestrzeń przeznaczona dla partnerów zewnętrznych (dystrybutorów, resellerów, systemów
zakupowych) i jedyna część dokumentu OpenAPI na żywo (GET /api/v1/_openapi.json), która jest
dokumentowana dla partnerów. Publiczne endpointy storefrontu (/api/v1/catalog/…) i endpointy sesji
klienta (/api/v1/orders…) nie są API partnerskim — całkowicie ignorują klucze API.
Uwierzytelnianie
Każde żądanie do /api/v1/external/* musi zawierać token bearer klucza API:
GET /api/v1/external/catalog/products?limit=50 HTTP/1.1
Host: api.example.com
Authorization: Bearer sk_live_REDACTED
- Żądania anonimowe dostają
401 UNAUTHORIZED. - Klucze unieważnione i wygasłe wszędzie dostają
401 UNAUTHORIZED. - Klucz bez wymaganego zakresu dostaje
403 API_KEY_OUT_OF_SCOPE(zapisywane w audycie).
Klucze tworzy się w Panel administracyjny → API Keys. Token jest pokazywany tylko raz, przy utworzeniu; przechowywany jest wyłącznie jego skrót SHA-256.
Dwa rodzaje kluczy
| Klucz niepowiązany | Klucz powiązany | |
|---|---|---|
| Tożsamość | Dane uwierzytelniające platformy (kontekst systemowy) | Działa w imieniu jednej organizacji, w jednym przypiętym kanale sprzedaży, przez wskazane techniczne konto klienta |
| Typowe zastosowanie | Synchronizacja PIM, generowanie feedów | Integracja dystrybutora: katalog z cenami organizacji, składanie zamówień |
| Odczyty katalogu | Ceny kanału dla wszystkich (bez organizacji); kanał z nagłówka X-Sales-Channel, hosta albo domyślny | Ceny obowiązujące organizację, dostępność i progi ilościowe; zawsze powiązany kanał |
| Ceny hurtowe / zamówienia | Odmowa (403 API_KEY_NOT_BOUND) | Dozwolone z odpowiednim zakresem |
| Dozwolone zakresy | catalog:read, catalog:write | catalog:read, orders:read, orders:write (catalog:write jest zabronione dla kluczy powiązanych) |
| Ważność | Opcjonalne expiresAt | Opcjonalne expiresAt |
Powiązania (organizacja, kanał sprzedaży i techniczne konto klienta) nie można zmienić po
utworzeniu — aby powiązać klucz inaczej, unieważnij go i utwórz nowy. Reguły tworzenia opisuje
dokumentacja modułu api_keys.
Katalog zakresów
| Zakres | Klucz niepowiązany | Klucz powiązany |
|---|---|---|
catalog:read | Odczyty zewnętrznego API katalogu (ceny kanału dla wszystkich) i odczyty zestawów atrybutów PIM | Odczyty zewnętrznego API katalogu (ceny organizacji) i ceny hurtowe |
catalog:write | Zapis produktu w PIM według SKU | Nie można przyznać (reguła tworzenia) |
orders:read | Nie można przyznać bez powiązania | Lista i szczegóły zamówień przez zewnętrzne API |
orders:write | Nie można przyznać bez powiązania | Składanie zamówień przez zewnętrzne API |
platform.api_description.read | Opis API (GET /api/v1/_openapi.json) | Opis API (GET /api/v1/_openapi.json) |
Przypięcie kanału (klucze powiązane)
Klucz powiązany zawsze działa w powiązanym kanale sprzedaży. Nagłówek X-Sales-Channel wskazujący
inny kanał jest odrzucany z 403 API_KEY_CHANNEL_MISMATCH (i zapisywany w audycie). Gdy
powiązany kanał jest nieaktywny, żądania są odrzucane standardowym błędem nieaktywnego kanału — bez
przełączania na inny kanał.
Zasada dotycząca pamięci podręcznej (wiążąca)
Każda odpowiedź z /api/v1/external/* ma nagłówek:
Cache-Control: private, no-store
Odpowiedzi zależą od danych uwierzytelniających (ceny organizacji, dane zamówień) i nigdy nie wolno ich umieszczać we współdzielonej ani trwałej pamięci podręcznej. Nie przechowuj ich po swojej stronie dłużej niż trwa żądanie, które je zwróciło; pobieraj je ponownie.
Odczyty katalogu
Wymagany zakres: catalog:read.
GET /api/v1/external/catalog/products— lista stronicowana (limit1–100,cursor), filtrycategorySlug,qichangedSince(ISO 8601). Zwracana deterministycznie z PostgreSQL (x-search-backend: postgres).GET /api/v1/external/catalog/products/:idOrSlug— szczegóły; dla kluczy powiązanych zawierająpriceTiers(drabinę progów ilościowych organizacji: cenę przy każdej ilości, od której zaczyna się próg jednego z cenników, które jej dotyczą).GET /api/v1/external/catalog/categories— drzewo kategorii wyznaczonego kanału.
Wywołujący z kluczem powiązanym widzą opublikowany asortyment powiązanego kanału dokładnie tak jak
storefront; produkty wykluczone z kanału nie występują, a ich adresy szczegółów zwracają 404 — tak
samo jak dla nieistniejących. Pozycje zwracane dla klucza powiązanego zawierają dodatkowo:
price— cenę jednostkową obowiązującą organizację przy ilości 1, obliczoną tą samą wyceną z cenników co w koszyku (null, gdy żaden cennik nie wycenia produktu dla tej organizacji);priceUnavailable: true— znacznik, gdy nie udało się wyznaczyć ceny organizacji;availability—{ band, inStock }.
Synchronizacja przyrostowa z changedSince
Przy pełnym eksporcie przechodź przez strony z cursor, aż się skończą. Przy synchronizacji
przyrostowej pytaj z changedSince=<początek ostatniej udanej synchronizacji>. Zawsze stosuj
nakładające się okna: zapisz znacznik czasu przed rozpoczęciem synchronizacji i przekaż go w
następnym przebiegu, aby nie pominąć zmian dokonanych w trakcie przebiegu. Usuwaj duplikaty według
identyfikatora produktu.
Ceny hurtowe
Wymagany zakres: catalog:read, tylko klucze powiązane.
POST /api/v1/external/catalog/prices
{ "lines": [ { "sku": "SKU-1", "quantity": 10 }, … ] } // 1–200 lines
Odpowiedź zachowuje kolejność pozycji. Każda pozycja ma albo cenę (amount, currency, isSale,
bracketStartQuantity, priceListId), albo price: null z reason równym
sku_not_in_assortment lub price_unavailable. priceListId to cennik, który wycenił pozycję, a
bracketStartQuantity — ilość, od której zaczyna się jej próg ilościowy; nazwy pól pochodzą sprzed
obecnych cenników i zostały zachowane dla zgodności. Pozycja wskazuje SKU produktu; SKU wariantu nie
jest wyszukiwane i daje sku_not_in_assortment. Braki w pojedynczych pozycjach to dane, a nie
błędy — zawsze dostajesz odpowiedź dla całego zestawu. Ponad 200 pozycji to 422 VALIDATION_FAILED.
Gwarancja: dla dowolnej pary (sku, quantity) zwrócona kwota jest równa, co do grosza, kwocie, którą
koszyk i składanie zamówienia naliczyłyby powiązanej organizacji w powiązanym kanale przy tej ilości.
Cena jest wyceniana dla organizacji i jej grupy klientów; własna grupa klientów powiązanego konta
serwisowego, jeśli ją ma, nie jest tu stosowana.
Idempotentne składanie zamówień
Wymagany zakres: orders:write, tylko klucze powiązane.
POST /api/v1/external/orders
Idempotency-Key: acme-order-1001
{
"lines": [ { "sku": "SKU-1", "quantity": 10 } ],
"deliveryMethodId": "…", "paymentMethodId": "…",
"deliveryAddressId": "…", "billingAddressId": "…",
"customerReference": "PO-2026-0042"
}
- Nagłówek
Idempotency-Key(1–128 znaków) jest wymagany; jego brak ⇒422 IDEMPOTENCY_KEY_REQUIRED. - Ponowne wysłanie tego samego klucza z tą samą treścią — także równoległe — zwraca to samo
zamówienie (
200); zawsze powstaje dokładnie jedno zamówienie. - Ponowne użycie klucza z inną treścią ⇒
409 IDEMPOTENCY_KEY_REUSED. - Adresy: podaj identyfikatory istniejących adresów organizacji albo obiekty
deliveryAddress/billingAddressbezpośrednio w treści. - Odrzucenie pojedynczych pozycji daje odpowiedź
422 ORDER_INTAKE_LINES_REFUSEDdla całego zamówienia, którejdetailsto tablica problemów przy każdej pozycji ({ path, issue, sku },issueSKU_NOT_IN_ASSORTMENTalboPRICE_UNAVAILABLE); nic nie zostaje zapisane. Do zgłoszenia #627 kodem byłoVALIDATION_FAILED; tablica się nie zmieniła. - Inne przyjmowanie zamówienia dla tego samego klucza wciąż trwa ⇒
409 ORDER_INTAKE_BUSY. Ponów żądanie z tym samymIdempotency-Key: ponowienie trafi na zamówienie złożone przez to drugie przyjmowanie. Do zgłoszenia #627 była to odpowiedź409 VALIDATION_FAILEDzdetails.codeintake_busy, którego już nie ma. - Pozycja, której SKU należy do asortymentu kanału, ale której produkt nie jest teraz dostępny dla
Twojej organizacji w tym kanale — wyłączony w kanale, zarchiwizowany, poza oknem publikacji albo
ograniczony do innych klientów — odrzuca całe zamówienie odpowiedzią
404 PRODUCT_NOT_FOUND, bez nazwy produktu; nic nie zostaje zapisane. To sprawdzenie następuje po sprawdzeniu pozycji, więc422ma pierwszeństwo. Różnica między tymi odpowiedziami jest zamierzona: klucz jest powiązany z jedną organizacją i jednym kanałem — Twoją własną integracją — a numery SKU są zwykle publiczne. - Odpowiedź po powodzeniu (
201) to standardowa struktura zamówienia — taka sama jak w sesjach klientów. Zamówienia można śledzić przezGET /api/v1/external/ordersiGET /api/v1/external/orders/:id(orders:read); identyfikatory spoza zakresu widoczności zwracają404.
Granice możliwości organizacji
Klucz powiązany nigdy nie może zrobić więcej niż kupujący z danej organizacji. Zamówienie składa ta
sama ścieżka kodu domenowego, więc każda reguła działa identycznie: zawieszona organizacja ⇒ 423;
metoda płatności albo dostawy spoza listy dozwolonych dla organizacji ⇒ ta sama odmowa co w checkoucie
klienta (400 ORDER_PAYMENT_METHOD_UNAVAILABLE albo 400 ORDER_DELIVERY_METHOD_UNAVAILABLE,
error.details.code payment_method_not_allowed_for_organization albo
delivery_method_not_allowed_for_organization); przekroczony limit kredytowy ⇒ ten sam błąd zabezpieczenia limitu; minimalna wartość
zamówienia, asortyment, strategia magazynowa i automatyczne promocje działają dokładnie tak jak w
storefroncie. Nie ma parametru, który by to nadpisywał lub omijał.
Webhooki (ograniczone do organizacji)
Zdarzenia zamówień są wysyłane do subskrypcji webhooków (transport, weryfikację HMAC i zasady ponawiania opisuje przegląd integracji). Dla partnerów istotne są dwa fakty:
- Subskrypcję można ograniczyć do jednej organizacji (ustaw opcjonalną organizację w formularzu
webhooka). Subskrypcje ograniczone do organizacji dostają tylko zdarzenia
order.created.v1/order.status_changed.v1tej organizacji; subskrypcje obejmujące całą platformę (bez organizacji) dostają wszystkie. Zdarzenie bez przypisanej organizacji nigdy nie trafia do subskrypcji ograniczonej do organizacji (w razie wątpliwości — odmowa). - Wysyłka już działa. Subskrypcje webhooków zarejestrowane, zanim ta funkcja powstała, były
przyjmowane, ale zdarzenia zamówień nie były wysyłane. Mechanizm wysyłki już działa: każda
istniejąca subskrypcja zdarzeń
order.created.v1luborder.status_changed.v1zacznie je otrzymywać. Przed aktualizacją upewnij się, że odbiorcy są idempotentni.
Słownik błędów (API partnerskie)
| Kod | HTTP | Znaczenie |
|---|---|---|
UNAUTHORIZED | 401 | Brak klucza albo klucz nieprawidłowy, unieważniony lub wygasły |
API_KEY_OUT_OF_SCOPE | 403 | Kluczowi brakuje wymaganego zakresu (zapisywane w audycie) |
API_KEY_NOT_BOUND | 403 | Endpoint tylko dla kluczy powiązanych wywołany kluczem niepowiązanym |
API_KEY_CHANNEL_MISMATCH | 403 | Klucz powiązany wskazał inny kanał sprzedaży |
IDEMPOTENCY_KEY_REQUIRED | 422 | Brak Idempotency-Key przy składaniu zamówienia |
IDEMPOTENCY_KEY_REUSED | 409 | Ten sam klucz idempotencji, inna treść |
ORDER_INTAKE_BUSY | 409 | Trwa inne przyjmowanie zamówienia dla tego klucza; ponów z tym samym Idempotency-Key |
ORDER_INTAKE_LINES_REFUSED | 422 | Odrzucono co najmniej jedną pozycję; details podaje problem każdej pozycji |
SKU_NOT_IN_ASSORTMENT | 422 (dla pozycji) | SKU nie występuje w asortymencie powiązanego kanału |
PRICE_UNAVAILABLE | 422 (dla pozycji) | Nie da się wyznaczyć ceny dla organizacji |
PRODUCT_NOT_FOUND | 404 | Produkt z asortymentu nie jest teraz dostępny dla organizacji w kanale |
STOCK_UNAVAILABLE | 409 | Niewystarczający stan magazynowy przy składaniu zamówienia |
FORBIDDEN (organization_cannot_transact) | 423 | Organizacja jest zawieszona albo nie może składać zamówień |