APOS开放平台1210统一对接方案- v1.4

深圳芥舟科技有限公司

2022-06-17

版本所有 侵权必究

修改历史

版本	日期	修订人员	修正信息
1.0	2022-06-17	Hamsingli	创建初版接口文档
1.1	2022-07-20	Hamsingli	完善发货接口
1.2	2022-07-25	Hamsingli	完善库存查询接口
1.3	2022-08-01	Hamsingli	完善订单接口字段信息
1.4	2022-08-30	Hamsingli	字段信息调整

一、项目背景

• 本项目是芥舟科技整合其在跨境电商多年系统集成资源，提供的保税业务综合解决方案；主要功能为对接第三方现有商城系统，获取跨境订单，推单到APSO系统，然后完成订单整个后续履约，清关，发货功能等，具体说明如下系统方案：

1.1 方案

• 如上系统流程图业务参与方包含第三方商城，芥舟APOS开放平台，芥舟清关平台，芥舟合作的保税仓储企业及海关单一窗口。

• 订单下单前先完成注册备案，由第三方完成电商企业备案，获取海关ukey及配置信息后交给芥舟，搭建179反查功能，跨境商品信息入保税仓进行备案操作，入库后完成海关核注，获取商品账册及料号，然后在电商平台完成商品上架开始销售。

• 订单产生后由第三方商城下单按照仓库分单，支付单拆单，订单支付完成后，推给APOS开放平台，由芥舟申报系统完成订单上报，然后将订单物流和商品信息推送保税仓，保税仓匹配商品料号并完成物流下单申报后将结果反馈清关平台，清关平台依次生成订单和清单，并向海关系统完成申报。海关单窗根据清单信息核验三单对碰，信息正确后返回放行回执到清关平台，清关平台触发保税仓发货并将发货状态同步回传给新景界跨境商城。

• 另外增加两个日常系统操作的接口，售后接口用来处理客户退货的情况，由跨境商城发起，清关平台判定订单状态，未完成清单申报的订单支持订单取消，已完成的则需要线下进行售后操作。库存同步接口同步保税仓库存给到电商平台系统，应对库存变化，防止超卖。

二、系统调用、部署关系图

三、芥舟开放平台接口调用

3.1 约定

• APOS开放平台通过Https协议(支持TLS1.2版本)对外提供Web Api接口。

  API请求头信息:

  Accept: application/json；

  Content-Type: application/json;charset=UTF-8；

• 所有请求内容需要包含参数appId(应用Id)、version(1.0)、time(UTC毫秒时间戳)、sign(签名信息)、signType(支持MD5)。

3.2 环境信息、账号秘钥获取

• 环境信息:

  测试环境: https://gwfat.kldidi.com，后文统一定义为变量TEST_PATH。

  生产环境地址: https://gateway-cn.jieztech.com，后文统一定义为变量PRO_PATH。

• 账号密钥获取

  测试环境: 选择MD5加密方式时联系芥舟开发同事提供appId、appSecret给到外部系统。

  生产环境: 密钥生成及验证和测试环境一致、联系芥舟开发同事提供生产的相关授权资料。

3.3 签名、验签

• 筛选

  获取所有请求参数，sign、signType参数不参与签名，需要剔除sign、signType参数。需要注意为空的参数不参与签名，空字符串需要参与签名。

• 排序

  将筛选后的参数按照位置加字母升序排序(ASCII码递增排序)，先按第一个字符键值排序，遇到相同字母按第二个字符键值排序，以此类推。对于多层级参数的情况，每个层级的参数根据各层级参数名的ASCII码从小到大排序。

• 拼接

  将排序后的参数与其对应值，组合成“参数=参数值”的格式，并且把这些参数用&字符连接起来，此时生成的字符串为待签名字符串。

• 存在数组的情况

  如果参数中存在子json是数组的情况，直接使用数组原始key[数组下标]=值方式组合，参考示例3，

  如果参数中存在子json是数组的情况,且数组是KEY:VALUE方式，则对key进行ASCII码从小到大排序，然后使用数组原始key[下标]_子key方式组合,如：{id:1,param1:{key1:val1},param2:{data:[{name:zs,sex=boy},{name:ls,sex=girl}]}}，组合后的字符串为: id=1&param1_key1=val1&data[0]_name=zs&data[0]_sex=boy&data[1]_name=ls&data[1]_sex=girl。参考示例4

• 示例1: 请求参数

appId=802020070300001&orderNo=102020070300001&time=1593767721515&version=1.0

