Получение данных Express-tracking по заказу

POST /v1/dbs/tracking/get

POST/v1/dbs/tracking/get

Возвращает информацию о выполнении экспресс-доставки: статус поиска и движения курьера, данные назначенного курьера, его текущее местоположение и координаты места доставки. Метод применяется только для заказов с экспресс-доставкой (delivery_type = EXPRESS). Рекомендуемый интервал polling со стороны витрины — около одного запроса в минуту. После DELIVERED данные tracking доступны 24 часа.

Запрос передаёт merchant_order_ids или client_order_id. Ответ — массив trackings.

Тело запроса

merchant_order_ids
string[]

Идентификаторы заказов продавца.

client_order_id
string

Идентификатор заказа клиента.

Успешный ответ

200A successful response.
application/json
object
trackings
array
required

Элементы трекинга.

Элемент трекинга.

Показать свойства
merchant_order_id
string

Идентификатор заказа продавца.

client_order_id
string

Идентификатор заказа клиента.

courier_search_deadline_at
string

Дата и время, до которого ожидается назначение курьера. Формат RFC3339 с обязательным timezone (пример: 2026-07-02T10:25:00+02:00). Несоблюдение формата может привести к непредсказуемому поведению системы и проблемам с заказами. Часовой пояс остаётся текстом внутри этой строки.

status_history
array

История статусов Express-доставки. Текущий статус — последний элемент по changed_at.

DbsTrackingStatusHistoryItem

Показать свойства

DbsTrackingStatusHistoryItem

status_id
string
required

Идентификатор статуса.

  • SEARCHING: Поиск курьера
  • ASSIGNED: Курьер назначен
  • PICKED_UP: Курьер забрал заказ
  • ON_THE_WAY: Курьер направляется к месту доставки
  • DELIVERED: Заказ доставлен
  • CANCELLED: Доставка не состоится
Допустимые значения
SEARCHINGASSIGNEDPICKED_UPON_THE_WAYDELIVEREDCANCELLED
status_name
string

Человекочитаемое название статуса.

changed_at
string
required

Время события (date-time, RFC3339). Формат RFC3339 с обязательным timezone (пример: 2026-07-02T10:25:00+02:00). Несоблюдение формата может привести к непредсказуемому поведению системы и проблемам с заказами.

courier
object

Данные курьера.

Показать свойства
name
string
required

Имя курьера.

phone
string
required

Телефон курьера.

vehicle
object

Транспортное средство (опционально).

Показать свойства
model
string

Модель транспортного средства.

plate_number
string

Государственный номер.

courier_location
object

Последняя известная позиция курьера.

Показать свойства
latitude
number
required

Широта.

longitude
number
required

Долгота.

changed_at
string

Время актуальности координат (date-time, RFC3339). Формат RFC3339 с обязательным timezone (пример: 2026-07-02T10:25:00+02:00). Несоблюдение формата может привести к непредсказуемому поведению системы и проблемам с заказами.

destination_location
object

Координаты места доставки.

Показать свойства
latitude
number

Широта.

longitude
number

Долгота.

errors
array

Ошибки элемента.

Ошибка для scope «DbsTrackingGet». Допустимые field: merchant_order_id. Коды — DbsTrackingValidationErrorCode.

Ошибка для scope «DbsTrackingGet». Допустимые field: merchant_order_id. Коды — DbsTrackingValidationErrorCode.

Показать свойства
field
string
required

Путь к полю. Ожидаемые: merchant_order_id.

code
string
required

Коды ошибок трекинга.

  • REQUIRED_ONE_OF: Нужен ровно один фильтр
  • INVALID_TYPE: Неверный JSON-тип
  • TOO_MANY_ITEMS: Превышен лимит элементов
  • NOT_FOUND: Заказ не найден или данные tracking недоступны
  • STATUS_NOT_ALLOWED: Метод применим только для заказов с delivery_type = EXPRESS
Допустимые значения
REQUIRED_ONE_OFINVALID_TYPETOO_MANY_ITEMSNOT_FOUNDSTATUS_NOT_ALLOWED
message
string
required

Текст для клиента.

Ошибки

400Некорректный запрос
application/json
object
error_type
string

Класс транспортной ошибки запроса (HTTP 4xx/5xx).

Поэлементные и бизнес-ошибки сущности приходят в HTTP 200 в errors/failed, не в этом поле.

  • ERROR_TYPE_UNSPECIFIED: не используется
  • ERROR_TYPE_UNAUTHORIZED: HTTP 401
  • ERROR_TYPE_RATE_LIMIT: HTTP 429
  • ERROR_TYPE_INTERNAL: HTTP 500
  • ERROR_TYPE_BAD_REQUEST: HTTP 400 (уровень запроса)
