Destinations API
Методы для работы с пунктами назначения.
Методы применяются к уже существующим объектам. То есть сначала создаётся объект ( /object_add || /object_reactivate ).
Затем к нему добавляются пункты назначения.
В последствии к имеющимся пунктам назначения могут быть добавлены новые.
Либо, они могут быть отредактированы.
Вы можете изменять статус пунктов назначения. Всего определено пять статусов:
- new - не пройденный пункт назначения
- current - пункт назначения к которому движется объект
- finished - пункт назначения был пройден
- censeled - пункт назначения был отменённ
- deleted - пункт назначения был удалён
distance_get - получение списка маршрутных точек
параметры
- phone - номер телефона в формате 79999999999, обязательный
- object_type - тип объекта, сейчас принимаются значения 'gsm', 'mgps', не обязательный, значение по умолчанию 'gsm'
В ответ на вызов метода вернётся массив объектов, где каждый объект это одна маршрутная точка.
пример в JSON:
{"id":"6704962","status":"finished","dest_time":"1899651212","estimate":1899660212,"distance":102,"finished":null,"text":"Склад_no1","lat":"61.047953","lon":"32.704795","order":2}
distance_add - добавление маршрутных точек
Пункт назначения будет добавлен только если для него переданы корректные координаты, время прибытия из будущего и не пустой текст названия пункта.
При этом будет проведена проверка на наличие точки с такими же координатами и временем прибытия.В случае если совпадение найдено пункт назначения будет отредактирован (поле text и status). Если совпадение не найдено, пункт будет добавлен. Такой алгоритм гарантирует идемпотентность методу добавления.
параметры
- phone - номер телефона в формате 79999999999, обязательный
- object_type - тип объекта, сейчас принимаются значения 'gsm', 'mgps', не обязательный, значение по умолчанию 'gsm'
- destination - массив пунктов назначения,
каждый пункт назначения передается в виде массива вложенного в destination
для пункта назначения применимы параметры:
- lat - широта (обязательное) 6 знаков после разделителя
- lon - долгота (обязательное) 6 знаков после разделителя
- dest_time - timestamp время назначенное для прибытия (указанное в маршрутном листе) (условно обязательное)
- text - название пункта назначения (любое) (обязательное)
- status - (опционально) статус точки. значение по умолчанию 'new' , (текущая, новая, пройденная, удалённая, отменённая) 'current','new','finished','deleted','canceled'
- timestamp_finished - timestamp время прохождения точки, если устанавливаете ей новый статус 'finished' (только для distance_edit)
пример массива destination для GET запроса:
phone=79ХХХХХХХХХ&destination[0][id]=6729957&destination[0][text]=Склад_no1&destination[0][lat]=68.321212&destination[0][lon]=32.546333&destination[0][dest_time]=1813321212&destination[0][status]=current
start_time - время когда должно начаться исполнение заказа, используется для расчёта ETA (ожидаемого времени прибытия)
В ответ на вызов метода вернётся массив объектов, где каждый объект это одна маршрутная точка.
пример в JSON:
{"id":"6704962","status":"finished","dest_time":"1899651212","estimate":1899660212,"distance":102,"finished":null,"text":"Склад_no1","lat":"61.047953","lon":"32.704795","order":2}
distance_edit - редактирование маршрутных точек
параметры:
- phone - номер телефона в формате 79999999999, обязательный
- object_type - тип объекта, сейчас принимаются значения 'gsm', 'mgps', не обязательный, значение по умолчанию 'gsm'
destination - массив пунктов назначения
- id - ID точки присваиваемый при добавлении (только для distance_edit)
- lat - широта (обязательное) 6 знаков после разделителя
- lon - долгота (обязательное) 6 знаков после разделителя
- dest_time - timestamp время назначенное для прибытия (указанное в маршрутном листе) (условно обязательное)
- text - название пункта назначения (любое) (обязательное)
- status - (опционально) статус точки. значение по умолчанию 'new' , (текущая, новая, пройденная, удалённая, отменённая) 'current','new','finished','deleted','canceled'
- timestamp_finished - timestamp время прохождения точки, если устанавливаете ей новый статус 'finished' (только для distance_edit)
В ответе присутствуют не редактируемые (расчётные) параметры:
- timestamp_eta - расчётное время прибытия на данную точку с учетом текущего местоположения.
- orderby порядковый номер точки маршрута по порядку следования объекта
Они пересчитываются при добавлении и редактировании новых точек и при запросе distance_get.