API在线文档

一、接口总述

1.1接口请求说明

为保证双方传输数据统一，接口统一采集JSON格式，UTF-8编码，且仅允许POST方式进行交互
注意:因部分语言存在精度丢失问题，接口中涉及金额部分，均以分为单位进行传输

1.2全局参数说明

参数名	参数类型	是否必填	参数说明
method	String	是	业务请求方法
appid	String	是	系统分配的APPID
timestamp	Long	是	当前请求的时间戳,单位:秒。当此时间与服务器时间相关十分钟以上，为保证安全，系统会拒绝此次请求
data	String	可选	业务级参数，详情参考各业务接口
sign	String	是	请求签名，详情见1.4

1.3全局响应参数说明

参数名	参数类型	是否必填	参数说明
success	bool	是	响应全局业务处理结果
message	String	否	当业务处理不成功时，此处返回不成功原因
timestamp	Long	是	业务处理响应的时间戳

1.4请求签名说明

为保证请求安全，所有接口必须签名。对不合格签名，系统会直接拒绝。
具体签名方法如下:
md5(method + appid + timestamp + data + appsecret),得到32位签名值，请求时签名不区分大小写

二、订单相关接口

2.1下单接口 描述:使用此接口进行订单推送 业务请求方法: Order.Info.Create

业务参数说明：

参数名	参数类型	是否必填	参数说明
trade_no	String	是	交易订单号。平台唯一订单号
total_amount	BigDecimal	是	总交易金额。订单交易金额，单位: 分。交易金额 + 运费 - 优惠金额 = 支付金额
post_fee	BigDecimal	是	运费。交易运费，无运费可填0，单位：分
discount_fee	BigDecimal	是	优惠金额。订单总计优惠金额，如有多个优惠条件，请合并成一个优惠金额,没有请填0
modification_date	Date	是	订单修改时间。格式:yyyy-MM-dd HH:mm:ss
creation_date	Date	是	订单创建时间。订单创建时间，如为空则为当前时间。格式:yyyy-MM-dd HH:mm:ss
custom	Integer	否	申报海关。跨境订单必填。 0:非跨境(默认) 1:直邮 2:宁波 3:杭州 4:上海 5:郑州 6:义乌 7:太仓，8:绍兴，9:宁波专仓
platform_custom_code	String	否	所属电商平台海关备案编码。多平台时必填
platform_custom_name	String	否	所属电商平台海关备案名称。多平台时必填
buyer_note	String	否	买家备注。
seller_note	String	否	卖家备注。
mobile	String	可选	用户手机号。系统支持通过手机号或通过open_id,union_id组合查找关联用户
open_id	String	可选	微信或支付宝的openId,如使用open_id时，必须同时传入union_id
union_id	String	可选	微信或支付宝的unionId
payment	CreateOrderPaymentInput	是	订单支付信息。
clearance	CreateOrderClearanceInput	否	订单清关信息。
receiver	CreateOrderReceiverInput	是	收件信息。订单收件人信息
items	CreateOrderItemInput[]	是	商品信息。有效的订单应该至少包含一个商品

CreateOrderPaymentInput 结构如下:

参数名	参数类型	是否必填	参数说明
pay_order_no	String	否	申报订单号。海关申报时的订单号
declare_order_no	String	否	申报单号。海关申报产生的申报单号
pay_time	Date	是	支付时间。订单支付时间。格式:yyyy-MM-dd HH:mm:ss
pay_amount	BigDecimal	是	支付金额。此金额应为支付机构实际产生的支付金额
pay_channel	Integer	是	支付渠道。用户支付使用的渠道。1:支付宝，2:微信，3:网银，4:零元支付，5:高汇通，6:易付宝，7:通联支付，8:财付通，9:重庆易极付，10:广州合利宝，11:多多支付，12:易联支付，13:易宝支付，14:首信易，15:钱袋宝(美团支付), 16:上海汇付，18:连连支付, 20:银盛支付, 21:商盟支付, 22:银联商务，0:其它

CreateOrderClearanceInput 结构如下:

