# Webhook 机制

# 介绍

webhook 是一种消息回调机制，包括：商品、变体、库存、订单的任何改动的消息通知，主要用于实时同步

建议：建议接收到消息后，再查询一次接口详情，确认变更

要求: 请求方法： POST

参数名称	参数意义	参数类型	是否必传	备注
code	状态码	int	是	成功200
result	处理结果	string	是	success=成功, 其他=fail
message	处理结果消息	string	是	具体消息内容

# 对接步骤

1）设置消息监听，参考消息设置接口
2）客户端设置监听接口，试例如下（Java 语言）
3）测试监听，处理业务逻辑

# 消息

# 商品消息

# 接收到的商品消息体

{
    "messageId": "ca72a4834cd14b9588e88ce206f614a0",
    "type": "PRODUCT",
    "openId": 12312,
    "params": {
        "categoryId": null,
        "categoryName": null,
        "pid": "1424608189734850560",
        "productDescription": "xxxxxx",
        "productImage": null,
        "productName": null,
        "productNameEn": null,
        "productProperty1": null,
        "productProperty2": null,
        "productProperty3": null,
        "productSellPrice": null,
        "productSku": null,
        "productStatus": null,
        "fields" : [
            "productDescription"
        ],
    }
}

参数名称	参数意义	参数类型	是否必传	长度	备注
messageId	商品消息 Id	string	Y	200	Message Id
type	商品消息 type	string	Y	200	PRODUCT，VARIANT
params		object	Y	5
categoryId	商品品种 Id	string	Y	200
categoryName	商品品种名称	string	Y	200
pid	商品 id	string	Y	200
productDescription	商品详情	string	Y	2000
productImage	商品照片	string	Y	200
productName	商品名称	string	Y	200
productNameEn	商品名称(英文名)	string	Y	200
productProperty1	商品属性1	string	Y	200
productProperty2	商品属性2	string	Y	200
productProperty3	商品属性3	string	Y	200
productSellPrice	商品售价	double	Y	20
productSku	商品 sku	string	Y	200
productStatus	商品消息状态	int	Y	5	status:2-offline, 3-delete
fields	修改字段列表	list	Y	5

# 接收到的变体消息

{
    "messageId": "7cceede817dc47ed9748328b64353c5c",
    "type": "VARIANT",
    "openId": 12312,
    "params": {
        "vid": "1424608152007086080",
        "variantName": null,
        "variantWeight": null,
        "variantLength": null,
        "variantWidth": null,
        "variantHeight": null,
        "variantImage": null,
        "variantSku": null,
        "variantKey": null,
        "variantSellPrice": null,
        "variantStatus": null,
        "variantValue1": null,
        "variantValue2": null,
        "variantValue3": null,
        "fields" : [
            "variantLength"
        ],
    }
}

参数名称	参数意义	参数类型	是否必传	长度	备注
messageId	变体消息 Id	string	Y	200	Message Id
type	变体消息 type	string	Y	200	PRODUCT，VARIANT
params		object	Y	5
vid	变体 Id	string	Y	200
pid	商品 id	string	Y	200
variantName	变体名称	string	Y	200
variantWeight	变体重量	int	Y	200
variantLength	变体长度	int	Y	2000
variantWidth	变体宽度	int	Y	200
variantHeight	变体高度	int	Y	200
variantImage	变体名称(英文名)	string	Y	200
variantSku	变体 sku	string	Y	200
variantKey	变体关键字	string	Y	200
variantSellPrice	变体售价	double	Y	200
variantStatus	变体状态	int	Y	5
variantValue1	变体属性1	string	Y	200
variantValue2	变体属性2	string	Y	200
variantValue3	变体属性3	string	Y	200
fields	修改字段列表	list	Y	5

# 库存消息

{
    "messageId": "ca72a4834cd14b9588e88ce206f614a0",
    "type": "STOCK",
    "openId": 12312,
    "params": {
        "1424608152007086080": [
            {
                "vid": "1424608152007086080",
                "pid": "123890023"
                "areaId": "2",
                "areaEn": "US Warehouse",
                "countryCode": "US",
                "storageNum": 12
            }
        ],
        "AE7DB9BC-4290-4C85-B8A6-F8957F3DB053": [
            {
                "vid": "AE7DB9BC-4290-4C85-B8A6-F8957F3DB053",
                 "pid": "123890023"
                "areaId": "2",
                "areaEn": "US Warehouse",
                "countryCode": "US",
                "storageNum": 1
            }
        ]
    }
}

# 接收到的物流轨迹变更消息

