# 8 消息
# 1 设置
# Webhook配置要求
# 一、协议要求
- 支持协议: HTTPS
- 加密要求: 建议使用 TLS 1.2 或 TLS 1.3 进行安全传输
- 请求方法: POST
- 内容类型:
Content-Type: application/json
# 二、响应规范
- 成功状态码:
200 OK - 响应超时时间: 3秒
(请避免在接收端执行耗时的业务逻辑,确保快速响应) - 地址校验: 监听地址必须使用公网
HTTPS地址,不能使用localhost、127.0.0.1等本地地址 - 失败信息: 当地址校验失败时,
message会直接返回具体失败原因,便于排查
# 1.1 监听设置(POST)
消息监听,监听设置
# URL
https://developers.cjdropshipping.com/api2.0/v1/webhook/set
# CURL
curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/webhook/set' \
--header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
"product": {
"type": "ENABLE",
"callbackUrls": [
"https://your-host/api2.0/"
]
},
"stock": {
"type": "ENABLE",
"callbackUrls": [
"https://your-host/api2.0/"
]
},
"order": {
"type": "ENABLE",
"callbackUrls": [
"https://your-host/api2.0/"
]
},
"logistics": {
"type": "ENABLE",
"callbackUrls": [
"https://your-host/api2.0/"
]
},
"makeup": {
"type": "ENABLE",
"callbackUrls": [
"https://your-host/api2.0/"
]
},
"privateOrder": {
"type": "ENABLE",
"callbackUrls": [
"https://your-host/api2.0/"
]
},
"dispute": {
"type": "ENABLE",
"callbackUrls": [
"https://your-host/api2.0/"
]
},
"wallet": {
"type": "ENABLE",
"callbackUrls": [
"https://your-host/api2.0/"
]
}
}'
| 参数名称 | 参数意义 | 参数类型 | 是否必传 | 长度 | 备注 |
|---|---|---|---|---|---|
| product | 商品消息 | object | 是 | 200 | 商品消息设置 |
| - type | 监听类型 | string | 是 | 200 | ENABLE-启用,CANCEL-取消 |
| - callbackUrls | 监听接口 | string[] | 是 | 只支持单个监听,且必须为可访问的公网 HTTPS 地址 | |
| stock | 库存消息 | object | 是 | 200 | 库存消息设置 |
| - type | 监听类型 | string | 是 | 200 | ENABLE-启用,CANCEL-取消 |
| - callbackUrls | 监听接口 | string[] | 是 | 只支持单个监听,且必须为可访问的公网 HTTPS 地址 | |
| order | 订单消息 | object | 是 | 200 | 订单消息设置 |
| - type | 监听类型 | string | 是 | 200 | ENABLE-启用,CANCEL-取消 |
| - callbackUrls | 监听接口 | string[] | 是 | 只支持单个监听,且必须为可访问的公网 HTTPS 地址 | |
| logistics | 物流轨迹消息 | object | 是 | 200 | 物流消息设置 |
| - type | 监听类型 | string | 是 | 200 | ENABLE-启用,CANCEL-取消 |
| - callbackUrls | 监听接口 | string[] | 是 | 只支持单个监听,且必须为可访问的公网 HTTPS 地址 | |
| makeup | 补款单消息 | object | 否 | 200 | 补款单消息设置(添加/取消/支付成功通知) |
| - type | 监听类型 | string | 是 | 200 | ENABLE-启用,CANCEL-取消 |
| - callbackUrls | 监听接口 | string[] | 是 | 只支持单个监听,且必须为可访问的公网 HTTPS 地址 | |
| privateOrder | 私有订单消息 | object | 否 | 200 | 私有订单(SY单/私有库存单)消息设置(状态变更通知) |
| - type | 监听类型 | string | 是 | 200 | ENABLE-启用,CANCEL-取消 |
| - callbackUrls | 监听接口 | string[] | 是 | 只支持单个监听,且必须为可访问的公网 HTTPS 地址 | |
| dispute | 纠纷消息 | object | 否 | 200 | 纠纷消息设置(新建/取消/拒绝/退款完成/同意补发通知) |
| - type | 监听类型 | string | 是 | 200 | ENABLE-启用,CANCEL-取消 |
| - callbackUrls | 监听接口 | string[] | 是 | 只支持单个监听,且必须为可访问的公网 HTTPS 地址 | |
| wallet | 钱包通知 | object | 否 | 钱包账单流水通知设置(新增流水、金额或状态变化),只能给当前取 token 的账号订阅;建议单独用一次请求设置(与其它主题放在同一请求时,钱包这项出错可能让整个请求失败,也可能只保存了一部分),见下文「6 钱包通知(Wallet)」 | |
| - type | 监听类型 | string | 是 | 20 | ENABLE-启用,CANCEL-取消 |
| - callbackUrls | 监听接口 | string[] | 是 | 只支持单个监听,且必须为可访问的公网 HTTPS 地址;取消时也要填 |
纠纷消息(dispute)的覆盖范围与查询接口不同
纠纷消息只推送能关联到店铺的订单所产生的纠纷。而 查询纠纷会话 / 回复纠纷 两个接口覆盖的是你账号名下的全部纠纷。
因此可能出现:某个纠纷用 API 查得到、也回复得了,但收不到它的 webhook 推送。这是预期行为, 不是推送故障。请勿把 webhook 当作纠纷的完整清单,务必配合纠纷列表接口做定期核对。
另外,客服追加一条回复不会触发本消息——本消息只在纠纷状态变化时推送。若需感知"对方回复了",
请使用纠纷列表返回的 updateDate 字段。
# 返回
success
{
"code": 200,
"result": true,
"message": "Success",
"data": true,
"requestId": "97367e0f-cf3a-4c9b-acea-a36fb56f81b8",
"success": true
}
| 返回字段 | 字段意思 | 字段类型 | 长度 | 备注 |
|---|---|---|---|---|
| code | 错误码 | int | 20 | 返回错误码标准表 |
| result | 是否正常返回 | boolean | 1 | |
| message | 返回信息 | string | 200 | |
| data | 是否设置成功 | boolean | 1 | 接口数据返回 |
| requestId | 请求Id | string | 48 | 用于日志查询错误 |
| success | 是否调用成功 | boolean | 1 | true-成功,false-失败 |
error
{
"code": 1607001,
"result": false,
"message": "Please do not use domain names such as localhost, 127.0.0.1",
"data": null,
"requestId": "a18c9793-7c99-42f9-970b-790eecdceba2",
"success": false
}
| 返回字段 | 字段意思 | 字段类型 | 长度 | 备注 |
|---|---|---|---|---|
| code | 错误码 | int | 20 | 返回错误码标准表 |
| result | 是否正常返回 | boolean | 1 | |
| message | 返回信息 | string | 200 | |
| data | 接口数据返回 | |||
| requestId | 请求Id | string | 48 | 用于日志查询错误 |
| success | 是否调用成功 | boolean | 1 | true-成功,false-失败 |
# 2 商品订阅
# 2.1 订阅商品(POST)
订阅指定商品或开启全部商品订阅,用于商品/变体/库存的webhook通知。
注意:订阅指定商品和订阅全部商品互斥。
- 如果传入
productIds,则只订阅指定商品,系统会自动取消全部商品订阅。- 如果只传
subscribeAll=true(不传productIds),则历史订阅的指定商品将被清空。
subscribeAll 限制
- 2026年7月份之前,仅 2026年6月份之前注册 的用户可以订阅所有商品(
subscribeAll=true) - 2026年7月份之后,所有用户均不可订阅所有商品,必须指定具体商品 ID 进行订阅
# URL
https://developers.cjdropshipping.com/api2.0/v1/webhook/product/subscribe
# CURL
curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/webhook/product/subscribe' \
--header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
"productIds": ["1952652478987366401", "1952652478987366402"],
"subscribeAll": false
}'
| 参数名称 | 参数意义 | 参数类型 | 是否必传 | 长度 | 备注 |
|---|---|---|---|---|---|
| productIds | 商品ID列表 | string[] | 否 | 最大100 | 要订阅的商品ID,不能超过用户等级对应的订阅上限 |
| subscribeAll | 订阅全部商品 | boolean | 否 | true=开启全部商品订阅,false=关闭。与productIds互斥 |
# 返回
success
{
"code": 200,
"result": true,
"message": "Success",
"data": {
"successProductIds": ["1952652478987366401"],
"failProductIds": ["1952652478987366402"],
"subscribeAll": false
},
"requestId": "97367e0f-cf3a-4c9b-acea-a36fb56f81b8",
"success": true
}
| 返回字段 | 字段意思 | 字段类型 | 长度 | 备注 |
|---|---|---|---|---|
| code | 错误码 | int | 20 | 返回错误码标准表 |
| result | 是否正常返回 | boolean | 1 | |
| message | 返回信息 | string | 200 | |
| data | 返回数据 | object | ||
| - successProductIds | 订阅成功的商品ID列表 | string[] | ||
| - failProductIds | 订阅失败的商品ID列表(已订阅、不存在等原因) | string[] | ||
| - subscribeAll | 是否开启全量订阅 | boolean | 仅当请求中subscribeAll有值时返回 | |
| requestId | 请求Id | string | 48 | 用于日志查询错误 |
| success | 是否调用成功 | boolean | 1 | true-成功,false-失败 |
error
{
"code": 1606010,
"result": false,
"message": "Product webhook is not enabled",
"data": null,
"requestId": "a18c9793-7c99-42f9-970b-790eecdceba2",
"success": false
}
错误码说明:
| 错误码 | 说明 |
|---|---|
| 1606010 | 商品webhook未开启 |
| 1606011 | 超过订阅上限 |
| 1606012 | 商品不可订阅 |
| 1606013 | 商品订阅失败 |
各等级订阅上限:
| 等级 | 最大订阅数 |
|---|---|
| lv1 | 1000 |
| lv2 | 2000 |
| lv3 | 3000 |
| lv4 | 5000 |
| lv5 | 10000 |
# 2.2 取消订阅商品(POST)
从订阅列表中移除指定商品。
# URL
https://developers.cjdropshipping.com/api2.0/v1/webhook/product/unsubscribe
# CURL
curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/webhook/product/unsubscribe' \
--header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
"productIds": ["1952652478987366401", "1952652478987366402"]
}'
| 参数名称 | 参数意义 | 参数类型 | 是否必传 | 长度 | 备注 |
|---|---|---|---|---|---|
| productIds | 商品ID列表 | string[] | 是 | 最大100 | 要取消订阅的商品ID |
# 返回
success
{
"code": 200,
"result": true,
"message": "Success",
"data": true,
"requestId": "97367e0f-cf3a-4c9b-acea-a36fb56f81b8",
"success": true
}
| 返回字段 | 字段意思 | 字段类型 | 长度 | 备注 |
|---|---|---|---|---|
| code | 错误码 | int | 20 | 返回错误码标准表 |
| result | 是否正常返回 | boolean | 1 | |
| message | 返回信息 | string | 200 | |
| data | 是否成功 | boolean | 1 | true=成功 |
| requestId | 请求Id | string | 48 | 用于日志查询错误 |
| success | 是否调用成功 | boolean | 1 | true-成功,false-失败 |
# 2.3 查询已订阅商品(GET)
分页查询当前用户已订阅的商品列表。
# URL
https://developers.cjdropshipping.com/api2.0/v1/webhook/product/subscribe/list
# CURL
curl --location --request GET 'https://developers.cjdropshipping.com/api2.0/v1/webhook/product/subscribe/list?pageNum=1&pageSize=20&sku=CJJJJTJT00784&shopId=123456' \
--header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxx'
| 参数名称 | 参数意义 | 参数类型 | 是否必传 | 长度 | 备注 |
|---|---|---|---|---|---|
| pageNum | 页码 | int | 否 | 默认:1,最小:1 | |
| pageSize | 每页条数 | int | 否 | 默认:20,最小:1,最大:200 | |
| sku | 商品SPU | string | 否 | 21 | 可选,按SPU搜索 |
| productId | 商品ID | string | 否 | 50 | 可选,按商品ID筛选 |
| shopId | 店铺ID | string | 是 | 必须是你自己的店铺(或授权给你的店铺)。他人的店铺、不存在的店铺都返回 1600006 |
# 返回
success
{
"code": 200,
"result": true,
"message": "Success",
"data": {
"pageSize": 20,
"pageNumber": 1,
"totalRecords": 50,
"totalPages": 3,
"content": [
{
"productId": "1952652478987366401",
"sku": "CJJJJTJT00784",
"productName": "Wireless Bluetooth Headphone",
"productImage": "https://cdn.cjdropshipping.com/xxx.jpg",
"status": true,
"reason": null,
"createAt": "2026-04-01 10:30:00"
}
]
},
"requestId": "97367e0f-cf3a-4c9b-acea-a36fb56f81b8",
"success": true
}
| 返回字段 | 字段意思 | 字段类型 | 长度 | 备注 |
|---|---|---|---|---|
| code | 错误码 | int | 20 | 返回错误码标准表 |
| result | 是否正常返回 | boolean | 1 | |
| message | 返回信息 | string | 200 | |
| data | 返回数据 | object | 分页包装对象 | |
| - pageSize | 每页条数 | int | ||
| - pageNumber | 当前页码 | int | ||
| - totalRecords | 总记录数 | int | ||
| - totalPages | 总页数 | int | ||
| - content | 商品列表 | array | ||
| -- productId | 商品ID | string | 50 | |
| -- sku | 商品SPU | string | 21 | |
| -- productName | 商品名称 | string | ||
| -- productImage | 商品图片URL | string | ||
| -- status | 订阅状态 | boolean | true=生效,false=失效 | |
| -- reason | 失效原因 | string | 255 | 如 "Product delisted" |
| -- createAt | 订阅时间 | string | 格式:yyyy-MM-dd HH:mm:ss | |
| requestId | 请求Id | string | 48 | 用于日志查询错误 |
| success | 是否调用成功 | boolean | 1 | true-成功,false-失败 |
# 3 通知规则
# 3.1 商品/变体通知过滤
当商品或变体发生变更时,webhook通知根据用户的订阅配置进行过滤:
- 用户开启了
subscribeAllProducts=true→ 发送通知 - 用户订阅了该具体商品 → 发送通知
- 以上均不满足 → 跳过通知
# 3.2 库存通知过滤
库存变更通知遵循相同的商品订阅过滤规则。只有订阅了对应商品的用户才会收到库存变更通知。
# 3.3 自动关闭机制
- 每个Topic的webhook推送成功/失败次数按小时维度记录
- 如果前2个完整小时内,每个小时区间的成功率都低于80%(可配置),则该Topic的webhook将被自动关闭
- 被自动关闭的webhook需要手动重新激活
- 关闭原因会记录在系统中
# 3.4 私有库存出库单通知
私有库存出库单复用「订单消息(ORDER)」主题推送,开通订单 webhook 后即可收到,无需单独订阅:
- 创建私有库存出库单时即推送一条
messageType=INSERT消息(普通订单创建不推送 INSERT); - 后续状态/支付/发货等变更与普通订单一致按
UPDATE推送; - 消息体在订单消息
params中带privateOutboundOrder=true标识,普通订单为false; - 订单消息体字段详见入门-Webhook 机制 订单消息。
# 3.5 各主题(Topic)触发时机
下表按主题列出什么时候会收到推送。未列入的变更(内部字段、版本号、统计字段等)不会触发推送。
延迟合并
商品、变体、库存、物流采用延迟合并推送:同一条记录在合并窗口内的多次变更会合并成一条消息推送,而不是每改一次推一条。当前窗口为商品/变体约 2 分钟、库存/物流约 5 分钟(窗口时长属于服务端调优参数,可能调整,请勿依赖其精确值)。订单、补款单、私有订单、钱包为实时推送。
# product(商品)
| 触发节点 | type | messageType |
|---|---|---|
| 商品创建 | PRODUCT | INSERT |
| 商品关键字段变更,且变更后处于待上架/审核通过状态 | PRODUCT | UPDATE |
| 商品变更后不再处于待上架/审核通过状态(下架、审核不通过、删除等) | PRODUCT | DELETE |
| 变体创建 | VARIANT | INSERT |
| 变体关键字段变更,且变体处于上架状态 | VARIANT | UPDATE |
| 变体变更后非上架状态 | VARIANT | DELETE |
- 商品的「关键字段」指:类目、商品名称(中/英)、SKU、主图、售价、描述、上下架状态、属性 1/2/3、英文属性、供应商、商品类型、商品可见范围。只有这些字段变化才会推送;
params.fields会给出本次合并窗口内累计变更的字段名。 - 变体的「关键字段」指:变体英文名、长、宽、高、重量、图片、售价、规格值 1/2/3。
- 仅售价变化的变体变更暂不推送(价格之外没有任何其它关键字段同时变化时);商品侧平台批量改价活动引起的变更同样不推送。需要价格以查询接口为准。
- 数据库物理删除不产生推送;
DELETE表示"该商品/变体对你不再可售",不代表记录被删除。 - 是否推送还要先过商品订阅过滤(见 3.1)。
# stock(库存)
| 触发节点 | type | messageType |
|---|---|---|
| 变体库存记录新增,或库存数量发生变化 | STOCK | INCREASE |
| 变体库存记录被删除 | STOCK | REDUCE |
- 只有变体、商品、仓库、可用库存、实际库存这几项发生变化才触发。
messageType只表示事件来源(新增/更新 vs 删除),不代表库存增减方向;准确数量以消息体中各仓库的storageNum为准。- 是否推送还要先过商品订阅过滤(见 3.2)。
# order(订单)
| 触发节点 | type | messageType |
|---|---|---|
| 订单由不完整变为完整(对接成功) | ORDER | ORDER_CONNNECTED |
| 私有库存出库单创建 | ORDER | INSERT |
| 订单状态、支付状态、纠纷、支付时间、完成时间、运费、出库时间发生变更 | ORDER | UPDATE |
| 店铺订单的履约状态、生产状态、异常状态变更 | ORDER | UPDATE |
| 店铺订单的物流单号换单、人工重新推送 | ORDER | UPDATE |
- 普通订单创建时不推送,只有私有库存出库单创建才推送
INSERT(见 3.4)。 - 订单删除不推送。
# logistics(物流)
| 触发节点 | type | messageType |
|---|---|---|
| 物流轨迹记录首次生成 | LOGISTIC | INSERT |
物流单号、物流渠道、物流状态、轨迹事件、物流服务商(trackingProvider)发生变更 | LOGISTIC | UPDATE |
- 推送前置条件:订单号、物流状态、物流单号三者都已有值,缺一不推。
- 仅内部版本号变化不推送。
# makeup(补款单)、privateOrder(私有订单)、wallet(钱包)
这三个主题的触发时机见下文「4 补款单消息(Makeup)」「5 私有订单消息(PrivateOrder)」与「6 钱包通知(Wallet)」。
# 4 补款单消息(Makeup)
订阅后,补款单发生以下变化时推送到已注册的 makeup 回调地址:
| messageType | 触发时机 | params.status |
|---|---|---|
INSERT | 补款单创建(添加) | CREATED |
CANCEL | 补款单取消 | CANCELED |
PAID | 补款单支付成功(完成) | PAID |
# 4.1 消息体示例
{
"messageId": "f3c2a1d09e8b4c5da6b7c8d9e0f1a2b3",
"type": "MAKEUP",
"messageType": "PAID",
"params": {
"orderId": "BT2606061320024499900",
"relationOrderId": "SD2606060858539645300",
"payOrderId": "2605260000000001",
"amount": 12.35,
"reason": "Postage difference",
"type": 1,
"diffUseType": 0,
"status": "PAID",
"createDate": "2026-06-04 10:00:00",
"paymentDate": "2026-06-04 12:00:00"
}
}
单号说明:
orderId为补款单号,统一以BT开头(示例BT2606061320024499900),与补款列表orderCode一致;relationOrderId为本次补款关联的原 CJ 订单号(被补款的订单),类型随原订单而定(如私有库存出库单SD…、代发/直发订单等),可用其在订单查询接口反查原订单详情。
| 字段 | 类型 | 说明 |
|---|---|---|
| messageId | string | 消息唯一ID(消费方可用作幂等去重键) |
| type | string | 业务类型,补款单固定 MAKEUP |
| messageType | string | INSERT-添加 / CANCEL-取消 / PAID-支付成功 |
| params.orderId | string | 补款单号,BT 开头,与补款列表 orderCode 一致,示例 BT2606061320024499900 |
| params.relationOrderId | string | 关联的原 CJ 订单号(被补款订单),类型随原订单而定:私有库存出库单 SD…、代发/直发订单等,示例 SD2606060858539645300 |
| params.payOrderId | string | 补款支付单号(支付后返回) |
| params.amount | number | 补款金额,单位 USD |
| params.reason | string | 补款原因(英文) |
| params.type | int | 1=补款 |
| params.diffUseType | int | 0=订单补款 1=Balance Top-up 2=Repayment 3=Transfer Shipping Fee |
| params.status | string | CREATED / CANCELED / PAID |
| params.createDate | string | 创建时间 yyyy-MM-dd HH:mm:ss |
| params.paymentDate | string | 支付时间(PAID 时返回) |
# 4.2 验签
请求头携带 sign,算法:sign = Base64( HmacSHA256( secret = openId字符串, message = 请求体JSON原文 ) )。接收端用自己的 openId 作为密钥对原始请求体计算 HmacSHA256 并 Base64 编码,与 sign 头比对一致即为合法请求。
# 4.3 响应要求
与其他主题一致:3 秒内返回 200 OK;推送失败不重试(消息不会自动补发),持续失败将触发自动关闭机制(见 3.3)。
# 5 私有订单消息(PrivateOrder)
订阅 privateOrder 主题后,私有订单(SY单/私有库存单,订单号以 SY 开头)发生状态变更时推送到已注册的回调地址。仅推送 SY 单,不含直发/押金等其它单据。
| messageType | 触发时机 |
|---|---|
UPDATE | SY 单状态发生变化(如待支付→已付款→待发货→已发货→已完成/已取消) |
# 5.1 消息体示例
{
"messageId": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
"type": "PRIVATE_ORDER",
"messageType": "UPDATE",
"params": {
"orderId": "SY2606061320024499900",
"orderNumber": "shop_order_123",
"status": "SHIPPED",
"orderType": 2,
"createDate": "2026-06-04 10:00:00",
"paymentDate": "2026-06-04 12:00:00",
"deliveryDate": "2026-06-05 09:00:00",
"completeDate": null
}
}
| 字段 | 类型 | 说明 |
|---|---|---|
| messageId | string | 消息唯一ID(消费方可用作幂等去重键) |
| type | string | 业务类型,私有订单固定 PRIVATE_ORDER |
| messageType | string | UPDATE-状态变更 |
| params.orderId | string | 私有订单号,单号规则:固定 SY 前缀 + 19 位数字(雪花ID),示例 SY2606061320024499900 |
| params.orderNumber | string | 店铺订单号 |
| params.status | string | 订单状态名称,见 5.2 状态表 |
| params.orderType | int | 订单类型:2=备货(私有库存单/SY单)。私有订单 webhook 目前仅推送 SY 单,orderType 固定为 2 |
| params.createDate | string | 创建时间 yyyy-MM-dd HH:mm:ss |
| params.paymentDate | string | 支付时间(已支付时返回) |
| params.deliveryDate | string | 发货(出库)时间(已发货时返回) |
| params.completeDate | string | 完成时间(完成时返回) |
# 5.2 status 状态值
| status | 说明 |
|---|---|
| WAIT_PAY | 待支付 |
| PAYMENT_INCOMING | 支付中 |
| PAID | 已付款待处理 |
| WAIT_SHIPMENT | 待发货 |
| INTERCEPTING / INTERCEPT | 拦截中 / 已拦截 |
| SHIPPED | 已发货 |
| COMPLETED | 已完成 |
| OVER | 已结束/关闭 |
| CANCELLED | 已取消 |
| REFUND_COMPLETE | 纠纷退款完成 |
| RESEND_OVER | 纠纷补发完成 |
# 5.3 验签与响应
验签算法与其它主题一致:sign = Base64( HmacSHA256( secret = openId字符串, message = 请求体JSON原文 ) );接收端 3 秒内返回 200 OK,推送失败不重试(消息不会自动补发),持续失败触发自动关闭机制(见 3.3)。
# 6 钱包通知(Wallet)
订阅 wallet 主题后,你的 CJ 钱包每新增一条账单流水,或已有流水的金额、状态发生变化时,推送到已注册的 wallet 回调地址。数据与 My CJ → Wallet → Billing History 来自同一张账单流水表,但推送不做页面上的类型过滤与状态归并,条数可能比页面多(见 6.5)。
| messageType | 触发时机 |
|---|---|
CREATED | 新增一条账单流水 |
UPDATED | 已有流水的金额(交易金额、手续费、交易前余额、交易后余额)或状态发生变化;其它字段变化不推送 |
# 6.1 订阅方式
- 在「1.1 监听设置」的请求体里加
wallet对象,格式与其它主题相同(type+callbackUrls)。type为ENABLE开启、CANCEL取消(不区分大小写),无法识别的值按取消处理。 - 钱包订阅归属当前取 token 用的那个 API 账号(openId),只能用该账号自己的 token 设置。请求里带了
wallet时,平台先校验钱包通知是否开放、token 是否属于该账号;这项校验不通过时,整个请求失败,同一请求里的其它主题也不会保存,报错分别为Wallet notifications are not enabled、Authenticated account is required、Wallet account ownership mismatch。 - 同一请求里
wallet排在其它主题之后处理:钱包这一项出错时(callbackUrls是空数组或只有空串、地址格式不对或测试没通过),同一请求里排在前面的其它主题已经保存;但wallet里不传callbackUrls、type为空或超过 20 个字符时,请求在参数校验阶段就整个失败,什么都不保存。 - 开启和取消时,平台都会先向回调地址发一条测试消息检查地址可用,要求 3 秒内返回
200 OK,否则设置失败;所以取消时也要带上回调地址。测试消息的messageId为wallet-registration-check,type为WALLET、messageType为CREATED,顶层带openId,params只有id(固定为test)、currency、amount(0)三个字段。它不是真实交易:请按messageId识别,直接返回200,不要入账。 - 设置成功后约 10 秒内生效。
- 同一客户有多个 API 账号时,每个开启了钱包订阅的账号各自收到一份推送:
messageId相同,各用自己的 openId 签名。正式推送的消息体里没有 openId,多个账号共用同一个回调地址时,无法从消息体区分是哪个账号的,建议每个账号用不同的回调地址。
# 6.2 消息体示例
{
"messageId": "5b0f3c2e-8a1d-3e4f-9c7b-2d6e8f1a4b3c",
"messageType": "CREATED",
"params": {
"id": "2100000000000000001",
"orderId": "SD2610230000000000001",
"type": "4",
"status": "1",
"createDate": 1792742400000,
"amount": 12.35,
"feeAmount": 0.0,
"balanceBefore": 120.5,
"balanceAfter": 132.85,
"currency": "USD",
"eventTime": 1792742399000
},
"type": "WALLET"
}
| 字段 | 类型 | 说明 |
|---|---|---|
| messageId | string | 消息唯一ID,由消息内容生成;同一条消息重复送达时不变,消费方可用作幂等去重键 |
| messageType | string | CREATED-新增流水 / UPDATED-金额或状态变化 |
| type | string | 业务类型,钱包固定 WALLET |
| params.id | string | 流水ID,与《账单流水查询》返回的 id 相同 |
| params.orderId | string | 流水上记录的关联单号,随交易类型可能是订单号、子单号、纠纷号等,不一定能直接拿去查订单;没有关联单号时不返回该字段,也可能为空串 |
| params.type | string | 交易类型码(支付内部码,与《账单流水查询》的 tradeType 不是同一套码),见 6.3 |
| params.status | string | 流水状态:0 Pending、1 Success、2 Failed、3 Frozen、4 Failed(Canceled)、5 / 6 Pending(提现处理中);客户自己取消的付款推送为 2(Billing History 里订单付款、押金、CJ PRIME、店铺售卖这几类显示为 Failed(Canceled)) |
| params.createDate | number | 流水创建时间,UTC 毫秒时间戳,与《账单流水查询》返回的 createDate 是同一时刻 |
| params.amount | number | 交易金额,单位 USD,与《账单流水查询》的 copeMoney 相同(目前观察到的都是非负数)。这笔是否动了钱包余额、往哪个方向动,以 balanceBefore、balanceAfter 比较为准,交易类型码只作参考 |
| params.feeAmount | number | 手续费,流水上记录的原值(目前观察到的都是 0) |
| params.balanceBefore | number | 交易前余额,单位 USD。是支付写这条流水时记下的钱包合计余额:多数流水是可用余额+冻结金额+不可提现金额+充值卡余额,钱包余额付款等流水还含信用借款额度,各类交易的算法不完全相同。与 Billing History 的 Current Balance、《账单流水查询》的 afterTransactionMoney 同口径,与《余额查询》返回的 amount(只含可用余额)不同 |
| params.balanceAfter | number | 交易后余额,单位 USD,口径同 balanceBefore |
| params.currency | string | 固定 USD |
| params.eventTime | number | 本次变化写入账单流水的时间,UTC 毫秒时间戳,精确到秒;CREATED 时一般与 createDate 相差 1 秒以内,UPDATED 时是这次变化的时间 |
params里没有值(null)的字段整个不返回,请按「字段可能缺省」解析。部分流水不记余额(如用 PayPal、银行卡等第三方直接付款,以及原路退回这些渠道的退款),这时不返回balanceBefore、balanceAfter。不要按收到的消息条数自己累加推算余额(消息可能重复送达,也可能因回调失败而缺失)。消息不保证到达顺序:同一条流水的CREATED、UPDATED可能先后颠倒,请按params.id覆盖更新、以eventTime较新的为准;同一秒内多次变化时,以《账单流水查询》回查到的状态和金额为准;交易后余额在流水带展示币种时会被换算,内部类型10~16查不到,见 6.5。
# 6.3 交易类型码(params.type)
| 码值 | 含义 | 在 Billing History /《账单流水查询》中显示为 |
|---|---|---|
1 | 充值 | Top-up(tradeType 2) |
2、6、9、18、19、20、29 | 订单付款类(含补发运费、账单支付、定制订单、问题包裹等);其中 9 也用于分销利润提现入账(钱进钱包) | Order Payment(1) |
3 | 提现 | Withdrawal(6) |
4 | 订单退款 | Order Refund(7) |
5 | 缺货退款 | Order Refund: Sold Out(8) |
7 | 福利 | Charging Benefit(4) |
8 | 余额扣款 | System Deduction(10) |
17 | 充值卡充值 | Top-up with Gift Card(3) |
21 | 押金支付 | Deposit(5) |
22 | 押金退款 | Deposit Refund(12) |
23 | 系统退款 | System Refund(9) |
26 | CJ 会员 | CJ PRIME(13) |
30 | 订单运费付款 | Order Payment-Shipping Cost(14) |
31 | 付费搜品 | Paid Sourcing(15) |
32 | 定制付款 | Paid Customization(16) |
33 | 调拨运费补款 | Freight Payment(17) |
34 | 付费服务 | Paid Services(18) |
35 | AI 点数充值 | AI Credits Top-up(19) |
36 | 信用借款放款 | Credit Loan(20) |
37 | 店铺售卖 | Store Purchase(21) |
10~16、24、25、27、28 | 内部类型 | 无对应类型;其中 10~16 不在 Billing History 显示 |
付款方式为系统退款时,Billing History 把类型名显示为 System Refund,所以只凭 params.type 不能完全还原页面上的类型名。
# 6.4 验签与响应
- 验签算法与其它主题一致:
sign = Base64( HmacSHA256( secret = openId字符串, message = 请求体JSON原文 ) );openId 用你为该 API 账号取 token 时拿到的那个(消息体里没有 openId)。 - 接收端 3 秒内返回
200 OK,只有200算成功;推送失败不重试(消息不会自动补发),持续失败触发自动关闭机制(见 3.3)。 - 同一条消息可能重复送达(
messageId相同),请按messageId去重,处理逻辑做成幂等。
# 6.5 补数据与对账
需要补数据时,用《账单流水查询》接口按时间范围拉取。两边可以按 id 对应,但以下几处不同:
- 查询不返回内部类型
10~16,状态5、6显示为0; - 查询不返回手续费和交易前余额,这两项补不回来;
- 这条流水带展示币种时,查询返回的余额会换算成展示币种,推送是 USD 原值;
- 补款等关联了原订单的付款,查询返回的
cjOrderId是关联的原订单号,推送的orderId是流水上记录的单号; - 查询按流水创建日期筛选,已有流水后来的状态变化,要按它的创建日期回拉。