代发外部仓对接文档 - v1.7

深圳芥舟科技有限公司

2022-01-18

版本所有侵权必究

修改历史

版本	日期	修订人员	修正信息
1.0	2022-01-18	Hamsingli	创建初版接口文档
1.1	2022-01-19	Hamsingli	新增物流发货接口
1.2	2022-01-25	Hamsingli	新增订单支付时间，购买人平台ID，支付类型字段
1.3	2022-02-08	Hamsingli	新增SesstionKey字段
1.4	2022-02-22	Hamsingli	去除不必要字段定义
1.5	2022-03-10	Hamsingli	添加商品维度税费字段
1.6	2022-08-02	Hamsingli	更新商品价格为4位小数
1.7	2022-09-15	Hamsingli	新增订单状态售后推送订阅接口

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

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

2.1 约定

ERP服务通过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)。

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

环境信息:
测试环境: https://gwfat.kldidi.com，后文统一定义为变量TEST_PATH。
生产环境地址: https://gateway-cn.jieztech.com，后文统一定义为变量PRO_PATH。
账号密钥获取
测试环境: 选择MD5加密方式时联系芥舟开发同事提供appId、appSecret给到外部系统。
生产环境: 密钥生成及验证和测试环境一致、联系芥舟开发同事提供生产的相关授权资料。

2.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

注意：

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

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

三、统一信息

3.1 公共请求参数

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

3.2 应答信息

3.2.1 统一应答参数

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

示例:

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

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

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

3.2.3 应答编码

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

四、订单模块

4.1 代发订单拉取

请求说明

请求项	说明信息
正式请求路径	`{PRO_PATH}/apos.aps/api/DropShipping/QueryOrder`
测试请求方式	`{TEST_PATH}/apos.aps/api/DropShipping/QueryOrder`
请求方式	`POST`
描述信息	第三方平台商户维度向APOS拉取原始代发业务订单数据

业务请求参数说明

请求位置	Body
参数	类型	是否必填	默认值	说明
`sessionKey`	`String`			APOS平台分发，与外部仓库1对1绑定
`startTime`	`Long`			开始时间 (UTC 毫秒时间戳)
`endTime`	`Long`			结束时间 (UTC 毫秒时间戳)
`pageIndex`	`Int`		1	页码
`pageSize`	`Int`		30	分页大小，最大200

data应答参数说明

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

参数	描述	类型	长度	说明
`orderNo`	订单编号	`String`	64	商户唯一
`orderTime`	下单时间	`Long`		时间戳(毫秒)
`orderPaidTime`	订单支付时间	`Long`		时间戳(毫秒)
`orderAmount`	订单金额	`String`	32	保留2位小数
`orderTax`	订单税额	`String`	32	保留2位小数
`discountAmount`	订单总优惠	`String`	32	保留2位小数
`actualPayAmount`	实际支付金额	`String`	32	保留2位小数
`goodsAmount`	货品总价值	`String`	32	保留2位小数
`payNo`	支付单流水号	`String`	32	支付单流水号
`payType`	支付类型，支付宝或微信	`String`	32	WeChat、AliPay
`payCompany`	支付公司名称	`String`		第三方支付公司名称
`payCompanyNo`	支付公司十位海关编码	`String`		支付公司海关备案编码
`ebcCode`	电商企业代码	`String`		电商企业代码
`ebcName`	电商企业名称	`String`		电商企业名称
`ebpCode`	电商平台代码	`String`		电商平台代码
`ebpName`	电商平台名称	`String`		电商平台名称
`buyerId`	支付人购物平台ID	`String`	255	支付人购物平台ID
`buyerIdNumber`	支付人身份证号	`String`	255	支付人身份证号
`buyerName`	支付人姓名	`String`	50	支付人姓名
`buyerMobile`	支付人手机号	`String`		支付人手机号
`postAmount`	运费	`String`	255	运费，保留小数点2位
`receiverIdNumber`	收件人身份证号	`String`	255	收件人身份证号
`receiverName`	收件人姓名	`String`	255	收件人姓名
`receiverMobile`	收件人手机号	`String`	255	收件人手机号
`receiverCountry`	收件人国家	`String`	255	收件人国家
`receiverProvince`	收件人省	`String`	255	收件人省
`receiverCity`	收件人市	`String`	255	收件人市
`receiverDistrict`	收件人区	`String`	255	收件人区
`receiverAddress`	收件人详细地址	`String`	255	收件人详细地址
`receiverZip`	收件人邮编	`String`	255	收件人邮编
`note`	订单备注	`String`	255	订单备注
`goodsList`	订单商品信息明细	`List<Object>`
`└sku`	商品SKU	`String`		商品SKU
`└barCode`	商品条码	`String`		商品条码
`└goodsName`	商品名称	`String`		商品名称
`└qty`	数量	`String`		数量
`└salePrice`	商品原价	`String`	32	保留4位小数
`└dealPrice`	商品实际售价	`String`	32	保留4位小数
`└tax`	商品税费	`String`	32	保留4位小数
`└thirdSkuId`	第三方skuId	`String`	32	第三方sku

