一、WMS用户新建开发者

需要参数：开发者名称、Webhook地址
获取开发者 client_id, client_secret

二、授权

1、获取授权码

https://app.apifox.com/link/project/3972134/apis/api-145133310

2、通过授权码获取accessToken、refreshToken、userId等授权信息

https://app.apifox.com/link/project/3972134/apis/api-145133309

3、刷新accessToken

https://app.apifox.com/link/project/3972134/apis/api-145133308

首次授权调用1、2两个接口获取到 accessToken 和 refreshToken，调用具体的接口时使用 accessToken
accessToken为短效token（有效期24小时），失效后调用接口3，通过refreshToken获取新的accessToken
refreshToken为长效token（有效期1年），失效后需要重新进行授权操作即调用1、2两个接口

三、Webhook

WebHook数据格式

// 订单发货

{
          "timestamp":  "时间戳",
          "type":  "order",
          "data":  {
                    "userId":  "1 // oms用户id",
                    "erpNo":  "123123",
                    "warehouseCode": "xxx",// WMS仓库编号
                    "status":  "Shipped"，
                    "skuList": [{
			"sku": "2309-1Bei",// sku
			"total": 26,// 库存总数
			"locked": 0,// 已锁数量
			"available": 26,// 可用数量
			"nonGood": 0,// 不良品数量
			"totalChange": -1// 库存变动数量
                    }]
          }
}

// 入库单上架

{
          "timestamp":  "时间戳",
          "type":  "storage",
          "data":  {
                    "userId":  "24 // oms用户id",
                    "erpNo":  "Lucky1704360185 // ERP单号",
                    "warehouseCode": "xxx",// 仓库编号
                    "putawayNo":  "P11240104100153 // 入库单号",
                    "finishTime":  "2024-01-04T09:23:26.729",
                    "status":  "null // 单据完成是的话是Finish",
                    "skuList":  [
                              {
                                        "skuCode":  "BUG_more898 // ERP的商品GTIN码",
                                        "sku":  "BUG_more898 // sku",
                                        "num":  10,
                                        "badNum":  0,
                                        "thisTimeNum":  10
                              },
                              {
                                        "skuCode":  "BUG_more899",
                                        "sku":  "BUG_more899",
                                        "num":  "5 // 良品数量",
                                        "badNum":  "0 // 次品数量",
                                        "thisTimeNum":  "5 //本次上架数量"
                              }
                    ]
          }
}

// 退货入库单完成

{
          "timestamp":  "时间戳",
          "type":  "return",
          "finishTime":  "完成时间",
          "data":  {
                    "userId":  "1 //oms用户id",
                    "erpNo":  "ERP单号",
                    "warehouseCode": "xxx",// 仓库编号
                    "status":  "FINISH",
                    "skuList":  [
                              {
                                        "sku":  "sku",
                                        "num":  "1 // 良品数量",
                                        "badNum":  "0 // 次品数量"
                              }
                    ]
          }
}

// 订单截单（status: 成功：“success” 失败：“fail”）

{
          "timestamp":  "时间戳",
          "type":  "orderIntercept",
          "data":  {
                    "userId":  "1 // oms用户id",
                    "erpNo":  "123123",
                    "status":  "success"
          }
}

// 库存盘点

{
	"timestamp": 时间戳,
	"type": "inventoryCount",
	"data": {
		"warehouseCode": "xxx",// 仓库编号
		"documentNo": "xx",// 盘点单号
		"userId": 1, // oms用户id
		"finishTime": "2025-02-07T08:07:56.908",// 完成时间
		"skuList": [{
			"sku": "2309-1Bei",// sku
			"total": 26,// 库存总数
			"locked": 0,// 已锁数量
			"available": 26,// 可用数量
			"nonGood": 0,// 不良品数量
			"totalChange": -1,// 库存变动数量
			"lockedChange": null,// 已锁变动数量
			"availableChange": null,// 可用变动数量
			"nonGoodChange": null// 次品变动数量
		}]
	}
}

// 库存调整

{
	"timestamp": 时间戳,
	"type": "adjust",
	"data": {
		"warehouseCode": "01",// 仓库编号
		"documentNo": "ADSE02620",// 调整单号
		"userId": 1,// oms用户id
		"finishTime": "2025-02-07T09:10:03.951",// 完成时间
		"skuList": [{
			"sku": "819-Dark GL",// sku
			"total": 1,// 库存总数
			"locked": 0,// 已锁数量
			"available": 1,// 可用数量
			"nonGood": 0,// 不良品数量
			"totalChange": 1,// 库存变动数量
			"lockedChange": null,// 已锁变动数量
			"availableChange": null,// 可用变动数量
			"nonGoodChange": null // 次品变动数量
		}]
	}
}

