# JSON REST API v1 - możliwości integracji

API wystawiane przez system Okien czasowych firmy Logintegra umożliwia wykonywanie podstawowych operacji przez systemy wewnętrzne kontrahentów. Wszystkie zapytania powinny być szyfrowane za pomocą protokołu HTTPS.

## 1\. Struktura komunikatów

API budowane jest w sposób używający metod HTTP do rozpoznawania akcji, którą chcesz wykonać.

1. `HTTP GET` - pobieranie danych
2. `HTTP POST` - autentykacja oraz zapisanie danych
3. `HTTP PUT` - edycja istniejących danych
4. `HTTP DELETE` - usuwanie danych

Każdy komunikat oprócz logowania wymaga podania tokenu autoryzacyjnego w nagłówku węzła `Authorization: Bearer access_token`. Jeżeli komunikat przesyła dane, które powinny zostać zapisane w systemie Okien czasowych dodatkowo w nagłówku konieczne jest przesłanie węzła `Content-Type: application/json`. Analiza odpowiedzi powinna w pierwszej kolejności opierać się na kodach HTTP otrzymanych z systemu. Obsługiwane aktualnie kody to:

1. `200   OK` W treści odpowiedzi znajdują się dane, o które pytałeś.
2. `201   Created` Utworzono – wysłany dokument został zapisany na serwerze.
3. `400 Bad Request` Nieprawidłowe zapytanie – żądanie nie może być obsłużone przez serwer z powodu nieprawidłowości postrzeganej jako błąd użytkownika (np. błędna składnia zapytania).
4. `401 Unauthorized` Nieautoryzowany dostęp – żądanie zasobu, który wymaga uwierzytelniania.
5. `403 Forbidden` Zabroniony – serwer zrozumiał zapytanie, lecz konfiguracja bezpieczeństwa zabrania mu zwrócić żądany zasób.
6. `404 Not Found` Nie znaleziono – serwer nie odnalazł zasobu według podanego URL ani niczego co by wskazywało na istnienie takiego zasobu w przeszłości.
7. `422 Unprocessable Entity` Przesłano niepoprawne dane — serwer zrozumiał zapytanie, ale dane nie spełniają reguł walidacji.
8. `500 Internal Server Error` Wewnętrzny błąd serwera – serwer napotkał niespodziewane trudności, które uniemożliwiły zrealizowanie żądania.
9. `504 Gateway Timeout` Przekroczony limit czasu — zapytanie wykonuje się zbyt długo.

