Files

T

guke a563c1ca4b @ (#111 )

docs/api目录文档分类和补全

---------

Co-authored-by: guke <guke@autohome.com.cn>
Reviewed-on: #111

2026-07-03 15:00:37 +08:00

邀请绑定（bind + landing-track）

所属:Invite 组（前缀 /api/v1/invite） | 鉴权:bind 需 Bearer / landing-track 无需鉴权 | ← 返回 API 索引

POST /bind — 绑定邀请人

把当前登录用户（被邀请人）绑定到某邀请码。支持三种归因路径：clipboard（首启读剪贴板）、manual（手动输入邀请码）、fingerprint（指纹兜底反查）。绑定成功双方各发 1 万金币。

字段	类型	必填	说明
`invite_code`	string \| null	❌	邀请码；走指纹兜底时为空
`channel`	string	✅	归因来源：`clipboard` / `manual` / `fingerprint`
`fingerprint`	object \| null	❌	指纹兜底时必传
`fingerprint.screen`	string	-	屏幕分辨率（如 `1080x2400`）
`fingerprint.device_model`	string	-	设备型号（如 `24115RA8EC`）

Mock 入参（clipboard 归因）:

{
  "invite_code": "A3F8K2",
  "channel": "clipboard",
  "fingerprint": null
}

Mock 入参（指纹兜底）:

{
  "invite_code": null,
  "channel": "fingerprint",
  "fingerprint": {
    "screen": "1080x2400",
    "device_model": "24115RA8EC"
  }
}

响应 200:BindInviteOut

字段	类型	说明
`status`	string	`success` / `already_bound` / `invalid_code` / `self_invite` / `not_eligible` / `fp_not_found`
`coins_awarded`	int	本次给当前用户（被邀请人）发的金币
`message`	string	给前端直接展示的文案

Mock 出参:

{
  "status": "success",
  "coins_awarded": 10000,
  "message": "邀请绑定成功"
}

B 浏览器打开 dl.html?ref=xxx 时上报指纹（剪贴板归因失败时兜底）。无需鉴权（浏览器没 token）。

字段	类型	必填	说明
`ref`	string	✅（4-16 位）	邀请码（落地页 `?ref=`）
`screen`	string	❌	屏幕分辨率（如 `1080x2400`）

Mock 入参:

{
  "ref": "A3F8K2",
  "screen": "1080x2400"
}

响应 200:LandingTrackOut

字段	类型	说明
`status`	string	`ok` / `invalid_code` / `no_ip`

Mock 出参:

{"status": "ok"}