// 移货

{
	"timestamp": 时间戳,
	"type": "move",
	"data": {
		"warehouseCode": "A",// 仓库编号
		"documentNo": "MOL703",// 移货单号
		"userId": 3256,// oms用户id
		"finishTime": "2025-02-06T03:59:21.009",// 完成时间
		"finishTime": "2025-02-07T09:10:03.951",// 完成时间
		"skuList": [{
			"sku": "819-Dark GL",// sku
			"total": 1,// 库存总数
			"locked": 0,// 已锁数量
			"available": 1,// 可用数量
			"nonGood": 0,// 不良品数量
			"totalChange": 1,// 库存变动数量
			"lockedChange": null,// 已锁变动数量
			"availableChange": null,// 可用变动数量
			"nonGoodChange": null // 次品变动数量
		}]
	}
}

// 创建订单

{
	"timestamp": 时间戳,
	"type": "orderCreate",
	"data": {
		"warehouseCode": "YK",// 仓库编号
		"documentNo": "BSZ1AF0608",// erp单号
		"userId": 3256,// oms用户id
		"finishTime": "2025-02-06T03:59:21.009",// 完成时间
		"finishTime": "2025-02-07T09:10:03.951",// 完成时间
		"skuList": [{
			"sku": "819-Dark GL",// sku
			"total": 1,// 库存总数
			"locked": 0,// 已锁数量
			"available": 1,// 可用数量
			"nonGood": 0,// 不良品数量
			"totalChange": 1,// 库存变动数量
			"lockedChange": null,// 已锁变动数量
			"availableChange": null,// 可用变动数量
			"nonGoodChange": null // 次品变动数量
		}]
	}
}

// 取消订单

{
	"timestamp": 时间戳,
	"type": "orderCancel",
	"data": {
		"warehouseCode": "YK",// 仓库编号
		"documentNo": "BSZ1AF0608",// erp单号
		"userId": 3256,// oms用户id
		"finishTime": "2025-02-06T03:59:21.009",// 完成时间
		"finishTime": "2025-02-07T09:10:03.951",// 完成时间
		"skuList": [{
			"sku": "819-Dark GL",// sku
			"total": 1,// 库存总数
			"locked": 0,// 已锁数量
			"available": 1,// 可用数量
			"nonGood": 0,// 不良品数量
			"totalChange": 1,// 库存变动数量
			"lockedChange": null,// 已锁变动数量
			"availableChange": null,// 可用变动数量
			"nonGoodChange": null // 次品变动数量
		}]
	}
}

// 库存转换

{
	"timestamp": 时间戳,
	"type": "convert",
	"data": {
		"warehouseCode": "A",// 仓库编号
		"documentNo": "MOL703",// 库存转换单号
		"userId": 3256,// oms用户id
		"finishTime": "2025-02-06T03:59:21.009",// 完成时间
		"finishTime": "2025-02-07T09:10:03.951",// 完成时间
		"skuList": [{
			"sku": "819-Dark GL",// sku
			"total": 1,// 库存总数
			"locked": 0,// 已锁数量
			"available": 1,// 可用数量
			"nonGood": 0,// 不良品数量
			"totalChange": 1,// 库存变动数量
			"lockedChange": null,// 已锁变动数量
			"availableChange": null,// 可用变动数量
			"nonGoodChange": null // 次品变动数量
		}]
	}
}

Webhook响应数据格式

{
    "code": "0是正确，其他异常",
    "msg": ""
}

Webhook签名

Map<String, Object> signMap = Maps.newHashMap();
signMap.put("data", "数据");
signMap.put("clientSecret", "客户端密码");
String sign =  Md5Utils.md5Hex(JSONUtil.objectToJson(signMap));

四、调用业务接口

1、所有业务接口请求方式均为post，业务请求参数均以JSON格式放在请求体中

2、请求头中必须带有以下公共参数

clientId：开发者id
accessToken：用户授权获取到的请求令牌
timestamp：时间戳，毫秒
nonce：随机数字（建议2位数），用于防止重复请求
userId：用户id
sign：签名

3、签名生成方式

key：
accessToken、clientId、method（请求方式get/post，目前固定为post）、nonce、timestamp、url（接口请求路径）、userId
七个参数排序后用&拼接

