POST公开接口
提交用户反馈
客户端提交评分与反馈内容。服务端会额外记录调用方 IP、User-Agent 与解析出的地区； 未声明 platform 时按 User-Agent 推断。短时间内（默认 60 秒，可用 VERHUB_DEDUP_WINDOW_SECONDS 调整）同一调用方提交完全相同的内容会被判为重复提交， 直接返回已存在的那条记录而不新建。 `forward_to_github` 由提交者逐条选择，默认 false。传 true 时： - 项目必须已开放转发（见 `GET /public/{projectKey}/feedbacks/options`），否则 400； - `contact` 必填，缺失时 400（SDK 在本地就会拒绝，请求不会发出）； - 受单 IP 转发限流约束（默认每小时 3 次，`VERHUB_GITHUB_FORWARD_RATE_LIMIT` 可调）， 超额返回 429； - Issue 建成功才记录这条反馈：GitHub 侧失败时返回 503 且服务端不留任何记录， 客户端可提示用户稍后重试或去掉转发再提交。 转发成功的记录会带上 `forwarded_to_github`、`github_issue_number` 与 `github_issue_url`。上述错误 SDK 均原样透传给客户端处理。
URL
/api/v1/public/{projectKey}/feedbacks鉴权方式
无需鉴权
请求参数
Path 参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| projectKey | string | 是 | 项目主键 project_key（大小写不敏感） |
Header 参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| x-verhub-platform | windows | linux | macos | ios | android | web | others | 否 | 客户端平台声明，仅用于请求统计，不影响接口返回内容。 识别优先级：本请求头 > query 参数 `platform` > 请求体 `platform` 字段 > User-Agent 推断。 取值大小写不敏感，无法识别时统计为 OTHERS。 具体系统版本请用 `x-verhub-platform-version` 单独提交；若把版本混在本字段里 （如 `Windows 11`、`ubuntu 24.04`），服务端会拆开，平台与版本分别入库。 建议 SDK 显式声明本请求头：服务端调用的 User-Agent 往往不可靠。 |
| x-verhub-platform-version | string | 否 | 客户端系统版本明细，仅用于请求统计，不影响接口返回内容。 自由文本，如 `11`、`ubuntu 24.04`、`26`；超过 32 字符视为无效直接丢弃。 识别优先级：本请求头 > query 参数 `platform_version` > 请求体 `platform_version` 字段 > 从 `platform` 中拆出的版本 > User-Agent 推断。 |
请求体
{
"user_id": "user-001",
"rating": 5,
"content": "更新检查很好用。",
"contact": "[email protected]",
"forward_to_github": false,
"platform": "windows",
"platform_version": "11",
"custom_data": {
"app_version": "1.2.0"
}
}响应示例
201 响应
{
"id": "fb-001",
"user_id": "user-001",
"rating": 5,
"content": "更新检查很好用。",
"contact": "[email protected]",
"is_hidden": false,
"platform": "windows",
"platform_version": "11",
"custom_data": {
"app_version": "1.2.0"
},
"ip": "203.0.113.9",
"user_agent": "verhub-sdk/1.0",
"country_code": "CN",
"country_name": "中国",
"region_name": "广东省",
"city": "深圳",
"created_at": 1760000000
}POST
