Przejdź do treści
Premium Supply Developer

Co nowego

Changelog Seller API

Każdy wpis ma datę, typ i listę zasobów, których dotyczy. Zmiany niekompatybilne ogłaszamy tutaj z wyprzedzeniem i oznaczamy wprost — najpierw zapowiedź z datą, potem potwierdzenie w dniu wejścia w życie.

Zasady wersjonowania#

  • Wersja w ścieżce (/v1/), nie w nagłówku. Zmienia się wyłącznie przy zmianie łamiącej zgodność; do tego czasu /v1/ jest stabilne.
  • Zmiany zgodne wstecz wchodzą bez zapowiedzi: nowe pola w odpowiedziach, nowe opcjonalne parametry, nowe zasoby, nowe zdarzenia webhooków, nowe wartości w polach opisanych jako rozszerzalne. Twój klient musi ignorować nieznane pola.
  • Zmiany niekompatybilne (usunięcie pola, zmiana typu, zaostrzenie walidacji, wyłączenie zasobu) — wpis z etykietą „Zmiana niekompatybilna” i datą wejścia w życie, wcześniej niż data. Stara wersja działa równolegle przez okres przejściowy podany we wpisie.
  • Kontrakt OpenAPI w Dokumentacji zawsze opisuje bieżący stan; historia zmian jest tutaj.

Webhooki i przegląd bezpieczeństwa#

Nowe

Dostarczanie webhooków uruchomione (podpis HMAC-SHA256, ponowienia 1 min–12 h, historia dostarczeń). Po adwersarialnym przeglądzie bezpieczeństwa wzmocniono OAuth i bramkę API.

  • Webhooki: order.created, order.paid, order.shipped, order.delivered, order.cancelled, offer.rejected; GET/POST /v1/webhooks, DELETE /v1/webhooks/{id}, GET /v1/webhooks/{id}/deliveries (zakresy settings:read / settings:write).
  • OAuth: limit 30 żądań/min per IP i 60/min per client_id na /oauth/token; refresh_token wymaga, by token należał do przedstawiającej go aplikacji; ponowne użycie zużytego refresh tokenu odwołuje całą rodzinę.
  • Zakresy tokenu są przecinane z AKTUALNYMI zakresami aplikacji — zwężenie uprawnień w panelu działa wstecz.
  • Idempotency-Key zakresowany per sprzedawca, z odciskiem metody, ścieżki i ciała: inne ciało → 422 idempotency_key_reused, żądanie w trakcie → 409 idempotency_in_progress.
  • PATCH /v1/offers/{id}: oferta w moderacji (proposed/rejected) → 422 status_locked_by_moderation.
  • POST /v1/orders/{id}/shipments: zamówienie z towarem innego sprzedawcy → 409 multi_seller_order; odpowiedź zawiera item_ids.
  • Dane kupującego wyłącznie po opłaceniu — także w zamówieniach anulowanych bez zapłaty.
  • Kontrakt OpenAPI 3.1 bez `nullable` (typy tablicowe), schemat OAuthError dla /oauth/*, pełna lista kodów błędów w ErrorCode.

Zasoby

  • GET /v1/webhooks
  • POST /v1/webhooks
  • DELETE /v1/webhooks/{id}
  • GET /v1/webhooks/{id}/deliveries

Seller API v1 — start#

Nowe

Pierwsza wersja publicznego API dla sprzedawców i integratorów. Jeden kontrakt OpenAPI 3.1, wersja w ścieżce (/v1/), OAuth 2.0 jako dostawca, limity widoczne w nagłówkach każdej odpowiedzi.

  • OAuth 2.0: client_credentials (własne skrypty), authorization_code + PKCE S256 (integratorzy), refresh_token z rotacją. Access token 12 h, refresh 90 dni, kod 10 min.
  • GET /v1/me — sprzedawca, aplikacja i zakresy bieżącego tokenu.
  • GET /v1/offers, GET /v1/offers/{id}, PATCH /v1/offers/{id} — cena (grosze, PLN), stan, status published/draft.
  • GET /v1/orders, GET /v1/orders/{id} — tylko pozycje sprzedawcy; dane kupującego po opłaceniu.
  • POST /v1/orders/{id}/shipments — zgłoszenie wysyłki z powiadomieniem kupującego.
  • Nagłówki X-RateLimit-Limit / -Remaining / -Reset w każdej odpowiedzi i Retry-After przy 429; limit 600 żądań/min na aplikację.
  • Idempotency-Key na POST/PATCH/DELETE (odpowiedź pamiętana 24 h, powtórka oznaczona nagłówkiem Idempotent-Replayed).
  • Paginacja kursorowa (limit ≤ 200, kursor w polu next), wybór pól ?fields=, jeden kształt błędu {traceId, errors[]} z katalogiem kodów na /errors.
  • Wymagany nagłówek User-Agent w formacie NazwaAplikacji/Wersja (+https://adres-dokumentacji).

Zasoby

  • POST /oauth/token
  • GET /oauth/authorize
  • GET /v1/me
  • GET /v1/offers
  • GET /v1/offers/{id}
  • PATCH /v1/offers/{id}
  • GET /v1/orders
  • GET /v1/orders/{id}
  • POST /v1/orders/{id}/shipments