RestApi - Integracje z zewnętrznymi systemami

Funkcjonalność dostępna od wersji platformy: 2.2924.0

Funkcjonalność jest aktywna u wszystkich klientów. Nie wymaga żadnej flagi aktywacyjnej.

Zmiana api

Wołanie poprzez context.api() zostało zastąpione api.rest.v1. Jest to jedyny poprawny sposób wykonywania requestów.

Funkcjonalność wołania zewnętrznych usług RESTowych jest dostępna dla skryptów (scriptService), zadań skryptowych (scriptTask) oraz walidatorów skryptowych (validationScript).

Integracja z usługami zewnętrznymi przez REST API

Czym jest REST?

REST (Representational State Transfer) to styl architektoniczny komunikacji pomiędzy systemami informatycznymi, który opiera się na standardowym protokole HTTP. Umożliwia on wymianę danych między klientem (np. aplikacją) a serwerem (np. usługą zewnętrzną), w sposób lekki, prosty i skalowalny.

Każdy zasób (np. użytkownik, zamówienie, dokument) jest identyfikowany przez unikalny URL, a operacje na nim wykonuje się za pomocą standardowych metod HTTP:

Metoda	Opis
GET	Pobiera dane z serwera
POST	Tworzy nowy zasób
PUT / PATCH	Aktualizuje istniejący zasób
DELETE	Usuwa zasób

---

Format danych

Wymiana informacji w REST API odbywa się najczęściej w formacie JSON (rzadziej XML). JSON jest czytelny dla człowieka, prosty do przetwarzania i obsługiwany natywnie przez większość języków programowania.

---

Autoryzacja i bezpieczeństwo

Dostęp do usług zewnętrznych zazwyczaj wymaga autoryzacji, która zapewnia, że tylko uprawnione aplikacje lub użytkownicy mogą korzystać z API.

Najczęstsze mechanizmy to:

• API Key – prosty klucz identyfikacyjny dodawany do nagłówka lub parametru żądania;

• Bearer Token (OAuth 2.0) – nowoczesny standard oparty o tokeny dostępu;

• Basic Auth – login i hasło kodowane w nagłówku (obecnie rzadziej stosowane, głównie w środowiskach testowych).

🔒 W przypadku integracji z usługami zewnętrznymi zawsze należy używać HTTPS, aby zapewnić szyfrowanie komunikacji.

---

Statusy odpowiedzi (HTTP status codes)

Serwer w odpowiedzi na żądanie zwraca kod statusu HTTP, który informuje o rezultacie operacji:

Kod	Znaczenie
200 OK	Operacja zakończona sukcesem
201 Created	Utworzono nowy zasób
400 Bad Request	Błędne żądanie (np. nieprawidłowe dane wejściowe)
401 Unauthorized	Brak autoryzacji lub błędny token
404 Not Found	Zasób nie istnieje
500 Internal Server Error	Błąd po stronie serwera

---

Typowy przepływ integracji REST

1. Zbudowanie żądania – przygotowanie adresu URL, nagłówków (np. autoryzacja, typ danych) i ewentualnego body (dla POST / PUT).

2. Wysłanie żądania – komunikacja z zewnętrznym API poprzez HTTP.

3. Odebranie odpowiedzi – przetworzenie danych zwróconych w formacie JSON.

4. Obsługa błędów – interpretacja kodów statusu i komunikatów błędów.

5. Mapowanie danych – zapis lub wykorzystanie otrzymanych danych w systemie lokalnym.

---

Zalety REST

• Prostota – łatwy do zrozumienia i wdrożenia.

• Skalowalność – dobrze działa w środowiskach rozproszonych.

• Niezależność – klient i serwer mogą być implementowane w dowolnych technologiach.

• Popularność – szerokie wsparcie w bibliotekach i narzędziach programistycznych.