Eyun 开发者文档

Appearance

POST{BASE_URL}/wx-api/api/contact/syncExternal
只读实测 2026-09-06联系人JSON · Bearer App Token · body appid

同步外部数据（非企业） ​

增量同步外部联系人（客户）数据；收到回调 contentType=2131（外部联系人变更）后调用拉增量。

说明与注意 ​

  • 响应 = data.{businessId, list[], hasNext?}；每项 {id, itemFlag, seq, createTime, updateTime, content:{userInfo:{uin,name,iconUrl,…}}}，无 op 字段。

请求参数 ​

参数必填类型说明
appid是string实例 appid，标识操作哪个已登录账号。示例：we_xxxxxxxxxxxxxxx
seq翻页时必填int64同步游标，首次 0。示例：15873502
businessId否int640 可用。示例：0

请求示例 ​

http
POST {BASE_URL}/wx-api/api/contact/syncExternal
Authorization: Bearer <你的 App Token>
Content-Type: application/json

{
  "appid": "we_xxxxxxxxxxxxxxx",
  "seq": 15873502,
  "businessId": 0
}
bash
curl -X POST '{BASE_URL}/wx-api/api/contact/syncExternal' \
  -H 'Authorization: Bearer <你的 App Token>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "appid": "we_xxxxxxxxxxxxxxx",
  "seq": 15873502,
  "businessId": 0
}'
python
import requests

url = "{BASE_URL}/wx-api/api/contact/syncExternal"
headers = {"Authorization": "Bearer <你的 App Token>", "Content-Type": "application/json"}
body = """{
  "appid": "we_xxxxxxxxxxxxxxx",
  "seq": 15873502,
  "businessId": 0
}"""

resp = requests.post(url, headers=headers, data=body.encode("utf-8"))
print(resp.text)
java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String url = "{BASE_URL}/wx-api/api/contact/syncExternal";
String body = "{\n" +
    "  \"appid\": \"we_xxxxxxxxxxxxxxx\",\n" +
    "  \"seq\": 15873502,\n" +
    "  \"businessId\": 0\n" +
    "}";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder(URI.create(url))
    .header("Authorization", "Bearer <你的 App Token>")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
php
<?php

$url = '{BASE_URL}/wx-api/api/contact/syncExternal';
$body = <<<'JSON'
{
  "appid": "we_xxxxxxxxxxxxxxx",
  "seq": 15873502,
  "businessId": 0
}
JSON;

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer <你的 App Token>',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

响应示例 ​

