Strona może być nieaktualna
Nikt jej nie zmieniał od 45 miesięcy (ostatni commit: 2023-02-01, Dariusz). 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:
200 OKW treści odpowiedzi znajdują się dane, o które pytałeś.201 CreatedUtworzono – wysłany dokument został zapisany na serwerze.400 Bad RequestNieprawidł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).401 UnauthorizedNieautoryzowany dostęp – żądanie zasobu, który wymaga uwierzytelniania.403 ForbiddenZabroniony – serwer zrozumiał zapytanie, lecz konfiguracja bezpieczeństwa zabrania mu zwrócić żądany zasób.404 Not FoundNie znaleziono – serwer nie odnalazł zasobu według podanego URL ani niczego co by wskazywało na istnienie takiego zasobu w przeszłości.422 Unprocessable EntityPrzesłano niepoprawne dane — serwer zrozumiał zapytanie, ale dane nie spełniają reguł walidacji.500 Internal Server ErrorWewnętrzny błąd serwera – serwer napotkał niespodziewane trudności, które uniemożliwiły zrealizowanie żądania.504 Gateway TimeoutPrzekroczony 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:
na adres
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:
Możliwe odpowiedzi:
HTTP 200- Serwis działa poprawnieHTTP 500- Wewnętrzny błąd serweraHTTP 504- Zbyt duże obciążenieTime 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
}
Tworzenie transportu¶
Przed utworzeniem transportu trzeba ustawić TRANSPORT_IDENTIFIER_TYPE. Opcje do wyboru :
* ERP_IDENTIFIER
* ALT_IDENTIFIER
* ID

