Przejdź do treści

Strona może być nieaktualna

Nikt jej nie zmieniał od 61 miesięcy (ostatni commit: 2021-10-14, Mateusz Sosnowski). Jeśli opisuje stan, którego już nie ma, zgłoś ją jako nieaktualną.

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.

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.

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.

Ostatnia zmiana: 2021-10-14 · Mateusz Sosnowski
Zbudowano: 2026-11-20 10:32 UTC · wersja 1.0.0 · rewizja: 19fcdc12e