参数示例

请求信息：

{
    "appId":"802020070300001",
    "time":"1642479037000",
    "version":"1.0",
    "sign":"24f22a638358e27b2a4ae729eec33081",
    "signType":"MD5",
    "sourceType":"1001",
    "sessionKey":"202cb962ac59075b964b07152d234b70",
    "startTime":1642479037000,
    "endTime":1642479697005,
    "pageIndex":1,
    "pageSize":200
}

响应：

{
    "data":{
        "dataSource":[
            {
                "orderNo":"854123658954412-1",
                "orderTimestamp":"1642479697005",
                "orderAmount":"31.00",
                "orderTax":"5.00",
                "discountAmount":"4.00",
                "actualPayAmount":"31.00",
                "goodsAmount":"20.00",
                "ebcCode":"525896358741256325",
                "ebcName":"测试公司",
                "ebpCode":"525896358741256325",
                "ebpName":"测试公司",
                "payNo":"55555555555555",
                "payCompany":"财付通支付科技有限公司",
                "payCompanyNo":"4403169D3W",
                "buyerIdNumber":"352227199805116235",
                "buyerName":"张三.",
                "buyerMobile":"18565214589",
                "postAmount":"10.00",
                "receiverIdNumber":"352227199805116235",
                "receiverName":"李四",
                "receiverMobile":"18565214589",
                "receiverCountry":"中国",
                "receiverProvince":"广东省",
                "receiverCity":"深圳市",
                "receiverDistrict":"宝安区",
                "receiverAddress":"新安街道新天地3栋555",
                "receiverZip":"",
                "goodsList":[
                    {
                        "sku":"8856558",
                        "barCode":"5555555",
                        "goodsName":"测试品",
                        "qty":"2.00",
                        "salePrice":"10.00",
                        "dealPrice":"8.00",
                        "thirdSkuId":"8856558"
                    }
                ]
            }
        ],
        "pageIndex":1,
        "pagesCount":1,
        "pageSize":10,
        "recordsCount":1
    },
    "success":true,
    "message":"操作成功",
    "code":"200"
}

4.2 清关状态回传

请求说明

请求项	说明信息
正式请求路径	`{PRO_PATH}/apos.aps/api/DropShipping/DeclareStatusNotify`
测试请求方式	`{TEST_PATH}/apos.aps/api/DropShipping/DeclareStatusNotify`
请求方式	`POST`
描述信息	第三方清关状态回传

业务请求参数说明

请求位置	Body
参数	类型	是否必填	默认值	说明
`orderNo`	`String`			订单编号
`returnStatus`	`Int`			申报状态：450:申报中; 800:放行;9999:失败;
`returnInfo`	`String`			申报信息
`declareTime`	`Long`			申报时间(UTC毫秒时间戳)
`expressNo`	`String`	选填（returnStatus=800必填）		物流单号
`expressChannelCode`	`String`	选填（returnStatus=800必填）		物流企业海关备案编号
`expressName`	`String`	选填（returnStatus=800必填）		物流名称

data应答参数说明

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

参数示例

请求信息：

