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: Контактна електронна адреса перевізника.
  • 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 - Перевізника з цим номером не знайдено (для автоматичного визначення).