开发者的包裹 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：一个与追踪号码匹配的运输商 ID 数组。

响应示例


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

在此响应中：

2 (USPS) 和 4 (Royal Mail) 是与追踪号码匹配的运输商 ID。您可以在运输商 API 部分查看所有运输商 ID。

错误代码

-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 当前运输商 ID 的请求示例


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 部分或查询（上文）中获取的运输商 ID。

响应参数描述

主响应对象

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": "国际特快邮件服务",
      "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 - 根据此号码未找到运输商（用于自动检测运输商）。

开发者的包裹 API

1. 通过追踪号码识别运输商（查询）

请求示例

响应参数描述

响应示例

错误代码

2. 通过追踪号码追踪包裹

2.1 自动检测运输商的请求示例

2.2 当前运输商 ID 的请求示例

响应参数描述

主响应对象

追踪数据 (carrier_tracking_data)

包裹数据 (parcel_other_data)

包裹的起始地与目的地

运输商数据 (carrier)

预计交付信息

包裹状态

响应示例

错误代码

追踪数据 (`carrier_tracking_data`)

包裹数据 (`parcel_other_data`)

运输商数据 (`carrier`)