json
{
  "code": 0,
  "data": {
    "businessId": 0,
    "list": [
      {
        "id": 1688855655434798,
        "itemFlag": 0,
        "seq": 9425784,
        "createTime": 1697595471,
        "updateTime": 1699432125,
        "content": {
          "userInfo": {
            "uin": 1688855655434798,
            "name": "蜘蛛侠",
            "emailAddr": "",
            "birthday": "1970-01-01 00:00:00",
            "phone": "",
            "number": "",
            "gender": 1,
            "iconUrl": "https://wx.qlogo.cn/mmhead/bSb5dSzPn0KzE4xrkiadlR6Q7HibrUOeaET22ibE8Q7pqGdmtHs0nWGhg/0",
            "corpId": 1970325925998027,
            "attr": 137757248,
            "dispOrder": 0,
            "bizUin": 0,
            "alias": "",
            "mainPartyId": 1688855655434807,
            "gid": 2251802468974430,
            "isNameVerified": true,
            "createSource": 1,
            "internationCode": "86",
            "bindEmailStatus": 2,
            "englishName": "ZhiZhuXia",
            "customInfo": {},
            "nameVerifyStatus": 1,
            "realName": "张**",
            "vCorpUseStatus": 1000,
            "inviteVid": 0,
            "holidayInfo": {
              "holidayStatus": 0,
              "holidayDesc": "",
              "oldHolidayIconIndex": 0,
              "createTime": 0,
              "holidayInfoId": 0,
              "holidayIconIndex": 0,
              "holidayGenerateSrc": 0,
              "holidayStatusNew": 0
            },
            "xcxStyle": 0,
            "attr2": 536871168,
            "tencentInfo": {},
            "isSyncInnerPosition": true,
            "unionId": "ozynqshxD5vlYYP1MZQ_ZFmugT3M",
            "vCode": "vc14653af37ba5080e",
            "schoolUserType": 3,
            "personalWorkType": 0,
            "attr3": 0
          },
          "corpInfo": {
            "corpId": 1970325925998027,
            "vid": 1688855655434798,
            "corpName": "奥特曼打葫芦娃",
            "createTime": 1685974036,
            "staffNum": 0,
            "trust": true,
            "corpLogo": "https://wework.qpic.cn/wwpic/186583_HKZLN-kIRie5_Ux_1685974037/0",
            "corpDesc": "",
            "adminVid": 1688855655434798,
            "isAccepted": true,
            "corpStat": 0,
            "corpFullName": "",
            "cmSubmitTime": 0,
            "createSourceInfo": "",
            "verifyMsg": "",
            "hasInfoCorp": false,
            "virtualCreateDomainName": "",
            "language": 1,
            "corpCardUrl": "https://work.weixin.qq.com/wework_admin/user/h5/corp?",
            "authedDomain": "",
            "vSuperadminVid": 1688855655434798,
            "bAuthedLicence": false,
            "joinNeedVerify": false,
            "pstnOfficePhoneState": 0,
            "authLicenceStatus": 1,
            "sCorpId": "<企业 corpId>",
            "corpAppWxaInfo": {
              "userName": "gh_303bdfa3334c@app",
              "appId": "<小程序 appId>",
              "enterPath": "/pages/index/index.html",
              "versionType": 0,
              "version": 0
            },
            "isOverseasCorp": false
          },
          "flag": 2057,
          "applyReason": "",
          "extraInfo": {
            "remarks": "",
            "wxTicket": "",
            "realRemark": "",
            "remarkUrl": "",
            "addCustomerTime": 1697595472,
            "companyRemark": "",
            "labelId": [
              {
                "labelId": 14073752485732091,
                "corpOrVid": 1970325156983916,
                "groupId": 14073752485732090,
                "businessType": 0,
                "serviceGroupId": 0
              },
              {
                "labelId": 14073752485732092,
                "corpOrVid": 1970325156983916,
                "groupId": 14073752485732090,
                "businessType": 0,
                "serviceGroupId": 0
              }
            ],
            "isFirstChat": true,
            "remarkTime": 1697614272
          },
          "sourceInfo": {
            "sourceType": 1,
            "applyMode": 2
          }
        },
        "createSeq": 9325776,
        "dataType": 0
      }
    ]
  },
  "detail": "",
  "message": "ok",
  "time": "2026-09-06 11:26:14"
}

响应字段 ​

