跳转到主要内容
POST
创建值班表

限制说明

使用说明

  • schedule_name(或旧字段 name)必填,最长 40 个字符,且在账户内唯一。description 最长 500 个字符。
  • time_zone 决定值班表所有墙钟规则(交接时间、限制时段、星期、定时通知)所用的时区,创建后不可修改。不传时按 Asia/Shanghai 计算,读取时 time_zone 为空字符串。
  • 分层时间既可以用数字字段(layer_start、handoff_time、restrict_periods 等)传入,也可以用墙钟字符串(starts_at、ends_at、handoff、restricts_wall)传入;同时传入时以墙钟字段为准,并按值班表时区换算。
  • 值班表数量超过账户套餐上限时返回 NoLicense 错误。
  • 保存前可用 /schedule/preview 预览排班结果。
  • 每次调用都会记录到账户审计日志。
  • 调用者必须是账户所有者或管理员,或属于 team_id 指定的团队;不归属团队的值班表任何成员都可创建。否则返回 AccessDenied。
  • 不属于本账户的成员 ID 或 IM 数据源返回 InvalidParameter;新增 IM 应用目标可能返回 NoLicense。

授权

app_key
string
query
必填

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

请求体

application/json

/schedule/create、/schedule/update、/schedule/preview 的请求体。创建时必须提供 schedule_name(或旧字段 name),更新时必须提供 schedule_id,预览时必须提供 start/end。

schedule_id
integer<int64> | null

值班表 ID,更新时必填,可通过 POST /schedule/list 获取。

schedule_name
string | null

值班表名称,最长 40 个字符,账户内唯一。更新时不传则保持原名称。

Maximum string length: 40
name
string | null

旧版名称字段,仅在创建且 schedule_name 为空时使用。更新时忽略。

Maximum string length: 40
description
string | null

值班表描述,最长 500 个字符。更新时不传保持原值,传空字符串则清空。

Maximum string length: 500
team_id
integer<int64> | null

所属团队 ID,可通过 POST /team/list 获取。创建时不传则不归属任何团队(0);更新时不传保持原团队。

time_zone
string

值班表墙钟规则所用的 IANA 时区,如 Asia/Shanghai、UTC;EST 之类的缩写以及 Etc/GMT±N 会被拒绝。创建时设置(不传则按 Asia/Shanghai 计算),之后不可修改——更新时不传或传当前值。预览时用于指定计算时区。

layers
object[]

轮转分层。更新时该列表会替换全部已有分层,不传即删除所有分层。单次请求最多 1000 项,更多请分多次调用。

Maximum array length: 1000
notify
object | null

换班通知配置。更新时不传保持原配置;传入则整体替换。

start
integer<int64>

预览窗口开始时间,10 位 Unix 秒。/schedule/preview 必填;创建和更新时忽略。

end
integer<int64>

预览窗口结束时间,10 位 Unix 秒,晚于 start 且相差不超过 45 天。/schedule/preview 必填;创建和更新时忽略。

disabled
enum<integer> | null

仅创建时生效:0 = 启用(默认),1 = 禁用。更新时忽略,请改用 status。

可用选项:
0,
1,
null
status
enum<integer> | null

0 = 启用,1 = 禁用。更新时不传保持当前状态。创建时优先于 disabled。

可用选项:
0,
1,
null

响应

成功

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

request_id
string
必填

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

示例:

"01HK8XQE3Z7JM2NTFQ5YJ8P9R4"

data
object

创建值班表后返回的 ID 响应。