春风物流合作商API技术接口规范
Version: 1.2.151203; Author: GAN
Mr.GAN
QQ: 3467088; Mail: gan@spring56.com
Tel: 021-31083456-8069; Mobile: 13816984330
日期↓ 版本号 作者 说明
2014-08-04 17:12 1.0.140804 GAN
  • 初版
2015-04-06 12:58 1.1.150406 GAN
  • 增加订单处理接口
2015-04-12 11:14 1.2.150412 GAN
  • 较大幅度调整订单及运单查询接口
2015-04-22 15:06 1.2.150420 GAN
  • 增加在未下单前通过地址及箱数获取运单号及箱号
  • 修正、优化其他部分接口
2015-07-13 14:41 1.2.150713 GAN
  • 修正、优化其他部分接口
2015-12-03 18:09 1.2.151203 GAN
  • 下单接口增加付款、运输方式等字段
前言
一、功能结构
二、数据交互说明
三、数据安全及调试
四、接口说明
(一)运输信息查询
1. 批量查询 (mail.batch)
重点说明:
数据字段定义
字段(运单号) 类型 必须 示例值 注释 / 说明
mailnos text 6000886859,6000887005 运单号,多个号运单号用半角的逗号“,”进行分隔
content格式
{
    "mailnos":"6000886859,6000887005"
}
服务器返回
{"result":true
  ,"remark":""
  ,"list":[
             {"time":"2017-04-05 20:22:15","mailno":"6000886859","state":"10","remark":"在【太原一部】做 转运 操作"}
            ,{"time":"2017-04-05 10:04:07","mailno":"6000887005","state":"9","remark":"在【西安一部】 派送配载 操作"}
           ]
}
查询错误或者未找到相关数据时返回
请参照“二、数据交互说明”中的错误代码
(二)订单管理
1. 订单下发、修改接口 (order.submit)
重点说明:
数据字段定义
字段 类型 是否必须 示例值 注释 / 说明
下单时 修改时
id string(32) 15041201234567 订单号,由合作商系统产生,具有系统唯一性。
type enum('simple') simple 订单类型,目前仅支持 simple=普通订单。
mailno string(32) 650400012345 托运单号,如下单时已有,请提供。
sendlist_id bigint(12) 650400012345 清单号,如下单时已有,请提供。
way enum('truck','air','sea') truck 默认truck,为汽运方式。如未提前约定,当前请勿选择其他方式。
deliver_type enum('deliver','selftake') deliver 递送方式,deliver=配送;selftake=自提。
quantity int(10) 7 订单中包含的总箱数,请注意并非指箱子里面的服装总件数。
quantity_large int(10) 1 订单中包含的大箱数。
quantity_small int(10) 3 订单中包含的小箱数。
pairs int(10) 3 双数,此列暂仅用于鞋类客户
weight decimal(10,3) 0.127 重量(千克)
bulk decimal(10,3) 0.006 体积(米³)
size_x decimal(10,2) 0.1 长(米)
size_y decimal(10,2) 0.2 宽(米)
size_z decimal(10,2) 0.3 高(米)
price decimal(10,2) 2736.12 货品声明价值
freight decimal(10,2) 108.00 运费
premium decimal(10,2) 56.00 保险费
pack_charges decimal(10,2) 5.00 包装费
other_charges decimal(10,2) 0.00 其他费用
sum decimal(10,2) 2905.12 (到付、代收)总金额
paymode enum('','sender_prompt',
'receiver_prompt','sender_batch',
'receiver_batch','other_batch')
sender_batch 支付方式,默认为空字符串。sender_prompt=现付;receiver_prompt=到付;sender_batch=发货方月结;receiver_batch=到货方月结;other_batch=其他月结。
payer string(32) 支付方。本列为支付方式选择other_batch=其他月结时才需录入。
goods string(255) 货品类别或简单描述
dangerous enum('N','Y') N 包含危险品
remark string(255) 请勿摔货 订单备注
sender -> code string(32) 130520142010 发件人在合作商系统中的ID号(可用于系统中的仓库编码等)
sender -> name string(32) 李琳 发件人姓名
sender -> company string(128) 新南电子商务有限公司 发件公司名
sender -> mobile string(11) 13912345678 发件人手机号码
sender -> phone string(128) 021-87654321 发件人电话号码
sender -> area int(6) 310118 发件人区域ID,如提供区域ID,请参考春风物流提供的国家行政区划代码。
sender -> city string(128) 上海市,上海市,宝山区 发件人所在城市,必须逐级指定,用英文半角逗号分隔,目前至少需要指定到地市级,如能往下精确更好,如“上海市,上海市,宝山区,月浦镇,春和路,187号”
sender -> address string(255) 月浦镇春和路187号 发件人路名门牌等地址信息
sender -> zipcode string(10) 310019 发件人邮政编码
sender -> email string(128) ll@abc.com 发件人电子邮件
sender -> im string(64) 1924656234 发件人即时通讯工具
sender -> starttime datetime 2015-04-11 12:00:00 取件起始时间
sender -> endtime datetime 2015-04-11 15:00:00 取件截至时间
receiver -> code string(32) 130520142097 收件人在合作商系统中的ID号(可用户系统中门店ID)
receiver -> name string(32) 杨逸嘉 收件人姓名
receiver -> company string(128) 逸嘉实业有限公司 收件公司名
receiver -> mobile string(11) 至少其
中之一
13687654321 收件人手机号码
receiver -> phone string(128) 010-22226789 收件人电话号码
receiver -> area int(6) 501022 收件人区域ID,如提供区域ID,请参考春风物流提供的国家行政区划代码。
receiver -> city string(128) 四川省,成都市,武侯区 收件人所在城市,逐级指定,用英文半角逗号分隔
receiver -> address string(255) 育德路497号 收件人路名门牌等地址信息
receiver -> zipcode string(10) 610012 收件人邮政编码
receiver -> email string(128) yyj@abc.com 收件人电子邮件
receiver -> im string(64) yangyijia-abc 收件人即时通讯工具
boxes[?] -> id string(32) 1234567 货箱ID,可以与箱条码相同
boxes[?] -> boxno string(32) 1234567 箱条码,必须按照规则生成,或者先传递订单基本信息,由春风生成箱条码
boxes[?] -> remark string(255) 请注意向上摆放 箱备注
boxes[?] -> items[?] -> id string(32) 1234567 货品ID,可以为货品SKU
boxes[?] -> items[?] -> name string(128) 迷你风扇 货品名称
boxes[?] -> items[?] -> category string(64) 电子产品 商品分类
boxes[?] -> items[?] -> material string(64) 金属 商品材质
boxes[?] -> items[?] -> size string(64) 12,11,23 大小(长,宽,高)(单位:厘米), 用半角的逗号来分隔长宽高
boxes[?] -> items[?] -> weight decimal(10,3) 0.752 重量(单位:千克)
boxes[?] -> items[?] -> unitprice decimal(10,2) 79 单价
boxes[?] -> items[?] -> price decimal(10,2) 1260.50 货箱中商品总价值
boxes[?] -> items[?] -> url string(256) http://www.abc.com/123.html 商品链接
boxes[?] -> items[?] -> quantity int(10) 1 本箱中货品的总数量(服装总件数或鞋类总双数)
boxes[?] -> items[?] -> remark string(255) 黑色大号 货品备注
content格式
{
     "id": "C123456789" //必须传递订单号
    ,"type": "simple" //目前只能为simple
    ,"mailno": "1000000016" //可以留空,数据传到春风后,春风自动分配运单号
    ,"sendlist_id": "650400012345" //与提货工人进行交接的清单号,如下单时已有,请提供。
    ,"way": "truck" //运输通道。默认truck,为汽运方式。如未提前约定,当前请勿选择其他方式。
    ,"deliver_type": "deliver" //递送方式,deliver=配送;selftake=自提。
    ,"quantity": "7" //订单中包含的总箱数,请注意并非指箱子里面的服装总件数
    ,"quantity_large": "1" //订单中包含的大箱数
    ,"quantity_small": "3" //订单中包含的小箱数
    ,"pairs": "20" //双数,此列暂仅用于鞋类客户
    ,"weight": "0.127" //重量(千克)
    ,"bulk": "0.006" //体积(米³)
    ,"size_x": "0.1" //长(米)
    ,"size_y": "0.2" //宽(米)
    ,"size_z": "0.3" //高(米)
    ,"price": "2736.12" //货品声明价值
    ,"freight": "108.00" //运费
    ,"premium": "56.00" //保险费
    ,"pack_charges": "5.00" //包装费
    ,"other_charges": "0.00" //其他费用
    ,"sum": "2905.12" //(到付、代收)总金额
    ,"paymode": "sender_batch" //支付方式
    ,"payer": "" //支付方。本列为支付方式选择other_batch=其他月结时才需录入。
    ,"goods": "服装" //货品类别或简单描述
    ,"dangerous": "N" //是否包含危险品
    ,"remark": "请勿摔货" //订单备注
    ,"sender": {
         "code": "130520142010" //可以为发货的仓库代码、尤其是有多个仓库的时候,必须传递此参数
        ,"name": "李琳"
        ,"company": "上海A公司"
        ,"mobile": "13912345678"
        ,"phone": "021-87654321"
        ,"area": "310118"
        ,"city": "上海市,上海市,宝山区"
        ,"address": "月浦镇春和路187号"
        ,"zipcode": "310019"
        ,"email": "ll@abc.com"
        ,"im": "1924656234"
        ,"starttime": "2014-05-20 12:00:00"
        ,"endtime": "2014-05-20 15:00:00"
    }
    ,"receiver": {
         "code": "130520142097" //可以为目的地的门店代码
        ,"name": "杨逸嘉"
        ,"company": "四川B公司"
        ,"mobile": "13687654321"
        ,"phone": "010-22226789"
        ,"area": "501022"
        ,"city": "四川省,成都市,武侯区" //尽可能的精确到省、市、区
        ,"address": "育德路497号"
        ,"zipcode": "610012"
        ,"email": "yyj@abc.com"
        ,"im": "yangyijia-abc"
    }
    ,"boxes":[
        { //第一箱
             "id":"3452000001" //第一箱的ID号,可以与箱条码相同
            ,"boxno": "1000000016001" //第一箱的箱条码
            ,"remark": "请注意向上摆放" //第一箱的备注
            ,"items": [
                { //第一箱中的第一种物品
                     "id": "1234567" //该物品的ID号
                    ,"name": "潮流女装"
                    ,"category": "服装"
                    ,"material": "棉质"
                    ,"size": "12,11,23"
                    ,"weight": "0.752"
                    ,"unitprice": "79"
                    ,"price": "1260.50"
                    ,"url": "http://www.abc.com/123.html"
                    ,"quantity": "16"
                    ,"remark": "黑色中号"
                }
                ,{ //第一箱中的第二种物品
                     "name": "A类服装"
                    ,"quantity": "50"
                    ,"remark": ""
                }
                //第一箱中的第...种物品
            ]
        }
        ,{ //第二箱
             "id":"3452000002"
            ,"boxno": "1000000016002"
            ,"items": [
                {
                     "name": "B类服装"
                    ,"quantity": "50"
                    ,"remark": ""
                }
                ,{
                     "name": "C类服装"
                    ,"quantity": "50"
                    ,"remark": ""
                }
            ]
        }
        //第...箱子
    ]
}
服务器返回
请参照“二、数据交互说明”中的错误格式
2. 订单取消 (order.cancel)
content中包含的字段定义
字段 类型 必须 示例值 注释 / 说明
id string(32) 15041201234567 订单ID
remark string(255) 信息错误,取消后重新下单 备注
content格式
{
     "id": "15041201234567"
    ,"remark": "信息错误,取消后重新下单"
}
服务器返回
请参照“二、数据交互说明”中的错误格式
3. 获取运单号及箱号列表 (order.mailno)
重点注意:
content中包含的字段定义
字段 类型 必须 示例值 注释 / 说明
id string(32) 15041201234567 订单ID
content格式
{
    "id": "15041201234567"
}
服务器返回
{
     "result": true
    ,"order": {
         "id": "15041201234567"
        ,"mailno": "650400012345" //运单号码
        ,"branch_code": "3100010" //目的地代码
        ,"branch_showy": "31-00-010" //目的地醒目的代码
        ,"branch_name": "天津二部" //目的地网点名称
        ,"quantity": "4" //总箱数
        ,"time": "2014-08-01 01:53:21"
        ,"boxnos":[
             "650400012345001" //箱条码
            ,"650400012345002"
            ,"650400012345003"
            ,"650400012345004"
        ]
    }
}
查询错误或者未找到相关数据时返回
请参照“二、数据交互说明”中的错误格式
4. 订单查询接口 (order.query)
重点说明:
数据字段定义
字段 类型 必须 示例值 注释 / 说明
id string(32) 必选其一
建议用订单号
15041201234567 订单号
mailno string(32) 650400012345 运单号码或者货箱条码。当同时也指定了订单号进行查询时,接口默认以订单号为首要查询条件
mode enum('simple','standard','full') simple 支持三种模式:simple=精简、standard=标准、full=完整,默认为标准模式
content格式
{
     "id":"15041201234567"
    ,"mode":"simple"
}
服务器返回,请选择返回模式
{
     "result": true
    ,"order": {
         "id": "15041201234567"
        ,"mailno": "650400012345"
        ,"status": "running"
        ,"type": "simple"
        ,"quantity": "4"
        ,"remark": "请勿摔货"
        ,"time": "2014-08-01 01:53:21"
    }
}
查询错误或者未找到相关数据时返回
请参照“二、数据交互说明”中的错误代码
(三)地址解析
1. 通过收货地址获取网点及城市名称 (address.parse)
数据字段定义
字段 类型 必须 示例值 注释 / 说明
city string(128) 上海市上海市宝山区 城市区域
address string(255) 月浦镇春和路187号 详细地址
content格式
{
     "city": "上海市上海市宝山区"
    ,"address": "月浦镇春和路187号"
}
服务器返回,请选择返回模式
{
    "result": true,
    "data": {
        "area_id": "310113",
        "area_names": "上海市,上海市,宝山区",
        "branch_code": "31-90-000",
        "branch_name": "上海转运中心"
    }
}
查询错误或者未找到相关数据时返回
请参照“二、数据交互说明”中的错误代码
2. 通过收货地址获取运单号及箱号列表 (address.mailno)
数据字段定义
字段 类型 必须 示例值 注释 / 说明
city string(128) 上海市上海市宝山区 城市区域
address string(255) 月浦镇春和路187号 详细地址
quantity int(10) 4 箱数,请注意并非鞋盒数量,指打包后的货品包(箱)数,每一个货包(箱)应粘贴一张物流货箱标签。
content格式
{
     "city": "上海市,上海市,宝山区"
    ,"address": "月浦镇春和路187号"
    ,"quantity": "4"
}
服务器返回
{
    "result": true,
    "order": {
        "mailno": "6000001427",
        "area_id": "310113",
        "area_names": "上海市,上海市,宝山区",
        "branch_code": "3190000",
        "branch_showy": "31-90-000",
        "branch_name": "上海转运中心",
        "quantity": "4",
        "time": "15:21:31",
        "boxnos": [
            "6000001427001",
            "6000001427002",
            "6000001427003",
            "6000001427004"
        ]
    }
}
查询错误或者未找到相关数据时返回
请参照“二、数据交互说明”中的错误代码
五、其他功能接口
1. 基础数据同步(global.sync)
重点说明:
数据字段定义
字段 类型 必须 示例值 注释 / 说明
table enym('enum','area','branch') enum 数据表,支持的分类有:enum=枚举;area=区域;branch=站点
last_time string(14) 20140727153209 最后一次获取时间
content格式
{
     "table":"enum"
    ,"last_time":"20140727153209"
}
服务器返回(以下格式仅为“enum=枚举”的数据,其他不同的表,返回内容不同,但格式一致)
{
     "result": true,
    ,"datetime": "2014-08-04 21:01:21"
    ,"rows": [
        {
            "kind": "system.error",
            "name": "s00",
            "title": "严重未知错误",
            "order": "0",
            "remark": ""
        },
        {
            "kind": "system.error",
            "name": "s01",
            "title": "服务器异常",
            "order": "0",
            "remark": ""
        },
        {
            "kind": "system.error",
            "name": "s02",
            "title": "非法的IP来源",
            "order": "0",
            "remark": ""
        }
        //...
    ]
}
查询错误或者未找到相关数据时返回
请参照“二、数据交互说明”中的错误代码
六、常规值定义
重点注意:
(一)错误代码定义
请参见接口中 table=enum 中 kind=system.error 的枚举。
代码 注释 / 说明
s00 严重未知错误
s01 服务器异常
s02 非法的IP来源
s03 无效的指令操作
s04 非法的数据签名
s05 缺少完整的参数
s06 非法的数据格式
s07 数据内容不符合要求
s30 图形验证码不正确
s31 短信验证码不正确
s50 没有指定有效的查询条件
s51 没有找到请求的数据
s52 未从数据源中获取到有效的数据内容
s53 无权操作指定的数据
s60 提交的数据与服务器中的数据一致,忽略更新
s70 数据保存失败
s90 重复操作
u01 用户未登录
u02 必须输入用户名和密码
u03 用户名或密码不正确
u04 账户已被停用
u05 账户信息需要完善
u06 用户名不能使用
e01 缺少业务所必须的数据内容
e02 业务所需要的数据内容不符合要求
注意:
(二)订单状态
代码 标题 注释 / 说明
1 提货
2 入站
3 录单
4 理货
5 干线配载
6 干线发车
7 到车
8 卸货
9 派送配载
10 转运
11 签收
(三)操作类型
请参见接口中 table=enum 中 kind=transport.status 的枚举。
代码 标题 注释 / 说明
input 录单 运单已录入系统
got 收件 已从客户那里成功揽收
in 到站(卸车) 货物进入站点
out 出站(装车) 货物从站点发出
store 入库 放入库位
freed 出库 出库
dispatch 派件 货物进行派送
signed 已签收 货物已被客户签收
bill_goback 单据返回
bill_signed 单据返回确认
unnormal 异常 货物异常
backed 退签 货品退回发件网点并已完成签收
goback 退回 货品退回发件客户
relay 转单/重发 由于某种原因,货品需要重新发送,或者需要转其他物流公司协助运送
(三)异常件类型
请参见接口中 table=enum 中 kind=transport.unnormal 的枚举。
代码 标题 注释 / 说明
A01 破损 货品破损
A02 遗失 货品遗失
A03 拒签 收货人拒绝签收
A04 无法联系 无法联系到收货人
A05 要求退回 发货人要求退回
A06 缺件 包装内货品缺少
A99 其他 当选择其他原因时,必须输入备注。
七、附件参考
(一)货箱标签
说明: