API Reference — 微联 Web

接口说明文档

微联网页版 · 13 个界面· 服务端接口全量对齐

界面总数

接口模块分组

150+

REST 接口端点

机器可读错误码

界面清单13 Screens

#	界面	文件	核心接口模块	主要能力
01	登录	login.html	auth	验证码/密码登录、注册、微信/扫码
02	发现	index.html	moment / search	推荐流、频道、点赞
03	照片墙	wall.html	wall / vip	城市筛选、点赞排行榜、上墙
04	搜索	search.html	search / account	全局搜索、用户/笔记/圈子/悬赏
05	笔记详情	note.html	moment / note	图文、评论、点赞收藏、转发
06	个人主页	profile.html	auth / moment / wall	资料、作品集、收藏、上墙
07	IM 聊天	im.html	im / wallet	消息、红包、转账、语音、投票
08	圈子	circle.html	im / circle	圈子广场、热帖、评论点赞
09	悬赏	task.html	task / wallet	发布/接单、城市筛选、结算
10	发布	publish.html	moment / media	图文视频、定位、可见范围、草稿
11	钱包	wallet.html	wallet	余额、充值、转账、支付密码、流水
12	会员	member.html	member / vip	套餐购买、特权、墙额度
13	设置	settings.html	auth / friend / block	账号安全、隐私、效率功能

GLOBAL全局接口规范

所有接口遵循统一约定，客户端（网页版 / App）对接时须遵守以下规则。

鉴权与请求Auth & Request

# 全局前缀  /api

# 鉴权头（登录后所有需鉴权接口）

Authorization: Bearer <token>

# 鉴权级别标记

🔒 = 需登录（Bearer token）   公开 = 无需登录   👑 = 仅 super 管理员

🔒 需登录公开无需登录 👑 仅管理员

响应结构Response

// 成功：直接返回业务数据

{ "id": 123, "created_at": "..." }

// 失败：统一结构（⚠️ 见错误码节，code 字段为本次新增改造项）

{ "statusCode": 400, "message": "账号或密码不正确", "code": "AUTH_BAD_CREDENTIALS" }

媒体 URL 规则：所有 /api/uploads/... 链接已带 ?sig= 签名，客户端必须使用接口原样返回的 URL，勿自行拼接。无签名访问返回 403。

ERRORS错误码表

机器可读错误码（服务端 AllExceptionsFilter 改造项）。客户端判据：code 在「可重试」列 → 显示「发送失败 + 重发」；否则显示「发送失败」不给重试。

code	HTTP	触发条件	可重试	客户端应对
AUTH_BAD_CREDENTIALS	400	账号或密码不正确	否	提示重输，不重试
AUTH_LOCKED	400	连续失败 5 次锁定	否	提示等待 N 分钟
AUTH_TOKEN_EXPIRED	401	token 过期/无效	否	跳登录
RATE_LIMITED	429	请求过于频繁	是	指数退避重试
UPLOAD_TOO_LARGE	400	图>5MB / 视频>300MB / 文件>100MB / 音频>20MB	否	提示压缩/分片
UPLOAD_BAD_SIZE	400	数据过小(<32B)	否	提示「文件为空或损坏」，与取图失败区分
UPLOAD_HEIC_FAILED	400	HEIC/HEIF 转换失败	否	提示转 JPG 重试
MEDIA_FILE_CORRUPT	400	图片损坏/无法解析	否	提示「文件损坏，无法发送」
MEDIA_VIDEO_CORRUPT	400	视频损坏/无法解析	否	提示「视频文件损坏，无法发送」
MEDIA_TRANSCODE_UNSUPPORTED	400	视频格式不支持	否	提示换格式
UPLOAD_CHUNK_MD5_FAILED	400	分片 MD5 校验失败	是	重传该分片
UPLOAD_MD5_FAILED	400	文件 MD5 校验失败	是	整文件重传
UPLOAD_SESSION_NOT_FOUND	400	上传会话过期/不存在	否	重新走 init
UPLOAD_MERGE_SIZE_MISMATCH	400	合并大小不符	否	重新上传
UPLOAD_ALREADY_FINISHED	400	重复 complete	否	视为成功，用已有消息 id
UPLOAD_FORBIDDEN	400	越权/非本人媒体	否	提示无权限
PAY_PWD_WRONG	400	支付密码错误	否	提示剩余次数
PAY_PWD_LOCKED	400	错 5 次锁定	否	提示等待 10 分钟
PAY_PWD_NOT_SET	400	未设置支付密码	否	引导设置
BALANCE_NOT_ENOUGH	400	微币余额不足	否	引导充值
MEDIA_NEED_SIGNATURE	403	无签名访问媒体	否	用接口返回的签名 URL
SERVER_ERROR	500	服务器内部错误	是(1次)	退避重试 1 次，仍失败提示稍后再试