eg：
accessToken=ds234ds&clientId=321321&method=post&nonce=14&timestamp=1692889556000&url=/api/order/get&userId=8

使用Hamc SHA256进行加密，开发者的client_secret为加密密钥

计算签名方法工具类：


    public static String sign(String key, String data) {
        return hmacsha256(key, data);
    }

    public static String hmacsha256(String key, String data) {
        try {
            Mac hmac = Mac.getInstance("HmacSHA256");
            SecretKeySpec secret_key = new SecretKeySpec(
                    key.getBytes(StandardCharsets.UTF_8),
                    "HmacSHA256");
            hmac.init(secret_key);
            return new String(Hex.encodeHex(hmac.doFinal(data.getBytes(StandardCharsets.UTF_8))));
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }

    public static void main(String[] args) {
        Map<String, Object> params = new HashMap<>();
        params.put("url","/api/order/get");
        params.put("method","post");
        params.put("accessToken","1b56814f081c432cb82751be145261d3");
        params.put("clientId","fe73489a9b5948dbafd07e7b28d6e268");
        params.put("timestamp","1692889556000");
        params.put("nonce","14");
        params.put("userId","8");
        String data = params.entrySet().stream().map(e -> e.getKey() + "=" + e.getValue()).sorted().collect(Collectors.joining("&"));
        // HmacSHA256签名
        String genSign = Signature.sign("4a506ccaf37e400bac4a42d2dc5f600a", data);
        System.out.println(data);
        System.out.println(genSign);
    }
}

main方法执行输出

accessToken=1b56814f081c432cb82751be145261d3&clientId=fe73489a9b5948dbafd07e7b28d6e268&method=post&nonce=14&timestamp=1692889556000&url=/api/order/get&userId=8

9bc08ba7552c5dfea4efab6bda78a4a9738010913f2403bd93f09c6bf974b939

4、调用接口示例：

请求链接
https://test.jfwms.com/api/order/get

请求头

clientId:fe73489a9b5948dbafd07e7b28d6e268
accessToken:1b56814f081c432cb82751be145261d3
timestamp:1692889556000
nonce:14
sign:9bc08ba7552c5dfea4efab6bda78a4a9738010913f2403bd93f09c6bf974b939
userId:8

请求体
{"erpNo":"123"}

{
    "code": 50017,
    "message": "The order was not found in the warehouse!",
    "data": null,
    "requestId": "7bb5ddef9aed415a88163e5d39b41691"
}

五、常见报错

SUCCESS(0, "SUCCESS"),
SERVICE_ERROR(1, "服务异常，请稍后重试"),

REQUEST_PARAMS_LACK(10000, "The request lacks necessary parameters"),
REQUEST_PARAMS_ERROR(10001, "Request parameter error"),
INVALID_ACCESS_TOKEN(10002, "Invalid ACCESS TOKEN "),
INVALID_REFRESH_TOKEN(10003, "Invalid REFRESH TOKEN"),
ACCESS_TOKEN_CANNOT_NULL(10004, "ACCESS TOKEN empty"),
REFRESH_TOKEN_CANNOT_NULL(10005, "REFRESH TOKEN empty"),
CLIENT_ID_CANNOT_NULL(10006, "CLIENT ID empty"),
CLIENT_SECRET_CANNOT_NULL(10007, "CLIENT SECRET empty"),
CLIENT_APP_NOT_FIND_OR_INVALID(10008, "Invalid client app info"),
CANNOT_FIND_APP_AUTH_INFO(10009, "Invalid client auth info"),
NOT_INT_WRITE_LIST(10010, "Request ip not in whitelist"),
REQUEST_EMAIL_ERROR(10011, "could not find any user by the email"),
REQUEST_PASSWORD_ERROR(10012, "wrong password"),
REQUEST_DOMAIN_ERROR(10013, "could not find domain info"),
REQUEST_APP_ERROR(10014, "could not find valid app info"),

USER_ID_CANNOT_NULL(10020, "USER ID 不能为空"),
SIGN_CANNOT_NULL(10021, "SIGN 不能为空"),
NONCE_CANNOT_NULL(10022, "NONCE 不能为空"),
TIMESTAMP_CANNOT_NULL(10023, "TIMESTAMP 不能为空"),
NONCE_FORMAT_ERROR(10024, "NONCE 格式异常"),
TIMESTAMP_FORMAT_ERROR(10025, "TIMESTAMP 格式异常"),
SIGN_ERROR(10026, "签名错误"),
REPEAT_SUBMIT(10027, "重复提交"),
TIMESTAMP_INVALID(10028, "时间戳失效"),
USER_ID_FORMAT_ERROR(10029, "USER ID 格式异常"),

