YubaoApi 接口文档

公共基础信息

请求协议：POST，支持 form‑data / application/json(raw)
返回code：1=成功；0=业务逻辑错误；-1=token鉴权失败
token：鉴权密钥，读取ls_api_user表，status=1密钥才生效
uid：业务用户ID，外部post传入

统一返回格式

{
  "code": 1,
  "msg": "提示信息",
  "data": {} | [] | null
}

公共返回字段说明

字段名	类型	说明
code	int	状态码：1成功，0业务错误，‑1鉴权失败
msg	string	返回提示文字
data	object\|array\|null	业务返回数据，失败时一般为null

接口1：快递包裹查询 queryPackage

接口地址：POST /Yubao/queryPackage

功能：根据快递单号查询包裹信息

请求参数

参数名	类型	必填	说明
token	string	是	api鉴权密钥
kdsn	string	是	快递包裹单号

返回参数(data对象)

字段名	类型	说明
id	int	包裹ID
weight	float	包裹重量
kdimage	string	包裹图片地址
bgname	string	包裹名称
status	int	包裹状态：1在途中，2已入库，4已出库
addtime	string	录入时间，格式化时间字符串
status_text	string	状态中文描述

请求示例 JSON

{
    "token":"abc123",
    "kdsn":"KD888888"
}

成功返回示例

{
    "code":1,
    "msg":"查询成功",
    "data":{
        "id":1001,
        "weight":2.3,
        "kdimage":"upload/xxx.jpg",
        "bgname":"样品包裹",
        "status":2,
        "addtime":"2026‑08‑11 15:30:00",
        "status_text":"已入库"
    }
}

status映射：1=在途中，2=已入库，4=已出库，其他=未知状态

错误示例

{"code":0,"msg":"未查询到该快递包裹","data":null}
{"code":-1,"msg":"token无效或账号已禁用","data":null}

接口2：添加收货地址 addressAdd

接口地址：POST /Yubao/addressAdd

功能：新增用户收货地址；设置def=1时自动把该用户其他地址置为非默认；内部areaid映射areaname

areaid编码映射
1=中国，10=东马‑马来西亚，12=西马‑马来西亚，13=新加坡，22=泰国，23=越南，24=澳洲，25=韩国，26=印尼，27=文莱，28=菲律宾，30=日本，31=美国，35=英国

请求参数

参数名	类型	必填	说明
token	string	是	api鉴权密钥
uid	int	是	业务用户ID，外部传入
uname	string	否	用户名称
consignee	string	是	收货人
tel	string	是	联系电话
areaid	int	是	国家地区编码
address	string	是	详细收货地址
zipcode	string	否	邮编
def	int	是	是否默认地址：0否 /1是

返回参数(data对象)

字段名	类型	说明
address_id	int	新增的地址ID
consignee	string	收货人姓名
areaname	string	地区中文名称

请求示例 JSON

{
    "token":"abc123",
    "uid":23079,
    "uname":"user01",
    "consignee":"李明",
    "tel":"6512345678",
    "areaid":13,
    "address":"XX街道XX大厦101",
    "zipcode":"123456",
    "def":1
}

成功返回示例

{
    "code":1,
    "msg":"地址添加成功",
    "data":{
        "address_id":63707,
        "consignee":"李明",
        "areaname":"新加坡"
    }
}

错误示例

{"code":0,"msg":"收货人不能为空","data":null}
{"code":0,"msg":"areaid国家编码不存在","data":null}

接口3：获取用户收货地址列表 getAddressList

接口地址：POST /Yubao/getAddressList

功能：获取用户全部收货地址；排序规则：默认地址优先(def desc)，再id倒序

请求参数

参数名	类型	必填	说明
token	string	是	api鉴权密钥
uid	int	是	业务用户ID

返回参数(data数组项)

字段名	类型	说明
id	int	地址ID
uid	int	业务用户ID
uname	string	用户名
consignee	string	收货人
tel	string	联系电话
areaid	int	地区编码
areaname	string	地区名称
address	string	详细地址
zipcode	string	邮编
def	int	是否默认：0否，1是
addtime	int	创建时间戳
edittime	int	编辑时间戳

请求示例 JSON

{
    "token":"abc123",
    "uid":23079
}

成功返回示例

{
    "code":1,
    "msg":"查询成功",
    "data":[
        {
            "id":63707,
            "uid":23079,
            "uname":"user01",
            "consignee":"李明",
            "tel":"6512345678",
            "areaid":13,
            "areaname":"新加坡",
            "address":"XX街道XX大厦101",
            "zipcode":"123456",
            "def":1,
            "addtime":1754201111,
            "edittime":1754201111
        }
    ]
}

无地址返回 data:[]

接口4：根据areaid获取运送方式 getDeliveryByAreaid

接口地址：POST /Yubao/getDeliveryByAreaid

功能：根据地区编码查询可用物流渠道（status=1有效），仅返回id、dname

请求参数

参数名	类型	必填	说明
token	string	是	api鉴权密钥
areaid	int	是	国家地区编码

返回参数(data数组项)

字段名	类型	说明
id	int	物流渠道ID(deliveryid)
dname	string	物流渠道名称

请求示例 JSON

{
    "token":"abc123",
    "areaid":13
}

成功返回示例

{
    "code":1,
    "msg":"查询成功",
    "data":[
        {"id":97,"dname":"新加坡专线A"},
        {"id":98,"dname":"新加坡专线B"}
    ]
}

无物流返回 data:[]

接口5：API提交预报订单 yubaoAdd

接口地址：POST /Yubao/yubaoAdd

功能：提交预报订单；生成运单sn

请求参数

参数名	类型	必填	说明
token	string	是	api鉴权密钥
uid	int	是	业务用户ID
addressid	int	是	收货地址ID【根据接口/Yubao/getAddressList获取，如果不存在，则用/Yubao/addressAdd进行添加】
deliveryid	int	是	运送方式ID【根据选中地址里的areaid然后调用接口获取】
yubaoid	string	是	选中包裹ID,多个以逗号分隔，例1001,1002
goods_name	string	是	物品名称
all_price	float	是	物品总价值，必须>0
goods_type	string	是	物品类型：普通货物敏感货物
baojia	int	是	是否保价：0=否，1=是
insured_amount	float	否	保价金额；baojia=1必填，>0
remark	string	否	订单备注

返回参数(data对象)

字段名	类型	说明
order_id	int	生成的运单ID(ydid)
sn	string	运单编号

请求示例 JSON

{
    "token":"abc123",
    "uid":23079,
    "addressid":63707,
    "deliveryid":97,
    "yubaoid":"1001,1002",
    "goods_name":"服饰配件",
    "all_price":280,
    "goods_type":"普通货物",
    "baojia":1,
    "insured_amount":500,
    "remark":"易碎轻放"
}

成功返回示例

{
    "code":1,
    "msg":"订单添加成功",
    "data":{
        "order_id":2001,
        "sn":"DD20260811002001"
    }
}

错误示例

{"code":0,"msg":"无效的保价金额!","data":null}
{"code":0,"msg":"收货地址不存在，越权操作","data":null}
{"code":0,"msg":"没有选择包裹，无法提交订单","data":null}
{"code":0,"msg":"用户不存在","data":null}

公共错误码汇总

code	说明
1	请求成功
0	业务参数错误、业务逻辑失败
-1	token无效 / api账号禁用