春风物流合作商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 的枚举。
SQLSTATE[HY000] [2002] Connection timed out
代码 注释 / 说明
注意:
(二)订单状态
代码 标题 注释 / 说明
1 提货
2 入站
3 录单
4 理货
5 干线配载
6 干线发车
7 到车
8 卸货
9 派送配载
10 转运
11 签收
(三)操作类型
请参见接口中 table=enum 中 kind=transport.status 的枚举。
SQLSTATE[HY000] [2002] Connection timed out
代码 标题 注释 / 说明
(三)异常件类型
请参见接口中 table=enum 中 kind=transport.unnormal 的枚举。
SQLSTATE[HY000] [2002] Connection timed out
代码 标题 注释 / 说明
七、附件参考
(一)货箱标签
说明: