一般贸易代发多仓对接文档 - v1.2

深圳芥舟科技有限公司

2022-03-11

版本所有侵权必究

修改历史

版本	日期	修订人员	修正信息
1.0	2022-03-11	Hamsingli	创建初版接口文档
1.1	2022-03-18	Hamsingli	新增实际支付金额
1.2	2022-04-18	TanJie	新增商品同步接口,订单新增支付时间字段
1.3	2022-04-27	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
示例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

注意：

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

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/DropShippingProductsPush`
测试请求方式	`{TEST_PATH}/apos.aps/api/DropShipping/DropShippingProductsPush`
请求方式	`POST`
描述信息	商品信息同步

业务请求参数说明

请求位置	Body
参数	类型	是否必填	默认值	说明
`sessionKey`	`String`			APOS平台分发，与外部仓库1对1绑定
`operateType`	`Int`			1、商品新增 2、商品修改 3、SKU新增（一个品多sku时候使用）
`productsList`	`List<Object>`
`└externalGoodsId`	`String`			APos系统与外部系统对接导入商品、商品信息时进行绑定
`└productName`	`String`			商品名称
`└shortName`	`String`	否		产品简称
`└mainImgs`	`List<String>`	否		产品主图
`└detailImgs`	`List<String>`	否		产品详情图
`└brandName`	`List<String>`			品牌名称
`└categoryName`	`String`			类别名称
`└barcode`	`String`			商品条码
`└parentCategoryName`	`String`			父级类别名称
`└relBarcode`	`String`	否		商品副条码 ,若有多个副条码使用逗号分隔
`└skuNo`	`String`			货品编号
`└attribute`	`String`	否		属性描述
`└externalSkuId`	`String`			外部货品Id,APos系统与外部系统对接导入商品、Sku信息时进行绑定
`└originCountry`	`String`	否		原产国名称
`└salesModel`	`String`	否		销售模式 0110:0110完税 0111:0111保税 1210:1210保税 1310:1310免税
`└weight`	`Decimal`			重量
`└size`	`String`			规格
`└unit`	`String`			单位
`└purchasePrice`	`Decimal`			进货价
`└salePrice`	`Decimal`			销售价
`└suggestedSalePrice`	`Decimal`			建议零售价
`└limitPrice`	`Decimal`			最低售价

data应答参数说明

参数	描述	类型	说明
`bool`	是否成功	`Bool`

参数示例

请求信息：

{
    "productList":[
        {
            "externalGoodsId":"GH00001122222",
            "productName":"圆领长袖卫衣黑色-XL_1",
            "shortName":"Champion 黑色袖口小logo薄绒圆领长袖卫衣 日版 C5-L004",
            "mainImgs":[
                "https://gvt-hk-dev01.oss-accelerate.aliyuncs.com/gms/Product/2020/11/20/5c1dea63-db50-4f2c-a05c-4a96a4cb8df7.jpeg"
            ],
            "detailImgs":[
"https://gvt-hk-dev01.oss-accelerate.aliyuncs.com/gms/Product/2020/11/20/5c1dea63-db50-4f2c-a05c-4a96a4cb8df7.jpeg"
            ],
            "brandName":"CHAMPION",
            "categoryName":"卫衣",
            "parentCategoryName":"衣服",
            "barcode":"0177048904",
            "skuNo":"GVT_0177048904",
            "relBarcode":"C00006,D00006",
            "externalSkuId":"GVT_0177048904",
            "originCountry":"法国",
            "salesModel":"1310",
            "attribute":"圆领长袖卫衣黑色_免税",
            "weight":250,
            "size":"黑色-XL_1-C5-L004-090-XL",
            "unit":"件",
            "purchasePrice":56.8,
            "salePrice":78,
            "suggestedSalePrice":78,
            "limitPrice":68
        }
    ],
    "appId":"802021011900001",
    "version":"1.0",
    "time":"43246546546546",
    "operateType":1,
    "sessionKey":"221abc746ffcb82312fdf9a124949987",
    "sign":"551abc746ffcb82312fdf9a1249418c2",
    "signType":"MD5"
}

响应：

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

五、订单模块

5.1 一般贸易业务订单拉取

请求说明

请求项	说明信息
正式请求路径	`{PRO_PATH}/apos.aps/api/DropShipping/QueryGeneralOrder`
测试请求方式	`{TEST_PATH}/apos.aps/api/DropShipping/QueryGeneralOrder`
请求方式	`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	商户唯一
`shopName`	门店名称	`String`	255	门店名称
`orderTime`	下单时间	`Long`		时间戳(毫秒)
`orderPaidTime`	支付时间	`Long`		时间戳(毫秒)
`orderAmount`	订单金额	`String`	32	保留2位小数
`orderTax`	订单税额	`String`	32	保留2位小数
`discountAmount`	订单总优惠	`String`	32	保留2位小数
`payNo`	第三方支付平台流水号	`String`	32	支付流水号
`goodsAmount`	货品总价值	`String`	32	保留2位小数
`actualPayAmount`	实际支付金额	`String`	32	保留2位小数
`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	保留2位小数
`└dealPrice`	商品实际售价	`String`	32	保留2位小数
`└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",
                "shopName":"测试门店",
                "orderTimestamp":1642479697005,
                "orderAmount":"31.00"
                "payNo":"42384293842983429842",
                "orderPaidTime":1642479697005,
                "orderTax":"5.00",
                "discountAmount":"4.00",
                "actualPayAmount":"31.00",
                "goodsAmount":"20.00",
                "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",
                        "tax":"2.5",
                        "thirdSkuId":"8856558"
                    }
                ]
            }
        ],
        "pageIndex":1,
        "pagesCount":1,
        "pageSize":10,
        "recordsCount":1
    },
    "success":true,
    "message":"操作成功",
    "code":"200"
}

