zentao-api

禅道 API v2.0

設定

優先順位の高い順：

変数	説明
ZENTAO_URL	サーバーアドレス。例：http://zentao.example.com
ZENTAO_TOKEN	token を直接指定します。ログインとキャッシュをスキップします（最優先）。サーバーアドレスは引き続き必要です
ZENTAO_ACCOUNT	ログインアカウントです。token がある場合は任意ですが、指定すると現在のユーザーに関する質問により適切に回答できます
ZENTAO_PASSWORD	ログインパスワードです。token がある場合は不要です

初回ログイン後、ZENTAO_URL、ZENTAO_TOKEN、ZENTAO_ACCOUNT は ~/.zentao-token.json に保存されるため、以降は再設定する必要はありません。

必要な変数が不足している場合は、ユーザーに知らせて export コマンドを提示してください。ユーザーがサーバー、アカウント、パスワードを直接指定した場合は、そのまま使用し、できるだけ環境変数に設定するよう案内してください。

認証フロー

すべての業務 API では、Header に token を含める必要があります。scripts/get-token.sh を実行して自動取得します：

eval "$(bash scripts/get-token.sh)"
# 执行后可直接使用 $ZENTAO_URL、$ZENTAO_TOKEN、$ZENTAO_ACCOUNT

スクリプトの依存関係：curl、node

以降のすべてのリクエストでは、Header に token: $ZENTAO_TOKEN を含めます。

API 呼び出しの手順

1. eval "$(bash scripts/get-token.sh)" を実行して認証情報を取得します（キャッシュを自動処理します。不足が残る場合はユーザーに知らせます）
2. ユーザーの意図に応じて適切な API エンドポイントを選択します（api-reference.md を参照）
3. PUT による編集操作で、ユーザーが必須フィールドをすべて指定していない場合は、対応する GET 詳細取得インターフェースを呼び出して現在のデータを取得し、ユーザーが指定したフィールドで上書きします
4. リクエスト（メソッド、URL、Header、Body）を構成し、書き込み操作の内容をユーザーに確認します
5. リクエストを実行し、レスポンスを解析します
6. 結果をわかりやすく読みやすい形式でユーザーに提示します

モジュール一覧

API のベースパス：$ZENTAO_URL/api.php/v2

モジュール	リソースパス	対応操作
プロジェクトセット Program	/programs	CRUD + 関連する製品／プロジェクトの一覧
製品 Product	/products	CRUD + 関連する要件／Bug／テストケース／計画／リリース／フィードバック／チケット／テストタスク／アプリケーション
プロジェクト Project	/projects	CUD + 関連する実行／要件／Bug／テストケース／ビルド／テストタスク
実行 Execution	/executions	CRUD + 関連する要件／タスク／Bug／テストケース／ビルド／テストタスク
要件 Story	/stories	CRUD + change/close/activate
業務要件 Epic	/epics	CRUD + change/close/activate
ユーザー要件 Requirement	/requirements	CRUD + change/close/activate
Bug	/bugs	CRUD + resolve/close/activate
タスク Task	/tasks	CRUD + start/finish/close/activate
テストケース Testcase	/testcases	CRUD
製品計画 Productplan	/productplans	CUD + 製品ごとの一覧取得
ビルド Build	/builds	CUD + プロジェクト／実行ごとの一覧取得
リリース Release	/releases	CUD + 製品ごとの一覧取得
テストタスク Testtask	/testtasks	CUD + 製品／プロジェクト／実行ごとの一覧取得
フィードバック Feedback	/feedbacks	CRUD + close/activate
チケット Ticket	/tickets	CRUD + close/activate
アプリケーション System	/systems	CU + 製品ごとの一覧取得
ユーザー User	/users	CRUD
ファイル File	/files	名前の編集 + 削除

CRUD = 作成(POST) + 取得(GET) + 更新(PUT) + 削除(DELETE)；CUD = 独立した全体一覧インターフェースなし

ページネーションとフィルター

すべての一覧インターフェースで、共通のクエリパラメーターに対応しています：

パラメーター	説明
browseType または status	状態で絞り込みます。例：all、doing、unclosed、undone など（モジュールによってパラメーター名と選択可能な値が異なります。詳しくは api-reference.md を参照）
orderBy	並べ替えます。形式は フィールド_asc または フィールド_desc です。例：id_desc、title_asc
recPerPage	1ページあたりの件数です。最大 1000 です
pageID	ページ番号です。1 から始まります

フィルターパラメーター名は統一されていません：Program の一覧、Execution の全体一覧、Task の一覧では status を使用し、それ以外では browseType を使用します。

よく使う操作の例

進行中のプロジェクトとその実行を取得する

curl -s "$ZENTAO_URL/api.php/v2/projects?browseType=doing&recPerPage=100" -H "token: $ZENTAO_TOKEN"
curl -s "$ZENTAO_URL/api.php/v2/projects/{projectID}/executions?browseType=doing" -H "token: $ZENTAO_TOKEN"

要件を作成する（必須：productID, title）

curl -s -X POST "$ZENTAO_URL/api.php/v2/stories" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"productID": 1, "title": "需求标题", "grade": 1, "pri": 3, "assignedTo": "admin", "spec": "需求描述"}'

業務要件を作成する（Epic）

curl -s -X POST "$ZENTAO_URL/api.php/v2/epics" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"productID": 1, "title": "业务需求标题", "grade": 1, "pri": 3, "reviewer": ["admin"]}'

