开发指引

更新时间：2026.08.19

||| 安装 Skill

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

1、开发前准备

1.1、熟悉微信支付接口规则

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

1.2、准备开发参数

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

注意事项：

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

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

1.3、权限申请

联系微信支付运营人员开通「人群包接入」能力权限。
由运营侧下发本品牌可用的人群包标识 user_package_id（20 位定长），商户不可自行生成或假设。

2、业务基础概念

概念	说明
人群包	微信支付侧的逻辑用户容器，用 user_package_id 标识；具有固定的运营类型（定向曝光 / 风险用户）与数据类型（OpenID / 手机号 MD5）
扩充	将用户名单导入人群包的操作，为增量语义（新增用户加入），不是覆盖
上传任务 upload_id	调用初始化上传后获得的会话句柄，用于后续分块上传与合并
用户标识	整文件只能是 OpenID 或手机号 MD5 之一，由 data_type 决定
生效模型	扩充提交后异步生效，无回调；大多数情况当天内生效，少数场景最长可能需要 T+2

3、接入全流程

四个接口必须严格按顺序调用，跳步会失败。

3.1、准备人群包文件（非API）

在本地按规范准备用户名单 CSV 文件：

纯文本 CSV、UTF-8（无 BOM）、无表头；每行仅 1 列；无引号、无前后空格。
整文件类型需与后续调用初始化上传接口时，选择的 data_type 一致：全 OpenID，或全手机号 MD5（32 位小写十六进制）。
OpenID 对应的 appid 须与本品牌已绑定，否则该行会被静默过滤。
文件名需符合规范并以 .csv 结尾；完整文件需计算 SHA256 digest（64 位小写十六进制），并记录 file_size（file_size 等于实际文件字节数）。
建议上传前先去重，便于核对实际处理量。

注意：

1、前置条件：已取得运营下发的 user_package_id。

2、CSV 含用户标识，属敏感数据：不允许提交到公开代码仓库；不允许通过非加密通道传递；上传完成后建议及时清理本地副本；建议记录每次扩充的 upload_id、user_package_id、提交人、文件 digest、行数。

3.2、初始化上传（API）

调用初始化上传创建上传会话，拿到 upload_id、file_part_size、file_part_count。

注意：

1、digest 为完整文件 SHA256；file_size 须与本地实际字节数一致；description UTF-8 长度至少 15。

2、file_part_size / file_part_count 由服务端决定，商户必须按此切分，不能自行决定分块大小。

3、本接口按「品牌 ID + 文件名」幂等：相同文件名重复调用会返回同一 upload_id；要开新会话须更换文件名。

3.3、上传文件分块（API）

按序调用上传文件分块，上传每个分块。

注意：

1、part_number 从 1 开始，最大值为 file_part_count。

2、除最后一块外，每块字节数必须等于 file_part_size；最后一块可以更小。

3、完整文件 digest 与单分块 digest 不要混用：初始化上传用整文件 SHA256，分块上传用当前块 SHA256。

4、同一 part_number 重传为覆盖幂等，可失败重试；必须等所有分块明确成功后再进入下一步。

3.4、文件分块合并（API）

全部分块成功后，调用文件分块合并触发合并。

注意：

1、任意分块未完成就调用合并，会返回 NOT_FINISHED。

2、建议拿到 upload_id 后尽快完成上传与合并全流程。

3.5、扩充人群包（API）

合并完成后，调用扩充人群包提交扩充任务。

注意：

1、user_package_id 必须是运营预分配的 20 位定长字符串。

2、应答 state 通常为 PROCESSING，仅表示任务已成功提交，不代表数据已生效。

3、无回调通知，也没有查询扩充任务最终状态的接口；不要写「轮询直到生效」的逻辑。

4、数据生效异步：大多数情况当天内，少数场景最长可能需要 T+2。建议业务侧设置至少 24 小时容忍窗口。

3.6、生效观察与排障

若接口均成功但入库用户数偏少，优先排查文件是否被静默过滤（appid 未绑定、MD5 格式不合规、含表头/多列等），见常见问题。
若 T+2 后仍完全未生效，保留各接口完整 Request-Id 与请求时间，联系微信支付运营人员核查；不要重复提交「试试看」。

4、接口接入说明

4.1、必接接口

API名称	描述
初始化上传	创建分块上传会话，获取 upload_id 与分块参数。限频：按 brand_id 维度 10/秒。
上传文件分块	按序上传单个分块。前置条件：已完成初始化上传。
文件分块合并	通知服务端合并全部分块。前置条件：所有分块上传成功。
扩充人群包	用合并后的资源扩充指定人群包。前置条件：已完成合并，且持有运营下发的 user_package_id。

文档是否有帮助

LLM请查看llms.txt

开发文档(服务商)开发者社区微信开放平台微信公众平台腾讯客服