Dla opcji ALT oraz ERP wybrany identyfikator, przy tworzeniu transportu przez API, musi być unikalny. Komunikat, który otrzymamy, gdy ktoś spróbuje powielić identyfikator:
Operacja nie powiodła się. W platformie już istnieje zlecenie o numerze alt/erp identifier "X"
Zapytanie:¶
HTTP POST
https://apollo.logintegra.com/apollo/api/transports/
Content-Type: application/json
Authorization: Bearer access_token
APIVersion: v1
{
"erpIdentifier": "AA3423", //numer transportu w systemie klienta
"altIdentifier": "84374753", //dodatkowy numer w systemie klienta
"description": "Uwaga: Załadunek tylko bokiem", //opis transportu
"tradesman": "[email protected]", //nazwa użytkownika odpowiedzialnego za realizację transportu po stronie klienta
"carrierCompany": {
//przewoźnik, który zostanie przypisany do transportu, może być wyszukany po jednym z pól poniżej
//węzeł ten może zostać pominięty jeśli przewoźnik powinien zostać przypisany w Oknach czasowych
//każdy z podanych niżej węzłów jest nieobowiązkowy i mogą one być stosowane zamiennie
//zalecane jest przesłanie jednego, dowolnie wybranego węzła. Wyszukiwanie odbywa się w następującej kolejności:
//najpierw po id, contractorNumber, shortName. Jeśli zostaną podane dwa węzły np. contractorNumber oraz shortName i obiekt nie zostanie znaleziony
//po polu contractorNumber to zostanie zwrócony błąd.
//UWAGA: przewoźnik musi istnieć w systemie Okien czasowych zanim będzie mógł być przypisany do transportu
"id": "3421231", //id przewoźnika w systemie Okien czasowych
"contractorNumber": "UID94392", //numer kontrahenta wpisany w zakładce 'Firmy'
"shortName": "Mexem" //nazwa skrócona
},
"principalCompany": {
//właściciel transportu. Przynajmniej jeden z podanych niżej węzłów jest obowiązkowy, mogą one być stosowane zamiennie
id:"76084423",
alias: "właściciel" //nazwa identyfikująca, ustalana przy wdrożeniu.
},
"transportType": {
//system Okien czasowych umożliwia obsługę transportów różnego rodzaju, mogą to być np. dostawy, załadunki, kurierzy lub odbiory własne.
//każdy typ transportu może posiadać inne statusy oraz dodatkowe pola formularzu
//przynajmniej jeden z podanych niżej węzłów jest obowiązkowy, mogą one być stosowane zamiennie
"id": "2423123",
"alias": "OWN_COLLECTION" //nazwa identyfikująca typ transportu, ustalana przy wdrożeniu.
},
"steps": [
//lista punktów z których składa się transport, w większości przypadków będzie zawierała 1 element
// większa liczba elementów może być podawana w przypadku przerzutów międzymagazynowych, albo zleceń z konieczną
// obsługą celną poza miejscem załadunku.
{
"stepTypeName": "load", //jedna z wartości: load/unload
"orderInTransport": "0", //kolejność realizacji, w przypadku transportów z jednym krokiem powinna wynosić 0
"documentIdentifier": "", //numer dokumentu WZ/PZ
"minAdviceDate": "2019-02-23T17:00:00Z", //najwcześniejsza możliwa data obsługi samochodu przez magazyn
"maxAdviceDate": "2019-02-23T21:00:00Z", //najpóźniejsza możliwa data obsługi samochodu przez magazyn
"arrivalDate": "2019-02-23T21:00:00Z", //zlecona data dostawy/odbioru
"volume": "21.1", //objętość towaru razem z opakowaniami
"weight": "15.3", //waga towaru z opakowaniami
"stepPackageTypes": [
{
"quantity": null, // Ilość opakowań
"packageTypeName": "PALLETS" // Rodzaj opakowania
},
{
"quantity": 333, // Ilość opakowań
"packageTypeName": "CARTONS" // Rodzaj opakowania
}
],
"company": {
// Kontrahent (dostawca lub odbiorca) towaru przypisany do transportu
// Wyszukiwanie i przypisywanie kontrahenta działa tak samo jak wyszukiwanie i przypisywanie przewoźnika
// UWAGA: Kontrahent musi istnieć w systemie Okien czasowych zanim będzie mógł być przypisany do transportu
"id": "23123", // Id kontrahenta w systemie Okien czasowych
"contractorNumber": "K942823", // Numer kontrahenta wpisany w zakładce 'Firmy'
"shortName": "PolPak" // Nazwa skrócona firmy kontrahenta
},
"warehouse": {
//magazyn w którym będzie wykonywany załadunek lub rozładunek
//wybór magazynu działa podobnie do wyboru przewoźnika, wystarczy podanie jednego z poniższych pól
//użytkownik, który będzie wybierał dokładny termin obsługi zostanie przekierowany do harmonogramu przypisanego do tego magazynu
//UWAGA: magazyn musi istnieć w systemie Okien czasowych zanim będzie mógł być przypisany do transportu
"id": "1231",
"idx" : "1", //numer magazynu w kolejności (jeżeli Twoja firma ma tylko jeden magazyn możesz używać 0)
"name": "Magazyn opakowań" //nazwa magazynu w systemie Okien czasowych
},
"address": {
// Adres załadunku lub rozładunku
// wymagane są wszystkie pola
// jeśli firma kontrahenta nie posiada w bazie danych jeszcze podanego adresu, to przy tworzeniu transportu zostanie on również utworzony
"recipient": "PolPak", // Adresat załadunku lub rozładunku
"street": "Sap 23", // Ulica załadunku lub rozładunku
"postal": "12345", // Kod pocztowy załadunku lub rozładunku
"city": "Krynica Morska", // Miasto załadunku lub rozładunku
"country": "PL" // Iban kraju
}
}
],
"customFields": [
//dodatkowe pola zdefiniowane podczas wdrożenia
{
"definitionName": "Temperatura towaru",
"value": "7"
},
{
"definitionName": "Poziom przygotowania",
"value": "80%"
}
]
}
Możliwe odpowiedzi¶
W przypadku poprawnego zapisania transportu komunikat zwrotny będzie zawierał kod HTTP 200 OK w którego treść będzie zawierała
dokument JSON o następującej treści:
{
"id": "32421231", //id transportu
"erpIdentifier": "AA3423", //numer transportu w systemie klienta
"altIdentifier": "84374753", //dodatkowy numer w systemie klienta
"description": "Uwaga: Załadunek tylko bokiem", //opis transportu
"tradesman": "[email protected]", //nazwa użytkownika odpowiedzialnego za realizację transportu po stronie klienta
"carrierCompany": {
//inaczej niż w przypadku zapytania o dodanie lub edycję transportu przesłane zostaną wszystkie węzły poniżej
"id": "3421231", //id przewoźnika w systemie Okien czasowych
"contractorNumber": "UID94392", //numer kontrahenta wpisany w zakładce 'Firmy'
"shortName": "Mexem" //nazwa skrócona
},
"transportType": {
//inaczej niż w przypadku zapytania o dodanie lub edycję transportu przesłane zostaną wszystkie węzły poniżej
"id": "2423123",
"name": "Odbiór własny"
},
"steps": [
{
"id": 123456789,
"stepTypeName": "load", //jedna z wartości: load/unload
"orderInTransport": "0", //kolejność realizacji, w przypadku transportów z jednym krokiem powinna wynosić 0
"documentIdentifier": "", //numer dokumentu WZ/PZ
"minAdviceDate": "2019-02-23T17:00:00Z", //najwcześniejsza możliwa data obsługi samochodu przez magazyn
"maxAdviceDate": "2019-02-23T21:00:00Z", //najpóźniejsza możliwa data obsługi samochodu przez magazyn
"arrivalDate": "2019-02-23T21:00:00Z", //zlecona data dostawy/odbioru
"volume": "21.1", //objętość towaru razem z opakowaniami
"weight": "15.3", //waga towaru z opakowaniami
"stepPackageTypes": [
{
"quantity": null, // Ilość opakowań
"packageTypeName": "PALLETS" // Rodzaj opakowania
},
{
"quantity": 333, // Ilość opakowań
"packageTypeName": "CARTONS" // Rodzaj opakowania
}
],
"company": {
//inaczej niż w przypadku zapytania o dodanie lub edycję transportu przesłane zostaną wszystkie węzły poniżej
"id": "23123", //id dostawcy w systemie Okien czasowych
"contractorNumber": "K942823", //numer kontrahenta wpisany w zakładce 'Firmy'
"shortName": "PolPak" //nazwa skrócona
},
"warehouse": {
//inaczej niż w przypadku zapytania o dodanie lub edycję transportu przesłane zostaną wszystkie węzły poniżej
"id": "1231",
"idx" : "1", //numer magazynu w kolejności (jeżeli Twoja firma ma tylko jeden magazyn możesz używać 0)
"name": "Magazyn opakowań" //nazwa magazynu w systemie Okien czasowych
},
"address": {
// Adres załadunku lub rozładunku
"id": "74727",
"recipient": "PolPak", // Adresat załadunku lub rozładunku
"street": "Sap 23", // Ulica załadunku lub rozładunku
"postal": "12345", // Kod pocztowy załadunku lub rozładunku
"city": "Krynica Morska", // Miasto załadunku lub rozładunku
"country": "PL" // Iban kraju
}
}
],
"checkpoints": [
//lista statusów, które zostały utworzone dla tego transportu
//ilość statusów, ich nazwy i znaczenie biznesowe jest zależne od konfiguracji zdefiniowanej podczas wdrożenia
{
//status zatwierdzany automatycznie podczas tworzenia transportu
"id": "38651834", //id statusu
"idx": "0", //kolejność statusu
"checkpointName": "Zapisanie zlecenia", //nazwa
"confirmator": "[email protected]", //nazwa użytkownika, który potwierdził status
"expectedDate": "2019-03-02T09:12:34Z", //oczekiwana przez system, najpóźniejsza data potwierdzenia statusu, która nie spowoduje zapisania opóźnienia
"executionDate": "2019-03-02T09:12:34Z", //rzeczywista data potwierdzenie statusu
"alias": "ORDER_CREATED"
},
{
//status, który nie został jeszcze zatwierdzony, czeka na wykonanie odpowiedniej akcji w systemie Okien czasowych
"id": "38651834",
"idx": "1",
"checkpointName": "Dodanie awizacji",
"confirmator": null,
"expectedDate": "2019-03-02T12:00:00Z",
"executionDate": null,
"alias": "ADVICE_SAVED"
}
],
"customFields": [
//dodatkowe pola zdefiniowane podczas wdrożenia
{
"definitionName": "Temperatura towaru",
"value": "7"
},
{
"definitionName": "Poziom przygotowania",
"value": "80%"
}
]
}
Więcej przykładowych komunikatów i odpowiedzi można znaleźć w pliku z przykładami.
Błędy walidacji¶
Walidacja wartości w węźle „step.address”¶
{
"address": {
"recipient": "PolPak",
// Adresat załadunku lub rozładunku
"street": "Sap 23",
// Ulica załadunku lub rozładunku
"postal": "12345",
// Kod pocztowy załadunku lub rozładunku
"city": "Krynica Morska",
// Miasto załadunku lub rozładunku
"country": "PL"
// Iban kraju
}
}
Walidacje¶
- Walidacja na obowiązkowość — obowiązkowe wszystkie pola.
- Walidacja na pole country — tylko dostępne w bazie
- Walidacja na długość podanych danych — maksymalna długość 255 znaków
Komunikaty zwrotne¶
W przypadku braku wartości:
Niepoprawny adres
W przypadku niewłaściwego kodu kraju:
Niepoprawny kod kraju
Walidacja wartości w węźle „step.company”¶
Obowiązkowe jedno z pól id, contractorNumber, shortName.
Komunikaty zwrotne¶
W przypadku niepodania żadnej wartości: Niepoprawne dane firmy
Walidacja wartości w węźle „step.warehouse”¶
Obowiązkowe jedno z pól id, idx, name.
W przypadku transportu z jednym stepem: sprawdzamy flagę transportType#requiresWarehouse i jeśli przyjmuje wartość true wymagamy magazynu.
W przypadku transportu z wieloma stepami: w każdym stepie wymagamy albo magazynu, albo adresu.
Komunikaty zwrotne¶
W przypadku niepodania żadnej wartości: Niepoprawne dane magazynu
Walidacja wartości w węźle „step”¶
| Nazwa pola | Walidacja | Komunikat walidacyjny |
|---|---|---|
| stepTypeName | Pole obowiązkowe. Dozwolone wartości: load lub unload | W przypadku niepodania wartości: Brak wartości w polu "stepTypeName", pole jest obowiązkowe. W przypadku podania niepoprawnej wartości: Niepoprawna wartość w polu "stepTypeName". Poprawne wartości to: "load", "unload". |
| orderInTransport | Pole obowiązkowe. Zbiór wartości z tego pola powinien zawierać kolejne liczby naturalne (włączając zero), wartości nie mogą się powtarzać. Dla n-stepów dopuszczalnymi wartościami będą: 0, 1, ..., n-1. | W przypadku niepodania wartości: Brak wartości w polu "orderInTransport", pole jest obowiązkowe. W przypadku podania niepoprawnej wartości: Nieprawidłowe wartości w polu "orderInTransport". W jednym komunikacie z n krokami mogą być następujące wartości: 0,1,2, ..., n-1 (bez powtórzeń). |
| documentIdentifier | Dowolny tekst do 255 znaków | Pole „documentIdentifier” przekracza maksymalny rozmiar 255 znaków |
| minAdviceDate | to do A-7604 | |
| maxAdviceDate | to do A-7604 | |
| quantity | to do A-7604 | |
| volume | to do A-7604 | |
| weight | to do A-7604 |
Walidacja wartości pól dodatkowych¶
W węźle customFields wysyłana jest lista pól dodatkowych. W pierwszej kolejności walidowana jest nazwa pola - sprawdzane jest, czy pole o takiej (lokalnej lub angielskiej) nazwie istnieje w danym typie transportu.
W drugiej kolejności walidowany jest ich format:
- pola tekstowe - brak szczególnej walidacji,
- pola numeryczne - poprawna liczba (dodatnia, ujemna, zmiennoprzecinkowa - separatorem jest kropka),
- pola typu selekt - poprawna opcja spośród opcji w języku lokalnym lub angielskim,
- pola typu data - poprawna data w jednym z formatów: "dd.MM.yyyy HH:mm", "dd.MM.yyyy", "yyyy-MM-dd'T'HH
ss'Z'"
- pola typu data i godzina - poprawna data i godzina w jednym z formatów: "dd.MM.yyyy HH:mm", "yyyy-MM-dd'T'HH
ss'Z'"
Edycja istniejącego transportu¶
Zapytanie:¶
HTTP PUT
https://apollo.logintegra.com/apollo/api/transports/$transportId lub
https://apollo.logintegra.com/apollo/api/transports/$erpIdentifier lub
https://apollo.logintegra.com/apollo/api/transports/$altIdentifier
Content-Type: application/json
Authorization: Bearer access_token
APIVersion: v1
Użycie zmiennych $erpIdentifier oraz $altIdentifier jest możliwe tylko w przypadku, gdy pola te mają unikalne wartości.
To które pole będzie używane do identyfikacji transportu będzie ustalane podczas wdrożenia i zapisane w bazie w tabelce settings - Setting.TRANSPORT_IDENTIFIER_TYPE
W zapytaniu o edycję transportu należy pamiętać o podaniu numeru ID do każdego stepu, który chcemy edytować, na przykład:
(...)
"steps": [
{
"id": 123456789, // id otrzymane po utworzeniu transportu
"address": {
"city": "Krynica Morska",
"country": "PL",
"id": 249672726,
"postal": "12345",
"recipient": "TESTOWY222",
"street": "Sap 23"
},
(...)
Możliwe odpowiedzi:¶
- W przypadku poprawnego zapisania zmian w transporcie otrzymamy komunikat
HTTP 200 OKo treści takiej samej jak w przypadku utworzenia nowego transportu - W przypadku przesłania błędnych danych otrzymamy komunikat
HTTP 422 Unprocessable Entity, którego treść będzie zawierać listę błędów tak jak w przypadku tworzenia nowego transportu - W przypadku braku aktualnego tokenu otrzymamy komunikat
HTTP 401 Unauthorized - W przypadku braku uprawnień do edycji transportu otrzymamy komunikat
403 Forbidden - W przypadku nie odnalezienia transportu o podanym identyfikatorze otrzymamy komunikat
HTTP 404 Not Found - W przypadku znalezienia więcej niż jednego transportu o podanym identyfikatorze otrzymamy komunikat
HTTP 422 Unprocessable Entity
Pobieranie danych transportu¶
Zapytanie:¶
HTTP GET
https://apollo.logintegra.com/apollo/api/transports/$transportId lub
https://apollo.logintegra.com/apollo/api/transports/$erpIdentifier lub
https://apollo.logintegra.com/apollo/api/transports/$altIdentifier
Content-Type: application/json
Authorization: Bearer access_token
APIVersion: v1
Użycie zmiennych $erpIdentifier oraz $altIdentifier jest możliwe tylko w przypadku, gdy pola te mają unikalne wartości.
To które pole będzie używane do identyfikacji transportu będzie ustalane podczas wdrożenia i zapisane w bazie w tabelce settings
Możliwe odpowiedzi:¶
- W przypadku poprawnej identyfikacji transportu otrzymamy komunikat
HTTP 200 OKo treści takiej samej jak w przypadku utworzenia nowego transportu - W przypadku braku aktualnego tokenu otrzymamy komunikat
HTTP 401 Unauthorized - W przypadku braku uprawnień do edycji transportu otrzymamy komunikat
403 Forbidden - W przypadku nie odnalezienia transportu o podanym identyfikatorze otrzymamy komunikat
HTTP 404 Not Found - W przypadku znalezienia więcej niż jednego transportu o podanym identyfikatorze otrzymamy komunikat
HTTP 422 Unprocessable Entity
Pobieranie listy aktualnych transportów¶
Zapytanie:¶
HTTP GET
https://apollo.logintegra.com/apollo/api/transports
Content-Type: application/json
Authorization: Bearer access_token
APIVersion: v1
Możliwe odpowiedzi:¶
W odpowiedzi otrzymasz listę aktualnie dostępnych transportów. Są to transporty, które nie zostały usunięte ani zarchiwizowane. Struktura danych transportu będzie identyczna jak w przypadku odpowiedzi na utworzenie nowego transportu. Ta funkcja nie jest zalecana do aktualizacji danych poszczególnych transportów na zasadzie regularnego odpytywania o dane z powodu dużej ilości zwracanych danych i potencjalnie dłuższego czasu przygotowania odpowiedzi.
W przypadku braku aktualnego tokenu otrzymamy komunikat HTTP 401 Unauthorized
Pobieranie informacji o ostatnio zaktualizowanych transportach¶
Zapytanie¶
HTTP GET
https://apollo.logintegra.com/apollo/api/transports/updates/$durationInSeconds
Content-Type: application/json
Authorization: Bearer access_token
APIVersion: v1
Proponowane kroki podczas implementacji 1. Zapisanie aktualnego czasu 2. Wysłanie zapytania do systemu okien czasowych o listę wszystkich aktywnych transportów 3. Przetworzenie odpowiedzi 4. Zaplanowanie zapytania o zaktualizowane transporty za kilka minut 5. Czekanie 6. Obliczenie okresu o jaki chcemy zapytać: aktualny czas - zapisany czas poprzedniego zapytania + margines błędu* 7. Zapisanie aktualnego czasu 8. Wysłanie zapytania o ostatnio zaktualizowane transporty 9. Przetworzenie odpowiedzi 10. Powrót do kroku nr 4
*margines błędu - zalecana wartość to 10 sekund.
Możliwe odpowiedzi¶
W odpowiedzi otrzymasz listę transportów, które zostały zaktualizowane w ostatnich $durationInSeconds sekundach.
Struktura danych transportu będzie identyczna jak w przypadku odpowiedzi na utworzenie nowego transportu.
W przypadku braku aktualnego tokenu otrzymamy komunikat HTTP 401 Unauthorized
Zatwierdzanie statusów¶
Zapytanie¶
HTTP PUT
https://apollo.logintegra.com/apollo/api/transports/$transportId/confirm/$alias lub
https://apollo.logintegra.com/apollo/api/transports/$erpIdentifier/confirm/$alias lub
https://apollo.logintegra.com/apollo/api/transports/$altIdentifier/confirm/$alias
Content-Type: application/json
Authorization: Bearer access_token
APIVersion: v1
Zmienna $alias to ustalona podczas wdrożenia nazwa statusu który chcemy potwierdzić.
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.
To, który numer powinien zostać użyty jako identyfikator transportu (transportId, erpIdentifier czy altIdentifier) określa ustawienie ogólne Setting.TRANSPORT_IDENTIFIER_TYPE.
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 nie odnalezienia transportu o podanym identyfikatorze lub nie odnalezienia 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
Dodanie/edycja awizacji¶
W celu dodania/edycji awizacji do komunikatu tworzącego/edytującego transport należy dołączyć węzeł z danymi awizacji:
{
"id": "32421231", //id transportu
"erpIdentifier": "AA3423", //numer transportu w systemie klienta
"altIdentifier": "84374753", //dodatkowy numer w systemie klienta
"description": "Uwaga: Załadunek tylko bokiem", //opis transportu
//(..)
"advice": {
"driverName": "GRAD PIOTR", //imię i nazwisko kierowcy
"carRegistrationNumber": "WGM11150", //numer rejestracyjny samochodu
"trailerRegistrationNumber": "WZ2303R", //numer rejestracyjny naczepy
"documentNumber": "ATD212324", //numer dokumentu identyfikacyjnego kierowcy
"documentType": "ID_CARD", //typ dokumentu kierowcy, jedna z wartości PASSPORT lub ID_CARD
"driverMobilePhoneNumber": "600284363", // numer telefonu kierowcy
"driverMobilePhonePrefix": "48", //numer kierunkowy kraju
"personalDataProcessingConsent": "true", //zgoda na przetwarzanie danych osobowych (RODO)
"termsOfConditionsAccepted": "true" // zgoda na warunki usługi, wymagane zależnie od ustawienia `SHOW_TERMS_OF_CONDITIONS_ACCEPTED`
},
//(..)
}
W przypadku, gdy w komunikacie nie będzie węzła "advice", a zlecenie będzie miało przypisaną na platformie awizacje, skopiujemy dane z bazy danych - nie da się zatem usunąć istniejącej awizacji z systemu przy pomocy API.
Dodanie/edycja okna czasowego¶
W celu dodania/edycji okna czasowego należy zmodyfikować komunikat tworzący/edytujący zlecenia. W stepie, do którego ma być przypisane okno, należy dodać węzęł "timeWindow":
{
"id": "32421231",
"erpIdentifier": "AA3423",
"altIdentifier": "84374753",
"description": "Uwaga: Załadunek tylko bokiem",
//(..)
"steps": [
{
"stepTypeName": "load",
"orderInTransport": "0",
//(..)
"timeWindow": {
"ramp": "Slot nr 1", // nazwa rampy
"start": "2019-03-04T12:30:00Z" // początek okna czasowego
},
//(..)
}
],
//(..)
}
Koniec okna czasowego będzie obliczany na platformie zgodnie z ustawieniami firmy.
Jeśli węzęł "timeWindow" nie zostanie przesłany, a zlecenie będzie posiadało okna na platformie, dane okna zostaną skopiowane z bazy danych - nie da się zatem usunąć okna przy pomocy API.
Przesyłanie informacji o przewożonych produktach¶
Aby obsługa tego węzła była możliwa, odpowiednia konfiguracja musi być przygotowana przez administratora. Między innymi konieczne jest uruchomienie modułu bazy produktów wytwarzanych przez klienta. W celu podania informacji o przewożonych produktach należy zmodyfikować komunikat tworzący/edytujący zlecenie dodając nieobowiązkowy węzeł "transportedGoods":
{
"id": "32421231", //id transportu
"erpIdentifier": "AA3423", //numer transportu w systemie klienta
"altIdentifier": "84374753", //dodatkowy numer w systemie klienta
"description": "Uwaga: Załadunek tylko bokiem", //opis transportu
// (..)
"transportedGoods": [ // jedno auto może przewozić wiele różnych produktów
{
"productName": "Clethodim 3L RR",
"productShortName": "Clethodim",
"indexNumber": "Q-CLT-RS1-0342",
"shipFrom": "0", // wartość odnosząca się do numeru etapu w zleceniu podawanego w polu orderInTransport
"shipTo": "1", // wartość odnosząca się do numeru etapu w zleceniu podawanego w polu orderInTransport
// dla zleceń jednoetapowych podajemy zawsze 0 w obu węzłach
// dla zleceń z jednym miejscem załadunku i jednym miejscem dostawy podajemy 0 jako shipFrom i 1 jako shipTo
// dla zleceń z większa liczbą rozładunków lub załadunków podajemy numer etapu zlecenie do którego należy
// przypisać załadunek i rozładnek jako wartość z pola orderInTransport z węzła step
"notes":"additional product description",
"company": {
//nieobowiązkowy węzeł - kontrachent do którego należy przewożony towar, firma musi być utworzona wcześniej
//w systemie, ale nie musi występować w innych polech tego konkretnego transportu
//każdy z podanych niżej węzłów jest nieobowiązkowy i mogą one być stosowane zamiennie
//zalecane jest przesłanie jednego, dowolnie wybranego węzła. Wyszukiwanie odbywa się w następującej kolejności:
//najpierw po id, contractorNumber, shortName.
"id": "23123", //id dostawcy w systemie Okien czasowych
"contractorNumber": "K942823", //numer kontrahenta wpisany w zakładce 'Firmy'
"shortName": "PolPak" //nazwa skrócona
},
"additionalInformation": [ // dodatkowe informacje, zależne od konfiguracji systemu
{
"value": 5,
"definitionName": "Liczba palet",
"unit": "sztuki",
},
{
"value": 44,
"definitionName": "Liczba opakowań",
"unit": "sztuki"
}
]
},
{
"productName": "Glifosate 300 G/L Lt. 500",
"productShortName": "Glifosate 500",
"indexNumber": "W-RR-1M4-0221",
"shipFrom": "0",
"shipTo": "1",
"notes": "other description",
"company": {
"id": "23123",
"contractorNumber": "K942823",
"shortName": "PolPak"
},
"additionalInformation": [
{
"value": 3,
"definitionName": "Liczba palet",
"unit": "sztuki",
},
{
"value": 21,
"definitionName": "Liczba opakowań",
"unit": "sztuki"
}
]
}
],
// (..)
}
Używając tego komunikatu możliwe będzie tworzenie nowych produktów systemie. Jeżeli zostanie przesłany produkt z numerem indeksu, który nie istnieje jeszcze w systemie, na podstawie przesłanych danych system utworzy nowy wpis w bazie produktów. Jeżeli zostanie przesłany produkt z numerem indeksu istniejącym w systemie to produkt ten zostanie przypisany do tworzonego transportu.
Zapytanie o propozycję wolnych okien¶
W celu uzyskania informacji o pierwszych wolnych miejscach na okno czasowe w danym magazynie i wskazanym zakresie czasu, należy wysłać następujące zapytanie:
HTTP POST
https://apollo.logintegra.com/apollo/api/time-windows/suggest
Content-Type: application/json
Authorization: Bearer access_token
APIVersion: v1
{
"principalCompany": {
"id": "", // id firmy pryncypała
"alias": "semmelrock" // alias firmy pryncypała - ustalany przy wdrożeniu
},
"transportType": {
"id": "", // id typu transportu
"alias": "LOADING" // alias typu transportu
},
"warehouse": {
"id": "", // id magazynu
"name": "Magazyn Gdynia" // nazwa magazynu
},
"searchStart": "2021-08-05T12:00:00Z", // początek zakresu, w którym poszukujemy dostępne okno czasowe
"searchStop": "2021-08-05T17:00:00Z" // koniec zakresu, w którym poszukujemy dostępne okno czasowe
}
W węźle principalCompany należy podać id i/lub alias firmy pryncypała.
W węźle transportType należy podać id i/lub alias typu transportu.
W węźle warehouse należy podać id i/lub nazwę magazynu.
W odpowiedzi przychodzi lista proponowanych miejsc na okno czasowe:
{
"slots": [
{
"start": "2021-08-05T12:00:00Z",
"stop": "2021-08-05T13:00:00Z",
"ramp": {
"id": 222498499,
"warehouse": {
"id": 222498476,
"name": "Magazyn Gdynia"
},
"name": "1/A",
"shortName": "1/A"
}
},
{
"start": "2021-08-05T12:00:00Z",
"stop": "2021-08-05T13:00:00Z",
"ramp": {
"id": 222498595,
"warehouse": {
"id": 222498476,
"name": "Magazyn Gdynia"
},
"name": "2/A",
"shortName": "2/A"
}
}
]
}
Zapytanie o zaktualizowane transporty w danym okresie¶
W celu uzyskania informacji o zaktualizowanych transportach w danym okresie należy wysłać następujące zapytanie:
```http request HTTP GET https://apollo.logintegra.com/apollo/api/transports/updates/startDate={startDateTime}&endDate={endDateTime}
Authorization: Bearer access_token APIVersion: v1
* W parametrze `startDateTime` podajemy datę i godzinę początku zakresu czasu.
* W parametrze `endDateTime` podajemy datę i godzinę końca zakresu czasu.
W odpowiedzi otrzymamy listę wszytkich transportów zaktualizowanych w czasie od `startDateTime` do `endDateTime`.
Przykład zapytania:
```http request
HTTP GET
https://apollo.logintegra.com/apollo/api/transports/updates/startDate=2022-10-19T17:00:00Z&endDate=2022-10-19T18:00:00Z
Authorization: Bearer access_token
APIVersion: v1
{
"erpIdentifier": "WZ^0000468",
"description": "Uwagi do zlecenia",
"principalCompany": {
"id": 268138707,
"alias": "atlas"
},
"archived": false,
"deleted": false,
"tradesman": null,
"creator": "atlas-admin",
"dateCreated": "2022-10-05T13:26:22Z",
"documents": null,
"goodsValue": null,
"goodsValueCurrency": null,
"id": 275222342,
"incoterms": null,
"internalIndex": 996909,
"packages": null,
"carrierCompany": {
"id": "268205585",
"name": "Przewoźnik testowy Atlas",
"shortName": "Przewoźnik Atlas",
"contractorNumber": "CARRIERTEST_1",
"taxIdNumber": "CARRIERTEST_1",
"typeOfService": null
},
"transaction": null,
"transportType": {
"id": 268143530,
"name": "Loading"
},
"advice": null,
"steps": [
{
"orderInTransport": 0,
"id": 275222344,
"stepTypeName": "load",
"documentIdentifier": null,
"arrivalDate": null,
"minAdviceDate": null,
"maxAdviceDate": null,
"volume": null,
"weight": null,
"address": null,
"company": null,
"warehouse": {
"id": 268140434,
"idx": "",
"name": "Magazyn Atlas Zgierz"
},
"timeWindow": null,
"assortmentGroup": {
"id": 271290057,
"name": "Załadunek 06:00 - 22:00",
"nameEn": "Loading 06:00 - 22:00",
"shortName": "Załadunek 6-22",
"shortNameEn": "Loading 6-22",
"adviceFromTime": "06:00",
"adviceToTime": "22:00",
"lastUpdated": "2022-09-19T03:19:28Z"
},
"locations": null,
"vehicleWeighings": null,
"stepPackageTypes": null,
"contactPerson": null,
"contactPersonMobilePhonePrefix": null,
"contactPersonMobilePhoneNumber": null
},
{
"orderInTransport": 1,
"id": 275222341,
"stepTypeName": "unload",
"documentIdentifier": "098876455",
"arrivalDate": "2022-10-04T13:00:00Z",
"minAdviceDate": null,
"maxAdviceDate": null,
"company": {
"contractorNumber": "COMPANYTEST_1",
"id": 268205742,
"name": "Rozładunek",
"shortName": "Rozładunek",
"taxIdNUmber": "COMPANYTEST1",
"typeOfService": null
},
"volume": 22,
"weight": 33,
"address": {
"city": "Sosnowiec",
"country": "PL",
"id": 275222339,
"postal": "43-985",
"province": null,
"recipient": "Leśna w Sosnowcu",
"street": "uL. Leśna 45"
},
"warehouse": null,
"timeWindow": null,
"assortmentGroup": null,
"locations": null,
"vehicleWeighings": null,
"stepPackageTypes": null,
"contactPerson": null,
"contactPersonMobilePhonePrefix": null,
"contactPersonMobilePhoneNumber": null
}
],
"customFieldValues": [
{
"definitionName": "Rodzaj zlecenia",
"definitionEnglishName": "Type of order",
"lastUpdated": "2022-10-05T13:26:22Z",
"value": "Eksport"
},
{
"definitionName": "Środek transportu",
"definitionEnglishName": "Mode of transportation",
"lastUpdated": "2022-10-05T13:26:22Z",
"value": "Chłodnia"
},
{
"definitionName": "Oczekuje na wahadło?",
"definitionEnglishName": "Waiting for inter-warehouse transport?",
"value": "Nie"
},
{
"definitionName": "Dystans [km]",
"definitionEnglishName": "Distance [km]",
"value": "174.8"
},
{
"definitionName": "Koszt",
"definitionEnglishName": "Cost",
"value": "1879.5"
},
{
"definitionName": "Waluta kosztu",
"definitionEnglishName": "Cost currency",
"value": "PLN"
},
{
"definitionName": "Rodzaj auta",
"definitionEnglishName": "Type of car",
"lastUpdated": null,
"value": null
}
],
"checkpoints": [
{
"id": 275222349,
"idx": 0,
"alias": "ORDER_CREATED",
"checkpointName": "Utworzenie zlecenia",
"checkpointEnglishName": "Order creation",
"confirmator": "super-admin-atlas",
"expectedDate": "2022-10-05T13:26:22Z",
"executionDate": "2022-10-05T13:26:22Z"
},
{
"id": 275222350,
"idx": 1,
"alias": "ADDITING_OF_ADVICE",
"checkpointName": "Dodanie awizacji",
"checkpointEnglishName": "Additing of advice",
"confirmator": null,
"expectedDate": "2022-10-05T12:26:22Z",
"executionDate": null
}
]
}
Ostatnia zmiana: 2023-02-01 · Dariusz
Zbudowano: 2026-11-20 10:32 UTC · wersja 1.0.0 · rewizja: 19fcdc12e