Skip to Content
数字员工服务调用接口

数字员工调用接口

所有接口使用应用服务凭证：

Authorization: Bearer <完整的 fc_app_ 应用服务凭证>

应用身份由凭证解析。调用方不传 applicationId、clientId、orgId 或 userId 来指定任务归属。接口返回直接 JSON 对象，不套用 Data API 的 code/message/data 包装。

接口一览

方法路径用途与成功状态
GET/api/open/v1/applications/me应用身份，200。
GET/api/open/v1/applications/me/employees当前应用可使用的员工，200。
POST/api/open/v1/applications/me/tasks提交任务，201。
GET/api/open/v1/applications/me/tasks/{id}任务状态，200。
GET/api/open/v1/applications/me/tasks/{id}/result已完成任务结果，200。
POST/api/open/v1/applications/me/tasks/{id}:cancel请求取消，200。

应用身份与员工

身份响应包含 applicationId、clientId、code、displayName。

员工列表返回 {items: Employee[]}，只包含员工本身与使用授权均有效、且当前应用具有读取或创建操作权限的员工。列表不保证员工当前在线或有空闲并发。

员工字段说明
id员工 UUID，作为提交时的 employeeId。
code / displayName员工代码和名称。
avatarUrl / roleTitle / description可空展示资料。
operations当前可用的 TASK_CREATE、READ 操作；创建并跟踪任务应同时具有这两项。
grantExpiresAt授权到期时间；null 表示长期。
maxConcurrentAssignments员工最大并发数。
activeAssignmentCount员工当前活跃任务数，属于员工总体并发，不是本应用任务数量。

仅授予“空间启用”的员工不会出现在此应用任务目录。应用无需获取 Runtime、连接密钥或员工内部指令。

提交任务

除认证头外，必须提供：

Content-Type: application/json
Idempotency-Key: collection:run-001
请求字段必填约束
employeeId是当前应用获授权的有效员工 UUID。
title是非空，去除首尾空白后最多 255 个字符。
instructions是非空执行指令，包括所需的结果交付约定。
input是JSON 对象，可为 {}；不能为数组、null 或二进制。
{
  "employeeId": "00000000-0000-4000-8000-000000000003",
  "title": "分析素材",
  "instructions": "按应用约定分析 input，并通过任务结果文件交付结构化 output。",
  "input": {"materialId": "material-001"}
}

该片段只展示请求字段，完整执行示例见快速接入和输入与结果。任务请求中没有 skillKey、capabilityKey 或回调配置字段；业务参数放在 input 中，由执行逻辑理解。

请求与平台输入信封均受 64 KiB 限制，存储后的 JSON 大小也会检查。请为指令与信封开销留出空间。

幂等

Idempotency-Key 由 1–128 个字母、数字或 :._- 组成，在同一应用内唯一。

  • 相同键、相同员工/标题/指令/input：返回原任务，仍为 HTTP 201。
  • 相同键、不同内容：HTTP 409，APPLICATION_TASK_IDEMPOTENCY_CONFLICT。
  • 创建请求超时后，持久化并复用原键重试，避免重复派发。

任务状态

提交、查询和取消返回同一结构：

{
  "id": "00000000-0000-4000-8000-000000000001",
  "applicationId": "00000000-0000-4000-8000-000000000002",
  "employeeId": "00000000-0000-4000-8000-000000000003",
  "title": "分析素材",
  "status": "PENDING",
  "runStatus": "PENDING",
  "failureCategory": null,
  "createdAt": "2026-10-22T00:00:00Z",
  "completedAt": null,
  "caller": {
    "type": "APPLICATION",
    "id": "00000000-0000-4000-8000-000000000002"
  }
}
status含义
PENDING已接受，等待员工领取。
CLAIMED已领取，准备执行。
RUNNING执行中。
COMPLETED执行完成且平台已保存结果。
FAILED执行失败，可结合 failureCategory 排查。
CANCELLED已取消。

以上是状态集合；快速任务可能跳过客户端可观察到的中间状态。以 status 判断终态。runStatus 提供执行补充状态，例如运行中请求取消时可能显示 CANCEL_REQUESTED。

读取结果

查询状态和结果均需要实时 READ 授权。结果只有在任务 COMPLETED 后可读，否则返回 HTTP 409。

{
  "assignmentId": "00000000-0000-4000-8000-000000000001",
  "applicationId": "00000000-0000-4000-8000-000000000002",
  "output": {"received": true, "businessId": "material-001"}
}

output 必须是 JSON 对象，具体业务字段由应用约定。平台不会自动写业务库或发通用 Webhook。大文件和业务回执见输入与结果。

取消与授权变化

取消接口用于本应用自己的任务。等待中的任务可直接取消，执行中的任务需要 Adapter 确认。返回 200 不保证已经停止，继续跟踪到终态；重复取消或对终态任务取消不会启动新任务。

每次请求均校验应用、API 接入和服务凭证状态。员工使用授权还控制任务提交、执行、查询与读取；修改授权 revision、撤销或过期后，旧任务不会因重新授权而恢复。员工撤权后，有效应用身份仍可取消自己的任务。

轮换同一应用的服务凭证可以继续查询原任务。其他应用的任务与结果返回 404。

HTTP 错误

HTTP含义 / 典型原因处理
400输入不合法、缺少幂等键、JSON 超限；APPLICATION_TASK_INPUT_INVALID。检查请求字段、键格式和大小。
401凭证无效、撤销、过期，或应用/API 接入停用。检查完整服务凭证与生命周期状态。
403APPLICATION_TASK_NOT_AUTHORIZED。检查员工状态、操作范围、期限与任务接受时的授权版本。
404APPLICATION_TASK_NOT_FOUND。检查任务 ID 和调用应用身份。
409幂等冲突，或 APPLICATION_TASK_RESULT_NOT_READY。分别处理内容冲突和等待结果，不能统一无限重试。
5xx / 网络错误服务暂不可用或请求未完成。保留业务记录、任务 ID 与原幂等键，退避后继续查询或重试。

以 HTTP 状态判断成功或失败；员工服务没有承诺统一的错误 JSON 包装。错误原因可能在响应说明字段中，应用日志需脱敏且不记录凭证。

Last updated on
快速接入输入与结果