# 说明
新建需求，返回新建需求的数据
# url
https://api.tapd.cn/stories
# 支持格式
JSON/XML（默认JSON格式）
# HTTP请求方式
POST
# 请求数限制
一次插入一条数据
# 请求参数
| 字段名 | 必选 | 类型及范围 | 说明 |
|---|---|---|---|
| workspace_id | 是 | integer | 项目ID |
| name | 是 | string | 标题 |
| priority | 否 | string | 优先级。为了兼容自定义优先级，请使用 priority_label 字段，详情参考：如何兼容自定义优先级 |
| priority_label | 否 | string | 优先级。推荐使用这个字段 |
| business_value | 否 | integer | 业务价值 |
| version | 否 | string | 版本 |
| module | 否 | string | 模块 |
| test_focus | 否 | string | 测试重点 |
| size | 否 | integer | 规模 |
| owner | 否 | string | 处理人 |
| cc | 否 | string | 抄送人 |
| creator | 否 | string | 创建人 |
| developer | 否 | string | 开发人员 |
| begin | 否 | date | 预计开始 |
| due | 否 | date | 预计结束 |
| iteration_id | 否 | string | 迭代ID |
| templated_id | 否 | integer | 模板ID |
| parent_id | 否 | integer | 父需求ID |
| effort | 否 | string | 预估工时 |
| effort_completed | 否 | string | 完成工时 |
| remain | 否 | float | 剩余工时 |
| exceed | 否 | float | 超出工时 |
| category_id | 否 | integer | 需求分类 |
| workitem_type_id | 否 | integer | 需求类别 |
| release_id | 否 | integer | 发布计划 |
| source | 否 | string | 来源 |
| type | 否 | string | 类型 |
| description | 否 | string | 详细描述 |
| label | 否 | string | 标签，标签不存在时将自动创建，多个以英文坚线分格 |
| cus_{$自定义字段别名} | 否 | string | 自定义字段值，参数名会由后台自动转义为custom_field_*，如：cus_自定义字段的名称 |
| custom_field_* | 否 | string或者integer | 自定义字段参数，具体字段名通过接口 获取需求自定义字段配置 获取 |
| custom_plan_field_* | 否 | string或者integer | 自定义计划应用参数，具体字段名通过接口 获取自定义计划应用 获取 |
| is_apply_template_default_value | 否 | integer | 是否从模板继承默认值、保密设置（传值=1继承模板默认值） |
| apply_template | 否 | string | 模版选项,支持多个选项传入,使用','隔开 如: "option1,option2" 当前支持参数:preset_stories(支持创建需求模板预设子需求),preset_tasks(支持创建需求模板预设子任务) |
# 调用示例及返回结果
# 在项目下创建需求
# curl 使用 Basic Auth 鉴权调用示例
curl -u 'api_user:api_password' -d 'name=story_created_by_api&workspace_id=10158231&cus_自定义字段的名称=custom_field_value' 'https://api.tapd.cn/stories'
# 返回结果
{
"status": 1,
"data": {
"Story": {
"id": "1010158231500687939",
"name": "story_created_by_api",
"description": null,
"workspace_id": "10158231",
"creator": "api_doc_oauth",
"created": "2019-06-27 11:33:59",
"modified": "2019-06-27 11:33:59",
"status": "planning",
"owner": null,
"cc": null,
"begin": null,
"due": null,
"size": null,
"priority": "",
"developer": null,
"iteration_id": "0",
"test_focus": null,
"type": null,
"source": null,
"module": null,
"version": "",
"completed": null,
"category_id": "-1",
"parent_id": "0",
"children_id": "|",
"ancestor_id": "1010158231500687939",
"business_value": null,
"effort": "0",
"effort_completed": "0",
"exceed": "0",
"remain": "0",
"release_id": "0",
"label": "阻塞|延期",
"cus_自定义字段的名称": "custom_field_value",
"custom_field_one": null,
"custom_field_two": null,
"custom_field_three": null,
"custom_field_four": null,
"custom_field_five": null,
"custom_field_six": null,
"custom_field_seven": null,
"custom_field_eight": null,
"custom_field_9": null,
"custom_field_10": null,
"custom_field_11": null,
"custom_field_12": null,
"custom_field_13": null,
"custom_field_14": null,
"custom_field_15": null,
"custom_field_16": null,
"custom_field_17": null,
"custom_field_18": null,
"custom_field_19": null,
"custom_field_20": null,
"custom_field_21": "",
"custom_field_22": "",
"custom_field_23": "",
"custom_field_24": "",
"custom_field_25": "",
"custom_field_26": "",
"custom_field_27": "",
"custom_field_28": "",
"custom_field_29": "",
"custom_field_30": "",
"custom_field_31": null,
"custom_field_32": null,
"custom_field_33": null,
"custom_field_34": null,
"custom_field_35": null,
"custom_field_36": null,
"custom_field_37": null,
"custom_field_38": null,
"custom_field_39": null,
"custom_field_40": null,
"custom_field_41": null,
"custom_field_42": null,
"custom_field_43": null,
"custom_field_44": null,
"custom_field_45": null,
"custom_field_46": null,
"custom_field_47": null,
"custom_field_48": null,
"custom_field_49": null,
"custom_field_50": null,
"custom_field_51": null,
"custom_field_52": null,
"custom_field_53": null,
"custom_field_54": null,
"custom_field_55": null,
"custom_field_56": null,
"custom_field_57": null,
"custom_field_58": null,
"custom_field_59": null,
"custom_field_60": null,
"custom_field_61": null,
"custom_field_62": null,
"custom_field_63": null,
"custom_field_64": null,
"custom_field_65": null,
"custom_field_66": null,
"custom_field_67": null,
"custom_field_68": null,
"custom_field_69": null,
"custom_field_70": null,
"custom_field_71": null,
"custom_field_72": null,
"custom_field_73": null,
"custom_field_74": null,
"custom_field_75": null,
"custom_field_76": null,
"custom_field_77": null,
"custom_field_78": null,
"custom_field_79": null,
"custom_field_80": null,
"custom_field_81": null,
"custom_field_82": null,
"custom_field_83": null,
"custom_field_84": null,
"custom_field_85": null,
"custom_field_86": null,
"custom_field_87": null,
"custom_field_88": null,
"custom_field_89": null,
"custom_field_90": null,
"custom_field_91": null,
"custom_field_92": null,
"custom_field_93": null,
"custom_field_94": null,
"custom_field_95": null,
"custom_field_96": null,
"custom_field_97": null,
"custom_field_98": null,
"custom_field_99": null,
"custom_field_100": null
}
},
"info": "success"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
# 需求字段说明
# 需求重要字段说明
| 字段 | 说明 |
|---|---|
| id | ID |
| name | 标题 |
| priority | 优先级 |
| priority_label | 优先级 |
| business_value | 业务价值 |
| status | 状态 |
| version | 版本 |
| module | 模块 |
| test_focus | 测试重点 |
| size | 规模 |
| owner | 处理人 |
| cc | 抄送人 |
| creator | 创建人 |
| developer | 开发人员 |
| begin | 预计开始 |
| due | 预计结束 |
| created | 创建时间 |
| modified | 最后修改时间 |
| completed | 完成时间 |
| iteration_id | 迭代 |
| effort | 预估工时 |
| effort_completed | 完成工时 |
| remain | 剩余工时 |
| exceed | 超出工时 |
| category_id | 需求分类 |
| workitem_type_id | 需求类别 |
| release_id | 发布计划 |
| source | 来源 |
| type | 类型 |
| parent_id | 父需求 |
| children_id | 子需求 |
| ancestor_id | 祖先ID |
| description | 详细描述 |
| workspace_id | 项目ID |
# 需求优先级(priority)取值字段说明
为了兼容自定义优先级，请使用 priority_label 字段，详情参考：如何兼容自定义优先级 。下面取值将不再使用。
| 取值 | 字面值 |
|---|---|
| 4 | High |
| 3 | Middle |
| 2 | Low |
| 1 | Nice To Have |