// 授权识别码失效
INVALID_AUTH_CODE(10030, "Invalid authorization identification code"),

// OMS账号已被停用，请联系仓库
OMS_ACCOUNT_DISABLE(10040, "OMS account has been deactivated, please contact the warehouse"),
// 未识别到仓库，请联系仓库！
OMS_WAREHOUSE_NOT_EXIST(10041, "Warehouse not identified, please contact the warehouse"),
// 仓库状态已关闭，请联系仓库！
OMS_USER_WAREHOUSE_CLOSED(10042, "The warehouse status has been closed, please contact the warehouse!"),
// 仓库必填
OMS_WAREHOUSE_NO_EMPTY(10043, "warehouse is required"),
// 仓库已暂停收货，请联系仓库
OMS_WAREHOUSE_PROHIBIT_RECEIVE(10044, "The warehouse has suspended receiving goods. Please contact the warehouse"),
// 仓库尚未为您分配计费方案，请联系仓库！
OMS_FEE_TEMPLATE_NOT_EXIST(10045, "The warehouse has not yet assigned a billing plan for you. Please contact the warehouse!"),
// 单据中部分商品在仓库中不存在，请先推送商品！
OMS_SKU_NOT_EXIST(10046, "Some products in the document do not exist in the warehouse. Please push the products first!"),
// XXXX已被仓库设置禁收，请联系仓库！
OMS_SKU_PROHIBIT_RECEIVE(10047, "sku(%s) has been banned by the warehouse. Please contact the warehouse!"),
// 仓库已暂停接单，请联系仓库！
OMS_WAREHOUSE_PROHIBIT_SALE(10048, "The warehouse has suspended receiving orders, please contact the warehouse!"),
// 创建失败！您已欠费，请登录OMS系统充值或联系仓库
OMS_INSUFFICIENT_EXPENSES(10049,"Creation failed! You are in arrears. Please log in to the OMS system to recharge or contact the warehouse"),

// 商品SKU必填
MERCHANT_SKU_NO_EMPTY(20000, "sku is required"),
// 商品名称必填
MERCHANT_SKU_NAME_EMPTY(20001, "sku name is required"),
// 商品条码必填
MERCHANT_SKU_CODE_EMPTY(20002, "customer sku no name is required"),
// 商品SKU（XXXXXX）已存在
MERCHANT_SKU_IS_EXIST(20003, "sku(%s) is exist"),
// 商品条码（XXXXXX）已存在
MERCHANT_SKU_CODE_EXIST(20004, "customer sku no(%s) is exist"),
// 长宽高必须同时填写
MERCHANT_LENGTH_WIDTH_HEIGHT_ERROR(20005, "Length, width, and height must be filled in simultaneously"),
// 商品名称(商品条码)最多200（50）字符
MERCHANT_NAME_NO_LENGTH_ERROR(20006, "Product name (barcode) with a maximum of 200 (50) characters"),
// 商品SKU不存在
MERCHANT_SKU_NOT_EXIST(20007, "sku is not exist"),
// （单位g）:0.01-999.99
MERCHANT_WEIGHT_RANGE(20008, "weight range：0.01g-999999.99g"),
// 尺寸（cm）：0.01-999999.99
MERCHANT_SIZE_RANGE(20009, "size range：”0.01cm-999999.99cm"),

// 在仓库系统中未找到对应的商品
INVENTORY_SKU_NOT_EXIST(30001, "No corresponding product was found in the warehouse system"),

// ERP单号必填
INBOUND_ERP_NO_EMPTY(40000, "erp no is required"),
// ERP单号已存在
INBOUND_ERP_NO_EXIST(40001, "erp no is exist"),
// 商品必填
INBOUND_SKU_INFO_EMPTY(40002, "sku is required"),
// 商品数量必填
INBOUND_SKU_COUNT_EMPTY(40003, "sku count is required"),
// 在仓库系统中未找到入库单！
INBOUND_NOT_EXIST(40004, "No receipt found in the warehouse system!"),
// 当前状态(XXX)不允许取消入库单
INBOUND_STATUS_COUNT_NOT_CANCEL(40005, "The current status (%s) does not allow cancellation of the receipt order"),

