# 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通知根据用户的订阅配置进行过滤:

  1. 用户开启了subscribeAllProducts=true → 发送通知
  2. 用户订阅了该具体商品 → 发送通知
  3. 以上均不满足 → 跳过通知

# 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 是流水上记录的单号;
  • 查询按流水创建日期筛选,已有流水后来的状态变化,要按它的创建日期回拉。