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.
Jak to działa
Dział zatytułowany „Jak to działa”| 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.
Skąd biorą się zwroty
Dział zatytułowany „Skąd biorą się zwroty”- 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:
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”-
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 przezPOST, zwarehouseIdmagazynu. -
Znajdź zwrot. Gdy paczka dotrze do magazynu, wyszukaj zwrot po numerze przesyłki lub zamówieniu:
GET /api/v4/returnszShipmentsTrackingNumber,OrderIdalboReturnId. -
Pobierz pozycje z ich ID.
GET /api/v3/returns/{id}zwraca pozycje razem zidpotrzebnym do ich aktualizacji. -
Ustaw status każdej pozycji —
PUT /api/v3/returns/{returnId}/lineItems/{returnLineItemId}zreturnsPositionStatusId(i ewentualniereturnsReasonId). -
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.
Śledzenie zmian
Dział zatytułowany „Śledzenie zmian”- Lista z filtrem
StatusUpdatedFrom(iCreatedDateFromdla nowych zwrotów) — ten sam wzorzec co w Pobieraniu zamówień. - Historia statusów:
GET /api/v4/returns/{returnId}/statusHistory; zdarzenia:GET /api/v4/returns/{returnId}/events; historia zmian:GET /api/v4/returns/{returnId}/history/flatten. - Pola elastyczne zwrotu i pozycji dołączysz do listy parametrami
IncludeElasticFieldsiIncludeLineItemsElasticFields.
Na co uważać
Dział zatytułowany „Na co uważać”- 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 bezidpozycji. Do aktualizacji pozycji użyjGET /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.
Odpowiedniki w BaseLinker
Dział zatytułowany „Odpowiedniki w BaseLinker”getOrderReturns→GET /api/v4/returns;addOrderReturn→POST /api/v4/returnslubPOST /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.