根因说明：服务端原本所有业务错误统一返回 {statusCode, message}，无机器可读 code。本表为建议新增的 code 字段（一处改动多表受益），其中上传/媒体类必须与「取图失败」用不同 code——这是修复「发送失败被说成图片打不开」问题的前提。

WSWebSocket 实时通道

项	说明
地址	/im 命名空间（socket.io）
握手	auth.token 传登录 token
事件	presence / typing / message 推送 / recall / call（WebRTC 信令）/ group-call-* / location-share
离线推送	⚠️ 无 APNs/FCM 离线推送；离线消息靠重连后补拉

离线补拉口径：socket connect/reconnect 后固定执行一次 listConversations + messages(afterId=最后已读) 游标翻页（每页 ≤200，无硬上限）。游标按 id 单调递增不丢、不重复；服务重启瞬间的 socket 事件会丢，需补拉兜底。

01登录 · login.html

验证码 / 密码双 Tab 登录，支持微信与扫码。对应 App 登录注册模块。

方法	路径	鉴权	说明
POST	/api/auth/register	公开	注册（账号 6 位 + 手机号 + 密码，密码 ≥8 位含大小写数字）
POST	/api/auth/login	公开	登录 → 返回 {account_no, token, expires_at, kdf_salt, msg_key_env}
POST	/api/auth/forgot-password	公开	申请重置码（账号+手机匹配）
POST	/api/auth/forgot-password/verify	公开	凭码重置密码
GET	/api/auth/me	🔒	本人资料 + 钱包 + 好友数 + 隐私开关

02发现 · index.html

瀑布流信息流 + 频道切换（推荐/关注/同城/旅行/穿搭/美食/生活/好物），对应 App 笔记 feed。

方法	路径	鉴权	说明
GET	/api/moment/feed	🔒	信息流（游标 id 降序）
GET	/api/moment/:id	🔒	动态详情（canView 鉴权）
POST	/api/moment/:id/like	🔒	点赞 / 取消
POST	/api/moment/:id/favorite	🔒	收藏 / 取消
GET	/api/search/global	🔒	顶部搜索框（跳搜索页）

03照片墙 · wall.html

城市筛选 + 按点赞量排行榜（Top3 领奖台 + 4–10 榜单行）。用户要求仅保留「城市选项 + 排行榜」。

方法	路径	鉴权	说明
GET	/api/wall/feed	🔒	照片墙流（VIP 分流：非 VIP 仅 blur_url）
GET	/api/wall/rank	🔒	点赞排行榜（Top3 + 榜单）
GET	/api/wall/quota	🔒	上墙配额（本月免费 1 张）
GET	/api/wall/mine	🔒	我的照片
GET	/api/wall/liked	🔒	我赞过的
POST	/api/wall/like	🔒	点赞 / 取消
POST	/api/wall/from-moment	🔒	笔记一键上墙
POST	/api/wall/upload-from-album	🔒	相册直传上墙
POST	/api/wall/:id/remove	🔒	下架
GET	/api/vip/status	🔒	VIP 状态（墙通行证额度）

城市筛选：当前接口清单未提供独立的城市维度参数，城市筛选为前端本地过滤（对 rank/feed 结果按 city 字段分组），或需服务端在 wall/feed、wall/rank 增加 ?city= 查询参数。

04搜索 · search.html

全局搜索，Tab 分类：全部 / 笔记 / 用户 / 圈子 / 悬赏。

方法	路径	鉴权	说明
GET	/api/search	🔒	全局搜索
GET	/api/search/global	🔒	全局搜索（聚合）
GET	/api/account/search	🔒	账号搜索（用户 Tab）

05笔记详情 · note.html

左图右评论布局，含图文、话题、浏览/访客记录、评论二级回复、点赞收藏转发。

方法	路径	鉴权	说明
GET	/api/moment/:id	🔒	动态详情
GET	/api/moment/:id/comment	🔒	评论列表
POST	/api/moment/:id/comment	🔒	发评论（可 parentId 二级回复）
DELETE	/api/moment/comment/:id	🔒	删评论（本人或管理员）
POST	/api/moment/comment/:id/like	🔒	评论点赞
POST	/api/moment/:id/like	🔒	点赞
POST	/api/moment/:id/favorite	🔒	收藏
POST	/api/im/note/forward	🔒	转发到聊天
GET	/api/moment/:id/viewers	🔒	阅读记录（仅作者）

