Заказы

Создание

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

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,
    "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 — публичная страница отслеживания всего заказа, её можно отправить получателю. Сохраните её при создании заказа: при чтении и в списке возвращаются только уже существующие ссылки, новые там не создаются. Если ссылка нужна позже, запросите её явно:

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

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

Для заказа с несколькими dropoff:

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

Идемпотентность

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. Используйте тот же payload, что и при создании.

Если нужно изменить только часть заказа, используйте 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 с нуля; без него используется позиция элемента в переданном массиве.

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