#Jira 兼容 API

Jira 兼容 API 让为 Jira 编写的工具（命令行、报表、CI 插件、自动化脚本）不改代码逻辑、只改一个地址就能直接读写 HiFox 的任务。

所有端点兼容 Jira REST v2 / v3 的请求与响应格式：

• 响应是 Jira 的 issue / comment / search 形状，含 issuetype、duedate、statusCategory 等 Jira 字段拼写；
• 错误统一是 {"errorMessages": [...], "errors": {...}}；
• 分页统一使用 startAt / maxResults；
• v2 返回纯文本描述，v3 返回 ADF 文档。

#基本约定

Base URL

所有请求都发往你组织专属的子域名：

https://<组织 slug>.jira-api.hifox.com/rest/api/2/...
https://<组织 slug>.jira-api.hifox.com/rest/api/3/...

组织 slug 就是组织主页地址里的那段标识（https://app.hifox.com/my-team/ 中的 my-team）。

认证

使用个人访问令牌（PAT，参见「个人访问令牌」文档）：

# Bearer
curl -H "Authorization: Bearer hfx_xxx" \
  https://my-team.jira-api.hifox.com/rest/api/2/myself

令牌属于哪个成员，API 就以哪个成员的身份读写：能看到哪些空间、能改哪些任务，与在产品里完全一致；写操作会照常产生动态、通知、Agent 分配触发与双向同步回写。

速率限制：默认每个来源每分钟 600 次请求。超限返回 429。

可见性：不是该组织成员的令牌访问该组织时返回 404（不暴露组织是否存在）。

#概念映射

任务编号在每个空间内独立计数，因此 API 里 issue 一律用 key 形式（TEAM-42）访问；单独传数字编号会被拒绝并提示改用 key。

#端点清单

#当前用户与站点

#项目（空间）

#Issue（任务）

#元数据与用户

#创建 issue

curl -X POST \
  -H "Authorization: Bearer hfx_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "project":     {"key": "TEAM"},
      "summary":     "登录页在 Safari 崩溃",
      "description": "复现步骤：…",
      "issuetype":   {"name": "缺陷"},
      "priority":    {"name": "High"},
      "labels":      ["frontend", "login"],
      "duedate":     "2026-12-31"
    }
  }' \
  https://my-team.jira-api.hifox.com/rest/api/2/issue

响应 201：

{
  "id": "42",
  "key": "TEAM-42",
  "self": "https://my-team.jira-api.hifox.com/rest/api/2/issue/TEAM-42"
}

#更新 issue

PUT /issue/{key} 支持修改 summary、description、priority、assignee、duedate、labels、issuetype、parent。显式传 "assignee": null 即可清空处理人：

curl -X PUT \
  -H "Authorization: Bearer hfx_xxx" \
  -H "Content-Type: application/json" \
  -d '{"fields": {"assignee": null}}' \
  https://my-team.jira-api.hifox.com/rest/api/2/issue/TEAM-42

成功返回 204。

#流转（transitions）

GET /issue/{key}/transitions 返回该任务类型工作流里所有可到达的状态；transition 的 id 就是目标状态。执行流转：

curl -X POST \
  -H "Authorization: Bearer hfx_xxx" \
  -H "Content-Type: application/json" \
  -d '{"transition": {"id": "<transition id>"}}' \
  https://my-team.jira-api.hifox.com/rest/api/2/issue/TEAM-42/transitions

成功返回 204。

#JQL 搜索

GET /rest/api/2/search?jql=assignee = currentUser() AND status != Done ORDER BY priority DESC

支持常用子集：

• 字段：project、issuetype、status、statusCategory、resolution、priority、assignee、reporter、creator、labels、summary、description、text、created、updated、duedate、key、id；
• 操作符：= != > >= < <= ~ !~、IN / NOT IN、IS [NOT] EMPTY，以及 AND / OR / NOT 和括号；
• 函数：currentUser()；时间支持 2026-10-08 与相对偏移（-7d、-2w、-1M、-1y）；
• 排序：ORDER BY 支持 key、created、updated、priority、status、assignee、summary、duedate。

分页：startAt（默认 0）、maxResults（默认 50、上限 100；传 0 只返回 total）。

字段或语法有误时返回 400 和 Jira 格式错误体，例如：

{
  "errorMessages": [
    "Error in the JQL Query: Field 'bogus' does not exist or you do not have permission to view it."
  ]
}

#与 Jira 的差异

• 没有 webhooks、agile/boards、attachments、worklog、watchers、custom fields 映射（后续按需开放）；
• resolution 从状态推导：处于终态分类（完成 / 已取消 / 重复）视作 Done，否则为 Unresolved；
• v3 的 /search 是经典 GET 端点（不含 Jira Cloud 的 POST /search/jql）。

#常见问题

用数字 id 访问 issue 为什么报错？ 任务编号按空间计数，不同空间会有相同编号；请始终使用 key（TEAM-42）。

能看到别的组织吗？ 不能。URL 里的组织决定了一切，非本组织成员一律 404。

写入会触发自动化吗？ 会。写路径与产品界面完全一致：动态、通知、Agent 触发、双向同步回写全部照常发生。