参数名	参数类型	是否必填	参数说明
clearance_name	String	否	请关证件姓名。如为跨境订单，清关证件姓名必填
clearance_no	String	否	清关证件号码。如为跨境订单，清关证件号码必填

CreateOrderReceiverInput 结构如下:

参数名	参数类型	是否必填	参数说明
receiver_name	String	是	收件人姓名。
receiver_mobile	String	否	收件人手机号码。收件人电话和手机至少应该填一个
receiver_tel	String	否	收件人电话。收件人电话和手机至少应该填一个
zipcode	String	否	邮政编码。邮编如填写，则必须为6位数字
receiver_province	String	是	省。收件省份
receiver_city	String	是	市。收件城市
receiver_district	String	是	区。收件地区
receiver_address	String	是	详细地址。除省市区外详细地址

CreateOrderItemInput 结构如下:

参数名	参数类型	是否必填	参数说明
sub_order_no	String	否	商品级子订单号。
title	String	是	商品标题。
price	BigDecimal	否	销售价格。
amount	BigDecimal	否	单品实付小计金额
sku_code	String	是	商品SKU代码。
quantity	Integer	是	购买数量。单个SKU购买的件数

请求结构示例：

{
	"buyer_note": "",
	"clearance": {
		"clearance_name": "张三",
		"clearance_no": "330203198302024485"
	},
	"creation_date": "2020-02-16 17:22:33",
	"discount_fee": 0,
	"items": [{
		"price": 20,
		"quantity": 2,
		"sku_code": "S11223300",
		"title": "测试商品0"
	},
	{
		"price": 20,
		"quantity": 3,
		"sku_code": "S11223301",
		"title": "测试商品1"
	},
	{
		"price": 20,
		"quantity": 4,
		"sku_code": "S11223302",
		"title": "测试商品2"
	}],
	"modification_date": "2020-02-16 17:22:33",
	"payment": {
		"declare_order_no": "202033944485945560",
		"pay_amount": 100,
		"pay_channel": 1,	
		"pay_order_no": "P100102203304",
		"pay_time": "2020-02-16 17:32:33"
	},
	"post_fee": 0,
	"receiver": {
		"receiver_address": "无名路222号",
		"receiver_city": "上海市",
		"receiver_district": "普陀区",
		"receiver_mobile": "13822993384",
		"receiver_name": "张三",
		"receiver_province": "上海市",
		"zipcode": "000000"
	},
	"seller_note": "",
	"total_amount": 100,
	"trade_no": "100102203304"
}

响应结构示例：

{
	"success": false,	//响应success为true时,接口调用成功,否则参考message字段的错误
	"message": "OK",	// 请求有错误时，参考错误消息
	"data": null		//响应需要其它数据时，此处为响应数据
}

2.2更新订单关联用户 描述:使用此接口对历史订单进行用户关联 业务请求方法: Order.Member.Update

业务参数说明：

参数名	参数类型	是否必填	参数说明
trade_no	String	是	订单交易号
mobile	String	可选	用户手机号。系统支持通过手机号或通过open_id,union_id组合查找关联用户
open_id	String	可选	微信或支付宝的openId,如使用open_id时，必须同时传入union_id
union_id	String	可选	微信或支付宝的unionId

响应参数说明

参数名	参数类型	是否必填	参数说明

请求参数示例

	{
		"trade_no":"P100102203304"
	}

响应参数示例

	{
		"success":true,
		"message":"success"
	}

2.3获取发货单 描述:使用此接口获取订单发货单信息 业务请求方法: Order.Logistic.Info

业务参数说明：

参数名	参数类型	是否必填	参数说明
trades	String[]	是	唯一交易号,可多个交易一并查询，最多支持查询20个

响应参数说明

参数名	参数类型	是否必填	参数说明
order_no	String	否	订单号。唯一交易编号
logistic_company	String	否	快递公司代码。见附表快递公司代码
logistic_code	String	否	快递单号。
message	String	否	错误信息。发生错误时，此为错误描述
split_count	int32	是	拆单件数，如值大于1，则应该确认该订单所有包裹全部发出，才可标记订单已发货
success	boolean	否	操作是否成功。

请求参数示例

{
	"trades":["P100102203304", "P100102203305"]
}

响应参数示例