5.2 物流发货

请求说明

请求项	说明信息
正式请求路径	`{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",
    "expressCode":"1637737175000",
    "expressName":"顺丰国际",
    "version":"1.0",
    "sign":"ed77d0038a0e684e2b1ba6ba3117adb8",
    "signType":"MD5"
}

响应：

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

5.3 取消订单申请

请求说明

请求项	说明信息
正式请求路径	`{PRO_PATH}/apos.aps/api/DropShipping/CancelOrderApply`
测试请求方式	`{TEST_PATH}/apos.aps/api/DropShipping/CancelOrderApply`
请求方式	`POST`
描述信息	取消订单申请

业务请求参数说明

请求位置	Body
参数	类型	是否必填	默认值	说明
`orderNo`	`String`			订单编号
`Remark`	`String`			取消原因

data应答参数说明

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

参数示例

请求信息：

{
    "appId":"802020070300001",
    "orderNo":"854123658954412-1",
    "time":"1637737175000",
    "remark":"缺货需要取消",
    "version":"1.0",
    "sign":"ed77d0038a0e684e2b1ba6ba3117adb8",
    "signType":"MD5"
}

响应：

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

5.4 售后订单列表

请求说明

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

业务请求参数说明

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

data应答参数说明

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

参数	描述	类型	长度	说明
`orderNo`	订单编号	`String`	64	商户唯一
`afterSalesTime`	售后时间	`Long`		时间戳(毫秒)
`remark`	售后备注	`String`		售后备注

参数示例

请求信息：

{
    "data":{
        "dataSource":[
            {
                "orderNo":"854123658954412-1",
                "afterSalesTime":"1642479697005",
                "remark":"不想要了"
            }
        ],
        "pageIndex":1,
        "pagesCount":1,
        "pageSize":10,
        "recordsCount":1
    },
    "success":true,
    "message":"操作成功",
    "code":"200"
}

六、库存模块

6.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`			货号
`└barcode`	`String`	选填		商品条码
`└goodsName`	`String`			商品名称
`└qty`	`String`			可售库存数量
`└thirdSkuId`	`String`	选填	如果没有默认等于sku	第三方skuId

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
}