Интеграция со Starex

Этот документ предназначен для внешних систем, которые интегрируются со Starex. Он описывает webhook-уведомления и API для получения статусов отправлений.

Базовый URL и данные Basic-Auth (логин/пароль) предоставляются компанией Starex. Ниже базовый URL обозначен как {BASE_URL}.

1. О webhook

При изменении статуса отправления Starex автоматически отправляет HTTP POST запрос на предоставленный вами URL. Так вы получаете изменения статусов в реальном времени.

Чтобы начать интеграцию, вы предоставляете Starex:

Webhook URL — ваш адрес для приёма уведомлений (например https://ваш-домен.uz/starex/webhook).

Ответ: для подтверждения приёма верните HTTP 200. Любой другой ответ (4xx, 5xx, timeout) считается неудачей, и Starex повторит отправку несколько раз.

2. Содержимое webhook

Starex отправляет на ваш URL следующий запрос:

POST {ВАШ_WEBHOOK_URL}
Content-Type: application/json

Тело (JSON):

{
  "barcode": "AB123456789UZ",
  "state": 12,
  "statetime": "2026-06-15 14:30:00"
}

Поле	Тип	Описание
`barcode`	string	Штрих-код отправления
`state`	integer	Код статуса (значения кодов — раздел 3: API списка статусов)
`statetime`	string	Дата-время изменения статуса

3. API списка статусов

Возвращает список всех возможных статусов, чтобы расшифровать код state из webhook.

GET {BASE_URL}/api/v1/dictionaries/states

Авторизация: Basic Auth.

GET {BASE_URL}/api/v1/dictionaries/states
Authorization: Basic base64(логин:пароль)
Accept: application/json

Ответ (200) — пример (часть списка):

{
  "success": true,
  "data": [
    { "code": 0, "name": "Ожидает синхронизации", "advanced": "AWAITING_SYNC" },
    { "code": 1, "name": "Новый",                  "advanced": "NEW" },
    { "code": 9, "name": "Доставлен",              "advanced": "COMPLETE" }
  ]
}

Поле	Тип	Описание
`code`	integer	Код статуса (совпадает с `state` в webhook)
`name`	string	Название статуса (возвращается на русском)
`advanced`	string	Стабильный, языконезависимый код (машинный код)

Важно: список статусов не является постоянным — могут добавляться новые статусы или меняться существующие. Поэтому не «зашивайте» список в этот документ; всегда получайте актуальный список из этого API.

advanced — это текстовый (мнемонический) код, привязанный к каждому статусу, например NEW, PICKUP, DELIVERY, COMPLETE. Его вместе с code удобно использовать в логике; name — для отображения (на русском).

4. API статусов заказа

Возвращает историю статусов одного отправления (заказа) по штрих-коду.

GET {BASE_URL}/api/v1/order/trace

Авторизация: Basic Auth.

Параметр	Тип	Обязательный	Описание
`barcode`	string	Да	Штрих-код отправления

GET {BASE_URL}/api/v1/order/trace?barcode=AB123456789UZ
Authorization: Basic base64(логин:пароль)
Accept: application/json

Ответ (200):

{
  "success": true,
  "data": {
    "barcode": "AB123456789UZ",
    "date": "2026-06-10 09:00:00",
    "weight": 1.5,
    "recipient": "Имя Фамилия",
    "trace": [
      { "code": 1, "name": "Новый",     "advansed": "NEW",      "statetime": "2026-06-10 09:00:00" },
      { "code": 9, "name": "Доставлен", "advansed": "COMPLETE", "statetime": "2026-06-15 14:30:00" }
    ]
  }
}

Поле	Тип	Описание
`barcode`	string	Штрих-код отправления
`date`	string\|null	Дата приёма
`weight`	number\|null	Вес
`recipient`	string\|null	Получатель
`trace[]`	array	История статусов (по времени)
`trace[].code`	integer	Код статуса
`trace[].name`	string\|null	Название статуса
`trace[].advansed`	string\|null	Дополнительное описание
`trace[].statetime`	string\|null	Время статуса

Ошибка (например, штрих-код не найден) возвращается в виде:

{
  "success": false,
  "error": { "code": 422, "message": "..." }
}