春风物流合作商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": "310113",
        "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": "310113",
        "branch_showy": "310113",
        "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
代码 标题 注释 / 说明
七、附件参考
（一）货箱标签
说明：