Получение текущей позиции автомобиля по названию
Метод возвращает последнюю сохранённую позицию автомобиля. Автомобиль определяется по его точному названию в PILOT.
Метод предназначен для интеграции с системами отслеживания перевозок, включая WIMT. В отличие от методов, использующих IMEI, в запросе передаётся название автомобиля — truckNo.
Интерактивное описание метода доступно в Swagger — Track and Trace
Как получить данные
Метод
POST
Адрес запроса
https://<server_address>/api/v3/vehicles/track-and-trace
Замените <server_address> адресом сервера PILOT.
Авторизация
Для выполнения запроса используется стандартная авторизация API V3 с помощью Bearer token.
Передайте токен в заголовке Authorization:
Authorization: Bearer <access_token>
Замените <access_token> действующим токеном API V3.
Заголовки запроса
|
Заголовок
|
Обязательный
|
Описание
|
|
Authorization
|
Да
|
Bearer token для авторизации пользователя в API V3
|
|
X-Node
|
Да
|
Номер узла пользователя. Используется для перенаправления запроса на нужный сервер
|
|
Content-Type
|
Да
|
Формат тела запроса. Укажите application/json
|
|
Accept
|
Нет
|
Формат ответа. Рекомендуемое значение — application/json
|
Пример заголовков:
Authorization: Bearer <access_token>
X-Node: 3
Content-Type: application/json
Accept: application/json
Параметры запроса
Параметры передаются в теле запроса в формате JSON.
|
Параметр
|
Тип
|
Обязательный
|
Описание
|
|
shipmentNo
|
String
|
Да
|
Номер груза или перевозки. Метод принимает значение, но не сохраняет и не возвращает его
|
|
truckNo
|
String
|
Да
|
Название автомобиля в PILOT. Должно точно соответствовать значению vehiclenumber
|
|
countryID
|
String
|
Да
|
Код страны, например ZA. В ответе возвращается без изменений
|
|
trackingFlag
|
String
|
Да
|
Состояние отслеживания, например START или STOP. В текущей версии значение принимается, но не сохраняется и не влияет на обработку запроса
|
Поиск автомобиля
Метод ищет автомобиль по точному значению truckNo среди автомобилей, доступных авторизованному пользователю.
Переданное значение должно полностью совпадать с названием автомобиля — vehiclenumber — в PILOT. Учитывайте регистр символов, пробелы и специальные символы.
Например, если автомобиль называется KS51YPGP_F, в запросе необходимо передать:
"truckNo": "KS51YPGP_F"
|
Если название не совпадает или у пользователя нет доступа к автомобилю, метод не вернёт его позицию.
Пример запроса
{
"shipmentNo": "SHIPMENT-123",
"truckNo": "KS51YPGP_F",
"countryID": "ZA",
"trackingFlag": "START"
}
|
Пример запроса cURL:
curl --request POST \
--url "https://<server_address>/api/v3/vehicles/track-and-trace" \
--header "Authorization: Bearer <access_token>" \
--header "X-Node: 3" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
"shipmentNo": "SHIPMENT-123",
"truckNo": "KS51YPGP_F",
"countryID": "ZA",
"trackingFlag": "START"
}'
|
Ответ
Если запрос выполнен успешно, метод возвращает последнюю сохранённую GPS-позицию автомобиля, адрес, часовой пояс и название аккаунта.
Поля успешного ответа
|
Поле
|
Тип
|
Описание
|
|
code
|
Integer
|
Код выполнения запроса. Значение 0 означает успешное выполнение
|
|
msg
|
String
|
Результат выполнения запроса. При успешном выполнении возвращается OK
|
|
process_time
|
Number
|
Время обработки запроса в секундах
|
|
countryID
|
String
|
Код страны, полученный в запросе. Возвращается без изменений
|
|
timeZone
|
String
|
Часовой пояс в формате IANA, например Africa/Johannesburg
|
|
truckNo
|
String
|
Название найденного автомобиля в PILOT
|
|
latitude
|
Number
|
Широта последней сохранённой GPS-позиции
|
|
longitude
|
Number
|
Долгота последней сохранённой GPS-позиции
|
|
source
|
String
|
Название аккаунта, которому принадлежит автомобиль
|
|
streetName
|
String
|
Адрес последней позиции, полученный с помощью обратного геокодирования
|
|
lastRecordedOn
|
Integer
|
Время регистрации последней GPS-позиции в формате Unix timestamp
|
Поля shipmentNo, trackingFlag и trackLink в ответе не возвращаются.
Пример успешного ответа
{
"code": 0,
"msg": "OK",
"process_time": 0.001,
"countryID": "ZA",
"timeZone": "Africa/Johannesburg",
"truckNo": "KS51YPGP_F",
"latitude": -26.2041,
"longitude": 28.0473,
"source": "Example Fleet",
"streetName": "Main Road, Johannesburg",
"lastRecordedOn": 1785142800
}
|
Форматы времени
Часовой пояс
Поле timeZone содержит идентификатор часового пояса из базы IANA:
"timeZone": "Africa/Johannesburg"
|
Идентификатор IANA определяет региональный часовой пояс и позволяет корректно учитывать его правила.
Фиксированное смещение, например UTC+02:00, метод не возвращает.
Время последней позиции
Поле lastRecordedOn содержит время последней GPS-позиции в формате Unix timestamp:
"lastRecordedOn": 1785142800
|
Unix timestamp содержит количество секунд, прошедших с 1 января 1970 года, 00:00:00 UTC. Значение не зависит от часового пояса.
Чтобы отобразить дату и время пользователю, преобразуйте lastRecordedOn с учётом значения timeZone.
Определение адреса
Поле streetName формируется с помощью обратного геокодирования: PILOT преобразует координаты последней позиции в текстовый адрес.
"streetName": "Main Road, Johannesburg"
|
Полнота и точность адреса зависят от доступных картографических данных.