{
	"success":true,
	data:[
			{
				"success":true,
				"trade_no":"P100102203304",
				"logistic_company":"ZTO",
				"logistic_no":"92348572345",
				"split_count":1
			},
			{
				"success":false,
				"trade_no":"P100102203305",
				"message":"订单不存在"
			}
		]
}

2.4订单退款 描述:使用此接口拦截订单发货 业务请求方法: Order.Refund.Create

业务参数说明：

参数名	参数类型	是否必填	参数说明
order_no	String	是	平台唯一交易号
reason	String	否	退单原因
refund_all	boolean	是	是否整单退
refund_type	Integer	是	退款类型：0-仅退款（默认）,2-退款退货当订单未发货时，仅支持退款，订单已发货或退款拦截不成功时，仅支持退货退款
express_company	String	否	退货物流公司，退货退款时必填。代码见附录
express_code	String	否	退货快递单号，退货退款时必填
details	OrderRefundDetailInput[]	否	非整单退时，需要提供退单明细

OrderRefundDetailInput 结构如下:

参数名	参数类型	是否必填	参数说明
sku_code	String	是	退单商品规格代码
num	int	是	退单件数，至少应该包含1件，不可超过订单最大值

响应参数说明

参数名	参数类型	是否必填	参数说明
code	int	是	业务响应码为200时，订单可直接退款，其它值由人工确认退款
refund_order_no	String	否	退款单号，可用于后续查询

请求参数示例

{
	"order_no":"1031915534528720",
	"refund_all":true
}

响应参数示例

{
	"data":{
		"code":200,
		"refund_order_no":"20210319163494526"
	},
	"message":"success",
	"success":true,
	"timestamp":1616142862
}

2.5订单退款查询 描述:通过退款单号查询订单退款状态 业务请求方法: Order.Refund.Query

业务参数说明：

参数名	参数类型	是否必填	参数说明
refund_order_no	String	是	退款单号

响应参数说明

参数名	参数类型	是否必填	参数说明
refund_order_no	String	是	退款单号
refund_state	Integer	是	退款/退货状态:1-请求接收成功（未处理）,6-退款/退货处理中,9-退款/退货处理成功,10-退款/退货处理失败

请求参数示例

{
	"refund_order_no":"1031915534528720",
}

响应参数示例

{
	"data":
	{
		"refund_order_no":"1031915534528720",
		"refund_state":1
	},
	"message":"success",
	"success":true,
	"timestamp":1685885242
}

2.6推送原始支付数据 描述:跨境推送原始支付数据，以供海关查验，多次推送会根据订单号覆盖，仅以最后一次推送为准
此项仅供内部做为平台方时使用，外部商家请自行对接海关179号公告，无需对接此接口
业务请求方法: Order.Payment.Initial

业务参数说明：

参数名	参数类型	是否必填	参数说明
order_no	String	是	平台订单号，此单号为后续覆盖唯一索引
pay_order_no	String	是	支付申报时使用的订单号
pay_channel	String	是	支付方式，见订单推送中支付方式
initial_request	String	是	向支付平台发起支付时报文数据原文
initial_response	String	是	支付平台支付成功时响应数据原文
verify_dept	String	是	核验机构。1:银联，2:网联, 0:其它
verify_transaction	String	是	核验机构清算流水号
items	InitialPaymentGoods[]	是	订单中包含的原始商品数据

InitialPaymentGoods 结构如下:

参数名	参数类型	是否必填	参数说明
item_title	String	是	订单原始标题
item_link	String	是	订单原始链接
sku_code	String	是	商品原始SKU编码
num	int	是	订单下单件数

请求参数示例

{
	
	"order_no":"test129837523", 
	"pay_order_no":"payewertwr0923", 
	"verify_dept":1, 
	"verify_transaction":"4294830495234963059635", 
	"initial_request":"init payment",
	"initial_response":"initial_response",
	"items":[
		{
			"item_link":"https://www.baidu.com",
			"item_title":"测试商品",
			"sku_code":"SKU123",
			"num":1
		}
	]
}

响应参数示例

{
	"success":true,
	"data":null,
	"message":"SUCCESS"
}

