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":"系统错误"
}

3.2清关状态推送 描述:跨境订单在清关状态发生变更时，向下游供应商推送状态 业务请求方法: Order.Cleareance.Result

跨境订单在清关状态发生变更时，向下游供应商推送状态。

推送业务参数说明:

参数名	参数类型	是否必填	参数说明
trade_no	String	否	订单号。唯一交易编号
status	Integer	是	清关状态，业务取值见附录
desc	String	否	清关错误描述
action_time	Date	否	状态更新时间,格式:yyyy-MM-dd HH:mm:ss

请求参数示例:

{
  "data" : "{\"action_time\":\"2025-11-04 16:56:55\",\"desc\":\"订单已取消\",\"status\":999,\"trade_no\":\"1985537277760471040\"}",
  "method" : "Order.Cleareance.Result",
  "sign" : "189cd828f87ca6d35af6fa43c6b2f7a7",
  "timestamp" : 1762500810,
  "appid" : "test"
}

响应参数示例:

{
	"success":true,
	"message":"操作成功"
}

附录

1 物流公司代码

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

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

2 清关状态代码

系统默认按以下状态回传
注意:回传顺序可能会不一样，不影响订单状态展示，仅供参考，不在此表中的状态可忽略不处理

状态代码	状态名称	说明
220	未申报	订单完成推送动作，暂未发起海关申报
221	库存不足	订单中商品锁定库存失败
222	通知仓库配货	海关单证放行后，订单下发仓库，准备发货
223	仓库已配货	仓库完成配货，准备出库
241	订单已推送	订单已推送海关进行申报
242	海关单证放行	海关单证放行
243	海关单证审核未过	订单审核出现异常，需要人工介入
275	购买人证件与支付单不一致	订单中购买人身份证件与支付单中提交的身份证不一致
276	用户超过年度购买额	用户身份证超过海关规定的每年2.6万跨境额度
300	海关货物放行	海关货物放行，订单出库
690	海关发起真实性核验	海关发起真实性核验，联系消费者在15个工作日内通过掌上海关进行验证
890	发送海关失败	发送海关失败
900	订单已撤回	订单取消时从海关撤回订单
903	海关退单	三单对碰不通过，海关发送退单指令
951	订单身份证姓名错误	订单中传入身份证姓名错误
952	身份证核验失败	订单中传入身份证号码基础格式核验失败
955	订单金额超过限制金额	订单金额超过海关规定上限
999	订单已取消	订单取消成功

* 本接口文档最后更新时间：2025-11-07