guke
a563c1ca4b
docs/api目录文档分类和补全 --------- Co-authored-by: guke <guke@autohome.com.cn> Reviewed-on: #111
101 lines
2.5 KiB
Markdown
101 lines
2.5 KiB
Markdown
# 邀请绑定（bind + landing-track）
|
||
|
||
> 所属:Invite 组（前缀 `/api/v1/invite`） | 鉴权:bind 需 Bearer / landing-track 无需鉴权 | [← 返回 API 索引](../README.md)
|
||
|
||
---
|
||
|
||
## 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 归因）:
|
||
```json
|
||
{
|
||
"invite_code": "A3F8K2",
|
||
"channel": "clipboard",
|
||
"fingerprint": null
|
||
}
|
||
```
|
||
|
||
Mock 入参（指纹兜底）:
|
||
```json
|
||
{
|
||
"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 出参:
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"coins_awarded": 10000,
|
||
"message": "邀请绑定成功"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## POST /landing-track — 落地页指纹采集
|
||
|
||
B 浏览器打开 `dl.html?ref=xxx` 时上报指纹（剪贴板归因失败时兜底）。**无需鉴权**（浏览器没 token）。
|
||
|
||
### 入参
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| `ref` | string | ✅（4-16 位） | 邀请码（落地页 `?ref=`） |
|
||
| `screen` | string | ❌ | 屏幕分辨率（如 `1080x2400`） |
|
||
|
||
Mock 入参:
|
||
```json
|
||
{
|
||
"ref": "A3F8K2",
|
||
"screen": "1080x2400"
|
||
}
|
||
```
|
||
|
||
### 出参
|
||
|
||
响应 `200`:`LandingTrackOut`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `status` | string | `ok` / `invalid_code` / `no_ip` |
|
||
|
||
Mock 出参:
|
||
```json
|
||
{"status": "ok"}
|
||
```
|
||
|
||
---
|
||
|
||
## 说明
|
||
- `bind`: 绑定只在注册后首次有效（`not_eligible` = 已过新人期），自邀屏蔽
|
||
- `landing-track`: IP/UA 服务端从 HTTP 头自动拿，JS 无需上报
|
||
- 指纹反查窗口期由 `INVITE_FP_WINDOW_DAYS` 控制
|