Wepnij zwroty w system, którego już używasz

Zobacz dokumentację · Załóż darmowe konto

Kiedy API ma sens

• Masz własny sklep i chcesz formularz zwrotu we własnym layoucie.
• Twój zespół pracuje w ERP albo WMS i nie chce przełączać się między systemami.
• Jesteś agencją lub integratorem i wpinasz zwroty u kilku klientów naraz.
• Sprzedajesz w kilku kanałach i chcesz mieć jeden widok po swojej stronie.

Szukasz gotowego narzędzia bez pisania kodu? RetJet działa też sam, przez panel. Zobacz funkcje, integracje i cennik.

Co możesz zrobić

Zgłoszenia. Załóż zwrot lub reklamację w imieniu klienta, pobierz listę spraw i szczegóły pojedynczej, zmień status w przepływie pracy.

Produkty z zamówienia. Znajdź pozycje, które klient może zwrócić: po e-mailu i numerze zamówienia, po telefonie i loginie Allegro albo po samym numerze przesyłki. Dane zamówienia pobierasz w momencie zgłoszenia, nie importujesz całej bazy na zapas. (Ten sam mechanizm z perspektywy sklepu, a nie kodu, opisujemy w Lekka integracja bez pobierania zamówień.)

Operacje masowe. Zmiana statusu, przypisanie opiekuna, gwiazdka: do 100 zgłoszeń w jednym wywołaniu. Zgłoszenia, których stan nie pozwala na zmianę, wracają w odpowiedzi zamiast zniknąć po cichu.

Kwota zwrotu. Zatwierdź albo skoryguj kwotę i walutę. Zaktualizuj pozycję w zgłoszeniu: potwierdzoną ilość i kwotę.

Rozmowa z klientem. Dodaj wiadomość widoczną dla klienta albo notatkę wewnętrzną. Dołącz zdjęcia i dokumenty: jako adresy URL albo dane base64.

Historia i zespół. Pobierz oś czasu zgłoszenia z filtrem po typie zdarzenia i widoczności. Ustaw termin rozpatrzenia, dopisz obserwatorów, oznacz sprawę etykietą.

Konfiguracja sklepu. Powody zwrotu, stany produktu, sposoby rozwiązania, punkty zwrotów i kanały sprzedaży: dokładnie tak, jak ustawił je sklep.

Pierwsze wywołanie w trzy kroki

1. Wygeneruj klucz w ustawieniach konta, sekcja API keys.
2. Dodaj nagłówek Authorization: Bearer <twój-klucz>.
3. Sprawdź połączenie: GET /v1/sale-channels zwraca Twoje kanały sprzedaży.

Klucz należy do firmy, nie do konta osoby, która go utworzyła. Integracja nie przestanie działać, gdy pracownik odejdzie.

Nie widzisz sekcji API keys w ustawieniach? Napisz do nas, włączymy dostęp.

Na czym możesz polegać

Limity są jawne. 60 żądań w serii, odnawiane w tempie 60 na minutę, oraz 10 000 żądań na dobę na klucz. Każda odpowiedź niesie X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset dla limitu, który jest bliżej wyczerpania. Odmowa niesie Retry-After z czasem oczekiwania.

Każde żądanie ma identyfikator. Nagłówek X-Request-Id w odpowiedzi. Podaj go w zgłoszeniu do nas, a znajdziemy dokładnie to wywołanie w logach.

Paginacja bez zgadywania. Kolekcje zwracają X-Total-Count, X-Total-Pages, X-Page i X-Per-Page, a nagłówek Link niesie relację rel="next". Domyślnie 30 rekordów na stronę, maksymalnie 100.

Specyfikacja zamiast opisu. Pełny OpenAPI 1.0.0 w JSON i YAML, do tego Swagger UI i ReDoc. Wygeneruj z niego klienta w swoim języku.

Biblioteka PHP: pierwszy oficjalny klient

Nie musisz pisać warstwy HTTP od zera. Wydaliśmy oficjalną bibliotekę PHP, na razie w wersji beta.

composer require retjet/returns-api-php-client:^0.1@beta

use RetJetApi\Returns\Client;

$client = Client::create('TWOJ_KLUCZ_API');
$rma = $client->rmaRequests()->get(1234);
echo $rma->identifier;

Wymaga PHP 8.2 i dowolnej implementacji PSR-18/PSR-17 (Guzzle, Symfony HTTP Client lub inny, jakiego używasz w projekcie). Licencja MIT, kod na GitHubie: RetJet/returns-api-php-client.

Beta znaczy beta: API biblioteki może się jeszcze zmienić przed 1.0. Samo API RetJeta jest stabilne w wersji v1. Bibliotekę traktuj jako wygodę, nie jako warunek integracji. Zgłoszenia i pull requesty w repozytorium czytamy.

Piszesz w innym języku? Wygeneruj klienta ze specyfikacji OpenAPI albo napisz do nas: kolejność kolejnych bibliotek ustalamy na podstawie zgłoszeń.

Zanim zaczniesz pisać kod

Trzy rzeczy, o których lepiej wiedzieć od razu.

Klucz trzymaj po stronie serwera. Daje odczyt i zapis wszystkich zwrotów firmy. API nie zwraca nagłówków CORS, więc przeglądarka i tak nie zawoła go bezpośrednio. Wywołania idą z Twojego backendu.

Lista zgłoszeń ma paginację, nie ma filtrów. GET /v1/rma-requests przyjmuje page i limit. Jeśli budujesz własne widoki po statusie albo po kliencie, zapisuj identyfikatory zgłoszeń u siebie w momencie tworzenia: POST zwraca pełne zgłoszenie z id, uuid i identifier.

Dziś to zwroty i reklamacje. Wysyłki i śledzenie paczek dołączą pod tym samym adresem bazowym, wersjonowane osobno. To, co napiszesz teraz, nie przestanie działać.

Częste pytania

Czy muszę zaimportować zamówienia do RetJeta? Nie. Dane zamówienia pobierasz w momencie, w którym klient zgłasza zwrot, przez GET /v1/ordered-products. Nie ma synchronizacji całej bazy na zapas.

Po czym mogę znaleźć zamówienie? Po e-mailu razem z numerem zamówienia, po telefonie razem z loginem Allegro albo po samym numerze przesyłki.

Czy mogę wywołać API z przeglądarki, prosto z formularza na stronie? Nie. API nie zwraca nagłówków CORS, a klucz daje pełny dostęp do zwrotów firmy. Formularz rozmawia z Twoim serwerem, serwer z API RetJeta.

Co się stanie z integracją, gdy odejdzie osoba, która ją stawiała? Nic. Klucze są przypisane do firmy, nie do konta użytkownika.

W jakim formacie odpowiada API? JSON. Pełna specyfikacja jest w standardzie OpenAPI, z interfejsem Swagger UI i ReDoc.

Czy API zastępuje panel RetJeta? Nie, pracuje obok niego. Zgłoszenie założone przez API widać w panelu i odwrotnie.

Czy jest gotowa biblioteka do mojego języka? Na razie PHP: retjet/returns-api-php-client na Packagiście, w wersji beta, na licencji MIT. Dla pozostałych języków wygenerujesz klienta ze specyfikacji OpenAPI.

Ile kosztuje dostęp do API?

Zamknięcie

Dokumentacja jest publiczna. Zajrzyj do niej, zanim założysz konto: zobaczysz dokładnie, co API robi i czego nie robi.

Zobacz dokumentację API · Załóż darmowe konto