Допустимые значения
ERROR_TYPE_UNSPECIFIEDERROR_TYPE_UNAUTHORIZEDERROR_TYPE_RATE_LIMITERROR_TYPE_INTERNALERROR_TYPE_BAD_REQUEST
code
string

Машинный код ошибки. Уточняет error_type.

message
string

Человекочитаемое сообщение об ошибке.

details
object
401Ошибка авторизации
application/json
object
error_type
string

Класс транспортной ошибки запроса (HTTP 4xx/5xx).

Поэлементные и бизнес-ошибки сущности приходят в HTTP 200 в errors/failed, не в этом поле.

  • ERROR_TYPE_UNSPECIFIED: не используется
  • ERROR_TYPE_UNAUTHORIZED: HTTP 401
  • ERROR_TYPE_RATE_LIMIT: HTTP 429
  • ERROR_TYPE_INTERNAL: HTTP 500
  • ERROR_TYPE_BAD_REQUEST: HTTP 400 (уровень запроса)
Допустимые значения
ERROR_TYPE_UNSPECIFIEDERROR_TYPE_UNAUTHORIZEDERROR_TYPE_RATE_LIMITERROR_TYPE_INTERNALERROR_TYPE_BAD_REQUEST
code
string

Машинный код ошибки. Уточняет error_type.

message
string

Человекочитаемое сообщение об ошибке.

details
object
429Превышен лимит запросов
application/json
object
error_type
string

Класс транспортной ошибки запроса (HTTP 4xx/5xx).

Поэлементные и бизнес-ошибки сущности приходят в HTTP 200 в errors/failed, не в этом поле.

  • ERROR_TYPE_UNSPECIFIED: не используется
  • ERROR_TYPE_UNAUTHORIZED: HTTP 401
  • ERROR_TYPE_RATE_LIMIT: HTTP 429
  • ERROR_TYPE_INTERNAL: HTTP 500
  • ERROR_TYPE_BAD_REQUEST: HTTP 400 (уровень запроса)
Допустимые значения
ERROR_TYPE_UNSPECIFIEDERROR_TYPE_UNAUTHORIZEDERROR_TYPE_RATE_LIMITERROR_TYPE_INTERNALERROR_TYPE_BAD_REQUEST
code
string

Машинный код ошибки. Уточняет error_type.

message
string

Человекочитаемое сообщение об ошибке.

details
object
500Внутренняя ошибка сервера
application/json
object
error_type
string

Класс транспортной ошибки запроса (HTTP 4xx/5xx).

Поэлементные и бизнес-ошибки сущности приходят в HTTP 200 в errors/failed, не в этом поле.

  • ERROR_TYPE_UNSPECIFIED: не используется
  • ERROR_TYPE_UNAUTHORIZED: HTTP 401
  • ERROR_TYPE_RATE_LIMIT: HTTP 429
  • ERROR_TYPE_INTERNAL: HTTP 500
  • ERROR_TYPE_BAD_REQUEST: HTTP 400 (уровень запроса)
Допустимые значения
ERROR_TYPE_UNSPECIFIEDERROR_TYPE_UNAUTHORIZEDERROR_TYPE_RATE_LIMITERROR_TYPE_INTERNALERROR_TYPE_BAD_REQUEST
code
string

Машинный код ошибки. Уточняет error_type.

message
string

Человекочитаемое сообщение об ошибке.

details
object
POST/v1/dbs/tracking/get
1curl https://api.example.com/v1/dbs/tracking/get \2  --request POST \3  --header 'Content-Type: application/json' \4  --data '{5  "merchant_order_ids": [6    "string"7  ],8  "client_order_id": "string"9}'
{
  "trackings": [
    {
      "merchant_order_id": "string",
      "client_order_id": "string",
      "courier_search_deadline_at": "string",
      "status_history": [
        {
          "status_id": "string",
          "status_name": "string",
          "changed_at": "string"
        }
      ],
      "courier": {
        "name": "string",
        "phone": "+79995553311",
        "vehicle": {
          "model": "string",
          "plate_number": "string"
        }
      },
      "courier_location": {
        "latitude": 0,
        "longitude": 0,
        "changed_at": "string"
      },
      "destination_location": {
        "latitude": 0,
        "longitude": 0
      },
      "errors": [
        {
          "field": "string",
          "code": "string",
          "message": "string"
        }
      ]
    }
  ]
}

A successful response.