API посылок для разработчиков

1. Определение перевозчиков по трек-номеру (Поиск)

GET-запрос может получить полный список всех поддерживаемых перевозчиков, доступных через API отслеживания Посылки из Китая. Этот конечный пункт полезен для определения, какие перевозчики связаны с конкретным трек-номером, до начала запроса отслеживания.

Пример запроса


curl -X GET "https://developers.chinaparcels.com/api/v1/user/{USER_API_SECRET_ACCESS_KEY}/parcels/{TRACKING_NUMBER}/lookup"

Примечание:

  • Замените {USER_API_SECRET_ACCESS_KEY} на ваш уникальный секретный ключ API, полученный в личном кабинете.
  • Замените {TRACKING_NUMBER} на трек-номер вашей посылки.

Описание параметров ответа

  • error: Код ошибки, указывающий на результат запроса (см. коды ошибок ниже).
  • result: Массив идентификаторов перевозчиков, соответствующих трек-номеру.

Пример ответа


{
  "error": -1,
  "result": ["2", "4"]
}

В этом ответе:

  • 2 (USPS) и 4 (Royal Mail) являются идентификаторами перевозчиков, которые соответствуют трек-номеру. Вы можете просмотреть все идентификаторы перевозчиков в разделе API перевозчиков. 

Коды ошибок

  • -1 - Запрос выполнен успешно;
  • 0 - Пользователь не найден;
  • 1 - Недостаточно средств на балансе;

2. Отслеживание посылки по трек-номеру

Мы предлагаем два метода отслеживания посылки: наш алгоритм может автоматически определять перевозчика. Вы также можете указать перевозчика для отслеживания посылки.

2.1 Пример запроса с автоматическим определением перевозчика


curl -X GET "https://developers.chinaparcels.com/api/v1/user/{USER_API_SECRET_ACCESS_KEY}/parcels/{TRACKING_NUMBER}/track"

Примечание:

  • Замените {USER_API_SECRET_ACCESS_KEY} на ваш уникальный секретный ключ API, полученный в личном кабинете.
  • Замените {TRACKING_NUMBER} на трек-номер вашей посылки.

2.2 Пример запроса для текущего идентификатора перевозчика


curl -X GET "https://developers.chinaparcels.com/api/v1/user/{USER_API_SECRET_ACCESS_KEY}/parcels/{TRACKING_NUMBER}/track/{CARRIER_ID}"

Примечание:

  • Замените {USER_API_SECRET_ACCESS_KEY} на ваш уникальный секретный ключ API, полученный в личном кабинете.
  • Замените {TRACKING_NUMBER} на трек-номер вашей посылки.
  • Замените {CARRIER_ID} на идентификатор перевозчика, полученный в разделе API перевозчиков или в результатах поиска (выше).

Описание параметров ответа

Основной объект ответа

  • error: Код ошибки, указывающий на результат запроса (см. коды ошибок ниже).
  • result: Объект, содержащий данные отслеживания посылки и информацию о перевозчике.

Данные отслеживания (carrier_tracking_data)

Массив событий отслеживания:

  • time: Временная метка события (в формате Unix).
  • info: Описание события.
  • location: Местоположение, где произошло событие.
  • date: Дата и время события в формате YYYY-MM-DD HH:mm:ss.

Данные о посылке (parcel_other_data)

Детали посылки:

  • postal_product: Почтовый продукт или услуга, которая была использована (например, "Priority Mail Express International").
  • reference_tracking_numbers: Дополнительный массив референсных трек-номеров, если они доступны.
  • description: Описание посылки, предоставленное перевозчиком.
  • recipient: Информация о получателе, если доступна.
  • sender: Информация об отправителе, если доступна.
  • scheduled_delivery: Ожидаемая информация о доставке от перевозчика.
  • weight: Вес посылки.
  • dimensions: Габариты посылки.

