跳转到主要内容
POST
变更团队信息

限制说明

使用说明

  • 省略 team_id(或置为 0)表示创建团队;传入已有的 team_id 表示更新。team_id 找不到团队时返回 400。
  • team_name 在账户内的团队中必须唯一。名称已被其他团队使用时返回 400;但当 team_id 为 0 且 reset_if_name_exist 为 true 时,会更新该同名团队。
  • 成员列表总是整体替换:团队成员变为 person_ids、emails、phones 三者解析结果的并集。更新时三者都不传会清空所有成员。
  • 解析不到本账户成员(或账户主体)的条目会被静默丢弃,不会发出邀请。
  • 更新时 description 和 ref_id 也会被覆盖——不传即清空原值。
  • 更新团队时,调用者还必须是团队成员、团队创建者、账户主体或拥有 Admin 角色。
  • 每次调用都会记录到账户审计日志,请不要把敏感信息放在请求字段中。

授权

app_key
string
query
必填

在 Flashduty 控制台 我的 → APP Key 中创建的 APP Key。可通过 query 参数 app_key 或请求头 Fd-App-Key 传入。实际可访问范围是该 APP Key 的权限范围与创建者当前角色权限的交集,请妥善保管。

请求体

application/json

创建或更新团队的参数。

team_name
string
必填

团队显示名称,1–39 个字符。

Required string length: 1 - 39
team_id
integer<uint64>

要更新的团队 ID。省略或置为 0 表示创建新团队;非 0 时必须是本账户已有团队的 ID。

description
string

自由文本描述,最多 500 个字符。更新时不传会清空原有描述。

Maximum string length: 500
person_ids
integer<uint64>[]

要加入团队的人员 ID(成员 ID;账户主体使用账户 ID)。与 emails、phones 合并后整体替换成员列表;不是本账户成员的 ID 会被忽略。

emails
string<email>[]

要加入团队的已有成员邮箱,与 person_ids、phones 合并。匹配不到成员的邮箱会被忽略,不会发出邀请。

phones
string[]

要加入团队的已有成员手机号,与 person_ids、emails 合并。不带 + 前缀的号码按 countryCode 解析;无法解析的号码会使整个请求返回 400,匹配不到成员的号码会被忽略。

countryCode
string

phones 中不带 + 前缀号码的地区提示:ISO 3166-1 alpha-2 地区代码(如 CN,未传时默认)或数字区号(如 86)。

ref_id
string

外部引用 ID(如 HR 系统中的部门 ID),可在 POST /team/info、POST /team/delete 中作为查找键。更新时不传会清空原值。

reset_if_name_exist
boolean

为 true 且 team_id 为 0 时,若已存在同名团队,则原地更新该团队,而不是返回名称冲突错误。

响应

成功

成功响应结构。2xx 响应中 request_id 标识本次调用(同时出现在 Flashcat-Request-Id 响应头中),data 为接口业务 payload。失败响应使用不同结构,参见 ErrorResponse。

request_id
string
必填

本次请求的唯一 ID,也会在 Flashcat-Request-Id 响应头中返回。反馈问题时请一并附上。

示例:

"01HK8XQE3Z7JM2NTFQ5YJ8P9R4"

data
object

创建或更新团队的结果。