Заказы

Создание

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

curl -X POST https://api.govza.app/v1/delivery/orders \
  -H "Authorization: Bearer $GOVZA_KEY" \
  -H "Content-Type: application/json" \
  -d @order.json

В ответе:

{
  "success": true,
  "data": {
    "external_order_id": "SHOP-10432",
    "order_code": "YB2072",
    "status": "new",
    "price": 300,
    "tracking_url": "https://track.govza.app/abc123",
    "tracking_urls": null,
    "visit_order": [0],
    "delivered_at": null,
    "driver": null,
    "driver_location": null
  }
}

Когда курьер назначен и заказ в работе, driver и driver_location заполняются:

{
  "status": "in_progress",
  "delivered_at": null,
  "driver": {
    "name": "Иса",
    "phone": "+79280003396",
    "transport": { "type": "car", "make": "Toyota", "model": "Camry", "color": "белый", "number": "A123BC" }
  },
  "driver_location": {
    "latitude": 43.2389,
    "longitude": 45.7127,
    "heading": 120,
    "updated_at": "2026-09-18T08:27:00.000Z"
  }
}

driver_location приходит только в статусах assigned и in_progress и только если местоположение курьера обновлялось за последние 30 минут. После доставки в delivered_at записывается время завершения заказа.

tracking_url — публичная страница отслеживания всего заказа, её можно отправить получателю. Ссылка перестаёт работать через 24 часа после того, как заказ доставлен или отменён. Сохраните её при создании заказа: при получении заказа и в списке возвращаются только уже существующие ссылки, новые там не создаются. Если ссылка нужна позже, запросите её явно:

curl -X POST https://api.govza.app/v1/delivery/orders/SHOP-10432/tracking_link \
  -H "Authorization: Bearer $GOVZA_KEY"

Если точка доставки одна, tracking_urls равен null. Если их несколько, он содержит отдельную ссылку для каждой точки в том же порядке, в котором вы передали точки доставки, либо null, если такие ссылки недоступны.

Для заказа с несколькими точками доставки:

"tracking_urls": [
  "https://track.govza.app/abc123?route=8f3a1c2d",
  "https://track.govza.app/abc123?route=41b7e902"
]

Порядок точек доставки

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

given (по умолчанию) — в переданном порядке;
optimized — все точки в порядке кратчайшего маршрута от точки забора;
optimized_keep_last — так же, но последняя переданная точка остаётся последней, например возврат на склад.

{
  "external_order_id": "SHOP-10433",
  "routing_mode": "sequential",
  "dropoff_order": "optimized_keep_last",
  "pickup": { … },
  "dropoffs": [ … ]
}

Точка забора всегда первая. Маршрут выбирается по расстоянию по дорогам, и стоимость доставки считается по нему же. Если ни один порядок не короче переданного, точки остаются как есть. Поле работает только при routing_mode: sequential: с parallel каждая точка и так считается от точки забора, и запрос вернёт ошибку 400.

Порядок объезда приходит в visit_order — это номера точек в переданном массиве dropoffs, считая с нуля, в том порядке, в котором их посетит курьер:

"visit_order": [2, 0, 1]

Здесь курьер сначала едет к третьей переданной точке, затем к первой и ко второй. Всё остальное по-прежнему следует вашему порядку: tracking_urls, dropoffs в ответе POST /quotes и index в PATCH. Если не указать, у какой точки выкуп, он относится к первой точке в dropoffs — первой в вашем порядке, а не в порядке объезда.

Чтобы зафиксировать цену, передайте в POST /quotes то же значение dropoff_order, что и в POST /orders: расчёт с другим порядком не подходит к заказу, и маршрут будет рассчитан заново.

Защита от дублей

external_order_id — ваш идентификатор заказа. Повторный запрос с тем же значением не создаёт дубликат.

201 — заказ создан;
200 — этот external_order_id уже использовался, возвращён исходный заказ;
409 — параллельный запрос прямо сейчас создаёт этот заказ, повторите позже.

Повтор после сетевого таймаута безопасен. Используйте идентификатор из своей системы и не используйте его повторно для другой доставки.

Получение статуса

Получить список заказов можно так:

curl 'https://api.govza.app/v1/delivery/orders?limit=20&offset=0' \
  -H "Authorization: Bearer $GOVZA_KEY"

Заказы возвращаются от новых к старым. limit — не больше 100, по умолчанию 20.

Для одного заказа:

curl https://api.govza.app/v1/delivery/orders/SHOP-10432 \
  -H "Authorization: Bearer $GOVZA_KEY"

Последовательность статусов:

new → assigned → in_progress → delivered

либо cancelled в любой момент до доставки.

Ответ содержит текущий статус, цену, ссылку на отслеживание, назначенного курьера (если он уже есть) и историю изменений статуса.

Отмена

curl -X POST https://api.govza.app/v1/delivery/orders/SHOP-10432/cancel \
  -H "Authorization: Bearer $GOVZA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "customer_changed_mind" }'

Редактирование

Изменить заказ можно через PUT /v1/delivery/orders/{external_order_id}, пока его статус new или assigned. Передайте то же тело запроса, что и при создании.

Если нужно изменить только часть заказа, используйте PATCH. Передавайте только изменяемые поля:

curl -X PATCH https://api.govza.app/v1/delivery/orders/SHOP-10432 \
  -H "Authorization: Bearer $GOVZA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "comment": "Позвонить за 5 минут", "dropoffs": [{ "index": 1, "contact": { "name": "Залина" } }] }'

Вложенные адреса и контакты объединяются с сохранёнными значениями. Передавайте только изменяемые точки. Поле index — номер точки доставки, считая с нуля; без него используется позиция элемента в переданном массиве.

При изменении координат, размера груза, режима маршрута или dropoff_order Govza проверяет quote_id и при необходимости рассчитывает маршрут заново, а вместе с ним и порядок точек. Если курьер уже взял заказ, порядок объезда не меняется, пока число точек остаётся прежним. Изменение имени, контакта, текстовой части адреса, комментария или суммы выкупа сохраняет существующий маршрут и само по себе не меняет стоимость доставки.