Eyun 开发者文档

Appearance

联系人 ​

通讯录同步、详情、搜索、加好友、备注、标签。

本模块接口全部 POST。{BASE_URL} 是含 /wx-api 的完整 API Base；直接复制接口页的请求示例。

接口用途安全级别
同步通讯录 ID 列表
/wx-api/api/contact/getSyncList		拉取内部通讯录的成员和部门 ID 列表，以及做增量同步用的版本号，这是通讯录同步的第一步。只读
批量获取通讯录详细信息
/wx-api/api/contact/fetchUsersProfileBatch		把 getSyncList 的节点列表换成每个节点的详细资料（成员资料 / 部门信息）。只读
获取用户详情
/wx-api/api/contact/getUserProfileDetail		按用户 id 列表直接查最全的用户资料（内部成员或外部联系人均可）。只读
手机号搜索
/wx-api/api/contact/phoneNumberSearch		按手机号搜索用户，拿到添加好友所需的票据（wxTicket）与身份（openid / uin / corpId），供后续加好友接口使用。只读
通过手机号添加个微
/wx-api/api/contact/phoneNumberAddWechat		用 phoneNumberSearch 拿到的票据，向对方的个人微信发起好友申请。写操作
通过手机号添加企微
/wx-api/api/contact/phoneNumberAddWework		用 phoneNumberSearch 拿到的企微身份与票据，向对方的企业微信发起好友/客户申请。写操作
同意新客户
/wx-api/api/contact/agreeToNewCustomer		对方主动申请添加你为好友/客户时，调用本接口同意。写操作
更新外部联系人信息
/wx-api/api/contact/updateExternalContactInfo		修改某个外部联系人（客户）的备注、公司、真实备注、备注手机号等。写操作
删除联系人
/wx-api/api/contact/delete		删除一个联系人（解除好友关系）。高风险
设置同事备注
/wx-api/api/contact/setColleagueRemark		给内部成员（同事）设置备注 / 描述。写操作
添加名片
/wx-api/api/contact/addCard		通过收到的「个人名片消息」添加对方为好友。写操作
添加群成员为好友
/wx-api/api/contact/addRoomMember		把群内某成员添加为自己的好友（不是把人拉进群）。写操作
同步外部联系人
/wx-api/api/contact/syncExternal		增量同步外部联系人（客户）数据；收到回调 contentType=2131（外部联系人变更）后调用拉增量。只读
更新用户标签
/wx-api/api/contact/updateLabel		给某个用户打 / 去 / 改标签（操作的是「用户 ↔ 标签」的关联）。写操作

安全级别与「实测 日期」标记的含义见API 参考的表格说明。

通讯录和客户数据都不是一次拉全：先拿 ID 列表和游标，再按 ID 查详情；之后靠推送通知去拉变化的部分。

同步内部通讯录（同事和部门） ​

  1. 调同步通讯录 ID 列表，拿到成员和部门的列表 nodeList，以及版本号 svrVersion。第一次 svrVersion 传空，拿全部；以后传上次返回的值，只拿变化的部分。
  2. 把 nodeList 原样传给批量获取通讯录详细信息，可以分批传，换回每个成员或部门的资料 patchList：成员是 member 对象，部门是 department 对象。
  3. 只查少数几个人时，直接用获取用户详情，按 vid 或 uin 查，返回的资料更全，多一层 level。

nodeList 每一项：

字段含义
type1 成员，2 部门
vid成员 ID，等于他的 uin；部门项没有
partyId部门 ID；成员项里是他所在的部门，部门项里是部门自己
seq这条记录的版本号（int64），越大越新

同步客户（外部联系人） ​

客户就是外部联系人。

  1. 调同步外部联系人，第一次 seq 传 0。返回 hasNext=true 时，用返回的新 seq 继续翻页，直到 hasNext=false。把最新的 seq 存下来，下次从这里接着拉。
  2. 客户资料变化时会收到 contentType 为 2131 的推送，收到后再调一次同步，拉变化的部分；个人标签变化会推 2186，收到后调同步标签。报文见回调字典 · 类型速查表。

加好友、加客户 ​

场景怎么做
用手机号加对方的个人微信先手机号搜索，取返回的 openid 和 wxTicket，再调通过手机号添加个微
用手机号加对方的企业微信先手机号搜索，取 contactInfo.uin、contactInfo.corpId 和 wxTicket，再调通过手机号添加企微
对方申请加你调同意新客户
收到名片，想加对方调添加名片
想加群里的某个人调添加群成员为好友

用户资料字段 ​

member、info、userInfo、contactInfo 这几种用户对象的字段基本相同，统一在这里说明，各接口页只列顶层结构。常用字段：

字段类型含义
uinint64用户唯一 id；内部成员等于其 vid，外部客户等于 id。int64，注意精度。
namestring昵称 / 显示名
realNamestring实名（已脱敏为「张**」）
aliasstring别名 / 花名
mobilestring手机号（仅内部同事和已授权场景可见）
genderint性别：1 男 / 2 女 / 0 未知
job / positionstring职位 / 职务
iconUrlstring头像 URL
corpIdint64所属企业 id
partyIdint64所在部门 id
unionIdstring微信 unionId（跨应用用户标识）
其他字段
字段类型含义
englishNamestring英文名
phonestring电话（外部对象常为空）
internationCodestring国际区号，如 86
emailAddrstring个人邮箱
bizMailstring企业邮箱
birthdaystring生日 YYYY-MM-DD HH:MM:SS
externPositionstring对外展示职位，base64 编码（如 5oC757uP55CG→「总经理」）
numberstring工号
mainPartyIdint64主部门 id
dispOrder / partyMemberDispOrderint通讯录 / 部门内显示排序
isNameVerifiedbool是否已实名认证
nameVerifyStatusint实名认证状态（常见值 1）
inviteVidint64邀请人 vid
vCodestring名片/验证码（形如 vc31f1...）
customInfo / externalCustomInfoobject自定义字段集合（常为空对象）
holidayInfoobject休假信息（holidayStatus / holidayDesc / ...）
tencentInfoobject腾讯生态相关（常为空对象）
isSyncInnerPositionbool是否同步内部职位
hashint数据 hash（变更检测用）
createSourceint创建来源（外部客户常见）
superiorsarray上级链（汇报关系），元素为对象。
xcxCorpAddressstring小程序名片-企业地址，base64 编码。
businessDescobject业务描述自定义字段：{fieldName(base64), fieldId(base64,如 busi_desc), fieldType}；内部成员/外部客户均可能出现。
corpDescInfoobject企业描述信息（常为空对象 {}）。
corpDescobject / string企业描述（仅 getUserProfileDetail 的部分 info 出现）。
holidayInfo.vacationSyncTypeintholidayInfo 内字段：休假同步类型。
含义未公开的字段（原样保存即可）
字段类型说明
mobileAreaCodeint手机区号（常为 0）
bindEmailStatusint邮箱绑定状态（常见值 2 已绑定、1）
gidint64全局 id（跨企业标识）
attr / attr2 / attr3int属性位掩码（bitmask）
bizUinint64企业 uin
vCorpUseStatusint企业使用状态（常见值 1000）
xcxStyleint小程序名片样式
personalWorkTypeint个人工作类型
schoolUserType / collegeIdentityint学校 / 高校身份类型