Feedback API

Almirant 提供一个公开 REST API（非 MCP），用于从嵌入网站的小组件或服务器到服务器的集成接收反馈。此 API 独立于 MCP 服务器，不需要 Almirant API Key。

身份验证

Feedback API 使用基于 Public Keys 和 widget tokens 的身份验证系统：

Public Key (pk_...)：用于标识反馈来源。创建 Almirant 中的反馈来源时获得，可安全地暴露在前端。
Widget Token：通过 bootstrap endpoint 获取的临时签名令牌。它有有限的有效期，用于验证接收请求。

Endpoints

`GET /feedback/widget/bootstrap`

初始化反馈小组件。返回来源配置以及发送反馈所需的临时签名令牌。

Query Parameters：

名称	类型	必填	说明
publicKey	string	是	反馈来源的 Public Key (`pk_...`)

请求示例：

curl "https://api.almirant.ai/feedback/widget/bootstrap?publicKey=pk_abc123def456"

成功响应 (200)：

{
  "success": true,
  "data": {
    "source": {
      "publicKey": "pk_abc123def456",
      "type": "widget",
      "name": "Web App Feedback"
    },
    "token": "eyJzb3VyY2VJZCI6Ii4uLiJ9.a1b2c3d4e5f6",
    "expiresAt": 1708531200,
    "config": {
      "requireCaptcha": true
    }
  }
}

错误：

代码	说明
404	未找到所提供 publicKey 对应的反馈来源
403	请求来源（域名）不在允许域名列表中

`POST /feedback/ingest`

发送一个反馈项。需要从 bootstrap endpoint 获取的令牌。

Headers：

Content-Type: application/json

Body：

名称	类型	必填	说明
publicKey	string	是	反馈来源的 Public Key
token	string	是	从 `bootstrap` 获取的 Widget token
message	string	是	反馈内容（1-5000 个字符）
category	string	否	类别：`bug`、`feature_request`、`improvement`、`question`、`praise`、`other`
email	string	否	发送者的电子邮件
pageUrl	string	否	提交反馈所在页面的 URL
locale	string	否	用户的语言/locale
captchaToken	string	否	hCaptcha 令牌（来源启用 captcha 时必填）

请求示例：

curl -X POST "https://api.almirant.ai/feedback/ingest" \
  -H "Content-Type: application/json" \
  -d '{
    "publicKey": "pk_abc123def456",
    "token": "eyJzb3VyY2VJZCI6Ii4uLiJ9.a1b2c3d4e5f6",
    "message": "El formulario de registro no valida emails correctamente",
    "category": "bug",
    "email": "[email protected]",
    "pageUrl": "https://miapp.com/registro",
    "locale": "es"
  }'

成功响应 (201)：

{
  "success": true,
  "data": {
    "id": "fb-uuid-001",
    "status": "new",
    "createdAt": "2025-02-15T10:30:00.000Z"
  }
}

错误：

代码	说明
400	captcha 令牌无效或缺失（需要 captcha 时）
401	Widget token 无效或已过期
403	请求来源（域名）不被允许
404	未找到反馈来源
409	检测到重复反馈（最近发送了相同内容）
429	超出速率限制

完整集成流程

1. Widget se carga en la pagina del usuario
   |
2. GET /feedback/widget/bootstrap?publicKey=pk_...
   |-- Obtiene token temporal + configuracion
   |
3. Usuario escribe feedback y envia
   |
4. POST /feedback/ingest
   |-- publicKey + token + message + metadata
   |
5. Feedback aparece en Almirant como item nuevo

保护措施

API 包含以下保护措施：

来源验证：仅接受来自反馈来源中配置的域名的请求（支持 *.midominio.com 等通配符）
已签名的 Widget tokens：具有临时过期时间的 HMAC-SHA256 令牌
速率限制：在时间窗口内限制每个 IP 和来源的请求数量
去重：检测并拒绝最近发送的重复反馈（基于标准化内容的 SHA-256 哈希）
hCaptcha：按来源提供可选的 captcha 验证（默认启用）

反馈类别

类别	说明
`bug`	错误或故障报告
`feature_request`	新功能请求
`improvement`	对现有功能的改进建议
`question`	问题或信息请求
`praise`	正面评论
`other`	未指定时的默认类别

服务器到服务器集成

对于来自后端的集成（不使用小组件），流程相同：先调用 bootstrap 获取令牌，再将反馈发送至 ingest。区别在于，你必须确保请求的来源域名位于反馈来源的允许列表中，或将来源配置为不限制域名。

将反馈关联到想法

提交的反馈可使用 MCP tool link_feedback_to_idea_item 关联到 Idea Hub 项。这会在用户反馈和产品决策之间建立可追溯性。

身份验证​

Endpoints​

GET /feedback/widget/bootstrap​

POST /feedback/ingest​

完整集成流程​

保护措施​

反馈类别​

服务器到服务器集成​