Импорт заказов

Поля заказа

Поле	Тип	Обязательно	Описание
externalId	строка до 100	для bulk — да	код документа в вашей системе (номер реализации/поставки) — ключ обновления
number	строка до 100	да	номер заказа, который видят диспетчер и водитель; уникален в пределах дня
deliveryDate	YYYY-MM-DD	да	день доставки
customerExternalId / customerId	строка / uuid	одно из трёх*	точка доставки из справочника
address, location	строка, {lat, lon}	одно из трёх*	свой адрес и координаты заказа
warehouseExternalId / warehouseId	строка / uuid	нет	склад отгрузки
windowFrom, windowTo	HH:MM	нет	окно доставки (иначе — окно точки)
serviceMinutes	целое	нет	время разгрузки, мин
weightKg, volumeM3, pallets	числа	нет	вес, объём, паллеты — для подбора машины
amount, currency, paymentType	число, KZT…, prepaid/cash/card/transfer	нет	сумма к получению при доставке
recipientName, recipientPhone	строки	нет	получатель; телефон в любом виде, сохраняется как +7…
priority	0–9	нет	приоритет
notes	строка до 1000	нет	комментарий водителю

* нужна точка доставки или адрес или координаты. Без координат заказ попадёт в план только после того, как диспетчер поставит точку на карте (геокодирование адресов — в разработке).

Один заказ

POST /orders создаёт заказ, PATCH /orders/{id} меняет отдельные поля, GET /orders/external/{externalId} находит заказ по вашему коду.

Пакетная загрузка — рекомендуемый способ

POST /orders/bulk с телом { "orders": [ … ] } — от 1 до 1000 заказов за запрос (тело до 1 МБ).

• Заказ с новым externalId создаётся, с уже известным — обновляется (меняются только переданные поля).
• Каждая строка обрабатывается отдельно: ошибка в одной не отменяет остальные.
• Ответ всегда 200 с итогами и результатом по каждой строке в порядке отправки:

{
  "created": 1, "updated": 1, "failed": 1,
  "results": [
    { "index": 0, "externalId": "РТ-00001", "result": "created", "id": "4b0c…" },
    { "index": 1, "externalId": "РТ-00002", "result": "updated", "id": "9d1e…" },
    { "index": 2, "externalId": "РТ-00003", "result": "error",
      "error": { "code": "CUSTOMER_NOT_FOUND", "message": "No delivery point with this customerExternalId", "field": "customerExternalId" } }
  ]
}

Коды ошибок строки

code	Причина	Что делать
VALIDATION_FAILED	неверный формат поля; подробности в issues	исправить данные
CUSTOMER_NOT_FOUND / WAREHOUSE_NOT_FOUND	нет точки/склада с таким кодом	сначала выгрузить справочник
DUPLICATE_IN_BATCH	externalId повторяется в одном запросе	оставить одну строку
DUPLICATE	номер number уже занят другим заказом этого дня	дать уникальный номер
ORDER_LOCKED	заказ уже у водителя или завершён (in_transit, delivered, failed)	изменения — через диспетчера

Отмена

Заказ отменили в учётной системе — отправьте его в bulk с "status": "cancelled". Отменённый заказ не попадает в маршруты.

Как выгружать

• Отправляйте изменения (новые и изменённые документы) по расписанию — например, раз в 5–15 минут, и полный день — перед планированием.
• Большие объёмы — пачками по 500–1000, последовательно.
• Ставьте Idempotency-Key на каждый запрос (например, orders-<номер пакета>), чтобы повтор после обрыва связи был безопасным — см. Идемпотентность.
• Нужны права ключа orders.create и orders.edit.