Заказы

Создание

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

curl -X POST https://api.govza.app/v1/partner/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
  }
}

tracking_url — публичная страница отслеживания всего заказа, её можно отправить получателю. Для одного 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/partner/orders?limit=20&offset=0' \
  -H "Authorization: Bearer $GOVZA_KEY"

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

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

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

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

new → assigned → in_progress → delivered

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

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

Отмена

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

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

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

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

curl -X PATCH https://api.govza.app/v1/partner/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 и при необходимости рассчитывает маршрут заново. Изменение имени, контакта, текстовой части адреса, комментария или суммы выкупа сохраняет существующий маршрут и само по себе не меняет стоимость доставки.