Przejdź do głównej zawartości

Zwroty

Zwrot w Sellrocket to osobny obiekt powiązany z zamówieniem, a nie tylko status zamówienia. Ma własne statusy, powody, statusy poszczególnych pozycji i własne przesyłki. Dzięki temu np. system magazynowy może potwierdzać przyjęcie każdej zwróconej pozycji osobno, a obsługa klienta prowadzić zwrot niezależnie od procesu zamówienia.

Element Opis Endpointy
Zwrot orderId (zamówienie pierwotne), returnStatusId, fulfillmentStatus, pozycje, płatności, przesyłki, referenceNumber, additionalField1/2, pola elastyczne Lista, szczegóły
Statusy zwrotów Definiowane per instancja (nazwa, kolor, groupId); jeden z nich jest domyślny dla nowych zwrotów GET /api/v3/returns/statuses/all
Grupy statusów Drzewo — grupa może mieć rodzica (parentId) GET /api/v3/returns/status-groups
Statusy pozycji Stan pojedynczej pozycji (np. „Przyjęto na magazyn”, „Uszkodzony”); opcjonalnie powiązany z magazynem (warehouseId) GET /api/v3/returns/positions/statuses
Powody zwrotu Słownik wielojęzyczny (names[] z language i name) GET /api/v3/returns/reasons
Przesyłki zwrotne Przesyłki przypisane do zwrotu GET /api/v1/Returns/{returnId}/Shipments

Pole fulfillmentStatus opisuje etap realizacji zwrotu: aktywny, zaakceptowany, zakończony, anulowany (Active, Accepted, Done, Canceled). W API jest przekazywane jako wartość liczbowa.

Statusy, grupy, statusy pozycji i powody możesz zakładać przez API (POST na tych samych ścieżkach) — przydatne, gdy integracja wymaga własnego słownika, np. statusów pozycji dla magazynu. Operacje zapisu są asynchroniczne.

  • Z marketplace’u — zwroty zgłoszone np. na Allegro trafiają do Sellrocket przez połączenie z tym kanałem.
  • Z zamówienia — obsługa lub Twoja integracja tworzy zwrot dla wybranych pozycji zamówienia: POST /api/v3/returns/fromOrder. Dane kupującego i pozycji są przenoszone z zamówienia.
  • Po numerze zamówienia z kanału sprzedaży — POST /api/v4/returns (platformOrderId, platformReturnId, pozycje i paczki zwrotne).

Przykład — zwrot jednej pozycji z zamówienia:

Okno terminala
curl -X POST "https://$SR_INSTANCE-smerp-api.enterprise.sellrocket.pl/api/v3/returns/fromOrder" \
-H "Authorization: Bearer $SR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"orderId": 204295,
"orderLineItems": [
{ "id": 991, "quantity": 1, "returnsReasonId": 3, "clientNote": "Pęknięte ucho kubka" }
],
"returnParams": {
"referenceNumber": "RMA-2026-0117",
"returnStatusId": 21,
"buyerComment": "Proszę o zwrot środków na konto"
}
}'

orderLineItems[].id to ID pozycji zamówienia. Wynik sprawdzisz w zadaniu, a zwroty zamówienia pobierzesz przez GET /api/v3/returns/GetByOrderId/{id}.

Typowy scenariusz: magazyn potwierdza przyjęcie towaru

Dział zatytułowany „Typowy scenariusz: magazyn potwierdza przyjęcie towaru”
  1. Przygotuj słownik. Pobierz statusy pozycji (GET /api/v3/returns/positions/statuses) i statusy zwrotów. Jeśli brakuje potrzebnych (np. „Przyjęto — pełnowartościowy”, „Przyjęto — uszkodzony”), załóż je przez POST, z warehouseId magazynu.

  2. Znajdź zwrot. Gdy paczka dotrze do magazynu, wyszukaj zwrot po numerze przesyłki lub zamówieniu: GET /api/v4/returns z ShipmentsTrackingNumber, OrderId albo ReturnId.

  3. Pobierz pozycje z ich ID. GET /api/v3/returns/{id} zwraca pozycje razem z id potrzebnym do ich aktualizacji.

  4. Ustaw status każdej pozycji — PUT /api/v3/returns/{returnId}/lineItems/{returnLineItemId} z returnsPositionStatusId (i ewentualnie returnsReasonId).

  5. Przesuń zwrot dalej — gdy wszystkie pozycje są obsłużone, zmień status zwrotu: PUT /api/v3/returns/status/bulk.

    { "returnIds": [5512], "targetStatusId": 24 }

Zmiana statusu zwrotu, tak jak w zamówieniach, może uruchomić automatyzacje — np. zwrot płatności czy e-mail do klienta.

  • Nie wpisuj ID statusów, powodów ani statusów pozycji na sztywno — każda instancja ma własne słowniki.
  • Dwa modele odczytu. GET /api/v4/returns/{returnId} zwraca rozszerzony model, ale bez id pozycji. Do aktualizacji pozycji użyj GET /api/v3/returns/{id}.
  • Aktualizacja pozycji — treść żądania obejmuje wszystkie pola pozycji. Najbezpieczniej wyślij dane odczytane chwilę wcześniej, zmieniając tylko status.
  • Powody zwrotu są wielojęzyczne — wybierz nazwę w języku, który pokazujesz użytkownikowi.
  • getOrderReturns → GET /api/v4/returns; addOrderReturn → POST /api/v4/returns lub POST /api/v3/returns/fromOrder.
  • setOrderReturnFields → PUT /api/v4/returns/{id}; setOrderReturnStatuses → PUT /api/v3/returns/status/bulk.
  • setOrderReturnProductFields → PUT /api/v3/returns/{returnId}/lineItems/{returnLineItemId}.
  • getOrderReturnStatusList → GET /api/v3/returns/statuses; getOrderReturnReasonsList → GET /api/v3/returns/reasons.