Документ по разработке API запроса статуса отгрузки

пакетное путешествие

API автоматически определит, на каком этапе находится посылка, на основе номера заказа, и вернет текущий статус, полный график и (если посылка поступила на Тайваньскую таможню) ход пятиэтапного таможенного оформления GC329.

Base URL

Заголовок аутентификации (выберите один)

Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx
// 或
X-API-Key: lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Пожалуйста, вызовите его со стороны сервера и не вводите ключ во внешний JavaScript. Ограничение скорости указывается в ключевых единицах, а заголовок ответа X-RateLimit-Remaining сообщит об оставшемся лимите; если лимит превышен, будет возвращен HTTP 429.

GETPOST /api/v1/shipment/track

Проверьте статус отправки одной посылки по номеру отслеживания. Допускаются как GET (строка запроса), так и POST (JSON/форма).

Параметры запроса

параметр	Тип	Необходимый	иллюстрировать
tracking_number	string	Необходимый	Номер отслеживания посылки (4–64 символа, буквенно-цифровой и - _). Номер отслеживания экспресс-доставки в Китае/номер отслеживания клиента/номер отслеживания доставки приемлемы.

Пример запроса (GET)

curl "https://0523.tw/api/v1/shipment/track?tracking_number=SF1234567890123" \
  -H "Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Ответ 200 (пример уже на складе/в пути)

{
  "success": true,
  "cached": false,
  "tracking_number": "SF1234567890123",
  "data": {
    "tracking_number": "SF1234567890123",
    "customer_order_no": "LK260601001",
    "carrier_tracking_no": "SF1234567890123",
    "logistics": "順豐速運",
    "status_code": 2,
    "status": "已入倉",
    "description": "包裹已進入深圳集運倉,等待集運打包",
    "is_delivered": false,
    "is_final": false,
    "last_event_time": "2026-06-01 12:30:00",
    "updated_at": "2026-06-01 12:31:05",
    "timeline": [
      { "name": "已攬收", "completed": true,  "time": "2026-05-30 09:00:00" },
      { "name": "已入倉 (深圳集運倉)", "completed": true,  "time": "2026-06-01 12:30:00" },
      { "name": "集運打包/台灣運送", "completed": false, "time": null },
      { "name": "已簽收", "completed": false, "time": null }
    ],
    "customs_stages": null,
    "events": null
  }
}

Ответ 404 (номер заказа не найден)

{
  "success": false,
  "error": "not_found",
  "message": "查無此單號。請確認單號正確,或包裹尚未進入集運系統。",
  "tracking_number": "SF1234567890123"
}

поле	Тип	иллюстрировать
status	string	Текущий статус (читабельный для человека) , например, прогнозируется/на складе/в пути/отправлено на Тайвань/подписано для получения. Рекомендуется отображать эту строку напрямую.
status_code	number	Код состояния (зависит от источника, см. следующий раздел). Для управления пользовательским интерфейсом рекомендуется использовать status, is_delivered, is_final.
is_delivered	bool	Подписано ли оно?
is_final	bool	Является ли оно окончательным (подписанным/возвращенным/отмененным/недоставленным). Верно, чтобы остановить опрос.
logistics	string	Логистический провайдер (доставка через терминал China Express или Тайвань).
description	string	Последнее описание события.
last_event_time	datetime	Время последнего логистического события.
timeline	array	Временная шкала этапа, каждый элемент содержит name / completed / time / description.
customs_stages	object|null	Тайваньская таможня GC329 Ход таможенного оформления (ноль, если таможенное оформление еще не завершено). См. следующий раздел.
events	array|null	Исходная история логистических событий (предоставляется при отслеживании доставки через терминал).

Основной этап консолидации (хронология)

этап	значение
Прогнозируемый (не поступивший на склад)	Клиент предсказал номер заказа, но посылка еще не прибыла на консолидационный склад в Шэньчжэне.
Уже складировано (контейнерный склад в Шэньчжэне)	Склад консолидации Шэньчжэня получил посылку.
Консолидация и упаковка/доставка в Тайвань	Упаковано и отправлено, отправлено морским/воздушным транспортом на Тайвань.
В пути/доставке в Тайвань	Таможенное оформление и окончательная доставка после прибытия на Тайвань.
Подписался на	Получатель подписался на доставку (is_delivered = true).

Этапы таможенного оформления (customs_stages,GC329)

После того, как посылка попадет на таможню Тайваня, customs_stages покажет ход выполнения пяти этапов и общий процент:

{
  "hbl": "691MK539819",
  "trans_type_name": "海運",
  "current_stage_name": "海關放行",
  "progress_percent": 80,
  "is_completed": false,
  "stages": [
    { "code": "XX", "name": "船(機)抵達",   "done": true },
    { "code": "E1", "name": "連線收單建檔", "done": true },
    { "code": "D1", "name": "計稅",        "done": true },
    { "code": "RL", "name": "海關放行",     "done": true },
    { "code": "OW", "name": "出倉",        "done": false }
  ],
  "source": "關港貿單一窗口 GC329"
}

HTTP	error	иллюстрировать
401	missing_api_key / invalid_api_key	Нет/неверный ключ API.
403	insufficient_scope	Ключу не предоставлено разрешение shipment:read.
404	not_found	Этот номер отслеживания не найден, или посылка еще не вошла в систему консолидации.
422	validation_failed	track_number отсутствует или не соответствует формату.
429	rate_limit_exceeded	Превышение лимита запросов в минуту, см. Повтор-После.

• Частота опроса : рекомендуется проверять один и тот же номер заказа каждые 15–30 минут; результат кэшируется на этом сервере в течение 5 минут (cached: true означает попадание).
• прекращает опрос. : останавливает опрос, когда is_final = true (подписано/возвращено/отменено).
• Драйвер состояния : Отобразите строку status, используйте is_delivered / is_final, чтобы оценить процесс и избежать жесткого кодирования. status_code (различные определения исходного кода различны).
• Номер заказа отсутствует :404 Скорее всего, это означает, что посылка еще не поступила в систему консолидации (клиент только что разместил заказ, но не отправил его), и вы можете повторить попытку позже.

техническая поддержка: howyunqisoftware@gmail.com

Версия API: v1 (стабильная).

История изменений: 01.06.2026 — API запроса статуса доставки v1 доступен в сети.