// 面单必填
OT_LABEL_URL_EMPTY(50000, "label url is required"),
// 面单最多2048字符！
OT_LABEL_URL_TOO_LONG(50001, "label url up to 2048 characters"),
// 收件人(国家/地区)必填
OT_RECIPIENT_COUNTRY_EMPTY(50002, "recipient country is required"),
// ERP单号必填
OT_ERP_NO_EMPTY(50003, "erp no is required"),
// 物流名称必填
OT_LOGISTICS_NAME_EMPTY(50004, "logistics name is required"),
// 运单号必填
OT_TRACKING_NO_EMPTY(50005, "tracking no is required"),
// 详细地址最多300字符！
OT_RECIPIENT_ADDRESS_TOO_LONG(50006, "recipient address up to 300 characters"),
// 暂不支持该国家，或国家需要传二字码
OT_COUNTRY_CODE_ERROR(50007, "The country is currently not supported, or the country needs to transmit a two character code"),
// erp单号最多100字符！
OT_ERP_NO_TOO_LONG(50008, "erp no up to 100 characters"),
// 平台订单号最多100字符！
OT_PLATFORM_ORDER_NO_TOO_LONG(50009, "erp no up to 100 characters"),
// 卖家姓名最多100字符！
OT_BUYER_NAME_TOO_LONG(50010, "buyer name up to 100 characters"),
// 手机号最多100字符！
OT_BUYER_PHONE_TOO_LONG(50011, "buyer phone up to 100 characters"),
// 收件人(省/州)最多100字符！
OT_RECIPIENT_PROVINCE_TOO_LONG(50012, "recipient province up to 100 characters"),
// 收件人(市/县)最多100字符！
OT_RECIPIENT_CITY_TOO_LONG(50013, "recipient city up to 100 characters"),
// 邮编最多100字符！
OT_ZIP_CODE_TOO_LONG(50014, "zip code up to 100 characters"),
// 物流名称最多100字符！
OT_LOGISTICS_NAME_TOO_LONG(50015, "logistics name up to 100 characters"),
// 运单号最多100字符！
OT_TRACKING_NO_TOO_LONG(50016, "tracking no up to 100 characters"),
// 在仓库中未找到该订单！
OT_ORDER_NOT_EXIST(50017, "The order was not found in the warehouse!"),
// 订单已发货，请联系物流拦截
OT_ORDER_STATUS_COUNT_NOT_CANCEL(50018, "The order has been shipped, please contact logistics interception"),
// ERP单号已存在
OT_ORDER_ERP_NO_EXIST(50019, "ERP order number already exists"),
// 物流不存在，请联系仓库
OT_LOGISTICS_NOT_EXIST(50020, "Logistics does not exist, please contact the warehouse"),
// 物流方式未启用
OT_LOGISTICS_CLOSED(50021, "Logistics method not enabled"),
// 商品必填
OT_SKU_EMPTY(50022, "sku is required"),
// 商品数量异常
OT_SKU_NUM_ERROR(50023, "sku num error"),
// 商品SKU: XXXX、XXXX在仓库中不存在，请先推送商品！
OT_SKU_NUM_NOT_EXIST(50024, "Product SKU: %s do not exist in the warehouse, please push the product first!"),
// 物流不能够发到收件国家
OT_LOGISTICS_SHIP_COUNTRY_ERROR(50025, "Logistics cannot be sent to the recipient country"),
// 库存不足，请检查！
OT_SKU_NOT_ENOUGH_STOCK(50026, "Not enough stock,Please check!"),
// 订单已取消
OT_ORDER_IS_CANCELED(50027, "Order cancelled"),
// 一次性最多查询100条数据
OT_ORDER_query_max(50028,"Query up to 100 pieces of data at once"),
// 仓库不允许截单，截单失败
MERCHANT_ORDER_INTERCEPT_ERROR(20022,"The warehouse does not allow interception of orders, interception of orders failed!"),
// 截单已申请，仓库审核中
MERCHANT_ORDER_INTERCEPT_APPLY(20023,"Order interception has been applied and is under review by the warehouse!"),

API使用说明

一、WMS用户新建开发者#

二、授权#

1、获取授权码#

2、通过授权码获取accessToken、refreshToken、userId等授权信息#

3、刷新accessToken#

三、Webhook#

WebHook数据格式#

Webhook响应数据格式#

Webhook签名#

四、调用业务接口#

1、所有业务接口请求方式均为post，业务请求参数均以JSON格式放在请求体中#

2、请求头中必须带有以下公共参数#

3、签名生成方式#

计算签名方法工具类：#

4、调用接口示例：#

五、常见报错#