批量设置用户联合投放配置

更新时间:2026.01.27
||| 安装 Skill
提示:本功能目前处于灰度测试阶段、暂未开放使用,待全量开放后将通过文档门户公告同步,感谢您的理解。

批量设置用户在当前品牌下的联合投放配置,支持通过OpenID或手机号MD5设置。为每个用户设置在当前品牌下的可投放计划列表。

注意事项:

  1. 单次请求最多设置200-2000个用户

  2. 仅设置当前品牌(通过Authorization头识别)下的投放配置

  3. OpenID对应的appid需要确保与品牌之间有绑定关系

  4. 设置操作为全量替换,会覆盖该用户在当前品牌下的原有配置

  5. 不影响该用户在其他品牌下的投放配置

  6. 无法识别的用户标识将在响应中标记错误信息

  7. 设置结果按请求顺序返回,与输入一一对应

  8. 部分用户设置失败不影响其他用户的设置

接口说明

支持商户:【品牌商户】

请求方式:【POST】/brand/marketing/joint-delivery/users/delivery-configs/batch-set

请求域名:【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点

     【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ,指引点击查看

接口限频:20/秒(品牌ID维度)

请求参数
折叠全部参数

Header  HTTP头参数

 Authorization  必填 string

请参考签名认证生成认证信息


 Accept  必填 string

请设置为application/json


 Content-Type  必填 string

请设置为application/json


 Wechatpay-Serial  必填 string

【微信支付公钥ID】  请传入brand_id对应的微信支付公钥ID,接口将会校验两者的关联关系,参考微信支付公钥产品简介及使用说明获取微信支付公钥ID和相关的介绍。以下两种场景将使用到微信支付公钥: 1、接收到接口的返回内容,需要使用微信支付公钥进行验签; 2、调用含有敏感信息参数(如姓名、身份证号码)的接口时,需要使用微信支付公钥加密敏感信息后再传输参数,加密指引请参考微信支付公钥加密敏感信息指引。


body  包体参数

 identifier_type  必填   string

【用户标识类型】 用户标识类型,本次请求中所有用户标识的类型。

可选取值

  • USER_IDENTIFIER_TYPE_OPENID:  用户OpenID,所对应的appid需要确保与品牌之间有绑定关系

  • USER_IDENTIFIER_TYPE_PHONE_MD5:  手机号MD5哈希值,32位小写十六进制字符串


 user_configs  必填   array[object]

【用户联合投放配置列表】 用户联合投放配置列表,单次请求最少200个,最多2000个用户。每个用户需指定用户标识值和对应的投放计划ID列表。品牌ID通过Authorization头自动识别。

性能说明:批量设置数量越大,接口耗时越长。

推荐使用方式:

  1. 使用较小批次进行设置更新时,可获得更好的响应时延和稳定性

  2. 对于大批量更新任务,建议分批次串行或并行调用

属性

 user_identifier  必填   string(64)

【用户标识值】 用户标识值,根据请求中的identifier_type填写对应的值。例如:OpenID或手机号MD5


 plan_ids  选填   array[string(32)]

【投放计划ID列表】 当前品牌下可投放的投放计划ID列表,为空表示该用户在当前品牌下无可投放计划

请求示例

curl
Java
Go

POST

1curl -X POST \
2  https://api.mch.weixin.qq.com/brand/marketing/joint-delivery/users/delivery-configs/batch-set \
3  -H "Authorization: WECHATPAY-BRAND-SHA256-RSA2048 brand_id=\"XXXX\",..." \
4  -H "Accept: application/json" \
5  -H "Wechatpay-Serial: PUB_KEY_ID_XXXX"  \
6  -H "Content-Type: application/json" \
7  -d '{
8    "identifier_type" : "USER_IDENTIFIER_TYPE_OPENID",
9    "user_configs" : [
10      {
11        "user_identifier" : "oUasdgxuAJO_M2pxb1Q9zNjWeS6o",
12        "plan_ids" : [
13          "10001"
14        ]
15      }
16    ]
17  }'
18

应答参数
折叠全部参数

200 OK

 user_configs  必填   array[object]

【用户联合投放配置列表】 用户联合投放配置列表,返回设置后的最终配置。与请求中的用户配置列表一一对应(按顺序)。若某个用户设置失败,对应项的error_code和error_message字段会包含错误信息

属性

 user_identifier  必填   string

【用户标识值】 用户标识值,与请求中的标识值对应


 plan_ids  选填   array[string]

【投放计划ID列表】 当前品牌下可投放的投放计划ID列表,为空表示该用户在当前品牌下无可投放计划


 update_time  选填   string(64)

【更新时间】 该用户在当前品牌下投放计划的最后更新时间,RFC3339格式(如:2024-01-26T10:30:00+08:00),当前用户从未配置过联合投放配置时为空


 error_code  选填   string(64)

【错误码】 当该用户操作失败时的错误码,成功时为空


 error_message  选填   string(256)

【错误描述】 当该用户操作失败时的错误描述,成功时为空

应答示例

200 OK

1{
2  "user_configs" : [
3    {
4      "user_identifier" : "oUasdgxuAJO_M2pxb1Q9zNjWeS6o",
5      "plan_ids" : [
6        "10001"
7      ],
8      "update_time" : "2024-01-26T10:30:00+08:00",
9      "error_code" : "USER_NOT_FOUND",
10      "error_message" : "用户不存在或无法识别"
11    }
12  ]
13}
14

 

错误码

以下是本接口返回的错误码列表。详细错误码规则,请参考微信支付接口规则-错误码和错误提示

状态码

错误码

描述

解决方案

400

PARAM_ERROR

参数错误

请根据错误提示正确传入参数

400

INVALID_REQUEST

HTTP 请求不符合微信支付 APIv3 接口规则

请参阅 接口规则

401

SIGN_ERROR

验证不通过

请参阅 签名常见问题

500

SYSTEM_ERROR

系统异常,请稍后重试

请稍后重试

400

PARAM_ERROR

参数过短

请参考文档中对每个字段的要求以及组合要求,确认请求参数是否满足

400

PARAM_ERROR

参数错误

请参考文档中对每个字段的要求以及组合要求,确认请求参数是否满足

400

PARAM_ERROR

参数超出取值范围

请参考文档中对每个字段的要求以及组合要求,确认请求参数是否满足

401

SIGN_ERROR

Http头Authorization中的timestamp与发起请求的时间不得超过5分钟

Authorization 头 timestamp 与请求时间间隔超 5 分钟,需重新生成timestamp并替换该字段后重试。

401

SIGN_ERROR

Authorization不合法

Http头未传递Authorization值或Authorization值格式错误,请参考《APIv3如何签名和验签》,检查传递的Authorization值是否符合规则

 

反馈
目录
置顶