# RestApi - Integracje z zewnętrznymi systemami

{% hint style="warning" %}
Funkcjonalność dostępna od wersji platformy: 2.2924.0

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

{% hint style="warning" %}
Zmiana api

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

{% hint style="info" %}
Funkcjonalność wołania zewnętrznych usług RESTowych jest dostępna dla skryptów (scriptService), zadań skryptowych (scriptTask) oraz walidatorów skryptowych (validationScript).
{% endhint %}

## 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.eximee.com/budowanie-aplikacji/logika-biznesowa/scriptcode/restapi-integracje-z-zewnetrznymi-systemami.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.