06个人主页 · profile.html

封面横幅 + 头像悬浮 + 资料卡 + 四个内容 Tab（笔记/收藏/上墙/悬赏）。

方法	路径	鉴权	说明
GET	/api/auth/me	🔒	本人资料（昵称/状态/微号）
POST	/api/auth/profile	🔒	编辑资料（nickname/gender/bio/cover 等）
GET	/api/user/qrcode	🔒	二维码名片
GET	/api/moment/feed	🔒	我的笔记/动态（笔记 Tab）
GET	/api/moment/favorites	🔒	我的收藏（收藏 Tab）
GET	/api/wall/mine	🔒	上墙照片（上墙 Tab）
GET	/api/account/avatar	🔒	头像

07IM 聊天 · im.html

桌面双栏（会话列表 + 聊天窗），支持文字、图集、语音、红包、转账、群投票、群接龙、已读回执。

方法	路径	鉴权	说明
GET	/api/im/conversations	🔒	会话列表（含未读数）
POST	/api/im/conversation	🔒	开私聊会话（peer）
POST	/api/im/message	🔒	发消息（client_msg_id 幂等，文字端到端加密）
GET	/api/im/messages/:convType/:convId	🔒	拉历史/增量（afterId/beforeId/aroundId 游标，limit≤200）
POST	/api/im/upload-media	🔒	媒体上传（raw body + kind=image/video）
POST	/api/im/read	🔒	标记已读（lastReadMessageId）
GET	/api/im/unread/:convType/:convId	🔒	未读数
POST	/api/im/recall/:messageId	🔒	撤回（2 分钟限时，仅发送者）
POST	/api/im/forward	🔒	转发（单条）
POST	/api/im/forward-batch	🔒	转发（多条）
DELETE	/api/im/messages/batch	🔒	多选删除
POST	/api/im/tip	🔒	聊天打赏
POST	/api/im/group/:id/vote	🔒	群投票
POST	/api/im/group/:id/relay	🔒	群接龙
POST	/api/wallet/transfer	🔒	转账（红包/转账卡片）
GET	/api/im/call/history	🔒	通话记录

已读/送达口径：delivered_at（消息表）= 接收方拉取到该消息时写入，仅 private 与 note 消息写；read_receipt 按 (conv_type, conv_id, account_no) UPSERT last_read_message_id。UI 建议：单聊显示「已读/未读」（对方 last_read ≥ 该消息 id），群聊不显示已读（微信同款）。

删除语义：服务端 deleteMessagesBatch 写 message_hidden（仅自己隐藏），客户端删除为纯本机行为；删除后应用本地库剩余最后一条重算会话预览，不要调服务端删除接口。

08圈子 · circle.html

圈子广场 + 热帖，支持创建圈子、加入、帖子评论点赞。

方法	路径	鉴权	说明
POST	/api/im/circle	🔒	建圈子
POST	/api/im/circle/:id/join	🔒	加入圈子
GET	/api/im/circle/:id/posts	🔒	圈子帖子列表
POST	/api/im/circle/:id/posts	🔒	发帖
GET	/api/moment/:id/comment	🔒	帖子评论
POST	/api/moment/:id/like	🔒	帖子点赞

09悬赏 · task.html

同城悬赏，用微币发布/接单，完成结算入钱包，解锁联系方式需支付。

方法	路径	鉴权	说明
GET	/api/task	🔒	悬赏列表（城市/金额/距离/截止排序）
POST	/api/task	🔒	发布悬赏（金额 0–1,000,000 微币）
POST	/api/task/:id/accept	🔒	接单（不可接自己的单）
POST	/api/task/:id/complete	🔒	确认完成（触发结算）
POST	/api/wallet/transfer	🔒	结算入钱包
GET	/api/wallet/:accountNo/ledgers	🔒	已结算收入流水

提示：/api/task 的具体子路径（accept/complete 等）在接口清单中仅以「task 🔒 /api/task（发单/接单/悬赏）」概括，落地时需向服务端确认精确路由。

10发布 · publish.html

图文/视频发布，最多 18 张媒体，支持定位、圈子同步、可见范围、允许下载/复制、草稿。