响应字段（113 项）
字段类型说明
codeint64统一封套状态码：0=成功，负数=失败
dataobject业务数据
data.businessIdint640 可用
data.listarray<object>消息对象数组
data.list[].idint64记录/文件业务标识
data.list[].itemFlagint64变更标志；实测 0，删除态取值待确认
data.list[].seqint64同步游标（增量翻页位置）
data.list[].createTime / data.list[].updateTimeint64建立 / 更新时间戳（秒）
data.list[].contentobject消息内容；文本为数组、媒体为对象；未解析的消息为 {msgType, hex}（hex=protobuf 原始十六进制）
data.list[].content.userInfoobject客户用户信息（字段见字典）
data.list[].content.userInfo.uinint64用户唯一 id（int64，注意精度）
data.list[].content.userInfo.namestring昵称 / 显示名
data.list[].content.userInfo.emailAddrstring个人邮箱
data.list[].content.userInfo.birthdaystring生日 YYYY-MM-DD HH:MM:SS
data.list[].content.userInfo.phonestring电话（外部对象常为空）
data.list[].content.userInfo.numberstring工号
data.list[].content.userInfo.genderint64性别（1 男 / 2 女）
data.list[].content.userInfo.iconUrlstring头像 url
data.list[].content.userInfo.corpIdint64所属企业唯一 id
data.list[].content.userInfo.attrint64属性位掩码（bitmask），各 bit 含义待确认
data.list[].content.userInfo.dispOrderint64通讯录 / 部门内显示排序
data.list[].content.userInfo.bizUinint64企业 uin，含义待确认
data.list[].content.userInfo.aliasstring别名 / 花名
data.list[].content.userInfo.mainPartyIdint64主部门 id
data.list[].content.userInfo.gidint64全局 id（跨企业标识），含义待确认
data.list[].content.userInfo.isNameVerifiedboolean是否已实名认证
data.list[].content.userInfo.createSourceint64创建来源（外部客户常见）
data.list[].content.userInfo.internationCodestring国际区号，如 86
data.list[].content.userInfo.bindEmailStatusint64邮箱绑定状态（观测到 2=已绑定 / 1），枚举待确认
data.list[].content.userInfo.englishNamestring英文名
data.list[].content.userInfo.customInfoobject自定义字段集合（常为空对象）
data.list[].content.userInfo.nameVerifyStatusint64实名认证状态（观测 1）
data.list[].content.userInfo.realNamestring实名（示例已脱敏）
data.list[].content.userInfo.vCorpUseStatusint64企业使用状态（观测 1000），含义待确认
data.list[].content.userInfo.inviteVidint64邀请人 vid
data.list[].content.userInfo.holidayInfoobject休假信息（holidayStatus/holidayDesc/... ）
data.list[].content.userInfo.holidayInfo.holidayStatusint64假期状态 / 新版假期状态
data.list[].content.userInfo.holidayInfo.holidayDescstring假期描述文案
data.list[].content.userInfo.holidayInfo.oldHolidayIconIndexint64假期头像挂件索引 / 旧索引
data.list[].content.userInfo.holidayInfo.createTimeint64建立 / 更新时间戳（秒）
data.list[].content.userInfo.holidayInfo.holidayInfoIdint64假期信息 id
data.list[].content.userInfo.holidayInfo.holidayIconIndexint64假期头像挂件索引 / 旧索引
data.list[].content.userInfo.holidayInfo.holidayGenerateSrcint64假期来源（含义待确认）
data.list[].content.userInfo.holidayInfo.holidayStatusNewint64假期状态 / 新版假期状态
data.list[].content.userInfo.xcxStyleint64小程序名片样式，含义待确认
data.list[].content.userInfo.attr2int64属性位掩码（bitmask），各 bit 含义待确认
data.list[].content.userInfo.tencentInfoobject腾讯生态相关（常为空对象）
data.list[].content.userInfo.isSyncInnerPositionboolean是否同步内部职位
data.list[].content.userInfo.unionIdstring微信 unionId（跨应用用户标识）
data.list[].content.userInfo.vCodestring名片/验证码（形如 vc31f1...）
data.list[].content.userInfo.schoolUserTypeint64学校 / 高校身份类型，含义待确认
data.list[].content.userInfo.personalWorkTypeint64个人工作类型，含义待确认
data.list[].content.userInfo.attr3int64属性位掩码（bitmask），各 bit 含义待确认
data.list[].content.corpInfoobject企业信息（未搜到企业时 corpId=0）
data.list[].content.corpInfo.corpIdint64所属企业唯一 id
data.list[].content.corpInfo.vidint64联系人 id
data.list[].content.corpInfo.corpNamestring所属企业名称
data.list[].content.corpInfo.createTimeint64建立 / 更新时间戳（秒）
data.list[].content.corpInfo.staffNumint64
data.list[].content.corpInfo.trustboolean
data.list[].content.corpInfo.corpLogostring
data.list[].content.corpInfo.corpDescstring企业描述（仅 getUserProfileDetail 的部分 info 出现）。
data.list[].content.corpInfo.adminVidint64
data.list[].content.corpInfo.isAcceptedboolean
data.list[].content.corpInfo.corpStatint64
data.list[].content.corpInfo.corpFullNamestring
data.list[].content.corpInfo.cmSubmitTimeint64
data.list[].content.corpInfo.createSourceInfostring
data.list[].content.corpInfo.verifyMsgstring
data.list[].content.corpInfo.hasInfoCorpboolean
data.list[].content.corpInfo.virtualCreateDomainNamestring
data.list[].content.corpInfo.languageint64
data.list[].content.corpInfo.corpCardUrlstring
data.list[].content.corpInfo.authedDomainstring
data.list[].content.corpInfo.vSuperadminVidint64
data.list[].content.corpInfo.bAuthedLicenceboolean
data.list[].content.corpInfo.joinNeedVerifyboolean
data.list[].content.corpInfo.pstnOfficePhoneStateint64
data.list[].content.corpInfo.authLicenceStatusint64
data.list[].content.corpInfo.sCorpIdstring
data.list[].content.corpInfo.corpAppWxaInfoobject
data.list[].content.corpInfo.corpAppWxaInfo.userNamestring
data.list[].content.corpInfo.corpAppWxaInfo.appIdstring小程序 appId
data.list[].content.corpInfo.corpAppWxaInfo.enterPathstring
data.list[].content.corpInfo.corpAppWxaInfo.versionTypeint64
data.list[].content.corpInfo.corpAppWxaInfo.versionint64版本号，无特殊需求传 0
data.list[].content.corpInfo.isOverseasCorpboolean
data.list[].content.flagint64消息标志位 / 设备信息 / 摘要；观测到 flag 取 0 或 16777216，summary 常为空。精确含义待确认
data.list[].content.applyReasonstring添加时的申请语
data.list[].content.extraInfoobject统计明细：senderNums（已发）/senderTotalNums（应发）/serviceMember
data.list[].content.extraInfo.remarksstring备注描述
data.list[].content.extraInfo.wxTicketstring加好友票据；传给 add 接口的 ticket（实测长约 160 字符）
data.list[].content.extraInfo.realRemarkstring真实用户备注（改对方在你处的显示名）
data.list[].content.extraInfo.remarkUrlstring描述内的备注 URL
data.list[].content.extraInfo.addCustomerTimeint64添加为客户的时间戳
data.list[].content.extraInfo.companyRemarkstring企业/公司备注
data.list[].content.extraInfo.labelIdarray<object>打在该客户上的标签，每项 {labelId, groupId, corpOrVid, businessType, serviceGroupId}
data.list[].content.extraInfo.labelId[].labelIdint64打在该客户上的标签，每项 {labelId, groupId, corpOrVid, businessType, serviceGroupId}
data.list[].content.extraInfo.labelId[].corpOrVidint64
data.list[].content.extraInfo.labelId[].groupIdint64分组 id（0=无）
data.list[].content.extraInfo.labelId[].businessType / data.list[].content.extraInfo.labelId[].serviceGroupIdint64业务类型 / 排序 / 服务组 id（原样回传）
data.list[].content.extraInfo.isFirstChatboolean是否首次会话
data.list[].content.extraInfo.remarkTimeint64备注时间戳
data.list[].content.sourceInfoobject
data.list[].content.sourceInfo.sourceTypeint64来源类型
data.list[].content.sourceInfo.applyModeint64申请方式
data.list[].createSeqint64创建游标
data.list[].dataTypeint64数据类型，含义待确认（实测 0）
detailstring附加明细，通常为空
messagestring文案：成功为 ok；失败形如 -码|描述
timestring服务端处理时间 YYYY-MM-DD HH:MM:SS

下一步 ​