Особенности работы и ограничения

Политика опроса API

• Таймаут ответа API составляет 60 секунд.
• Один batch-запрос не должен содержать больше тысячи объектов. Если требуется передать больше данных, разделите их на несколько запросов.
• В редких случаях (менее одного процента запросов) API возвращает ошибку 504 Gateway Timeout. При получении такой ошибки отправляйте повторные запросы с растущей задержкой. Подробнее см. в разделе Ошибки сервиса.

Ограничения API

• Точность геокодирования адресов заказов не проверяется. Адрес в текстовом виде (задается параметром address) и координаты заказа (задаются параметрами lat и lon) должны соответствовать друг другу.

  Для построения маршрута используются геокоординаты. При недостаточной точности геолокации приложение может привести курьера не в ту точку, которая указана в приложении текстом. Распространенная ошибка в данных: адрес указан до дома, а геокоординаты указывают на середину улицы.

• Каскадное удаление сущностей не поддерживается. Лишние сущности с зависимостями от других сущностей можно не удалять, они не мешают работе.

Изменения в заказах

• При переносе отмененного заказа на другой день нужно присвоить ему статус new. В противном случае заказ добавится в маршрут на новый день в статусе cancelled.
• При изменении заказа необходимо обновлять только измененные атрибуты. В противном случае данные, полученные от курьера, будут перезаписаны. Например, курьер уже доставил заказ, а учетная система вернула заказу статус new при обновлении другого поля.
• После загрузки заказов нужно проверить их с помощью ресурса verification. Это позволяет убедиться в отсутствии ошибок. В противном случае курьер может не получить часть заказов. Такая проверка должна производиться ежедневно и в автономном режиме до выезда первого курьера.
• Значение route_number должно быть уникальным в рамках всего периода использования API.
• Поля с типом number и integer отправляются без кавычек, поля с типом string отправляются в кавычках. Поля с типом string должны передаваться в кодировке UTF-8.

Формат номера телефона

• Телефон нужно указывать в формате, который поддерживается терминалом мобильного сотрудника. Например, ряд терминалов не поддерживают номера телефонов, которые начинаются на 7. На такой телефон курьер не сможет позвонить из приложения. Рекомендуется начинать телефоны с +7 или 8.

Порядок загрузки данных

Рекомендуется следующий порядок загрузки данных:

1. Склады.
2. Курьеры.
3. Маршруты.
4. Заказы.

Другой порядок загрузки может привести к ошибкам при обращении к объектам, которые еще не загружены.

Рекомендованный способ загрузки данных

Для загрузки и обновления данных рекомендуется использовать batch-запросы, загружающие массив данных: depots-batch, couriers-batch, routes-batch, orders-batch.

Каждому загружаемому объекту присваивается:

• Уникальный номер, используемый в запросах к API Мониторинга. Записывается в полях с постфиксом _id, например depot_id.
• Уникальный номер, совпадающий с номером в базе данных компании, выполняющей доставку. Записывается в полях с постфиксом _number, например depot_number.

Существующие данные при batch-загрузке обновляются.

Срок хранения данных

Данные хранятся на серверах Яндекса ограниченное время:

• Треки движения курьеров: 1 месяц от даты маршрута.
• Фотографии, присланные курьерами для подтверждения доставки: 3 месяца от даты добавления фотографии.
• Данные мониторинга (заказы, маршруты): 1 год после окончания оплачиваемого периода или периода тестирования.
• Данные для построения отчетов План / Факт: 18 месяцев.

После окончания срока хранения данные могут быть удалены без возможности восстановления.

Написать в службу поддержки