有赞云用户 union_id 查询接口字段手册：从客户列表到微信 union_id 联查的实战教程

这个接口解决什么问题

在零售 SaaS 与微信生态深度耦合的今天,「同一个微信用户在公众号、小程序、商城之间是几个人」几乎是每个集成项目都要回答的问题。有赞云「用户 union_id 查询」接口正是为此而生:它先用主接口按时间窗分页拉取客户列表,再用联查接口把每个客户的微信 union_id 与 open_id 取回来,最终交付一条「带微信身份」的客户主数据,用于跨系统用户打通与会员主数据同步。

接口能力总览

• 所属系统:有赞云 SCRM。
• 主接口:/youzan.scrm.customer.list.1.0.0,GET,按 created_at_start / created_at_end(秒级时间戳)分页拉取客户,默认页大小 50,业务数据位于响应 data.record_list,分页键为 page_no。
• 联查接口:/youzan.user.weixin.openid.get.3.0.0,以主记录中的 yz_open_id 作为入参,返回 union_id 与 open_id 并合并至主记录。
• 认证方式:有赞云开放平台 OAuth 授权(应用级 access_token),多客户私有化部署时需逐租户配置。
• 增量模式:典型做法是用 {{LAST_SYNC_TIME}} 与 {{CURRENT_TIME}} 作为时间窗,实现按 created_at 的滚动增量;另可叠加 has_mobile=true 过滤无效记录。
• 策略类型:QUERY_ONLY,只读不写,通常作为前置环节为下游写入接口准备数据。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里,该策略通常被建模为「QUERY_ONLY 源策略 + 联查子流程」:源端选「有赞云 SCRM」适配器,主接口分页器配置 page_no/page_size 与时间窗变量;联查节点挂在主循环之后,detailkey1/detailkey2 均为 yz_open_id,响应回填 union_id、open_id。平台的字段映射器会自动按 metadata 把 id 绑定到 yz_open_id、number 绑定到 show_name,目标端映射到下游 OtOCustomer 的 CustomerId/Name/MobilePhone/Unionid。时间窗变量 {{LAST_SYNC_TIME}} 与 {{CURRENT_TIME}} 在轻易云的调度上下文里可直接引用,免去手写脚本。

跨方案实战要点

1. 「主接口+联查」是常态:不要试图在一个接口里拿到 union_id,务必拆成两步,先列表后联查,否则会丢字段。
2. 时间窗是增量同步的生命线:created_at 是首选锚点;若客户成为客户时间早于系统接入时间,要给一个固定的 created_at_start 兜底,防止历史数据永远拉不到。
3. 绑定状态决定 union_id 是否存在:未绑定认证服务号或未完成微信授权的客户,联查可能返回空,需要在映射层做容空处理,而不是直接报错。
4. 分页与限流的平衡:默认 page_size=50 在多客户并发时较稳;轻易云里可统一提到 100,但要配合有赞云 QPS 限流策略加退避。
5. 主键稳定性大于一切:yz_open_id 是这套数据唯一可靠的标识,下游不要用 mobile 或 show_name 做去重键,极易冲突。
6. 纯查询策略要预留下游写入位:QUERY_ONLY 自身不写目标系统,实际项目里通常紧跟一个 EXECUTE 策略写入 OtOCustomer,二者建议用 depends_on 串成有序链路。

踩坑复盘

• 踩坑一:union_id 为空整批失败。某次集成里客户未做微信授权,联查返回 null,上游脚本未做容空直接抛错,导致整批中断。稳妥做法是在轻易云字段映射器里对 union_id 设「容空 + 默认空串」,下游按需判断是否写入。
• 踩坑二:时间窗跨时区错位。created_at 是秒级时间戳但有赞云按东八区存储,UTC 项目里 {{CURRENT_TIME}} 不做时区转换就会漏掉当天数据。建议在轻易云里用平台提供的本地化时间函数显式 +8h。
• 踩坑三:分页键错配。把响应里的 total 当作翻页终止条件,但分页键其实是 page_no 与返回是否为空,导致无限循环。稳妥做法是「页码+空列表双重终止」。
• 踩坑四:手机号格式不一致。有赞云返回的手机号可能是明文也可能是带区号或脱敏,写入下游前需统一在轻易云里加一个字段转换器。
• 踩坑五:多租户 token 串用。私有化部署多个客户共用一个接入配置时,access_token 互相串用会触发鉴权失败。务必在轻易云的租户维度上为每个客户单独维护凭证。

何时选用

该接口适用于「需要把有赞客户与微信生态用户打通」的场景,如会员中台、跨渠道用户画像、统一身份认证;不适合「只需简单同步手机号、不依赖微信身份」的场景,此时直接走 SCRM 客户同步更轻量。