小粉开放平台
小粉开放平台
WeChat OpenAPI
登录 申请接入
v1 生产文档

API 文档

生产地址是 https://open.xiaofen.ai/v1。这里列的是当前生产真实可用接口：统一 Bearer Token、scope 权限、IP 白名单、分钟限流、幂等、请求审计和 Webhook 回调。

42
已上线接口
13
消息类型
17
Raw 白名单
4
Webhook 事件

快速开始

请求约定

鉴权：Authorization: Bearer xf_live_xxx
格式：Content-Type: application/json
幂等：写接口建议带 Idempotency-Key
分页：page + per_page，每页最多 100
排障：保存响应里的 request_id
异步：返回 operation_id 后查询 /operations/:id

验证 Token

curl https://open.xiaofen.ai/v1/me \
  -H "Authorization: Bearer $XFO_TOKEN"

扫码登录

curl https://open.xiaofen.ai/v1/accounts/1/login_qrcode \
  -H "Authorization: Bearer $XFO_TOKEN" \
  -H "Idempotency-Key: login-qrcode-1" \
  -X POST

创建 Webhook

curl https://open.xiaofen.ai/v1/webhooks \
  -H "Authorization: Bearer $XFO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://client.example.com/xiaofen/webhook",
    "event_types": ["message.sent", "operation.failed"]
  }'

端到端流程

从客户拿到 API Key，到扫码登录、同步联系人、发消息、发朋友圈，推荐按这个顺序联调。完整离线版见 docs/plans/11-openapi-wechat/api-usage-guide.md。

1. 创建 API Key

控制台

注册并审核通过后，在控制台创建应用。API Key 只展示一次，格式为 xf_live_...，服务端只保存 digest。

2. 创建微信实例

accounts:write

调用 POST /accounts 创建微信实例，保存返回的 account id。客户不接触底层 guid。

3. 扫码登录

accounts:write

调用 POST /accounts/:id/login_qrcode 获取二维码；扫码后用 GET /accounts/:id/status 轮询到 online。

4. 同步联系人

contacts:write

调用 POST /accounts/:id/sync_contacts，返回 operation；完成后通过 GET /contacts 查询联系人。

5. 发消息

messages:write

调用 POST /messages，优先传 contact_id；也可以传 account_id + to_username。群消息同样走这个接口。

6. 发朋友圈

moments:write

调用 POST /moments，content_type 支持 text、image、video、link，返回 operation 后查询最终结果。

7. 运维排障

operations:read / requests:read

客户报障时提供 request_id、operation_id、account_id 和 Idempotency-Key，可在 /operations 与 /requests 中追踪。

接口总览

以下接口都以 https://open.xiaofen.ai/v1 为前缀，除 /health 外都需要 Bearer Token。

健康与身份

用于验证服务状态、Token 有效性和当前应用授权范围。

方法 路径 Scope 模式 说明
GET /health 公开 同步 健康检查，不需要 Bearer Token。
GET /me 有效 Token 同步 返回当前 API 应用、组织和 scopes，不要求特定 scope。

微信号

管理客户组织下托管的微信号实例、登录二维码和账号状态。

方法 路径 Scope 模式 说明
GET /accounts accounts:read 同步 列出可用微信号，支持分页。
POST /accounts accounts:write 同步 创建微信实例，底层生成 guid 并映射为 account。
GET /accounts/:id accounts:read 同步 获取单个微信号资料和状态。
POST /accounts/:id/login_qrcode accounts:write 同步 生成登录二维码。
GET /accounts/:id/status accounts:read 同步 刷新并返回底层 SDK 在线状态。
POST /accounts/:id/logout accounts:write 同步 退出登录。
POST /accounts/:id/sync_contacts contacts:write 异步 触发联系人同步，返回 operation。

联系人与好友申请

读取联系人、更新客户字段，并处理好友申请。

方法 路径 Scope 模式 说明
GET /contacts contacts:read 同步 联系人列表，支持 account_id、type、q 查询。
GET /contacts/:id contacts:read 同步 联系人详情。
PATCH /contacts/:id contacts:write 同步 更新备注、标签、阶段等本地客户字段。
GET /friend_requests contacts:read 同步 好友申请列表。
POST /friend_requests/:id/accept contacts:write 异步 通过好友申请，返回 operation。
POST /friend_requests/:id/reject contacts:write 同步 拒绝好友申请。

消息

统一消息发送与消息查询。当前公开 v1 覆盖普通联系人和群消息，企微 / OpenIM 场景暂不对外开放。

方法 路径 Scope 模式 说明
GET /messages messages:read 同步 消息列表，支持 account_id、contact_id、message_type。
GET /messages/:id messages:read 同步 消息详情。
POST /messages messages:write 同步 发送消息；用 message_type 选择文本、图片、文件、链接等类型。

群

读取群、群成员和群二维码；成员同步走异步 operation。

方法 路径 Scope 模式 说明
GET /groups groups:read 同步 群列表，支持 account_id、q。
GET /groups/:id groups:read 同步 群详情。
GET /groups/:id/members groups:read 同步 群成员列表。
POST /groups/:id/qrcode groups:read 同步 获取群二维码。
POST /groups/:id/sync_members groups:write 异步 触发群成员同步，返回 operation。

朋友圈

读取、同步、发布和互动朋友圈内容。

