必威体育手机版合作商API技术接口规范
Version: 1.2.152504; Author: GAN
Mr.GAN
QQ: 3467088; Mail: gan@hsw360.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
  • 下单接口增加付款、运输方式等字段
2020-08-04 14:35 1.2.152503 GAN
  • 预先获取春风运单号
2020-08-19 09:35 1.2.152504 GAN
  • 获取运单签收图片
前言
一、功能结构
二、数据交互说明
content格式
{
     "mailno":"650400012345"
    ,"mode":"simple"
}
服务器返回
{
     "result": true
    ,"remark": ""
    ,"mailno": "650400012345"
    ,"status": "running"
    ,"last_time":"2014-07-29 23:22:09"
    ,"signer": ""
    ,"traces":{
         "time":"2014-07-29 23:22:09"
        ,"remark":"在 上海转运中心 进行出站扫描,并发往 天津转运中心"
    }
}
查询错误或者未找到相关数据时返回
请参照“二、数据交互说明”中的错误代码
-->
1. 批量查询 (mail.batch)
数据字段定义
字段(运单号) 类型 必须 示例值 注释 / 说明
mailnos text 6000886859,6000887005 运单号,多个号运单号用半角的逗号“,”进行分隔
content格式
{
    "mailnos":"50000000069,50000000070"
}
服务器返回
{
	"result":true,
	"error_code":"",
	"keys":"",
	"remark":"",
	"info":{
		"list":[
			[{"time":"2017-06-13 10:53:00","mailno":"50000000069","state":"11","remark":"在【徐州一部】做 签收 操作,签收人为:历"}],
			[{"time":"2017-06-11 12:53:47","mailno":"50000000070","state":"11","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) 13052 发件人在合作商系统中的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号(可用于系统中的仓库编码等)
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": ""
                }
            ]
        }
        //第...箱子
    ]
}  
服务器返回
{
	"result":true,
	"error_code":"",
	"keys":"",
	"remark":"下单成功",
	"info": {
			"mailno": "650400012345",
			"quantity": "1"
		}
	}
请参照“二、数据交互说明”中的错误代码
2. 订单取消 (order.cancel)
content中包含的字段定义
字段 类型 必须 示例值 注释 / 说明
id string(32) 15041201234567 订单ID
remark string(255) 信息错误,取消后重新下单 备注
content格式
{
     "id": "15041201234567"
    ,"remark": "信息错误,取消后重新下单"
}
服务器返回
请参照“二、数据交互说明”中的错误格式
3. 获取运单号及箱号列表 (order.mailno)
重点注意:
content中包含的字段定义
字段 类型 必须 示例值 注释 / 说明
id string(32) HB1912000777 订单ID
content格式
{
    "id":"HB1912000777"
}
服务器返回
{
	"result":"true",
	"error_code":"",
	"keys":"",
	"remark":"",
	"info":{
		"order":{
			"id":"HB1912000777",
			"mailno":"50000000069",//运单号码
			"branch_code": "330183", //目的地代码
			"branch_name": "杭州子公司", //目的地网点名称
			"quantity":"2", //箱数
			"time":"2020-01-17 15:44:24",//下单时间
			"boxnos":[ //箱号
			"HX1912007056",
			"HX1912007063"
			]
		}
	}
}
查询错误或者未找到相关数据时返回
请参照“二、数据交互说明”中的错误格式
4. 订单查询接口 (order.query)
重点说明:
数据字段定义
字段 类型 必须 示例值 注释 / 说明
id string(32) HB1912000777 订单号
content格式
{
     "id":"HB1912000777"
}
服务器返回
{
	"result":"",
	"error_code":"",
	"keys":"",
	"remark":"",
	"info":{
		"order":{
			"id":"HB1912000777",
			"mailno":"50000000069",
			"status":"input",
			"quantity":"2",
			"remark":"",
			"time":"2020-01-17 15:44:24"
		}
	}
}
查询错误或者未找到相关数据时返回
请参照“二、数据交互说明”中的错误代码
5. 预先获取春风运单号 (order.getMailno)
数据字段定义
字段 类型 必须 示例值 注释 / 说明
getmailno boolean true 该字段不为空即可
content格式
{
     "getmailno": "true"
}
服务器返回
{
	"result":"true",
	"error_code":"",
	"keys":"",
	"remark":"操作成功",
	"info":{
		"mailno":"6002852399"
	}
}
查询错误或者未找到相关数据时返回
请参照“二、数据交互说明”中的错误代码
6. 运单签收图片 (order.image)
数据字段定义
字段 类型 必须 示例值 注释 / 说明
mailno string 1890232529 订单下发时返回的运单号
content格式
{
     "mailno": "1890232529"
}
服务器返回 二进制图片
{
	"result":"true",
	"error_code":"",
	"keys":"",
	"remark":"",
	"info":{
		"mailno":"1890232529",
		"image":""  //图片二进制流 
	}
}
查询错误或者未找到相关数据时返回
请参照“二、数据交互说明”中的错误代码
(三)地址解析
1. 通过收货地址获取网点及城市名称 (address.parse)
数据字段定义
字段 类型 必须 示例值 注释 / 说明
city string(128) 上海市上海市宝山区 城市区域
address string(255) 月浦镇春和路187号 详细地址
content格式
{
     "city": "上海市上海市宝山区"
    ,"address": "月浦镇春和路187号"
}
服务器返回
{
	"result":true,
	"error_code":"",
	"keys":"",
	"remark":"",
	"info":{
		"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,
	"error_code":"",
	"keys":"",
	"remark":"",
	"info":{
		"order":{
			"mailno":"6002852511",
			"area_id":310113,
			"area_names":"上海市,上海市,宝山区",
			"branch_code":"310113",
			"branch_showy":"310113",
			"branch_name":"上海",
			"quantity":"4",
			"time":"13:56:45",
			"boxnos":[
				"6002852511001",
				"6002852511002",
				"6002852511003",
				"6002852511004"
			]
		}
	}
}
查询错误或者未找到相关数据时返回
请参照“二、数据交互说明”中的错误代码
wu、常规值定义
重点注意:
(一)错误代码定义
代码 注释 / 说明
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 签收
(三)操作类型
代码 标题 注释 / 说明
input录单运单已录入系统
got收件已从客户那里成功揽收
in到站(卸车)货物进入站点
out出站(装车)货物从站点发出
store入库放入库位
freed出库出库
dispatch派件货物进行派送
signed已签收货物已被客户签收
bill_goback单据返回
bill_signed单据返回确认
unnormal异常货物异常
backed退签货品退回发件网点并已完成签收
goback退回货品退回发件客户
relay转单/重发由于某种原因,货品需要重新发送,或者需要转其他物流公司协助运送
(三)异常件类型
代码 标题 注释 / 说明
A01破损货品破损
A02遗失货品遗失
A03拒签收货人拒绝签收
A04无法联系无法联系到收货人
A05要求退回发货人要求退回
A06缺件包装内货品缺少
A99其他当选择其他原因时,必须输入备注。
七、附件参考
(一)货箱标签
说明:
  • 标签尺寸为:100mm * 70mm
  • 为防止部门热敏打印头坏死以后打印出来的条码不能识别,特将标签及条码设计成以上图案,且旋转了90度,这不影响客户端的正确打印和识别。
  • 在粘贴时,应旋转90度,保证标签的正确方向,方便操作工人识别。
必威体育手机版