客服热线：13652661412 303718005@qq.com
API对接 English 登录/注册

API接口文档

标准RESTful API，助力您的系统无缝对接

概述

盛越物流提供标准的RESTful API接口，支持物流查询、价格查询、下单、取消订单等功能。通过API对接，您可以：

  • 实时查询物流轨迹信息
  • 在线获取运费报价
  • 系统直接下单，无需人工干预
  • 接收实时的物流状态变更通知

基础信息

API地址： https://shengyue56.com/api/v1
数据格式： JSON
字符编码： UTF-8
请求方式： HTTP POST/GET

认证方式

所有API请求都需要进行身份认证。请在HTTP Header中携带以下参数：

请求头示例 
POST /api/v1/tracking HTTP/1.1
Host: shengyue56.com
Content-Type: application/json
App-Key: your_app_key
App-Secret: your_app_secret
Timestamp: 1710758400
Sign: generated_signature

签名生成规则

  1. 将所有请求参数（包括App-Key和Timestamp）按照参数名ASCII码从小到大排序
  2. 将排序后的参数拼接成字符串：key1=value1&key2=value2...
  3. 在字符串末尾拼接App-Secret
  4. 对拼接后的字符串进行MD5加密，得到签名
签名生成示例（Python） 
import hashlib
import time

def generate_sign(params, app_secret):
    # 按键名排序
    sorted_params = sorted(params.items())
    # 拼接字符串
    sign_str = '&'.join([f'{k}={v}' for k, v in sorted_params])
    sign_str += app_secret
    # MD5加密
    return hashlib.md5(sign_str.encode()).hexdigest()

# 使用示例
params = {
    'app_key': 'your_app_key',
    'timestamp': str(int(time.time())),
    'tracking_no': 'SY202403180001'
}
sign = generate_sign(params, 'your_app_secret')

物流查询接口

查询运单的物流轨迹信息。

GET /tracking

请求参数

参数名 类型 必填 说明
tracking_no string 是 运单号，多个单号用逗号分隔，最多支持10个

响应参数

参数名 类型 说明
code int 状态码，0表示成功
message string 返回信息
data array 物流信息数组
请求示例 
curl -X GET "https://shengyue56.com/api/v1/tracking?tracking_no=SY202403180001" \
  -H "App-Key: your_app_key" \
  -H "Timestamp: 1710758400" \
  -H "Sign: your_signature"
响应示例 
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "tracking_no": "SY202403180001",
      "status": "delivered",
      "status_text": "已签收",
      "sender": {
        "name": "张先生",
        "phone": "138****1234",
        "address": "广东省深圳市龙华区"
      },
      "receiver": {
        "name": "Mr. Smith",
        "phone": "+1-213****5678",
        "address": "Los Angeles, USA"
      },
      "goods": {
        "name": "电子产品",
        "weight": 25.5,
        "quantity": 10
      },
      "timeline": [
        {
          "time": "2024-03-18 14:30:25",
          "status": "delivered",
          "description": "已签收，签收人：Mr. Smith",
          "location": "Los Angeles, USA"
        },
        {
          "time": "2024-03-18 08:15:00",
          "status": "delivering",
          "description": "当地快递员正在派送中",
          "location": "Los Angeles, USA"
        },
        {
          "time": "2024-03-17 22:00:00",
          "status": "arrived",
          "description": "到达美国洛杉矶海外仓",
          "location": "Los Angeles, USA"
        },
        {
          "time": "2024-03-15 18:30:00",
          "status": "shipped",
          "description": "货物已从深圳出口报关",
          "location": "Shenzhen, China"
        }
      ]
    }
  ]
}

价格查询接口

查询指定线路的运费价格。

POST /pricing

请求参数

参数名 类型 必填 说明
from_city string 是 发货城市代码
to_city string 是 目的城市代码
weight float 是 货物重量（kg）
volume float 否 货物体积（m³）
service_type string 是 服务类型：standard/standard快递, express/特快, economy/经济
cargo_type string 否 货物类型：general/普通, electronics/电子, fragile/易碎
请求示例 
curl -X POST "https://shengyue56.com/api/v1/pricing" \
  -H "App-Key: your_app_key" \
  -H "Timestamp: 1710758400" \
  -H "Sign: your_signature" \
  -H "Content-Type: application/json" \
  -d '{
    "from_city": "hangzhou",
    "to_city": "shanghai",
    "weight": 25.5,
    "volume": 0.5,
    "service_type": "standard",
    "cargo_type": "general"
  }'
响应示例 
{
  "code": 0,
  "message": "success",
  "data": {
    "from_city": "深圳",
    "to_city": "洛杉矶",
    "weight": 25.5,
    "volume_weight": 83.33,
    "chargeable_weight": 83.33,
    "options": [
      {
        "service_type": "standard",
        "service_name": "标准快递",
        "price": 166.66,
        "currency": "CNY",
        "transit_time": "1-2天",
        "description": "门到门服务，全程追踪"
      },
      {
        "service_type": "express",
        "service_name": "特快专递",
        "price": 291.66,
        "currency": "CNY",
        "transit_time": "次日达",
        "description": "优先派送，时效保障"
      },
      {
        "service_type": "economy",
        "service_name": "经济物流",
        "price": 100.00,
        "currency": "CNY",
        "transit_time": "3-5天",
        "description": "价格实惠，网点自提"
      }
    ]
  }
}

下单接口

创建物流订单。

POST /orders

请求参数

参数名 类型 必填 说明
order_no string 是 客户订单号（需唯一）
service_type string 是 服务类型
sender object 是 发货人信息（name, phone, address）
receiver object 是 收货人信息（name, phone, address）
goods object 是 货物信息（name, weight, volume, quantity, value）
remark string 否 订单备注
响应示例 
{
  "code": 0,
  "message": "success",
  "data": {
    "order_no": "ORD202403180001",
    "tracking_no": "SY202403180001",
    "status": "created",
    "estimated_price": 166.66,
    "created_at": "2024-03-18T14:30:25+08:00"
  }
}

Webhook通知

当运单状态发生变化时，我们会向您配置的Webhook URL发送通知。

配置方式

登录盛越物流开放平台，在"开发者设置"中配置Webhook URL。

通知格式

通知示例 
{
  "event": "tracking.updated",
  "timestamp": "2024-03-18T14:30:25+08:00",
  "data": {
    "tracking_no": "SY202403180001",
    "status": "delivered",
    "status_text": "已签收",
    "event_time": "2024-03-18 14:30:25",
    "description": "已签收，签收人：李先生",
    "location": "上海市浦东新区"
  }
}

事件类型

事件类型 说明
tracking.created 运单创建
tracking.picked 已揽收
tracking.in_transit 运输中
tracking.out_for_delivery 派送中
tracking.delivered 已签收
tracking.exception 异常件

错误码说明

错误码 说明 解决方案
0 成功 -
1001 参数错误 检查请求参数是否符合要求
1002 认证失败 检查App-Key和签名是否正确
1003 运单不存在 检查运单号是否正确
1004 请求过于频繁 降低请求频率
1005 服务暂不可用 稍后重试

SDK下载

我们提供多种语言的SDK，简化您的接入流程。

Python SDK

pip install shengyue-logistics

下载

Java SDK

Maven/Gradle 依赖

下载

PHP SDK

Composer 安装

下载

Node.js SDK

npm install shengyue-logistics

下载