Происхождение и пункт назначения посылки

  • parcel_origin_country_code: Код страны происхождения в формате ISO 3166-1 alpha-2.
  • parcel_destination_country_code: Код страны назначения в формате ISO 3166-1 alpha-2.

Данные перевозчика (carrier)

Информация о перевозчике:

  • carrier_website: Официальный вебсайт перевозчика.
  • carrier_email: Контактный email перевозчика.
  • carrier_phone: Контактный номер телефона перевозчика.
  • carrier_type: Тип перевозчика (например, "post", "courier").
  • carrier_support: Указывает, поддерживается ли перевозчик (1: Да, 0: Нет).
  • carrier_country_name: Страна, где базируется перевозчик.
  • carrier_icon: URL-адрес иконки перевозчика.
  • carrier_icon_width: Ширина иконки перевозчика (в пикселях).
  • carrier_icon_height: Высота иконки перевозчика (в пикселях).
  • carrier_thumbnail: URL-адрес миниатюры перевозчика.
  • carrier_thumbnail_width: Ширина миниатюры (в пикселях).
  • carrier_thumbnail_height: Высота миниатюры (в пикселях).
  • carrier_name: Название перевозчика.
  • carrier_country_code: Код страны перевозчика в формате ISO 3166-1 alpha-2.
  • carrier_language_code: Код языка, который использует перевозчик для данных отслеживания (например, "en").

Прогноз доставки

  • estimate_delivery_days: Ожидаемое количество дней до доставки.
  • estimate_delivery_date: Ожидаемая дата доставки (YYYY-MM-DD) от первой даты отслеживания.

Статус посылки

  • status: Текущий статус посылки:
    • 1 - Не найдено;
    • 2 - В пути;
    • 3 - Ожидает получения; 
    • 4 - Доставлено;
    • 5 - Предупреждение;
    • 6 - Не доставлено;
    • 7 - Просрочено.

Пример ответа


{
  "error": -1,
  "result": {
    "carrier_tracking_data": [
      {
        "time": 1733313180,
        "info": "Таможенная очистка.",
        "location": "ТУРЦИЯ",
        "date": "2024-12-04 11:53:00"
      },
      {
        "time": 1733313000,
        "info": "Обработано в центре.",
        "location": "ТУРЦИЯ",
        "date": "2024-12-04 11:50:00"
      }
    ],


    "parcel_other_data": {
      "postal_product": "Priority Mail Express International",
      "reference_tracking_numbers": [
        "REF_NUMBER_01",
        "REF_NUMBER_02"
      ],
      "description": "Описание посылки от перевозчика",
      "recipient": "Информация о получателе",
      "sender": "Информация об отправителе",
      "scheduled_delivery": "Ожидаемая доставка",
      "weight": "Вес посылки",
      "dimensions": "Габариты посылки"
    },
    "parcel_origin_country_code": "us",
    "parcel_destination_country_code": "tr",
    "status": 2,
    "carrier": {
      "carrier_website": "https://www.usps.com",
      "carrier_email": "support@usps.com",
      "carrier_phone": "1-800-222-1811",
      "carrier_type": "почтовый",
      "carrier_country_name": "Соединенные Штаты Америки",
      "carrier_name": "USPS",

      "carrier_icon": "http://developers.chinaparcels.com/cdn/images/carriers/icons/0002-usps.png",
      "carrier_icon_width": 256,
      "carrier_icon_height": 256,
      "carrier_thumbnail": "http://developers.chinaparcels.com/cdn/images/carriers/thumbnails/0002-usps.png",
      "carrier_thumbnail_width": 640,
      "carrier_thumbnail_height": 256,
      "carrier_country_code": "us",
      "carrier_language_code": "en"
    },
    "estimate_delivery_days": 16,
    "estimate_delivery_date": "2024-12-13"
  }
}

Коды ошибок

  • -1 - Запрос выполнен успешно;
  • 0 - Пользователь не найден;
  • 1 - Недостаточно средств на балансе;
  • 3 - Перевозчик с данным номером не найден (для автоматического определения).