ユーザー要件を作成する（Requirement）

curl -s -X POST "$ZENTAO_URL/api.php/v2/requirements" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"productID": 1, "title": "用户需求标题", "parent": 1001, "grade": 1, "pri": 3, "reviewer": ["admin"]}'

Bug を作成する（必須：productID, title, openedBuild）

curl -s -X POST "$ZENTAO_URL/api.php/v2/bugs" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"productID": 1, "title": "Bug标题", "openedBuild": ["trunk"], "severity": 2, "type": "codeerror"}'

Bug を解決する（必須：resolution）

curl -s -X PUT "$ZENTAO_URL/api.php/v2/bugs/{bugID}/resolve" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"resolution": "fixed"}'

タスクを作成する（必須：name, executionID）

curl -s -X POST "$ZENTAO_URL/api.php/v2/tasks" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"executionID": 1, "name": "任务名", "type": "devel", "assignedTo": "admin", "estimate": 4}'

タスクを完了する（必須：currentConsumed, realStarted, finishedDate）

curl -s -X PUT "$ZENTAO_URL/api.php/v2/tasks/{taskID}/finish" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"currentConsumed": 4, "realStarted": "2026-03-25", "finishedDate": "2026-03-25"}'

要件をクローズする（必須：closedReason）

curl -s -X PUT "$ZENTAO_URL/api.php/v2/stories/{storyID}/close" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"closedReason": "done"}'

常用枚举值速查

字段	可选值
项目模式 model	scrum, waterfall, kanban, agileplus, waterfallplus
Bug 类型 type	codeerror, config, install, security, performance, standard, automation, designdefect, others
Bug 解决方案 resolution	fixed, notrepro, bydesign, duplicate, external, postponed, willnotfix, tostory
需求关闭原因 closedReason	done, subdivided, duplicate, postponed, willnotdo, cancel, bydesign
需求来源 source	customer, user, po, market, service, operation, support, competitor, partner, dev, tester, bug, forum, other
需求类别 category	feature, interface, performance, safe, experience, improve, other
用例类型 type	unit, interface, feature, install, config, performance, security, other
测试单类型 type	integrate, system, acceptance, performance, safety
发布状态 status	wait, normal, fail, terminate
反馈关闭原因 closedReason	commented, repeat, refuse
工单类型 type	code, data, stuck, security, affair
产品类型 type	normal, branch, platform
产品访问控制 acl	open, private
执行类型 lifetime	short, long, ops

意图识别规则

用户意图关键词	对应操作
进行中的执行/迭代/Sprint	GET /projects?browseType=doing → GET /projects/{id}/executions
获取所有产品/项目/项目集	GET /products, /projects, /programs
某产品/项目/执行的 Bug	GET /products/{id}/bugs, /projects/{id}/bugs, /executions/{id}/bugs
创建/新增 Bug	POST /bugs（必填：productID, title, openedBuild）
更新/修改 Bug	PUT /bugs/{id}
解决 Bug	PUT /bugs/{id}/resolve（必填：resolution）
关闭 Bug	PUT /bugs/{id}/close
激活 Bug	PUT /bugs/{id}/activate
创建需求	POST /stories（必填：productID, title）
关闭/激活/变更需求	PUT /stories/{id}/close, /activate, /change
业务需求	/epics（同 stories 结构）
用户需求	/requirements（同 stories 结构）
创建任务	POST /tasks（必填：name, executionID）
启动任务	PUT /tasks/{id}/start（必填：realStarted）
完成任务	PUT /tasks/{id}/finish（必填：currentConsumed, realStarted, finishedDate）
关闭任务	PUT /tasks/{id}/close
测试用例	/testcases（CRUD）
测试单	/testtasks（CUD + 按产品/项目/执行查列表）
产品计划	/productplans（CUD + 按产品查列表）
版本/Build	/builds（CUD + 按项目/执行查列表）
发布	/releases（CUD + 按产品查列表）
反馈	/feedbacks（CRUD + close/activate）
工单	/tickets（CRUD + close/activate）
应用/系统	/systems（CU + 按产品查列表）
获取用户列表	GET /users

注意事项

• URL 中的 {id} 需替换为实际 ID；不知道 ID 时先调列表接口获取
• 创建 Epic / Requirement / Story 时，建议始终显式传 grade，不要依赖接口默认值。 已有用户反馈某些禅道实例在未传 grade 时会把需求层级写成 0，导致界面中 BR / UR / SR 标签显示异常。
• PUT 编辑接口：先 GET 详情获取当前完整数据，再将用户修改的字段覆盖进去一并提交
• 状态流转操作 (resolve/close/activate/start/finish/change) 通常有独立的必填字段，不需要先 GET 详情
• 写操作前向用户确认，用户明确要求不确认则直接执行
• 401 响应表示 token 已失效，执行 rm ~/.zentao-token.json 清除缓存后重新运行
• 字段名不一致注意：POST builds 用 executionID，PUT builds 用 execution；PUT testcases 的模块字段为 moudule（规范中的拼写）

完整 API 参考

详细的端点列表、必填/可选字段、枚举值和查询参数见 api-reference.md。

备用资源

• 禅道 API 2.0 官方文档：https://www.zentao.net/book/api/2309.html
• 1.0 API 文档（备用）：https://www.zentao.net/book/api/1397.html