开发指引

更新时间：2026.10.22

提示：本功能目前处于灰度测试阶段、暂未开放使用，待全量开放后将通过文档门户公告同步，感谢您的理解。

1、开发前准备

正式进入开发前，开发者需要先阅读基本规则、如何签名和验签了解调用微信支付接口的基本规则和签名、验签规则。

在发起接口请求时，开发者还需传入一些必要参数，如brand_id(品牌ID)、品牌API证书私钥、公钥等，获取方式详见：品牌商户模式开发必要参数说明。

注意事项：

1、开发联调阶段，调用接口后，建议在日志中保留应答的HTTP头Request-ID值，Request-ID作为请求的唯一标识，在调用接口遇到问题时，可向微信侧提供该值用于快速定位到请求记录，协助排查问题原因。

2、品牌API接入示例可参考快速调通第一个品牌API

概念	说明
投放计划ID	由运营提供，或品牌方在品牌经营平台/投放计划API 创建的投放计划，用 plan_id 标识
plan_ids	用户在本品牌下可投放的投放计划ID列表
用户标识	OpenID 或手机号 MD5；整批请求必须使用同一类型的用户标识
配置的生效方式	调用批量设置用户联合投放配置API 会用本次请求的 plan_ids 完全覆盖该用户在本品牌下原有 plan_ids，非增量追加；应答返回HTTP 200 后，配置就会开始生效，无异步的回调通知

在本地按规范准备一份需要配置的用户标识列表：

注意：

用户标识（OpenID、手机号 MD5）属敏感数据：不允许提交到公开代码仓库；不允许通过非加密通道传递；建议建立审计日志记录关键配置变更。

新增/更新用户联合投放配置前，建议先调用批量查询用户联合投放配置拿到用户当前配置的plan_ids信息。

注意：

1、单次请求 1-150 个用户；整批 identifier_type 必须一致。

2、应答的 user_configs 与请求顺序一一对应；需检查每项是否带单用户 error_code。

3、OpenID 对应的 appid 须与本品牌已绑定，否则该用户可能返回 USER_NOT_FOUND。

结合查询到的用户当前配置信息，按品牌方自身业务规则在本地计算每个用户的最终需要群配置的 plan_ids，建议分场景按以下方式计算：

注意：

1、单次请求最少 200、最多 2000 个用户；低于 200 直接 PARAM_ERROR。业务上单用户更新需做小批量延迟攒包。

2、配置的生效方式为全量覆盖：必须传合并后的最终 plan_ids，禁止只传新增项。清空配置须明确传 plan_ids: []；未出现在本次请求中的用户不会被修改。

单个用户的plan_ids配置生效示例：

调用批量设置用户联合投放配置API 应答返回HTTP 200 后，配置就会开始生效，无异步的回调通知，下一次曝光投放命中匹配时即可读到最新配置。

若业务侧观察不到效果，优先核对：

1、是否在正确的 user_identifier × plan_id 维度观察；

2、中间是否有其它程序再次调用了设置接口覆盖了配置。

API名称	描述
批量查询用户联合投放配置	查询本品牌下一批用户当前的 plan_ids。单次 1-150。限频：按 brand_id 维度 20/秒。
批量设置用户联合投放配置	全量覆盖本品牌下一批用户的 plan_ids。单次 200-2000。前置条件：已确认本品牌可用 plan_ids；增量场景建议先查询再合并。

文档是否有帮助