快速开始
5分钟快速集成物流API，开始您的第一次API调用
1
获取API密钥
首先，您需要注册账户并获取API密钥。每个API请求都需要使用您的密钥进行身份验证。
提示：请妥善保管您的API密钥，不要在客户端代码中暴露密钥。
- 登录您的账户
- 进入"API管理"页面
- 点击"创建新密钥"
- 复制生成的API密钥
2
发起第一个请求
让我们从一个简单的API调用开始，获取您的账户信息：
GET https://www.guansuda-express.com/api/v1/user/profile
# 使用 cURL
curl -X GET "https://www.guansuda-express.com/api/v1/user/profile" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"// 使用 JavaScript (fetch)
fetch('https://www.guansuda-express.com/api/v1/user/profile', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(data => console.log(data));响应示例：
{
"success": true,
"data": {
"id": 123,
"name": "张三",
"email": "zhangsan@example.com",
"balance": 1000.00,
"api_calls_remaining": 9500
}
}3
创建您的第一个订单
现在让我们创建一个快递订单：
POST https://www.guansuda-express.com/api/v1/orders
curl -X POST "https://www.guansuda-express.com/api/v1/orders" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sender": {
"name": "张三",
"phone": "13800138000",
"province": "北京市",
"city": "北京市",
"district": "朝阳区",
"detail": "三里屯街道1号"
},
"receiver": {
"name": "李四",
"phone": "13800138001",
"province": "上海市",
"city": "上海市",
"district": "浦东新区",
"detail": "陆家嘴金融中心1号"
},
"item": {
"name": "文件",
"description": "重要合同文件",
"weight": 0.5,
"value": 100.00,
"quantity": 1
},
"service_type": "standard"
}'响应示例：
{
"success": true,
"data": {
"id": 12345,
"order_no": "ORD20240722001",
"tracking_number": "TRK20240722123456",
"status": "pending",
"estimated_fee": 25.00,
"created_at": "2024-07-22T10:30:00Z"
},
"message": "订单创建成功"
}4
查询物流信息
使用物流单号查询包裹的实时位置和状态：
GET https://www.guansuda-express.com/api/v1/tracking/{tracking_number}
curl -X GET "https://www.guansuda-express.com/api/v1/tracking/TRK20240722123456" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"响应示例：
{
"success": true,
"data": {
"tracking_number": "TRK20240722123456",
"status": "in_transit",
"current_location": "北京分拣中心",
"estimated_delivery": "2024-07-23T18:00:00Z",
"records": [
{
"location": "北京分拣中心",
"description": "包裹已发出，正在运输途中",
"occurred_at": "2024-07-22T14:30:00Z"
},
{
"location": "北京三里屯营业点",
"description": "包裹已收寄",
"occurred_at": "2024-07-22T10:45:00Z"
}
]
}
}请求参数说明
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
sender |
Object | 必填 | 寄件人信息 |
receiver |
Object | 必填 | 收件人信息 |
item |
Object | 必填 | 物品信息 |
service_type |
String | 可选 | 服务类型：standard, express, same_day |
错误处理
当API调用失败时，会返回相应的错误信息：
{
"success": false,
"error": {
"code": "INVALID_PARAMETER",
"message": "寄件人电话号码格式不正确",
"details": {
"field": "sender.phone",
"value": "invalid_phone"
}
}
}
提示：完整的错误代码列表请参考 错误代码文档。