拼接后参数

appId=802020070300001&orderNo=102020070300001&time=1593767721515&version=1.0

• 示例2: 请求参数

{
    "appId": "802020070300001",
    "orderNo": "102020070300001",
    "time": "1593767721515",
    "version": "1.0",
    "signType": "MD5"
}

拼接后参数

appId=802020070300001&orderNo=102020070300001&time=1593767721515&version=1.0

• 示例3: 请求参数

{
    "appId": "802020070300001",
    "orderNo": "102020070300001",
    "time": "1593767721515",
    "orderNoList":["819000803560518","819000803560519"],
    "version": "1.0",
    "signType": "MD5"
}

拼接后参数

appId=802021042000001&orderNoList[0]=819000803560518&orderNoList[1]=819000803560519&time=1631241232765&version=1.0

• 示例4: 请求参数

{
    "appId":"3512618851001196672",
    "version":"1.0",
    "sessionKey":"string",
    "goodsList":[
        {
            "sku":"4548366593300",
            "barcode":"4548366593300",
            "goodsName":"SABRINA连裤袜黑色80厚度2双装JM-L",
            "qty":"40"
        }
    ]
}

拼接后参数

appId=3512618851001196672&goodsList[0]_barcode=4548366593300&goodsList[0]_goodsName=SABRINA连裤袜黑色80厚度2双装JM-L&goodsList[0]_qty=40&goodsList[0]_sku=4548366593300&sessionKey=string&version=1.0d7de99ccbd3fbaab38261f7a067c0e49

注意：

拼接签名之前的参数时需使用参数的原始值状态，不能基于原始值进行其他编码转换，否则会造成签名验证失败，无需剔除NULL等空字符串。

• signType = MD5：

签名需要将appSecret的值拼接在字符串后面，调用MD5算法生成sign；

appId: 802020070300001
appSecret: e338aeb855c94faca1c51a822740058e

请求参数

appId=802020070300001&orderNo=102020070300001&time=1593767721515&version=1.0&signType=MD5

拼接后签名前参数

appId=802020070300001&orderNo=102020070300001&time=1593767721515&version=1.0e338aeb855c94faca1c51a822740058e

请求信息

appId=802020070300001&orderNo=102020070300001&time=1593767721515&version=1.0&signType=MD5&sign=24f22a638358e27b2a4ae729eec33081

四、统一信息

4.1 公共请求参数

参数	类型	说明
appId	String	商户级别，应用Id由芥舟提供
version	String	接口版本: 默认传1.0
time	String	UTC毫秒时间戳
signType	String	加密方式 MD5
sign	String	签名信息

4.2 应答信息

4.2.1 统一应答参数

参数	类型	说明
success	Bool	成功: true, 失败: false
code	String	应答编码(具体参考:应答信息->应答编码)
message	String	应答描叙信息
data	泛型	各接口有具体应答参数说明

• 示例:

{
    "success": true,
    "code": "200",
    "message": "请求成功",
    "data": null
}

4.2.2 统一分页数据应答 data参数

参数	类型	说明
dataSource	List<泛型>	每页数据
pageIndex	Integer	当前页码
pagesSize	Integer	每页记录条数
pagesCount	Integer	总页数
recordsCount	Integer	总记录条数

4.2.3 应答编码

编码	描述
200	成功
110004	appId不存在
110005	签名错误

五、订单模块

5.1 创建渠道订单

• 请求说明

请求项	说明信息
正式请求路径	{PRO_PATH}/apos.aps/api/DropShipping/CreateChannelOrder
测试请求方式	{TEST_PATH}/apos.aps/api/DropShipping/CreateChannelOrder
请求方式	POST
描述信息	创建渠道订单

• 业务请求参数说明