方法 路径 Scope 模式 说明
GET /moments moments:read 同步 朋友圈列表，支持 account_id。
GET /moments/:id moments:read 同步 朋友圈详情。
POST /moments/sync moments:write 异步 同步朋友圈时间线，返回 operation。
POST /moments moments:write 异步 发布朋友圈，支持 text、image、video、link。
POST /moments/:id/like moments:write 同步 点赞或取消点赞，liked=false 表示取消。
POST /moments/:id/comment moments:write 同步 评论或回复评论。
DELETE /moments/:id moments:write 同步 删除自己发布的朋友圈。

异步、Webhook 与审计

所有长任务都返回 operation；Webhook 用 HMAC-SHA256 签名；请求日志可用于排障。

方法 路径 Scope 模式 说明
GET /operations operations:read 同步 异步任务列表。
GET /operations/:id operations:read 同步 异步任务详情和结果。
GET /webhooks webhooks:read 同步 Webhook endpoint 列表。
POST /webhooks webhooks:write 同步 创建 Webhook endpoint，secret 只返回一次。
GET /webhooks/:id webhooks:read 同步 Webhook endpoint 详情。
PATCH /webhooks/:id webhooks:write 同步 更新 URL、状态和事件类型。
DELETE /webhooks/:id webhooks:write 同步 删除 Webhook endpoint。
POST /webhooks/:id/rotate_secret webhooks:write 同步 轮换 Webhook secret。
GET /requests requests:read 同步 请求日志列表，支持 error_code。
GET /requests/:id requests:read 同步 请求日志详情。

Raw API

用于兜底访问尚未产品化封装的底层 SDK 能力；只允许白名单 path，客户不能传 guid、proxy、notify_url 等平台参数。

方法 路径 Scope 模式 说明
GET /raw/endpoints raw:invoke 同步 查看当前允许调用的底层 SDK path。
POST /raw/invoke raw:invoke 同步/异步 调用白名单 Raw API；async=true 时返回 operation。

消息类型

发送消息统一使用 POST /messages，通过 message_type 选择底层消息能力。当前公开 v1 覆盖普通联系人和群消息；企微 / OpenIM 场景暂不对外开放。

message_type 能力 关键参数
text 文本消息 content
image 图片 media_url，可选 file_name/big_file
video 视频 media_url，可选 file_name/big_file
file 文件 media_url，可选 file_name/big_file
emoji 表情 URL media_url
link 链接卡片 title、url，可选 desc/image_url
location 位置 latitude、longitude、title，可选 address
share_card 名片 share_username，可选 share_nickname
mini_program 小程序 appid、appname、title，可选 page_path/appicon
finder_video 视频号 object_id，可选 nonce_id/author_username/thumb_url
app_msg 原始 APPMSG xml，可选 app_type/appid/msg_source
refer 引用消息 content、refer_msg
pat 拍一拍 patted_username

Raw API 白名单

Raw API 只用于补齐稳定资源 API 尚未覆盖的底层 SDK 能力。客户传 account_id，平台自动注入 guid；请求参数禁止出现 guid、proxy、notify_url 等平台级字段。

SDK path Scope 说明
/client/get_client_status accounts:read 查询实例状态
/cloud/cdn_upload messages:write 上传消息素材
/contact/batch_get_contact_from_db contacts:read 从 SDK 本地库批量读取联系人
/contact/get_contact contacts:read 批量获取联系人资料
/contact/get_friends contacts:read 读取好友列表
/contact/init_contact contacts:write 触发联系人同步
/contact/modify_remark contacts:write 修改联系人备注
/login/check_login_qrcode accounts:write 检查扫码状态
/login/get_login_qrcode accounts:write 获取登录二维码
/room/get_chatroom_members groups:read 读取群成员
/room/get_chatroom_qrcode groups:read 读取群二维码
/sns/sns_comment moments:write 发表评论
/sns/sns_like moments:write 点赞或取消点赞
/sns/sns_object_detail moments:read 读取朋友圈详情
/sns/sns_timeline moments:read 读取朋友圈时间线
/sns/sns_userpage moments:read 读取指定用户朋友圈
/user/get_profile accounts:read 获取登录账号资料

Webhook

创建 Webhook 时返回的 secret 只展示一次。投递 payload 包含事件 id、type、created_at 和 data；客户侧应使用 secret 做 HMAC-SHA256 校验并记录 event_id 做幂等。

message.sent

消息发送成功后触发

operation.succeeded

异步任务完成后触发

operation.failed

异步任务失败后触发

*

订阅全部事件

错误与排障

所有错误响应都带 request_id。客户报障时同时提供 request_id、operation_id、account_id 或 raw path，定位速度会快很多。

code HTTP 说明
unauthorized 401 缺少或无效 Bearer Token
insufficient_scope 403 Token 缺少接口权限
ip_not_allowed 403 来源 IP 不在白名单
organization_suspended 403 组织已停用
not_found 404 资源不存在或无权访问
idempotency_key_conflict 409 同一 Idempotency-Key 用于不同请求
wechat_sdk_error 502 底层微信 SDK 返回错误
rate_limit_exceeded 429 超过应用分钟限流
raw_api_not_allowed 403 Raw API path 未在白名单
invalid_raw_params 422 Raw API 参数包含禁止字段

企微 / OpenIM 暂不开放

当前公开 v1 不开放底层 SDK 的 OpenIM 资源接口，包括企微好友、企微群、企业信息、添加/删除企微联系人等能力。

这些能力不会出现在公开 scope、Raw API 白名单或客户默认 API Key 中。后续如需对外开放，会在完成产品化封装、权限隔离和运维评估后再进入正式文档。