方法	路径	鉴权	说明
POST	/api/moment/media	🔒	上传动态媒体
POST	/api/moment	🔒	发动态（simple/rich，含可见范围 visibility）
GET	/api/moment/draft	🔒	读草稿
PUT	/api/moment/draft	🔒	保存草稿
DELETE	/api/moment/draft	🔒	删草稿
POST	/api/chunkupload/init	🔒	分片上传初始化（kind/totalSize/fileName）
POST	/api/chunkupload/chunk	🔒	上传单片
POST	/api/chunkupload/complete	🔒	合并 + 转码 + 秒发

大文件分片流程：init（拿 uploadId/chunkSize）→ 循环 chunk（raw body + uploadId/index/md5）→ complete（合并校验）。首次上传媒体进入审核态（reviewing）。

11钱包 · wallet.html

微币余额、充值申请（人工审核）、站内转账、支付密码服务端校验。合规：禁止提现/退币。

方法	路径	鉴权	说明
GET	/api/wallet/:accountNo/balance	🔒	余额
POST	/api/wallet/transfer	🔒	转账（toAccount, amount, payPassword）
GET	/api/wallet/pay-password/status	🔒	支付密码状态
POST	/api/wallet/pay-password	🔒	设置支付密码（6 位数字）
POST	/api/wallet/pay-password/change	🔒	改支付密码（需旧密码）
GET	/api/wallet/:accountNo/ledgers	🔒	流水（≤500）
POST	/api/wallet/recharge-request	🔒	充值申请（人工审核）
GET	/api/wallet/recharge-requests/mine	🔒	我的充值申请

12会员 · member.html

周卡/月卡套餐购买，特权：墙通行证、身份徽章、优先审核。

方法	路径	鉴权	说明
GET	/api/member/me	🔒	我的会员状态
GET	/api/member/plans	🔒	套餐列表（体验卡/周卡/月卡）
POST	/api/member/open	🔒	购买会员（微币支付）
GET	/api/vip/status	🔒	VIP 状态

13设置 · settings.html

账号安全、隐私、效率功能、关于四大分区。

方法	路径	鉴权	说明
GET	/api/auth/sessions	🔒	我的会话/设备列表
DELETE	/api/auth/sessions/:id	🔒	踢某设备下线
POST	/api/auth/password	🔒	改登录密码（需旧密码）
POST	/api/auth/deactivate	🔒	自助注销（余额须为 0）
POST	/api/account/appeal	🔒	账号申诉 / 数据导出
POST	/api/auth/profile	🔒	隐私开关（show_/single_device/teen_mode/privacy_）
GET	/api/block	🔒	黑名单列表
POST	/api/block	🔒	拉黑 / 取消
GET	/api/friend/tags	🔒	会话分组（标签分组）
GET	/api/help/categories	公开	帮助中心分类
GET	/api/help/articles	公开	帮助中心文章
POST	/api/report	🔒	意见反馈 / 提交举报
GET	/api/app/version	公开	版本号

APPX附录 · 其他接口模块

以下模块由多个页面共用，单独列出便于查询。

好友 friend🔒

方法	路径	说明
POST	/api/friend/request	发好友申请（target 账号 + via 渠道）
GET	/api/friend/requests	收到的好友申请
POST	/api/friend/request/:id/accept	同意
POST	/api/friend/request/:id/reject	拒绝
GET	/api/friend/list	好友列表
GET	/api/friend/stats	好友数与 gate
POST	/api/friend/match-contacts	通讯录匹配（≤200 手机号）
DELETE	/api/friend/:accountNo	删好友

媒体 / 分片上传 media · chunkupload🔒

方法	路径	说明
POST	/api/media/upload	媒体上传
GET	/api/media/mine	我的媒体
GET	/api/media/:id	媒体详情
POST	/api/chunkupload/init	初始化分片
POST	/api/chunkupload/chunk	上传单片
POST	/api/chunkupload/complete	合并 + 转码 + 秒发
GET	/api/uploads/media/{orig,preview,thumb,video,cover,file,audio}/<名>?sig=	媒体访问（需 sig 签名）

其他模块Misc

模块	关键路径	说明
account	/api/account/search · avatar · appeal	账号搜索 / 头像 / 申诉
user	/api/user/qrcode · status	我的二维码 / 状态
block	/api/block · /api/block/status/:account	拉黑列表 / 拉黑状态
report	/api/report · /reports👑 · /:id/resolve👑	举报 / 举报列表 / 处理
favorite	/api/favorite	收藏 CRUD
config	/api/config/rtc · /api/config/:key	RTC 配置 / 通用配置
health	/api/health	健康检查