企业微信 API 对接文档

对接模型

三方应用只能配置一个可信域名时，可把老系统作为企业微信 API 代理网关。新系统或第三方程序向老系统发起请求，老系统使用已授权企业的凭证代请求企业微信，并把企业微信返回的数据原样返回。

请求签名

除授权完成回调外，所有新系统调用老系统的 API 都需要 HMAC-SHA256 签名。

请求头

X-Api-Timestamp: 秒级时间戳
X-Api-Nonce: 随机字符串
X-Api-Signature: 签名

签名原文

METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + RAW_BODY

PHP 示例

$body = json_encode($payload, JSON_UNESCAPED_UNICODE);
$timestamp = (string) time();
$nonce = bin2hex(random_bytes(8));
$text = "POST\n" . $path . "\n" . $timestamp . "\n" . $nonce . "\n" . $body;
$signature = hash_hmac('sha256', $text, $apiSecret);

员工授权

生成企业微信员工授权链接。

{
  "source_domain": "new.example.com",
  "client_user_id": "1",
  "redirect_uri": "https://new.example.com/wecom/bind-result"
}

{
  "ok": true,
  "auth_url": "https://open.work.weixin.qq.com/...",
  "state": "wa_xxx"
}

查询新系统用户是否已绑定企业微信员工。

{
  "source_domain": "new.example.com",
  "client_user_id": "1"
}

{
  "ok": true,
  "bound": true,
  "binding": {
    "corp_id": "wwxxx",
    "userid": "zhangsan",
    "open_userid": "xxx",
    "employee_name": "张三"
  }
}

客户和群数据

实时获取该员工的客户数据。老系统不缓存，只返回企业微信数据。

{
  "source_domain": "new.example.com",
  "client_user_id": "1",
  "limit": 100
}

实时获取该员工管理或参与的客户群。

{
  "source_domain": "new.example.com",
  "client_user_id": "1",
  "limit": 100
}

实时获取指定客户群成员。

{
  "source_domain": "new.example.com",
  "client_user_id": "1",
  "chat_id": "wrxxx"
}

回调推送

老系统收到企业微信事件后，会根据绑定员工识别来源，并推送到来源域名的统一路径，默认是 /api/wecom/callback。

回调签名头

X-Wecom-Timestamp: 秒级时间戳
X-Wecom-Nonce: 随机字符串
X-Wecom-Signature: 签名

签名原文

TIMESTAMP + "\n" + NONCE + "\n" + RAW_BODY

推送示例

{
  "ok": true,
  "matched": true,
  "source_domain": "new.example.com",
  "client_user_id": "1",
  "corp_id": "wwxxx",
  "userid": "zhangsan",
  "open_userid": "xxx",
  "event_type": "change_external_contact",
  "change_type": "add_external_contact",
  "external_userid": "wmxxx",
  "chat_id": "",
  "state": "",
  "match_method": "corp_userid",
  "event_time": 1710000000,
  "raw": {}
}

识别规则

新系统用户不需要再单独绑定员工。只要从新系统发起授权，老系统会记录：

source_domain + client_user_id + corp_id + userid/open_userid

企业微信回调到达老系统后，老系统优先用 corp_id + userid 匹配员工；如果事件里没有 userid，再尝试 open_userid、state 等信息。匹配成功后推送到该 source_domain 的统一回调路径。

错误格式

{
  "ok": false,
  "error": "invalid_signature",
  "message": "signature verify failed"
}