Zawartość odpowiedzi jest przesyłana w formie pliku JSON zgodnego z formatem proponowanym przez Google w dokumencie [https://google.github.io/styleguide/jsoncstyleguide.xml](<https://google.github.io/styleguide/jsoncstyleguide.xml>).

## 2\. Autoryzacja

**Uwaga:** Do testów logowania można użyć loginu i hasła dowolnego użytkownika, jednak aby mieć dostęp do api, konieczne jest utworzenie użytkownika ze specjalną rolą. W tym celu należy skontaktować się z nami, pisząc na adres [info@logintegra.com](<mailto:info@logintegra.com>).

Logowanie do systemu odbywa się przez wysłanie dokumentu JSON o treści:

```
{
  "username": "user_name",
  "password": "secret"
}
```

na adres

```
HTTP POST
Content-Type: application/json
https://apollo.logintegra.com/apollo/api/login
```

W przypadku niepowodzenia zostanie wysłany komunikat `HTTP 401 Unauthorized`.

Jeżeli dane logowanie będą poprawne, wysłany zostanie kod `HTTP 200 OK` oraz odpowiedź

```
{
  "username": "user_name",
  "roles": [],
  "access_token": "tj0mljefgtscns82fhkj3v7ld27173281hc",
  "token_type": "Bearer"
}
```

Najistotniejszym elementem odpowiedzi jest węzeł access\_token, którego wartość będzie używana do autoryzacji podczas przesyłania kolejnych zapytań. W nagłówku każdego kolejnego zapytania konieczne będzie przesyłanie parametru `Authorization: Bearer tj0mljefgtscns82fhkj3v7ld27173281hc`. Bez tej informacji odpowiedzią będzie zawsze komunikat `HTTP 401 Unauthorized`. Token jest ważny 24 godziny od wykonania ostatniego zapytania. W przypadku wygaśnięcia tokenu konieczne będzie ponowne zalogowanie do systemu i zapisanie nowego tokenu.

Zapytaniem tym nie musi być logowanie, może to być wywołanie dowolnej funkcji systemu.

## 3\. Dostępne operacje

### Sprawdzenie, czy system jest dostępny

Zapytanie:

```
HTTP GET
https://apollo.logintegra.com/apollo/api/status
```

Możliwe odpowiedzi:

1. `HTTP 200` - Serwis działa poprawnie
2. `HTTP 500` - Wewnętrzny błąd serwera
3. `HTTP 504` - Zbyt duże obciążenie
4. `Time out` - Serwis niedostępny

W przypadku poprawnego działania serwisu zwrócone zostaną także następujące informacje:

```
{
  "status": "running",
  "version": "2.38.1", //aktualna wersja aplikacji
  "date": "2019-01-01T11:23:23Z" //aktualna data na serwerze
}
```

### Zatwierdzenie zakończenia rozładunku

Dowolna z poniższych opcji:

```
HTTP PUT

https://apollo.logintegra.com/apollo/api/trasports/$transportId/confirm/END_OF_UNLOAD lub
https://apollo.logintegra.com/apollo/api/trasports/$erpIdentifier/confirm/END_OF_UNLOAD lub
https://apollo.logintegra.com/apollo/api/trasports/$altIdentifier/confirm/END_OF_UNLOAD

Content-Type: application/json
Authorization: Bearer access_token
APIVersion: v1
```

Jako data potwierdzenia statusu zostanie użyta aktualna data serwera. Jako osoba potwierdzająca statusy zostanie zapisany użytkownik, którego system klienta używa podczas autoryzacji.

#### Możliwe odpowiedzi

- W przypadku poprawnego potwierdzenia statusu otrzymamy komunikat: `HTTP 200 OK`
- W przypadku braku aktualnego tokenu otrzymamy komunikat: `HTTP 401 Unauthorized`
- W przypadku braku uprawnień otrzymamy komunikat: `403 Forbidden`
- W przypadku nieodnalezienia transportu o podanym identyfikatorze lub nieodnalezienia odpowiedniego statusu otrzymamy komunikat: `HTTP 404 Not Found`
- W przypadku znalezienia więcej niż jednego transportu o podanym identyfikatorze otrzymamy komunikat: `HTTP 422 Unprocessable Entity`

### Tworzenie zamówienia

```
HTTP POST

https://apollo.logintegra.com/apollo/api/orders/

Content-Type: application/json
Authorization: Bearer access_token
APIVersion: v1
```

Treść komunikatu powinna być zgodna ze wzorem z pliku `neuca_order_no_log_operator.json5` jeżeli nie zdecydujemy się na synchronizowanie danych o operatorach logistycznych odpowiedzialnych za załadunek lub z plik `neuca_order.json5` jeżeli informacje o operatorach mają być przetwarzane.

### Edycja zamówienia

```
HTTP PUT

https://apollo.logintegra.com/apollo/api/orders/$id lub
https://apollo.logintegra.com/apollo/api/orders/$erpIdentifier lub
https://apollo.logintegra.com/apollo/api/orders/$altIdentifier

Content-Type: application/json
Authorization: Bearer access_token
APIVersion: v1
```

Treść komunikatu powinna być zgodna ze wzorem z pliku `neuca_order_no_log_operator.json5` jeżeli nie zdecydujemy się na synchronizowanie danych o operatorach logistycznych odpowiedzialnych za załadunek lub z plik `neuca_order.json5` jeżeli informacje o operatorach mają być przetwarzane.

### Pobieranie informacji o transportach

Zgodnie z ustaleniami utworzenie nowego transportu lub edycja istniejącego transportu spowoduje wysłanie komunikatu o treści zgodnej ze wzorem z pliku neuca\_transport na adres wskazany przez Klienta.
