Перейти к основному содержимому

Подводные камни

Собрано по опыту реальных интеграций.

10.1 Координаты появляются не сразу​

После создания заказа lat и lon равны null — определение координат выполняется асинхронно и занимает от секунд до пары минут при массовой загрузке.

Заказ без координат не попадёт в маршрут и, что важнее, не появится даже в списке нераспределённых — он просто исчезнет из результата планирования.

Правильная последовательность:

  1. Загрузить заказы.
  2. Дождаться появления координат (опрос GET /orders/{id}/).
  3. Только потом запускать планирование.

Если координаты не появились примерно за две минуты — адрес определить не удалось. Такой заказ надо исправить.

Альтернатива: передавайте lat и lon сразу, если они есть в вашей системе. Тогда геокодирование не выполняется и заказ готов к планированию немедленно.

10.2 Формат адреса​

Наиболее надёжный формат: город, улица, дом.

г. Минск, пр. Независимости, 154        ✅

Не вставляйте название страны в середину адреса. Такой адрес долгое время не определялся вовсе:

Минск, Беларусь, Независимости 154      ⚠️ определяется через запасной вариант
Минск, Независимости 154, Беларусь      ✅

Сейчас платформа умеет переставлять и убирать страну автоматически, но это дополнительные обращения к геокодеру и лишняя задержка. Лучше не указывать страну совсем.

Что убирается автоматически, о чём можно не заботиться:

  • почтовый индекс в начале;
  • «корпус 6», «1 этаж», «оф. 206», «пом. 3», «строение 2»;
  • «дом 6» и «д. 6» приводятся к «6».

Не вычищайте это самостоятельно — платформа справится.

10.3 external_id не уникален​

Номер документа не проверяется на уникальность. Это сделано намеренно: повторная выгрузка не завершится ошибкой.

Следствия:

  • GET /orders/?external_id=... может вернуть несколько заказов;
  • при планировании один номер документа может подтянуть несколько заказов;
  • защита от дублей при создании — не строгая (см. раздел 9).

Рекомендация: считайте external_id меткой для сопоставления, а не гарантией уникальности. Проверяйте дубли на своей стороне.

10.4 Дата доставки по умолчанию — сегодня​

Если не передать delivery_date, подставится текущая дата на сервере. Часовой пояс сервера может не совпадать с вашим, поэтому вечерняя выгрузка рискует попасть не на тот день. Всегда указывайте дату явно.

Если дата всё же оказалась неверной — её можно исправить через PATCH (см. 4.4), пока заказ не попал в маршрут.

10.5 Правки только до планирования​

После того как заказ попал в маршрут, PATCH и отмена возвращают 409. Все исправления делайте до запуска планирования.

10.6 Что нельзя задать через API​

Следующие свойства заказа существуют в системе, но через публичный API не задаются и не читаются: тип операции (доставка/забор), приоритет, метки, паллеты, электронная почта получателя, жёсткие временные окна, требования к транспорту, грузовые места.

Особенно обратите внимание на требования к транспорту: из-за них заказ может попасть в нераспределённые с причиной requirements, хотя задать или проверить их через API нельзя. Настраиваются в интерфейсе диспетчера.

10.7 Ссылку на отслеживание получить нельзя​

Персональная ссылка отслеживания для получателя через API недоступна. Она рассылается самой платформой (SMS, email). Если такая ссылка нужна в вашей системе — сообщите нам, это доработка.