使用说明

项目说明【对接前，请务必认真阅读此文档】

此项目为我司对外API接口项目，主要职责为API接口用户提供省市区地址、商品分类、品牌、商品基础信息、订单、售后等订单相关的所有服务。

业务流程

1、首先与我司商务对接，走完商务对接流程后，可登录我司后台，完成对应的认证，充值储备金，在API接口用户确认支付时，我司会自动扣除对应的储备金，并且系统会自动进行订单审核、商品拣货、配货、发货等操作，对应的物流单号信息会自动通知API接口用户；
2、商品类型分为：礼品商品、通货商品两种类型；礼品商品业务系统只能以兑换的形式出售，通货商品无限制，可以兑换或人民币方式进行销售；
3、订单支付时，会扣除对应金额的储备金，所以请务必保证有充足的储备金余额；
4、订单售后，我司有处理售后的客服团队，需要售后的商品单号告知我司客服，会根据实际情况执行售后，售后完结后，对应的金额会自动退还到储备金余额；

接口对接说明

线下方式获取appKey、appSecret
测试服与正式服环境，除了域名、appKey、appSecret外，其余均一致，用户开发时，对接完测试服后，正式上线时，只需更换一下域名、appKey、appSecret 即可正常切换环境

接口规范

1. 报文格式及编码

接收及响应格式：JSON，字符编码：UTF-8
ContentType：application/json; charset=utf-8

2. 交互协议及请求方式

使用更安全的 HTTPS 协议，接口全部使用 POST方式请求

3. 公共参数

公共请求参数，通过 header 传输，值、类型及对应释义：

参数名	类型	参数值	描述
appKey	string	91856bd5-8622-4b18-aebb-79ce5e010f88	线下方式申请获取，标识用户唯一身份
timestamp	string	1688194275	请求时间戳（秒级），超出 30s 服务端将拒绝响应
nonce	string	2888788876	请求随机数
token	string	3DE3F432C376423D6CD69A8FB7BF0DC8	用户访问token，通过接口获取
signature	string	5DE3F432C376423D6CD69A8FB7BFBB00	根据签名规则生成的签名,防止数据被篡改，生成规则参考4

公共响应参数

参数名	类型	参数值	描述
status	int	200	非200 为请求失败
msg	string	操作成功	提示信息
requestId	int	21062921043033790720	返回请求唯一id，异常数据排查时，需提供此id
content	array/object		响应详细内容

4. 签名生成规则

签名生成规则: 按照下面的顺序拼接参数名和值，拼接为一个字符串，然后执行 md5，将md5后生成的字符串全部转为大写，则为此次请求的 signature
$param = appKey值timestamp值token值nonce值appSecret值
$signature = strtoupper(md5($param));

5. IP白名单

API接口用户需提供调用接口使用的服务器IP，只有用户白名单内的IP，才可以正常访问接口服务

6. 访问频次

为保证系统安全、稳定的提供服务，接口调用频次不到超过：300次/分钟，超过该频次会直接返回请求频繁

7. 回调地址

系统商品信息、订单状态变更时，会以回调的方式通知到API接口客户，所以，请自行开发好对应的变更接受地址，由于队列延时、网络等各种因素影响，建议用户收到通知后，主动调用商品、订单详情，此时获取到的信息为最新数据

接口使用说明

调用商品支持的运输方式----》获取运费(或直接调用4.8接口)----》订单预览----》生成订单----》订单支付（取消）

订单主流程时序图

1、首先通过接口，获取省市区、商品等的基本信息，API接口用户业务系统生成订单时，调用我司生成订单接口（30分钟内未支付，订单会自动取消，无法再进行支付），待业务系统用户支付成功后，调用我司订单支付接口，返回成功后，数据进入我司内部订单系统，开始执行订单的审核、拣货、配货、发货等操作，配货、发货时，会有对应的订单回调通知，快递单号、快递名称、发货时间等都会回调通知给API用户。
2、获取商品支持的运输方式及运费有两种方式：a、调用商品支持的运输方式接口，获取yfModeCode，在获取商品运费的时候，需要此字段；b、直接调用4.8接口，返回商品支持的所有运输方式及运费。
3、调用订单预览接口，会返回对应的运费、商品费用，订单生成时会使用。
4、用户下单时，需传递我司省市区对应的id，通常处理办法是通过省市区物料，在业务系统做好对应的映射，在订单预览、生成时，直接传输，订单生成后，请在30分钟内完成支付，超过30分钟订单会自动取消，无法再进行支付。
5、运输方式为快递时，订单支付扣除对应的运费金额；运输方式为物流时，需客户线下支付，不会扣除储备金。

专用术语

储备金：用户在我司系统预充值金额，主要用于订单支付时，系统自动扣除

预约服务：对订单进行咨询、售后等时，可在线申请预约服务，数据流入内部工单系统，我司客服部门会进行跟踪和后续处理

商品打包数：生成订单时，购买的商品数量如果不是采样量、起订量，则必须满足打包数的倍数，此属性在商品规格上面

商品采样量：基于商品，单次可购买的商品数量

快递起订量：基于商品规格，选择运输方式为快递时，则商品数量不得小于商品的快递起订量

物流起订量：基于商品规格，选择运输方式为物流时，则商品数量不得小于商品的物流起订量

市场价：即零售价、商品标签价格

商品价格：通过API接口下单支付时，扣除储备金时商品单价

商品id：goods_id:每个商品，不管有多少规格，只要goods_id一样，则属于同一个商品

规格id：spec_id: 同goods_id下，有多少具体规格的商品，就会有多少个spec_id，所有商品，至少有一个 spec_id

规格属性名、规格属性值：举例说明：一个杯子，规格属性名有颜色、容量，规格属性值有，（颜色）黑色、白色；（容量）500ml、600ml、700ml，则商品最多会有 2*3 = 6 个 spec_id,并且每个spec_id的属性值为：1、黑色 500ml；2、黑色 600ml；3、黑色 700ml；4、白色 500ml；5、白色 600ml；6、白色 700ml

运输方式：商品发货的运输方式，需用户主动选择；不同运输方式的时效、价格会不同

服务费：根据商品金额，扣除一定比例的储备金，确认合作前期，会沟通确认

API接口服务费：生成订单时，根据商品金额，扣除一定比例的储备金，确认合作前期，会沟通确认

支付单号：创建订单时，接口返回API单号，每次创建订单唯一

商品单号：多商品一次性下单时，会生成一个支付单号，并且以商品为维度，每款商品对应唯一一个商品单号orderId

物料下载

正式对接时，我司会线下发送相关物料

城市省市区

商品分类

商品品牌

快递物流

项目说明【对接前，请务必认真阅读此文档】#

业务流程#

接口对接说明#

接口规范#

1. 报文格式及编码#

2. 交互协议及请求方式#

3. 公共参数#

4. 签名生成规则#

5. IP白名单#

6. 访问频次#

7. 回调地址#

接口使用说明#

订单主流程时序图#

专用术语#

物料下载#