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 推断。 |
| x-verhub-client-time | string | 否 | 客户端发出请求时的本地时间，ISO 8601 并带显式 UTC 偏移，官方 SDK 默认附带。 仅用于统计，不影响接口返回内容：偏移让请求与事件热力图按用户当地时间折叠 （没带时按来源国家的代表时区近似）；与服务端接收时间的差值用于校正同一批 事件的 `occurred_at`（偏差不足 60 秒视为网络延迟，不校正）。 缺偏移、偏移超出 UTC-12:00 至 UTC+14:00 或不是 15 分钟整数倍的取值按未上报处理，不会报错。 |
请求体
{
"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