2.7会员信息变更 描述:使用此接口进行会员信息新增/变更 业务请求方法: Member.Info.Save

业务参数说明：

参数名	参数类型	是否必填	参数说明
mobile	String	可选	用户手机号，手机号有值时以手机号查询用户，手机号不存在时以open_id,union_id查询用户
open_id	String	可选	支付宝/微信用户openId
union_id	String	可选	支付宝/微信用户unionId
nickname	String	否	用户昵称
head_image	String	否	用户头像
birthday	Date	否	用户生日
sex	Integer	否	用户性别，1：男,0:女
email	String	否	用户电子邮箱
province	String	否	用户所在省份
city	String	否	用户所在城市
district	String	否	用户所在区
address	String	否	用户详细地址
enable_date	Date	否	用户入会日期

响应参数说明

参数名	参数类型	是否必填	参数说明
该接口不返回除公共参数以外的其它参数

请求参数示例

	{
		"birthday":"1981-03-05",
		"head_image":"https://www.baidu.com/head/image/s02/300/700",
		"address":"详细地址",
		"province":"上海",
		"enable_date":"2021-01-03",
		"open_id":"sU9s098a09d_mT2",
		"city":"上海市",
		"sex":1,
		"district":"普陀区",
		"mobile":"13800138000",
		"nickname":"CcXrF",
		"union_id":"u8sfa9090_o0i90ksx9o"
	}

响应参数示例

	{
		"message":"success",
		"success":true,
		"timestamp":1616142862
	}

2.8会员积分变更 描述:会员积分的增加，扣减可通过此接口进行同步操作 业务请求方法: Member.Score.Change

业务参数说明：

参数名	参数类型	是否必填	参数说明
mobile	String	可选	用户手机号，手机号有值时以手机号查询用户，手机号不存在时以open_id,union_id查询用户
open_id	String	可选	支付宝/微信用户openId
union_id	String	可选	支付宝/微信用户unionId
unique_id	String	是	变更记录唯一ID，预扣积分生效或取消时，此字段传入预扣记录的唯一ID号
score	Integer	是	变更的积分分值，正整数
remark	String	否	变更事由
type	Integer	是	变更类型。0:积分增加,1:积分扣减,2：积分预扣,3:预扣积分生效, 4:预扣积分取消
create_date	Date	是	积分变更产生时间
expire_date	Date	否	如果变更类型为预扣时，此它段表示预扣过期时间。如在过期前未主动调用预扣生效或预扣取消接口，则系统自动取消预扣。此字段如不传值，默认为24小时。

响应参数说明

参数名	参数类型	是否必填	参数说明
该接口不返回除公共参数以外的其它参数

请求参数示例

		{
			"score":30,
			"unique_id":"fa0dsf2gua0sdfa0sdf",
			"expire_date":"2024-01-01",
			"mobile":"13800138000",
			"remark":"购物获取",
			"type":0,
			"create_date":"2023-01-01"
		}

响应参数示例

		{
			"message":"success",
			"success":true,
			"timestamp":1616142862
		}

2.9会员积分等级查询 描述: 查询会员等级和积分，实时接口 业务请求方法: Member.Score.Level

业务参数说明：

参数名	参数类型	是否必填	参数说明
mobile	String	可选	用户手机号，手机号有值时以手机号查询用户，手机号不存在时以open_id,union_id查询用户
open_id	String	可选	支付宝/微信用户openId
union_id	String	可选	支付宝/微信用户unionId

响应参数说明

参数名	参数类型	是否必填	参数说明
grade	Integer	是	等级代码
gradeName	String	是	等级名称
score	Integer	是	会员实时积分值

请求参数示例

{
	"open_id":"OPENID",
	"union_id":"UNION_ID",
	"mobile":"13800138000",
}

响应参数示例

{
	"data":{
		"grade":1,
		"gradeName":"VIP1",
		"score":30
	},
	"message":"success",
	"success":true,
	"timestamp":1682315048
}

2.10会员积分变更记录 描述:会员积分变更日志查询，实时接口 业务请求方法: Member.Score.Log

业务参数说明：

