同步范围
状态回传只作用于已关联的故障，不会把蓝鲸中的其他工单导入为新故障。Flashduty 的认领、关闭或字段变更不会代替蓝鲸审批，也不会更新已创建工单的任意字段。
接入前准备
- 确认当前 Flashduty 版本已包含“蓝鲸 ITSM”集成。
- 在蓝鲸中准备已发布的工单服务，确认提单字段、必填项和流程节点含义。
- 准备蓝鲸应用的
app_code、app_secret，以及有目标服务和工单操作权限的蓝鲸用户名。 - 为应用申请以下 ESB / API 网关资源权限，并确认网关允许当前应用以配置的用户名访问资源。
- 确认 Flashduty 后端可访问网关；需要回调时，还应确保蓝鲸可访问 Flashduty 的回调地址。
正式接入使用 ESB / API 网关认证。Flashduty 将应用凭证和操作用户放入
X-Bkapi-Authorization 请求头，字段名为 bk_app_code、bk_app_secret 和 bk_username。如果网关要求额外的交互式用户令牌，需要先与蓝鲸管理员确认兼容的资源认证策略；当前页面不提供用户令牌配置。
SaaS 接入的网关需使用后端可访问的公网地址。私有化部署可使用可达的内网地址。独立测试环境的认证适配仅用于联调，不能据此判断正式网关认证已经通过。
在 Flashduty 配置集成
进入“集成中心”，找到“蓝鲸 ITSM”并创建集成，填写名称、描述和管理团队。连接认证
接口前缀不要包含
get_services 等具体接口名、查询参数或 URL 内嵌凭证。系统会在前缀后追加接口名及尾部 /。蓝鲸控制台登录地址和独立部署的原始 OpenAPI 地址不一定是正式网关前缀。
点击“测试连接并加载服务”，成功后选择“工单服务”。此操作只验证服务列表访问，并不证明创建工单、查询状态或回调权限都已验证。
同步设置
选择同步方向，以及本集成生效的“协作空间”。一个集成对应一个蓝鲸工单服务；同一故障在同一集成下只保留一个工单关联。需要接入不同服务时，分别创建集成。 允许向蓝鲸提单时，选择触发模式：- 手动触发：在故障详情的 BlueKing ITSM 区域点击“创建或关联蓝鲸工单”，选择集成，工单号留空后点击“创建工单”。
- 自动触发：配置匹配条件。符合协作空间范围和条件的故障，在新建、认领、关闭或字段更新事件触发处理时可提单。保存集成不会回溯扫描已有故障；已经关联工单时不会重复提单。
提单字段映射
先选择工单服务，再点击“添加映射”。蓝鲸字段列表来自服务定义；每个目标字段只能配置一次。
未显式映射
title 时，系统默认使用故障标题。其他蓝鲸必填字段需配置映射，并在实际提单时有值；标签或自定义字段不存在、值为空，也可能导致提单失败。仅入站同步不要求配置提单必填映射。
字段按蓝鲸服务类型转换：整数和数值字段需填写可转换的数字；多选、复选框或自定义表格的字符串值需为有效 JSON，例如多选值 ["a","b"]。枚举字段使用实际选项 Key，不能直接使用显示名称。严重程度读取故障原值，不会自动转换为蓝鲸优先级。
例如，将蓝鲸的服务名称字段映射为“标签 / service”，将环境字段映射为“固定值 / production”。目标字段必须确实存在于所选服务中。
映射仅在创建时写入。服务字段或流程重新发布后，应重新加载字段、核对映射，再用测试故障验证。
蓝鲸状态回传
节点映射
点击“添加节点映射”，填写已发布流程的节点 ID，并选择“认领故障”或“关闭故障”。节点 ID 对应状态接口current_steps[].state_id，不是工单 ID、工单号或节点名称。
节点映射在进入节点时生效，不是节点完成后生效。 只有当“进入该节点”本身表示已经解决时，才配置为关闭故障。不要把待审批或处理中节点映射为关闭。并行节点应避免配置互相冲突的动作。
“正常完结时的动作”可留空；留空时，单据完结本身不会关闭故障。终止（
TERMINATED）、撤回（REVOKED）或完结审批未通过不会执行完结关闭。运行中仍以节点映射为准，需保证流程的拒绝分支不会经过配置为关闭的节点。
已关闭的故障不会被回传重新打开，也不会退回处理中。Flashduty 不会自动审批、转单或撤回蓝鲸工单。
回调配置
- 完成连接与同步配置，先保存集成。新建阶段尚未生成该集成的回调地址。
- 重新进入该集成的编辑页，在右侧文档的“本集成回调地址”处复制完整地址，保留
integration_key参数。不要手动拼接地址，也不要复用示例或其他集成的 key。 - 如需在提单时注册完结回调，将复制的地址填入“蓝鲸回调地址”，再次保存后再创建工单。创建请求会将其作为
meta.callback_url传给蓝鲸。 - 如需节点变化时及时回传，在蓝鲸中为相应流程事件配置 HTTP 触发器，向同一地址发送
POST请求，设置Content-Type: application/json。 - 请求体将实际工单号放在顶层
sn字段。蓝鲸不同版本的触发器变量语法可能不同，请选择该版本实际提供的工单号变量，不要固定写入一个测试单号。
integration_key 确定集成，再向蓝鲸查询该单号的实际状态。请求体中的状态或审批结果不会直接用于认领、关闭故障。回调不会创建关联；已有工单必须先关联到故障，HTTP 200 也不能单独证明故障状态已更新。
可对测试故障及其已关联单号发送回调以验证链路：
关联已有工单与失败重试
在故障详情点击“创建或关联蓝鲸工单”，选择集成并填写已有工单号，再点击“关联工单”。工单必须属于该集成配置的蓝鲸服务，故障也必须属于所选协作空间。 创建失败或返回结果未知时，先在蓝鲸按故障标题和提单时间核对：- 上一次创建仍可能进行中：等待至少 60 秒再核对，系统会拒绝过早重试。
- 已存在对应工单：关联已有单号，不再创建。
- 确认不存在：使用“核对后重试”，阅读确认提示后再提交。
联调检查与常见问题
用测试故障完成以下检查后再接入业务流程：手动提单、关联已有单号、进入认领节点、正常审批完结、拒绝或撤回、回调暂停后的定期核对，以及仅入站和仅出站的方向限制。
当前不支持工单普通留言、创建后的任意字段更新、蓝鲸审批自动化或从蓝鲸批量导入新故障。蓝鲸的
comment 接口表示完结评价，不等同于普通留言。