{
    "messageId": "7cceede817dc47ed9748328b64353c5c",
    "type": "LOGISTIC",
    "openId": 12312,
    "params": {
        "orderId": "123",
        "trackingNumber": "CJPKL7160102171YQ",
        "logisticName": "CJPacket Sensitive",
        "trackingStatus": 0,
        "logisticsTrackEvents": "[{"activity": "The electronic information of the waybill has been received.", "eventTime": "2021-10-28 21:17:18", "thirdActivity": "运单电子信息已收到", "thirdEventTime": "2021-10-28 21:17:18"}]",
}

参数名称	参数意义	参数类型	是否必传	长度	备注
messageId	物流消息 Id	string	Y	200	Message Id
type	物流消息 type	string	Y	200
params		object	Y	5
orderId	cj订单Id	string	Y	200
trackingNumber	追踪单号	string	Y	200
trackingStatus	追踪单状态	integer	Y	20
logisticsTrackEvents	追踪信息events事件信息	string	Y	200	[{"activity": "The electronic information of the waybill has been received.", "eventTime": "2021-10-28 21:17:18", "thirdActivity": "运单电子信息已收到", "thirdEventTime": "2021-10-28 21:17:18"}]

# 接收到的纠纷变更消息

{
    "messageId": "7cceede817dc47ed9748328b64353c5c",
    "type": "DISPUTES",
    "openId": 12312,
    "params": {
        "orderId": "123",
        "status": 
    }
}

参数名称	参数意义	参数类型	是否必传	长度	备注
messageId	变体消息 Id	string	Y	200	Message Id
type	变体消息 type	string	Y	200
params		object	Y	5
orderId	订单 Id	string	Y	200
status	纠纷状态	string	Y	20

status状态值

参数名称	参数意义
1	新增纠纷
2	完成纠纷
3	取消纠纷

# 接收到的工单变更消息

{
    "messageId": "7cceede817dc47ed9748328b64353c5c",
    "type": "TICKET",
    "openId": 12312,
    "params": {
        "orderId": "123",
        "status": 
    }
}

参数名称	参数意义	参数类型	是否必传	长度	备注
messageId	工单消息 Id	string	Y	200	Message Id
type	工单消息 type	string	Y	200
params		object	Y	5
orderId	订单号	string	Y	200
status	工单状态	string	Y	20

status状态值

参数名称	参数意义
1	新增
2	已完成
3	已取消

# 接收到的订单变更消息

{
    "messageId": "7cceede817dc47ed9748328b64353c5c",
    "type": "TICKET",
    "params": {
        "orderNum": "api_52f268d40b8d460e82c0683955e63cc9",
        "cjOrderId": 210823100016290555,
        "orderStatus": "CREATED",
        "logisticName": "CJPacket Ordinary",
        "trackNumber": null,
        "createDate": "2021-08-23 11:31:45",
        "updateDate": "2021-08-23 11:31:45",
        "payDate": null,
        "deliveryDate": null
    }
}

返回字段	字段意思	字段类型	长度	备注
cjOrderId	CJ订单ID	string	200
orderNum	订单号	string	200
orderStatus	订单状态	string	200	参考订单状态
logisticName	物流名称	string	200
trackNumber	物流编号	string	200
postage	运费	BigDecimal	（18，2）	单位：$（美元）
updateDate	更新时间	string	200
createDate	创建时间	string	200
payDate	支付时间	string	200
deliveryDate	发货时间	string	200

# 接收到的订单拆单变更消息

{
    "messageId": "7cceede817dc47ed9748328b64353c5c",
    "type": "ORDERSPLIT",
    "params": {
        "originalOrderId": "原订单",
        "splitOrderList": [
            {
                "createAt":1673490845706,
                "orderCode":"SD1613355441583259648-2",
                "orderStatus":300,
                "productList":[
                {
                    "sku":"CJNSSYLY01043-Claret-S",
                    "vid":"2547992D-CEE1-4BFD-99AC-9E30354F771F",
                    "quantity":1,
                    "productCode":"1613355657229205504"
                },
                {
                    "sku":"CJJSAQXF00016-Orange",
                    "vid":"A9C95BCB-D824-4AA1-A389-E86F3CCB10EF",
                    "quantity":1,
                    "productCode":"1613355657229205506"
                },
                {
                    "sku":"CJNSSYCS03214-Photo Color-XXL",
                    "vid":"E5FED43E-F9DE-483F-ADCE-8C95D3380315",
                    "quantity":1,
                    "productCode":"1613355657229205507"
                }
                ]
            },
            {
                "createAt":1673490845706,
                "orderCode":"SD1613355441583259648-1",
                "orderStatus":300,
                "productList":[
                    {
                        "sku":"CJNSSYLY01043-White-M",
                        "vid":"0550DFC6-7FF7-4662-AE7D-B4DF0E4EB24A",
                        "quantity":1,
                        "productCode":"1613355657229205505"
                    }
                ]
            }
        ],
        "orderSplitTime": "拆单时间"
    }
}

返回字段	字段意思	字段类型	长度
originalOrderId	原订单号	string	200
splitOrderList	拆单列表	list
orderCode	拆单后的订单id	string	200
createAt	拆单时间	string	200
orderStatus	订单状态	int	11
productList	商品信息列表	list	200
productCode	商品code	string	200
vid	变体id	string	200
quantity	数量	int	10
sku	sku	string	200
orderSplitTime	拆单时间	string	200

# 接收到的纠纷变更消息（新）

{
    "messageId": "7cceede817dc47ed9748328b64353c5c",
    "type": "DISPUTE",
    "messageType": "insert/update/delete",
    "params": {
        "disputeId": "123",
        "orderId": "210823100016290555",
        "orderNumber": "api_52f268d40b8d460e82c0683955e63cc9",
        "status": "",
        "refuseReason": "ftdsr",
        "refundAmount": "123",
        "totalAmount": "123",
        "disputeType": "1",
        "reissueOrderId": "123",
        "trackingNumber": "123",
        "lineItems": [
            {
                "lineItemId": "lineItemId",
                "productId": "商品id",
                "variantId": "变体id",
                "sku"："sku",
                "price": 价格,
                "quantity": "数量"
            }
        ]
    }
}

返回字段	字段意思	字段类型	长度	备注
orderId	CJ订单ID	string	200
orderNumber	客户订单号	string	200
disputeId	纠纷Id	string	200
shippingProvince	交易省份	string	200
status	状态	string	200	(新增，取消，拒绝，同意退款，同意补发，完成)
refuseReason	拒绝原因	string	500
refundAmount	退款金额	BigDecimal	（18，2）	单位：$（美元）
totalAmount	总金额	BigDecimal	（18，2）	单位：$（美元）
disputeType	纠纷类型	BigDecimal	（18，2）	单位：$（美元）
reissueOrderId	补发单号	string	100	参考订单状态
trackingNumber	补发追踪号	string	100
productInfoList	商品信息	Object[]
productCode	商品code	string	200
productId	商品id	string	200
variantId	变体id	string	200
price	商品价格	BigDecimal	（18，2）	单位：$（美元）
quantity	数量	integer	100
sku	sku	string	100

状态	值
新增纠纷	1
取消纠纷	2
拒绝纠纷	3
同意退款	4
同意补发	5
完成纠纷	6

# 接收到的搜品创建结果消息

{
    "messageId": "7cceede817dc47ed9748328b64353c5c",
    "type": "SOURCINGCREATE",
    "params": {
        "cjProductId":"0550DFC6-7FF7-4662-AE7D-B4DF0E4EB24A",
        "cjVariantId":"0550DFC6-7FF7-4662-AE7D-B4DF0E4EB24A",
        "cjVariantSku":"CJ123582565212",
        "cjSourcingId":"125522",
        "status": "completed"
        "failReason":"",
        "createDate": "2023-02-07 00:00:00"    】
    }
}

返回字段	字段意思	字段类型	长度
cjProductId	商品id	string	100
cjVariantId	变体id	list	100
cjVariantSku	cj变体sku	string	50
cjSourcingId	搜品任务id	string	50
status	创建结果状态	string	20
failReason	失败原因	string	20
createDate	创建时间	String	50

# 示例

# 商品消息接收示例

package com.cj.cn.controller;

import com.alibaba.fastjson.JSON;
import com.cj.cn.constant.callback.domain.CallbackParams;
import com.cj.cn.util.result.Result;
import lombok.extern.slf4j.Slf4j;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * CJ webhook 监听示例
 *
 * @author : kay
 */
@RestController
@RequestMapping("/webhookListener")
@Slf4j
public class TestController {

    @PostMapping("/productMessage")
    public Result productMessage(@RequestBody @Validated CallbackParams query) {
        log.info("product message:{}", JSON.toJSONString(query));
        return Result.success(Boolean.TRUE);
    }
}

package com.cj.cn.constant.callback.domain;

import lombok.Data;

/**
 * @author : kay
 */
@Data
public class CallbackParams {
    private String messageId;
    private String type;
    private Object params;
}

package com.cj.cn.constant.callback.domain;

import lombok.Getter;
import org.springframework.util.StringUtils;

/**
 * @author : kay
 */
@Getter
public enum CallbackBusinessTypeEnum {
    PRODUCT,
    VARIANT,
    STOCK;

    public static CallbackBusinessTypeEnum create(String name) {
        if (!StringUtils.isEmpty(name)) {
            for (CallbackBusinessTypeEnum typeEnum: CallbackBusinessTypeEnum.values()) {
                if (typeEnum.name().equals(name.toUpperCase())) {
                    return typeEnum;
                }
            }
        }
        return null;
    }
}

← 实用工具沙盒机制 →