Przejdź do głównej zawartości

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ązanyKlucz 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 zastosowanieSynchronizacja PIM, generowanie feedówIntegracja dystrybutora: katalog z cenami organizacji, składanie zamówień
Odczyty kataloguCeny kanału dla wszystkich (bez organizacji); kanał z nagłówka X-Sales-Channel, hosta albo domyślnyCeny obowiązujące organizację, dostępność i progi ilościowe; zawsze powiązany kanał
Ceny hurtowe / zamówieniaOdmowa (403 API_KEY_NOT_BOUND)Dozwolone z odpowiednim zakresem
Dozwolone zakresycatalog:read, catalog:writecatalog:read, orders:read, orders:write (catalog:write jest zabronione dla kluczy powiązanych)
WażnośćOpcjonalne expiresAtOpcjonalne 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​

ZakresKlucz niepowiązanyKlucz powiązany
catalog:readOdczyty zewnętrznego API katalogu (ceny kanału dla wszystkich) i odczyty zestawów atrybutów PIMOdczyty zewnętrznego API katalogu (ceny organizacji) i ceny hurtowe
catalog:writeZapis produktu w PIM według SKUNie można przyznać (reguła tworzenia)
orders:readNie można przyznać bez powiązaniaLista i szczegóły zamówień przez zewnętrzne API
orders:writeNie można przyznać bez powiązaniaSkładanie zamówień przez zewnętrzne API
platform.api_description.readOpis 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 (limit 1–100, cursor), filtry categorySlug, q i changedSince (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 / billingAddress bezpośrednio w treści.
  • Odrzucenie pojedynczych pozycji daje odpowiedź 422 ORDER_INTAKE_LINES_REFUSED dla całego zamówienia, której details to tablica problemów przy każdej pozycji ({ path, issue, sku }, issue SKU_NOT_IN_ASSORTMENT albo PRICE_UNAVAILABLE); nic nie zostaje zapisane. Do zgłoszenia #627 kodem było VALIDATION_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 samym Idempotency-Key: ponowienie trafi na zamówienie złożone przez to drugie przyjmowanie. Do zgłoszenia #627 była to odpowiedź 409 VALIDATION_FAILED z details.code intake_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ęc 422 ma 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ć przez GET /api/v1/external/orders i GET /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.v1 tej 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.v1 lub order.status_changed.v1 zacznie je otrzymywać. Przed aktualizacją upewnij się, że odbiorcy są idempotentni.

Słownik błędów (API partnerskie)​

KodHTTPZnaczenie
UNAUTHORIZED401Brak klucza albo klucz nieprawidłowy, unieważniony lub wygasły
API_KEY_OUT_OF_SCOPE403Kluczowi brakuje wymaganego zakresu (zapisywane w audycie)
API_KEY_NOT_BOUND403Endpoint tylko dla kluczy powiązanych wywołany kluczem niepowiązanym
API_KEY_CHANNEL_MISMATCH403Klucz powiązany wskazał inny kanał sprzedaży
IDEMPOTENCY_KEY_REQUIRED422Brak Idempotency-Key przy składaniu zamówienia
IDEMPOTENCY_KEY_REUSED409Ten sam klucz idempotencji, inna treść
ORDER_INTAKE_BUSY409Trwa inne przyjmowanie zamówienia dla tego klucza; ponów z tym samym Idempotency-Key
ORDER_INTAKE_LINES_REFUSED422Odrzucono co najmniej jedną pozycję; details podaje problem każdej pozycji
SKU_NOT_IN_ASSORTMENT422 (dla pozycji)SKU nie występuje w asortymencie powiązanego kanału
PRICE_UNAVAILABLE422 (dla pozycji)Nie da się wyznaczyć ceny dla organizacji
PRODUCT_NOT_FOUND404Produkt z asortymentu nie jest teraz dostępny dla organizacji w kanale
STOCK_UNAVAILABLE409Niewystarczający stan magazynowy przy składaniu zamówienia
FORBIDDEN (organization_cannot_transact)423Organizacja jest zawieszona albo nie może składać zamówień