{
    "appId":"802020070300001",
    "orderNo":"854123658954412-1",
    "time":"1637737175000",
    "returnStatus":450,
    "declareTime":1637737175000,
    "returnInfo":"申报中",
    "version":"1.0",
    "sign":"ed77d0038a0e684e2b1ba6ba3117adb8",
    "signType":"MD5"
}

响应：

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

4.3 物流发货

请求说明

请求项	说明信息
正式请求路径	`{PRO_PATH}/apos.aps/api/DropShipping/ExpressStatusNotify`
测试请求方式	`{TEST_PATH}/apos.aps/api/DropShipping/ExpressStatusNotify`
请求方式	`POST`
描述信息	第三方清关状态回传

业务请求参数说明

请求位置	Body
参数	类型	是否必填	默认值	说明
`orderNo`	`String`			订单编号
`expressNo`	`String`			物流单号
`expressChannelCode`	`String`			物流企业海关备案编号
`expressName`	`String`			物流名称

data应答参数说明

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

参数示例

请求信息：

{
    "appId":"802020070300001",
    "orderNo":"854123658954412-1",
    "time":"1637737175000",
    "expressNo":"SF885412569",
    "expressChannelCode":"1637737175000",
    "expressChannelName":"顺丰国际",
    "version":"1.0",
    "sign":"ed77d0038a0e684e2b1ba6ba3117adb8",
    "signType":"MD5"
}

响应：

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

4.4 订单状态变更推送

请求说明

请求项	说明信息
正式请求路径	`第三方提供，apos后台配置`
测试请求方式	`第三方提供，apos后台配置`
请求方式	`POST`
描述信息	订单状态支付，售后变更推送

业务请求参数说明

请求位置	Body
参数	类型	是否必填	默认值	说明
`webhookName`	`String`			订阅名
`webhookCode`	`String`			订阅类型Code：订单状态变更=1001
`webhookUrl`	`String`			推送地址
`secret`	`String`	否		秘钥
`time`	`String`			推送时间格式：yyyy-MM-dd HH:mm:ss
`data`	`body`			核心推送内容体
`└orderNo`	`String`			订单号
`└orderState`	`String`			订单状态：已支付=2，已签收=16，售后=32

data应答参数说明

参数	描述	类型	说明
`Bool`	是否成功	`Bool`	true:成功 false:失败

参数示例

请求信息：

{
    "webhookName":"订单状态订阅",
    "secret":"",
    "webhookCode":1001,
    "webhookUrl":"http://gateway.gvtfat.com/apos.notify/api/NotifyTest/NotifyTest",
    "time":"2022-02-23 11:17:33",
    "data":{
        "orderNo":"3417701946726043648",
        "orderState":2
    }
}

响应：

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

五、库存模块

5.1 仓库库存同步

请求说明

请求项	说明信息
正式请求路径	`{PRO_PATH}/apos.aps/api/DropShipping/StockNotify`
测试请求方式	`{TEST_PATH}/apos.aps/api/DropShipping/StockNotify`
请求方式	`POST`
描述信息	第三方仓库库存信息回传

业务请求参数说明

请求位置	Body
参数	类型	是否必填	默认值	说明
`sessionKey`	`String`			APOS平台分发，与外部仓库1对1绑定
`goodsList`	`List<Object>`
`└sku`	`String`			第三方skuId
`└barcode`	`String`	选填		商品条码
`└goodsName`	`String`			商品名称
`└qty`	`String`			可售库存数量
`└thirdSkuId`	`String`	选填	如果没有默认等于sku	货号

data应答参数说明

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

参数示例

请求信息：

{
    "appId":"802020070300001",
    "time":"1637737175000",
    "version":"1.0",
    "sign":"ed77d0038a0e684e2b1ba6ba3117adb8",
    "signType":"MD5",
    "sourceType":"1001",
    "sessionKey":"hd77d0038a0e684e2b1ba6ba3127agsa",
    "goodsList":[
        {
            "sku":"8856558",
            "barcode":"5555555",
            "goodsName":"测试品",
            "qty":"2.00"
        }
    ]
}

响应：

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