参数名	参数类型	是否必填	参数说明
mobile	String	可选	用户手机号，手机号有值时以手机号查询用户，手机号不存在时以open_id,union_id查询用户
open_id	String	可选	支付宝/微信用户openId
union_id	String	可选	支付宝/微信用户unionId
type	Integer	是	查询变更类型 0:查询所有,1:赠送,3:扣减,5:赠送和扣减,7:互动日志
date_from	Date	否	查询开始时间
date_end	Date	否	查询结束时间(有起止时间跨度不超过三个月)
pageNo	Integer	是	查询页码
pageSize	Integer	是	每页记录数量，默认10
expire_date	Date	否	如果变更类型为预扣时，此它段表示预扣过期时间。如在过期前未主动调用预扣生效或预扣取消接口，则系统自动取消预扣。此字段如不传值，默认为24小时。

响应参数说明

参数名	参数类型	是否必填	参数说明
page_no	Integer	是	查询页码
page_size	Integer	是	每页记录数量，默认10
total	Integer	是	总记录数
data	MemberScoreLog[]	是	积分日志详情

MemberScoreLog 结构如下:

参数名	参数类型	是否必填	参数说明
expiredTime	Date	是	积分过期时间
createTime	BigDecimal	否	积分变更时间
point	Integer	是	积分变更分值
remark	String	是	变更详情
type	Integer	是	积分变更类型。1:赠送,3:扣减,5:赠送和扣减,7:互动日志

请求参数示例

{
	"mobile":"13800138000",
	"open_id":"OPEN_ID",
	"union_id":"UNION_ID", 
	"date_from":"2023-02-01 00:00:00",
	"date_end":"2023-04-24 15:00:00",
	"pageNo":1,
	"pageSize":10
}

响应参数示例

{
	"data":{
		"data":[
			{
				"createTime":"2023-04-24 11:59:03",
				"expiredTime":"2024-04-23 11:59:04",
				"point":30,
				"remark":"购物获取",
				"type":1
			}
		],
	"page_no":1,
	"page_size":10,
	"total":1
	},
	"message":"success",
	"success":true,
	"timestamp":1682316162
}

三、消息推送

提示:消息推送使用application/x-www-form-urlencoded 表单请求，报文体使用JSON字符串。注意不要使用application/json进行接收。
curl示例:

curl --location 'https://www.baidu.com' \

--header 'Content-Type: application/x-www-form-urlencoded' \

--data '{"appid":"your_app_id","data":"{

\"logistic_code\":\"1234567\",\"logistic_company\":\"ZTO\",\"order_no\":\"PLATFORM_ORDER_NO\"

}","method":"Push.Order.Logistic","sign":"764b349a21c155f15d3f6cd6df92e369","timestamp":1713952621}'

3.1物流推送 描述:将物流信息推送给下游服务商 业务请求方法: Push.Order.Logistic

系统在订单发货完成后，会调用下游服务商提供的接收地址，进行物流信息推送。
保证系统统一，推送消息时，仍将采用UTF-8编码，POST方式进行推送，同时也保持原有的接口公共参数(见1.2)。
下游服务商接收到消息后，就对消息进行处理，并返回全局响应参数结果(见1.3).

推送业务参数说明:

参数名	参数类型	是否必填	参数说明
order_no	String	否	订单号。唯一交易编号
logistic_company	String	否	快递公司代码。见附表快递公司代码
logistic_code	String	否	快递单号。

请求参数示例:

{
	"method":"Push.Order.Logistic",
	"appid": "test",
	"timestamp":"1581341552",
	"sign":"6ce5de15e70b384edd6b7821acc613d7",
	"data":"{\"order_no\":\"P100102203304\",\"logistic_company\":\"ZTO\",\"logistic_code\":\"12345678\"}"
}

响应参数示例:

{
	"success":false,
	"message":"系统错误"
}

附录

1 物流公司代码

系统默认按以下快递回传，如有特殊回传要求，联系技术人员配置

快递代码	快递公司	说明
STO	申通快递
ZTO	中通快递
YTO	圆通快递
SF	顺丰快递
POSTB	邮政快递包裹
EMS	EMS

* 本接口文档最后更新时间：2020-02-20