| 请求位置 | Body| || || |----|----|---|---|----|---|--| | 参数| 说明| 类型 | 默认值 | 说明| 是否必填 | | sessionKey | APOS平台分发，与外部仓库1对1绑定 | String | 64 | 仓库唯一，一仓一码 | | | orderNo | 订单编号 | String | 64 | 商户唯一，订单号不能带横杠（-）字符 | | | orderTime | 下单时间 | Long | | 时间戳(毫秒) | | | orderPaidTime | 订单支付时间 | Long | | 时间戳(毫秒) | | | orderAmount | 订单金额 | String | 32 | 保留2位小数 | | | orderTax | 订单税额 | String | 32 | 保留2位小数 | | | discountAmount | 订单总优惠 | String | | 保留2位小数 | | | actualPayAmount | 实际支付金额 | String | | 保留2位小数| | | goodsAmount | 货品总价值 | String | | 保留2位小数| | | payNo| 支付单流水号 | String | | 支付单流水号| | | payType| 支付类型，支付宝或微信 | String | | WeChat、AliPay | | | payCompany | 支付公司名称 | String | |第三方支付公司名称| | | payCompanyNo | 支付公司十位海关编码 | String | |支付公司海关备案编码 | | | ebcCode | 电商企业代码 | String | | 电商企业代码 | | | ebcName | 电商企业名称 | String | | 电商企业名称 | | | ebpCode | 电商平台代码 | String | | 电商平台代码 | | | ebpName | 电商平台名称 | String | | 电商平台名称 | | | buyerId | 支付人购物平台ID | String | | 支付人购物平台ID |否| | buyerIdNumber | 支付人身份证号 | String | | 支付人身份证号 | | | buyerName | 支付人姓名 | String | | 支付人姓名 | | | buyerMobile | 支付人手机号 | String | | 支付人手机号 | | | postAmount | 运费 | String | | 运费，保留小数点2位 | | | receiverIdNumber | 收件人身份证号 | String | | 收件人身份证号 | | | receiverName | 收件人姓名 | String | | 收件人姓名 | | | receiverMobile | 收件人手机号 |String | | 收件人手机号 | | | receiverCountry | 收件人国家 | String | 中国 | 收件人国家 | 否| | receiverProvince | 收件人省 | String | | 收件人省 | | | receiverCity | 收件人市 | String | | 收件人市 | | | receiverDistrict | 收件人区 | String | | 收件人区 | | | receiverAddress | 收件人详细地址 | String | | 收件人详细地址 | | | receiverZip | 收件人邮编 | String | 255 | 收件人邮编 |否| | note | 订单备注 | String | | 订单备注 |否| | goodsList | 订单商品信息明细 | List<Object> |||| | └sku | 商品SKU | String | | 商品SKU || | └barCode | 商品条码 | String | | 商品条码 || | └goodsName | 商品名称 | String | | 商品名称 || | └qty | 数量 | String | | 数量 || | └salePrice | 商品原价 | String |32| 保留2位小数 || | └dealPrice | 商品实际售价 | String |32| 保留2位小数 || | └tax | 商品税费 | String |32| 保留4位小数 ||

• data应答参数说明

通用返回，请参考3.2.1 统一应答参数

• 参数示例

请求信息：

{
    "sessionKey":"df0023046ce5c9cfda7cc032d7403423",
    "orderNo": "8477690416163369109-1",
    "orderTime": 1658891396562,
    "orderPaidTime": 1658891396562,
    "orderAmount": "0.04",
    "orderTax": "0.00",
    "discountAmount": "0.00",
    "actualPayAmount": "0.04",
    "goodsAmount": "0.02",
    "payNo": "2022071111082305421697480",
    "payType": "AliPay",
    "payCompany": "支付宝(中国)网络技术有限公司",
    "payCompanyNo": "31222699S7",
    "ebcCode": "dt001",
    "ebcName": "代塔测试有限公司",
    "ebpCode": "dt001",
    "ebpName": "代塔测试有限公司",
    "buyerId": "334652293381621632",
    "buyerIdNumber": "362204199703057419",
    "buyerName": "汪坤",
    "buyerMobile": "13767167888",
    "postAmount": "0.02",
    "receiverIdNumber": "362204199703057419",
    "receiverName": "汪坤",
    "receiverMobile": "13767167888",
    "receiverCountry": "中国",
    "receiverProvince": "广东省",
    "receiverCity": "深圳市",
    "receiverDistrict": "宝安区",
    "receiverAddress": "宝安1村",
    "receiverZip": "330800",
    "goodsList": [
        {
            "sku": "6972997190290",
            "barCode": "6972997190290",
            "goodsName": "荣耀手机9",
            "qty": "2",
            "salePrice": "0.01",
            "dealPrice": "0.01",
            "tax": "0.0009"
        }
    ],
    "note": null,
    "shopName": "测试APOS",
    "shopId": ""
}

响应：

{
    "success": true,
    "code": "200",
    "message": "请求成功",
    "data": null
}

5.2 清关状态回传（订阅推送接口）

• 请求说明

请求项	说明信息
正式请求路径
测试请求方式
请求方式	POST
描述信息	清关状态回传，提供接口地址，apos后台配置订阅

• 业务请求参数说明

