Obsługa wersji

Z tego przewodnika dowiesz się, jak interfejs Merchant API obsługuje wersjonowanie, wydania i cykl życia różnych wersji.

Schemat wersji

Interfejs Merchant API stosuje strategię wersjonowania na poziomie interfejsu API. Oznacza to, że każdy interfejs Merchant API, np. Produkty w interfejsie Merchant API, będzie miał własny cykl życia wersji.

Formatowanie i prezentacja wersji

• Stabilne wersje podrzędnych interfejsów API: jeśli podrzędny interfejs API jest w stabilnej wersji, wszystkie jego metody są w stabilnej wersji. Stabilna wersja podrzędna interfejsu API jest oznaczana jako vX (np. v1, v2). Są to główne wersje gotowe do wdrożenia w środowisku produkcyjnym.

• Wersje podrzędne interfejsu API w wersji alfa: jeśli podrzędny interfejs API jest w wersji alfa, wszystkie jego metody są w wersji alfa. Wersja podrzędna interfejsu API w wersji alfa jest oznaczona jako vXalpha (np. v1alpha, v2alpha). Zawiera ona eksperymentalne funkcje w ramach wczesnego dostępu, które są przeznaczone do testowania i szybkiego wprowadzania zmian. Wersje alfa nie zapewniają stabilności, nie mają określonego okresu użytkowania i mogą zostać zmienione lub wycofane z 30-dniowym wyprzedzeniem.

Zmiany wersji

• Zwiększenie numeru wersji głównej (np. z wersji 1 na wersję 2): sygnalizuje zmiany powodujące niezgodności wsteczne i zmiany, które wymagają działania ze strony dewelopera. Tylko zmiany powodujące niezgodności w stabilnych interfejsach API podrzędnych będą miały nowy numer wersji, np. z wersji 1 na wersję 2.
• Drobne zmiany: dodatki lub poprawki zgodne wstecznie są prezentowane jako zmiany w istniejącej wersji głównej. Szczegółowe informacje o takich zmianach znajdziesz w informacjach o wersji głównej. Niepowodujące przerw w działaniu dodatki do interfejsu API będą publikowane na kanale alfa najnowszej stabilnej wersji lub bezpośrednio w najnowszej stabilnej wersji.

Zasady wycofywania

Okresowo wycofujemy starsze wersje podrzędnych interfejsów Merchant API. W przypadku stabilnych wersji głównych (vX) obowiązuje 12-miesięczny okres wycofywania, który rozpoczyna się od oficjalnego ogłoszenia o wycofaniu.

Jeśli na przykład 15 stycznia 2026 r. wycofamy wersję 1 podrzędnego interfejsu API Usługi, zostanie ona wyłączona nie wcześniej niż 15 stycznia 2027 r. Po tym terminie starsza wersja interfejsu API nie będzie już dostępna.

Wersja interfejsu API i stan cyklu życia

W tabeli poniżej znajdziesz najnowsze wersje każdego interfejsu API Merchant API:

Sprawdzone metody

• Regularnie sprawdzaj informacje o wersji i najnowsze aktualizacje, aby być na bieżąco z nowymi wersjami, ważnymi aktualizacjami, ulepszeniami i ogłoszeniami dotyczącymi wprowadzania i wycofywania interfejsów API.
• Jeśli interfejs API ma co najmniej 2 stabilne wersje, zalecamy korzystanie z najnowszej wersji.
• Zaprojektuj aplikację tak, aby prawidłowo obsługiwała różne błędy interfejsu API, w tym problemy z siecią, limity częstotliwości i nowe kody lub komunikaty o błędach, które mogą zostać wprowadzone w nowszych wersjach interfejsu API.
• Nie czekaj, aż wersja podrzędna interfejsu API zostanie wycofana, aby rozpocząć planowanie uaktualnienia. Rozpocznij ocenianie i testowanie nowych wersji, gdy tylko staną się dostępne.
• Jeśli masz prośby o dodanie funkcji lub uwagi dotyczące planu rozwoju interfejsu API, skontaktuj się z nami. Informacje o tym, jak uzyskać pomoc techniczną od zespołu Merchant API, znajdziesz w artykule Jak uzyskać pomoc dotyczącą interfejsu API sprzedawcy.