请求位置	Body
参数	类型	是否必填	默认值	说明
orderNo	String			订单编号
returnStatus	String			清关返回状态：申报中=450，申报成功=800，申报失败=9999
returnInfo	String	否	清关返回信息
declareTime	Long			时间戳（毫秒）
expressNo	String	清关状态返回800，必填		物流单号
expressCode	String	清关状态返回800，必填		物流编号
expressName	String	清关状态返回800，必填		物流公司名称

• data应答参数说明

通用返回，请参考3.2.1 统一应答参数

• 参数示例

请求信息：

{
    "orderNo":"854123658954412",
    "declareTime":"1637737175000",
    "expressNo":"SF885412569",
    "expressCode":"shunfeng",
    "expressName":"顺丰国际",
    "returnStatus":"800",
    "returnInfo":"清关成功"
}

响应：

{
    "success": true,
    "code": "200",
    "message": "请求成功",
    "data": null
}

5.3 物流发货接口（订阅推送接口）

• 请求说明

请求项	说明信息
正式请求路径
测试请求方式
请求方式	POST
描述信息	物流发货，提供接口地址，apos后台配置订阅

• 业务请求参数说明

请求位置	Body
参数	类型	是否必填	默认值	说明
orderNo	String			订单编号
sendTime	Long			发货时间（时间戳毫，秒）
expressNo	String			物流单号
expressCode	String			物流编号
expressName	String			物流公司名称

• data应答参数说明

通用返回，请参考3.2.1 统一应答参数

• 参数示例

请求信息：

{
    "orderNo":"854123658954412",
    "declareTime":"1637737175000",
    "expressNo":"SF885412569",
    "expressCode":"shunfeng",
    "expressName":"顺丰国际",
    "returnStatus":"800",
    "returnInfo":"清关成功"
}

响应：

{
    "success": true,
    "code": "200",
    "message": "请求成功",
    "data": null  
}

5.4 订单售后

• 请求说明

请求项	说明信息
正式请求路径	{PRO_PATH}/apos.aps/api/OrderPub/CancelChannelOrder
测试请求方式	{TEST_PATH}/apos.aps/api/OrderPub/CancelChannelOrder
请求方式	POST
描述信息	订单售后

• 业务请求参数说明

请求位置	Body
参数	类型	是否必填	默认值	说明
sessionKey	String			SessionKey
orderNo	String			订单编号

• data应答参数说明

通用返回，请参考3.2.1 统一应答参数

• 参数示例

请求信息：

{
    "sessionKey":"df0023046ce5c9cfda7cc032d7403423",
    "orderNo":"854123658954412"
}

响应：

{
    "success": true,
    "code": "200",
    "message": "请求成功",
    "data": null
}

六、库存模块

6.1 库存查询

• 请求说明

请求项	说明信息
正式请求路径	{PRO_PATH}/apos.aps/api/DropShipping/QueryChannelStock
测试请求方式	{TEST_PATH}/apos.aps/api/DropShipping/QueryChannelStock
请求方式	POST
描述信息	查询库存信息

• 业务请求参数说明

请求位置	Body
参数	类型	是否必填	默认值	说明
sessionKey	String			APOS平台分发，与外部仓库1对1绑定
pageSize	Integer		15	每页记录条数,最大值200
pageIndex	Integer		1	页码,超始值为1

• data应答参数说明

通用返回，请参考 4.2.2 统一分页数据应答 data参数

参数	描述	类型	是否必填	说明
sku	货号	String		商户唯一
barcode	条码	String
goodsName	商品名称	String
qty	库存数量	String
cost	成本价	String	否
batch	批次号	String	否

• 参数示例

请求信息：

{
    "pageIndex":"1",
    "pageSize":"15",
    "sessionKey":"hd77d0038a0e684e2b1ba6ba3127agsa",
}

响应：

{
    "data":{
        "dataSource":[
            {
                 "sku":"8856558",
                 "barcode":"5555555",
                 "goodsName":"测试品",
                 "cost":15,
                 "qty":"2.00"
            }
        ],
        "pageIndex":1,
        "pagesCount":1,
        "pageSize":15,
        "recordsCount":1
    },
    "success":true,
    "message":"操作成功",
    "code":"200"
}

七.通用信息

7.1 物流code编码

物流Code	描述
shunfeng	顺丰
youhzeng	邮政
yundakuaiyun	韵达
yuantong	圆通
zhongtongkuaiyun	中通快运
zhongtongguoji	中通国际
zhongtong	中通快递
yuantongguoji	圆通国际