会员接口文档

读取会员和企业资料、管理任务、外包下单与验收、商品采购,只作用于密钥所属的企业和会员。

适合:把企业内部系统和诸葛军师账户打通的会员

服务地址
https://www.zhugejunshi.com/api/member-api/v1
鉴权
X-Zhuge-API-Key: zhuge_live_…
接口数量
28 个 · 文档版本 v1
文档文件
member-api.json(OpenAPI,可导入 Postman、Apifox 等工具)

使用须知

  • 密钥放在 X-Zhuge-API-Key 请求头;也可以写成 Authorization: Bearer,两种都带时以 X-Zhuge-API-Key 为准。
  • 每个密钥每分钟最多 120 次请求,超出返回 429。
  • 外包下单、安卓任务草案和商品下单要带幂等键,重复提交不会重复下单;各接口的写法见文档里的请求头参数。
  • 高风险权限(下单、发布、验收等)要人工审核通过后才能使用。
  • 请求一律按密钥绑定的企业和会员处理,客户端传入的租户参数不会被采用。
接口总说明

会员接口让企业会员的程序读取资料和任务、下外包单并验收交付、创建安卓受控执行草案、浏览商品并下采购单。

认证:每个请求都要带 API 密钥(以 zhuge_live_ 开头)。推荐写法是请求头 X-Zhuge-API-Key: 你的密钥;也可以写成 Authorization: Bearer 你的密钥,两种写法等价,同时提供时优先使用 X-Zhuge-API-Key。

权限:每个接口需要对应的权限(见各接口的 x-scope)。密钥自己和申请批准的权限里都要有,缺一不可。标为高风险的权限(发布并自动派单、发送返工要求、确认外包验收、发起外包争议、创建商务订单)需要人工审核批准后才会生效。

限流:每个密钥每分钟最多 120 次请求,超过返回 429。每个成功响应带响应头 X-RateLimit-Limit(上限)和 X-Zhuge-Tenant(密钥绑定的企业编号)。

租户隔离:所有请求都强制使用密钥绑定的企业和会员,客户端传入的租户参数不会被采用。

错误:错误响应一般是 {"detail": {"code": "...", "message": "..."}},可能多一个 details 对象。参数格式错误(422)是 FastAPI 的默认格式 {"detail": [...]}。

幂等:外包的写操作和安卓执行草案必须带幂等键,商务下单也必须带;同一个幂等键加相同内容重复提交,会原样返回第一次的结果,不会重复执行。

账户与任务

读取会员与企业资料、读取并创建企业任务、读取组织成员。

GET读取会员与企业资料

/profile

需要密钥 · 需要权限 profile:read

返回当前密钥所属会员和企业的基础资料。需要 profile:read 权限。密钥绑定的会员或企业不存在时返回 404(detail 为文字说明)。

返回

200会员与企业资料。
200 的返回字段
字段类型必填说明
dataobject否—
data.userobject否—
data.user.idinteger否—
data.user.usernamestring | null否—
data.user.nicknamestring | null否—
data.user.real_namestring | null否—
data.user.emailstring | null否—
data.user.mobilestring | null否—
data.enterpriseobject否—
data.enterprise.idinteger否—
data.enterprise.namestring | null否—
data.enterprise.short_namestring | null否—
data.enterprise.industry_typestring | null否—
data.enterprise.business_typestring | null否—
tenant_idinteger否

密钥绑定的企业编号。

返回示例
{
  "data": {
    "user": {
      "id": 20,
      "username": "demo_user",
      "nickname": "示例会员",
      "real_name": "示例姓名",
      "email": "user@example.com",
      "mobile": "13800000000"
    },
    "enterprise": {
      "id": 10,
      "name": "示例企业有限公司",
      "short_name": "示例企业",
      "industry_type": "示例行业",
      "business_type": "示例类型"
    }
  },
  "tenant_id": 10
}
401未提供有效的 API 密钥(invalid_api_key),或密钥上下文无效(invalid_api_context)。
401 的返回字段
字段类型必填说明
detailobject是—
detail.codestring是

错误代码,程序判断用。

detail.messagestring是

中文说明。

detail.detailsobject否

部分错误带的补充信息,例如版本冲突时的 current_version。

403密钥已撤销、过期或申请未获批准(api_key_inactive);申请主体不一致(api_actor_mismatch);会员、企业或成员关系已停用(api_actor_inactive);密钥没有该接口需要的权限(api_scope_denied);或业务规则拒绝,例如自动派单授权无效。

返回字段同 401。

404资源不存在或不属于当前密钥;路由不存在或请求方法不对时 code 为 member_api_route_not_found。

返回字段同 401。

429当前密钥每分钟请求次数已达上限(120 次)。

返回字段同 401。

错误返回的格式和重试建议见 错误处理。

调用示例

curl -X GET 'https://www.zhugejunshi.com/api/member-api/v1/profile' \
  -H 'X-Zhuge-API-Key: YOUR_API_KEY'
在线调试

这里会用你填的密钥向正式接口发一次真实请求。密钥只留在本页内存里,不保存、不上传到别处,刷新页面后要重新填写。

GET读取企业任务列表

/tasks

需要密钥 · 需要权限 tasks:read

按任务编号倒序返回当前企业的任务。企业管理员(所有者或管理员)能看到全部任务,普通成员只能看到自己负责或被分派的任务。需要 tasks:read 权限。

请求参数

读取企业任务列表的请求参数
参数位置类型必填说明
status查询string否

按任务状态筛选,不填返回全部;超过 20 个字符的部分会被截掉。

limit查询integer否

返回条数。

范围:1 到 100;默认:50

返回

200任务列表。
200 的返回字段
字段类型必填说明
dataarray<object>否—
data[].idinteger否—
data[].titlestring否—
data[].descriptionstring | null否—
data[].prioritystring否

low、medium、high、urgent 之一。

data[].statusstring否

任务状态,例如 todo、review。

data[].owner_user_idinteger否

负责人的会员编号,没有负责人时为 0。

data[].due_timestring(date-time) | null否—
data[].requires_approvalboolean否—
data[].source_labelstring | null否

任务来源,经接口创建的为 member_api。

tenant_idinteger否—
limitinteger否—
返回示例
{
  "data": [
    {
      "id": 3001,
      "title": "核对本周发货清单",
      "description": "对照仓库记录核对。",
      "priority": "medium",
      "status": "todo",
      "owner_user_id": 20,
      "due_time": "2026-11-10T09:00:00",
      "requires_approval": false,
      "source_label": "member_api"
    }
  ],
  "tenant_id": 10,
  "limit": 50
}
401未提供有效的 API 密钥(invalid_api_key),或密钥上下文无效(invalid_api_context)。
401 的返回字段
字段类型必填说明
detailobject是—
detail.codestring是

错误代码,程序判断用。

detail.messagestring是

中文说明。

detail.detailsobject否

部分错误带的补充信息,例如版本冲突时的 current_version。

403密钥已撤销、过期或申请未获批准(api_key_inactive);申请主体不一致(api_actor_mismatch);会员、企业或成员关系已停用(api_actor_inactive);密钥没有该接口需要的权限(api_scope_denied);或业务规则拒绝,例如自动派单授权无效。

返回字段同 401。

422请求参数或请求体格式不对(FastAPI 默认格式)。
422 的返回字段
字段类型必填说明
detailarray<object>是—
detail[].typestring否—
detail[].locarray<string | integer>否—
detail[].msgstring否—
detail[].inputany否—
429当前密钥每分钟请求次数已达上限(120 次)。

返回字段同 401。

错误返回的格式和重试建议见 错误处理。

调用示例

curl -X GET 'https://www.zhugejunshi.com/api/member-api/v1/tasks' \
  -H 'X-Zhuge-API-Key: YOUR_API_KEY'
在线调试

这里会用你填的密钥向正式接口发一次真实请求。密钥只留在本页内存里,不保存、不上传到别处,刷新页面后要重新填写。

POST创建企业任务

/tasks

需要密钥 · 需要权限 tasks:write

在当前企业创建任务,负责人必须是当前企业的有效成员。企业管理员可以指定任何成员为负责人,普通成员只能给自己创建(否则 403)。requires_approval 为 true 时任务进入 review 状态等待审批,否则为 todo。需要 tasks:write 权限。due_time 格式不对返回 400,负责人不是有效成员返回 400(这两种错误的 detail 是文字说明)。

请求内容 (application/json,必填)

创建企业任务的请求字段
字段类型必填说明
titlestring是

任务标题。

长度 1–200

descriptionstring否

任务说明。

最长 5000

prioritystring否

优先级。

可选值:low / medium / high / urgent;格式:^(low|medium|high|urgent)$;默认:medium

owner_user_idinteger | null否

负责人的会员编号,不填则为密钥所属会员。普通成员只能填自己。

due_timestring | null否

截止时间,ISO 8601 日期时间;带时区的会去掉时区信息按字面时间保存。

最长 80

requires_approvalboolean否

是否需要审批;为 true 时任务状态为 review。

默认:false

请求示例
{
  "title": "核对本周发货清单",
  "description": "对照仓库记录核对。",
  "priority": "medium",
  "due_time": "2026-11-10T09:00:00+08:00",
  "requires_approval": false
}

返回

200创建成功。
200 的返回字段
字段类型必填说明
dataobject否—
data.idinteger否—
data.titlestring否—
data.statusstring否

todo 或 review。

data.owner_user_idinteger否—
tenant_idinteger否—
返回示例
{
  "data": {
    "id": 3002,
    "title": "核对本周发货清单",
    "status": "todo",
    "owner_user_id": 20
  },
  "tenant_id": 10
}
400due_time 不是 ISO 8601 日期时间,或负责人不是当前企业的有效成员。
400 的返回字段
字段类型必填说明
detailstring是—
401未提供有效的 API 密钥(invalid_api_key),或密钥上下文无效(invalid_api_context)。
401 的返回字段
字段类型必填说明
detailobject是—
detail.codestring是

错误代码,程序判断用。

detail.messagestring是

中文说明。

detail.detailsobject否

部分错误带的补充信息,例如版本冲突时的 current_version。

403密钥已撤销、过期或申请未获批准(api_key_inactive);申请主体不一致(api_actor_mismatch);会员、企业或成员关系已停用(api_actor_inactive);密钥没有该接口需要的权限(api_scope_denied);或业务规则拒绝,例如自动派单授权无效。

返回字段同 401。

422请求参数或请求体格式不对(FastAPI 默认格式)。
422 的返回字段
字段类型必填说明
detailarray<object>是—
detail[].typestring否—
detail[].locarray<string | integer>否—
detail[].msgstring否—
detail[].inputany否—
429当前密钥每分钟请求次数已达上限(120 次)。

返回字段同 401。

错误返回的格式和重试建议见 错误处理。

调用示例

curl -X POST 'https://www.zhugejunshi.com/api/member-api/v1/tasks' \
  -H 'X-Zhuge-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "核对本周发货清单",
  "description": "对照仓库记录核对。",
  "priority": "medium",
  "due_time": "2026-11-10T09:00:00+08:00",
  "requires_approval": false
}'

GET读取组织成员

/organization/members

需要密钥 · 需要权限 organization:read

返回当前企业状态为有效的成员及其部门、岗位。企业管理员能看到全部成员,普通成员只能看到自己。需要 organization:read 权限。

返回

200成员列表。
200 的返回字段
字段类型必填说明
dataarray<object>否—
data[].user_idinteger否—
data[].namestring否

真实姓名,没有则取昵称、再取用户名。

data[].member_typestring否

成员类型,例如 owner、admin、member。

data[].departmentstring | null否—
data[].positionstring | null否—
data[].position_codestring | null否—
data[].employment_statusstring | null否—
tenant_idinteger否—
返回示例
{
  "data": [
    {
      "user_id": 20,
      "name": "示例姓名",
      "member_type": "owner",
      "department": "运营部",
      "position": "运营主管",
      "position_code": "ops_lead",
      "employment_status": "active"
    }
  ],
  "tenant_id": 10
}
401未提供有效的 API 密钥(invalid_api_key),或密钥上下文无效(invalid_api_context)。
401 的返回字段
字段类型必填说明
detailobject是—
detail.codestring是

错误代码,程序判断用。

detail.messagestring是

中文说明。

detail.detailsobject否

部分错误带的补充信息,例如版本冲突时的 current_version。

403密钥已撤销、过期或申请未获批准(api_key_inactive);申请主体不一致(api_actor_mismatch);会员、企业或成员关系已停用(api_actor_inactive);密钥没有该接口需要的权限(api_scope_denied);或业务规则拒绝,例如自动派单授权无效。

返回字段同 401。

429当前密钥每分钟请求次数已达上限(120 次)。

返回字段同 401。

错误返回的格式和重试建议见 错误处理。

调用示例

curl -X GET 'https://www.zhugejunshi.com/api/member-api/v1/organization/members' \
  -H 'X-Zhuge-API-Key: YOUR_API_KEY'
在线调试

这里会用你填的密钥向正式接口发一次真实请求。密钥只留在本页内存里,不保存、不上传到别处,刷新页面后要重新填写。

外包下单

查看外包服务目录、预览方案、检查自动派单授权、保存草稿并发布派单。

GET读取外包服务目录

/outsourcing/catalog

需要密钥 · 需要权限 outsourcing:catalog:read

返回外包服务类目、标准服务包、任务拆解方案和参考报价,创建预览或草稿时的 category、work_package_key 从这里取值。publish_requires_manual_scope_review 为 true,表示发布派单的权限需要人工审核。目录内部结构较深,这里只写到第二层。需要 outsourcing:catalog:read 权限。

返回

200外包服务目录。
200 的返回字段
字段类型必填说明
dataobject否—
data.catalog_versionstring否—
data.taxonomyarray<object>否

服务类目树。

data.service_packagesarray<object>否

标准服务包。

data.workflowarray<string>否

推荐的调用顺序。

data.publish_requires_manual_scope_reviewboolean否—
metaOutsourcingMeta否—
meta.request_idstring否

请求编号:取请求头 X-Request-Id,没有则由服务生成。

meta.tenant_idinteger否

密钥绑定的企业编号。

meta.idempotency_keystring否

写操作才有:本次使用的幂等键。

meta.idempotency_replayedboolean否

写操作才有:是否是重复提交返回的原结果。

meta.cursorinteger否

列表才有:本次使用的游标。

meta.next_cursorinteger否

列表才有:下一次请求使用的游标。

meta.limitinteger否

列表才有:本次使用的条数上限。

返回示例
{
  "data": {
    "catalog_version": "2026-07-v1",
    "taxonomy": [
      {
        "key": "example_category",
        "name": "示例类目"
      }
    ],
    "service_packages": [
      {
        "key": "example_package",
        "name": "示例服务包"
      }
    ],
    "workflow": [
      "preview",
      "create_draft",
      "publish",
      "track_events",
      "inspect_delivery"
    ],
    "publish_requires_manual_scope_review": true
  },
  "meta": {
    "request_id": "req-example-0001",
    "tenant_id": 10
  }
}
401未提供有效的 API 密钥(invalid_api_key),或密钥上下文无效(invalid_api_context)。
401 的返回字段
字段类型必填说明
detailobject是—
detail.codestring是

错误代码,程序判断用。

detail.messagestring是

中文说明。

detail.detailsobject否

部分错误带的补充信息,例如版本冲突时的 current_version。

403密钥已撤销、过期或申请未获批准(api_key_inactive);申请主体不一致(api_actor_mismatch);会员、企业或成员关系已停用(api_actor_inactive);密钥没有该接口需要的权限(api_scope_denied);或业务规则拒绝,例如自动派单授权无效。

返回字段同 401。

429当前密钥每分钟请求次数已达上限(120 次)。

返回字段同 401。

错误返回的格式和重试建议见 错误处理。

调用示例

curl -X GET 'https://www.zhugejunshi.com/api/member-api/v1/outsourcing/catalog' \
  -H 'X-Zhuge-API-Key: YOUR_API_KEY'
在线调试

这里会用你填的密钥向正式接口发一次真实请求。密钥只留在本页内存里,不保存、不上传到别处,刷新页面后要重新填写。

POST预览外包方案

/outsourcing/preview

需要密钥 · 需要权限 outsourcing:catalog:read

按提交的内容整理出外包方案、方案摘要和估算金额,不保存任何数据,也不会派单。title 或 category 为空返回 400。需要 outsourcing:catalog:read 权限。不接受未列出的字段。

请求内容 (application/json,必填)

预览外包方案的请求字段
字段类型必填说明
titlestring是

外包任务标题。

长度 1–200

categorystring是

服务类目,取值见 GET /outsourcing/catalog。

长度 1–80

requirementstring否

需求说明。

最长 10000

countrystring否

国家或地区。

最长 80

citystring否

城市。

最长 128

contactstring否

联系方式。

最长 128

budget_amountnumber否

预算金额。为 0 时按任务拆解方案自动估算。

范围:0 到 1000000000;默认:0

currencystring否

币种代码,返回时转为大写。

长度 3–8;格式:^[A-Za-z]{3,8}$;默认:CNY

delivery_hoursinteger否

交付时限,单位小时。

范围:1 到 4320;默认:48

work_package_keystring否

标准服务包编号,见外包服务目录。

最长 80

work_unitsarray<object>否

自定义工作单元。不传则按服务包自动拆解。单元内的字段由服务目录定义。

最多 200 项

acceptance_criteriastring否

验收标准。

最长 4000

evidence_requirementsstring否

交付证据要求。

最长 4000

response_sla_minutesinteger否

外包商响应时限,单位分钟。

范围:5 到 1440;默认:30

max_assignment_roundsinteger否

最多派单轮数。

范围:1 到 20;默认:5

project_keystring否

关联项目编号。

最长 100

project_namestring否

关联项目名称,不填时用标题。

最长 200

task_prioritystring否

任务优先级。

可选值:low / medium / high / urgent;格式:^(low|medium|high|urgent)$;默认:medium

contributor_pool_ratenumber否

收益池比例,仅收益分成计费时使用。

范围:0.01 到 1;默认:0.2

请求示例
{
  "title": "整理 200 条商品资料并翻译成英文",
  "category": "示例类目",
  "requirement": "按模板整理商品资料,英文翻译需人工校对。",
  "budget_amount": 800,
  "currency": "CNY",
  "delivery_hours": 72,
  "acceptance_criteria": "表格字段完整,抽检 20 条无错译。",
  "evidence_requirements": "提交完成的表格和抽检记录。"
}

返回

200方案预览。
200 的返回字段
字段类型必填说明
dataOutsourcingPlanPreview否—
data.planobject否

后端整理后的外包方案。

data.plan.titlestring否—
data.plan.categorystring否—
data.plan.requirementstring否—
data.plan.countrystring否—
data.plan.citystring否—
data.plan.contactstring否—
data.plan.budget_amountnumber否

预算为 0 时是估算金额。

data.plan.currencystring否—
data.plan.delivery_hoursinteger否—
data.plan.work_package_keystring否—
data.plan.work_package_namestring否—
data.plan.work_unitsarray<object>否—
data.plan.acceptance_criteriastring否—
data.plan.evidence_requirementsstring否—
data.plan.response_sla_minutesinteger否—
data.plan.max_assignment_roundsinteger否—
data.plan.project_keystring否—
data.plan.project_namestring否—
data.plan.task_prioritystring否—
data.plan.contributor_pool_ratenumber否—
data.plan_digeststring否

方案摘要(64 位十六进制)。

data.estimated_amountnumber否—
data.currencystring否—
data.unit_countinteger否

工作单元数量。

data.requires_publish_approvalboolean否

始终为 true,发布需要审核授权。

metaOutsourcingMeta否—
meta.request_idstring否

请求编号:取请求头 X-Request-Id,没有则由服务生成。

meta.tenant_idinteger否

密钥绑定的企业编号。

meta.idempotency_keystring否

写操作才有:本次使用的幂等键。

meta.idempotency_replayedboolean否

写操作才有:是否是重复提交返回的原结果。

meta.cursorinteger否

列表才有:本次使用的游标。

meta.next_cursorinteger否

列表才有:下一次请求使用的游标。

meta.limitinteger否

列表才有:本次使用的条数上限。

返回示例
{
  "data": {
    "plan": {
      "title": "整理 200 条商品资料并翻译成英文",
      "category": "示例类目",
      "requirement": "按模板整理商品资料,英文翻译需人工校对。",
      "country": "",
      "city": "",
      "contact": "",
      "budget_amount": 800,
      "currency": "CNY",
      "delivery_hours": 72,
      "work_package_key": "example_package",
      "work_package_name": "示例服务包",
      "work_units": [],
      "acceptance_criteria": "表格字段完整,抽检 20 条无错译。",
      "evidence_requirements": "提交完成的表格和抽检记录。",
      "response_sla_minutes": 30,
      "max_assignment_rounds": 5,
      "project_key": "",
      "project_name": "整理 200 条商品资料并翻译成英文",
      "task_priority": "medium",
      "contributor_pool_rate": 0.2
    },
    "plan_digest": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "estimated_amount": 800,
    "currency": "CNY",
    "unit_count": 0,
    "requires_publish_approval": true
  },
  "meta": {
    "request_id": "req-example-0001",
    "tenant_id": 10
  }
}
400请求内容不符合业务要求,例如幂等键格式不对、请求头与请求体幂等键不一致、订单标识不正确、方案缺少标题或类目、版本参数缺失。
400 的返回字段
字段类型必填说明
detailobject是—
detail.codestring是

错误代码,程序判断用。

detail.messagestring是

中文说明。

detail.detailsobject否

部分错误带的补充信息,例如版本冲突时的 current_version。

401未提供有效的 API 密钥(invalid_api_key),或密钥上下文无效(invalid_api_context)。

返回字段同 400。

403密钥已撤销、过期或申请未获批准(api_key_inactive);申请主体不一致(api_actor_mismatch);会员、企业或成员关系已停用(api_actor_inactive);密钥没有该接口需要的权限(api_scope_denied);或业务规则拒绝,例如自动派单授权无效。

返回字段同 400。

422请求参数或请求体格式不对(FastAPI 默认格式)。
422 的返回字段
字段类型必填说明
detailarray<object>是—
detail[].typestring否—
detail[].locarray<string | integer>否—
detail[].msgstring否—
detail[].inputany否—
429当前密钥每分钟请求次数已达上限(120 次)。

返回字段同 400。

错误返回的格式和重试建议见 错误处理。

调用示例

curl -X POST 'https://www.zhugejunshi.com/api/member-api/v1/outsourcing/preview' \
  -H 'X-Zhuge-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "整理 200 条商品资料并翻译成英文",
  "category": "示例类目",
  "requirement": "按模板整理商品资料,英文翻译需人工校对。",
  "budget_amount": 800,
  "currency": "CNY",
  "delivery_hours": 72,
  "acceptance_criteria": "表格字段完整,抽检 20 条无错译。",
  "evidence_requirements": "提交完成的表格和抽检记录。"
}'

POST检查自动派单授权

/outsourcing/automation/preflight

需要密钥 · 需要权限 outsourcing:dispatch:write

在发布前检查当前自动派单授权是否允许这张单(订单金额、每日预算、在途订单数、类目、币种)。只是参考结果,不创建也不预留任何东西,发布时会重新检查。授权额度由企业管理员在平台上设置,没有授权时 allowed 为 false 或返回 403。需要 outsourcing:dispatch:write 权限(高风险权限,需人工审核批准)。

请求内容 (application/json,必填)

检查自动派单授权的请求字段
字段类型必填说明
titlestring是

外包任务标题。

长度 1–200

categorystring是

服务类目,取值见 GET /outsourcing/catalog。

长度 1–80

requirementstring否

需求说明。

最长 10000

countrystring否

国家或地区。

最长 80

citystring否

城市。

最长 128

contactstring否

联系方式。

最长 128

budget_amountnumber否

预算金额。为 0 时按任务拆解方案自动估算。

范围:0 到 1000000000;默认:0

currencystring否

币种代码,返回时转为大写。

长度 3–8;格式:^[A-Za-z]{3,8}$;默认:CNY

delivery_hoursinteger否

交付时限,单位小时。

范围:1 到 4320;默认:48

work_package_keystring否

标准服务包编号,见外包服务目录。

最长 80

work_unitsarray<object>否

自定义工作单元。不传则按服务包自动拆解。单元内的字段由服务目录定义。

最多 200 项

acceptance_criteriastring否

验收标准。

最长 4000

evidence_requirementsstring否

交付证据要求。

最长 4000

response_sla_minutesinteger否

外包商响应时限,单位分钟。

范围:5 到 1440;默认:30

max_assignment_roundsinteger否

最多派单轮数。

范围:1 到 20;默认:5

project_keystring否

关联项目编号。

最长 100

project_namestring否

关联项目名称,不填时用标题。

最长 200

task_prioritystring否

任务优先级。

可选值:low / medium / high / urgent;格式:^(low|medium|high|urgent)$;默认:medium

contributor_pool_ratenumber否

收益池比例,仅收益分成计费时使用。

范围:0.01 到 1;默认:0.2

请求示例
{
  "title": "整理 200 条商品资料并翻译成英文",
  "category": "示例类目",
  "requirement": "按模板整理商品资料,英文翻译需人工校对。",
  "budget_amount": 800,
  "currency": "CNY",
  "delivery_hours": 72,
  "acceptance_criteria": "表格字段完整,抽检 20 条无错译。",
  "evidence_requirements": "提交完成的表格和抽检记录。"
}

返回

200预检结果。automation_policy 的内容随授权类型变化,这里只写到对象这一层。
200 的返回字段
字段类型必填说明
dataobject否—
data.previewOutsourcingPlanPreview否—
data.preview.planobject否

后端整理后的外包方案。

data.preview.plan.titlestring否—
data.preview.plan.categorystring否—
data.preview.plan.requirementstring否—
data.preview.plan.countrystring否—
data.preview.plan.citystring否—
data.preview.plan.contactstring否—
data.preview.plan.budget_amountnumber否

预算为 0 时是估算金额。

data.preview.plan.currencystring否—
data.preview.plan.delivery_hoursinteger否—
data.preview.plan.work_package_keystring否—
data.preview.plan.work_package_namestring否—
data.preview.plan.work_unitsarray<object>否—
data.preview.plan.acceptance_criteriastring否—
data.preview.plan.evidence_requirementsstring否—
data.preview.plan.response_sla_minutesinteger否—
data.preview.plan.max_assignment_roundsinteger否—
data.preview.plan.project_keystring否—
data.preview.plan.project_namestring否—
data.preview.plan.task_prioritystring否—
data.preview.plan.contributor_pool_ratenumber否—
data.preview.plan_digeststring否

方案摘要(64 位十六进制)。

data.preview.estimated_amountnumber否—
data.preview.currencystring否—
data.preview.unit_countinteger否

工作单元数量。

data.preview.requires_publish_approvalboolean否

始终为 true,发布需要审核授权。

data.automation_policyobject否

授权检查结果,含 allowed 以及超限项 violations 等。

data.advisory_onlyboolean否

始终为 true,表示只是参考。

data.reservation_createdboolean否

始终为 false,预检不预留额度。

data.publish_recheck_requiredboolean否—
data.checked_dimensionsarray<string>否

已检查的维度。

data.unchecked_dimensionsarray<string>否

没有检查的维度,需调用方自行把关。

metaOutsourcingMeta否—
meta.request_idstring否

请求编号:取请求头 X-Request-Id,没有则由服务生成。

meta.tenant_idinteger否

密钥绑定的企业编号。

meta.idempotency_keystring否

写操作才有:本次使用的幂等键。

meta.idempotency_replayedboolean否

写操作才有:是否是重复提交返回的原结果。

meta.cursorinteger否

列表才有:本次使用的游标。

meta.next_cursorinteger否

列表才有:下一次请求使用的游标。

meta.limitinteger否

列表才有:本次使用的条数上限。

返回示例
{
  "data": {
    "preview": {
      "plan": {
        "title": "整理 200 条商品资料并翻译成英文",
        "category": "示例类目",
        "requirement": "按模板整理商品资料,英文翻译需人工校对。",
        "country": "",
        "city": "",
        "contact": "",
        "budget_amount": 800,
        "currency": "CNY",
        "delivery_hours": 72,
        "work_package_key": "example_package",
        "work_package_name": "示例服务包",
        "work_units": [],
        "acceptance_criteria": "表格字段完整,抽检 20 条无错译。",
        "evidence_requirements": "提交完成的表格和抽检记录。",
        "response_sla_minutes": 30,
        "max_assignment_rounds": 5,
        "project_key": "",
        "project_name": "整理 200 条商品资料并翻译成英文",
        "task_priority": "medium",
        "contributor_pool_rate": 0.2
      },
      "plan_digest": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      "estimated_amount": 800,
      "currency": "CNY",
      "unit_count": 0,
      "requires_publish_approval": true
    },
    "automation_policy": {
      "allowed": true,
      "violations": []
    },
    "advisory_only": true,
    "reservation_created": false,
    "publish_recheck_required": true,
    "checked_dimensions": [
      "order_amount",
      "daily_budget",
      "active_orders",
      "category",
      "currency"
    ],
    "unchecked_dimensions": [
      "project_scope",
      "task_risk",
      "sensitive_data",
      "subcontracting"
    ]
  },
  "meta": {
    "request_id": "req-example-0001",
    "tenant_id": 10
  }
}
400请求内容不符合业务要求,例如幂等键格式不对、请求头与请求体幂等键不一致、订单标识不正确、方案缺少标题或类目、版本参数缺失。
400 的返回字段
字段类型必填说明
detailobject是—
detail.codestring是

错误代码,程序判断用。

detail.messagestring是

中文说明。

detail.detailsobject否

部分错误带的补充信息,例如版本冲突时的 current_version。

401未提供有效的 API 密钥(invalid_api_key),或密钥上下文无效(invalid_api_context)。

返回字段同 400。

403密钥已撤销、过期或申请未获批准(api_key_inactive);申请主体不一致(api_actor_mismatch);会员、企业或成员关系已停用(api_actor_inactive);密钥没有该接口需要的权限(api_scope_denied);或业务规则拒绝,例如自动派单授权无效。

返回字段同 400。

422请求参数或请求体格式不对(FastAPI 默认格式)。
422 的返回字段
字段类型必填说明
detailarray<object>是—
detail[].typestring否—
detail[].locarray<string | integer>否—
detail[].msgstring否—
detail[].inputany否—
429当前密钥每分钟请求次数已达上限(120 次)。

返回字段同 400。

错误返回的格式和重试建议见 错误处理。

调用示例

curl -X POST 'https://www.zhugejunshi.com/api/member-api/v1/outsourcing/automation/preflight' \
  -H 'X-Zhuge-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "整理 200 条商品资料并翻译成英文",
  "category": "示例类目",
  "requirement": "按模板整理商品资料,英文翻译需人工校对。",
  "budget_amount": 800,
  "currency": "CNY",
  "delivery_hours": 72,
  "acceptance_criteria": "表格字段完整,抽检 20 条无错译。",
  "evidence_requirements": "提交完成的表格和抽检记录。"
}'

POST保存外包草稿

/outsourcing/drafts

需要密钥 · 需要权限 outsourcing:draft:write

保存外包任务草稿,草稿 30 天内有效,不会自动派单。返回的 plan_digest 要在发布时原样回传确认。必须提供幂等键。需要 outsourcing:draft:write 权限。

请求参数

保存外包草稿的请求参数
参数位置类型必填说明
X-Idempotency-Key请求头string否

幂等键。本接口必须提供幂等键:放在这个请求头里(也接受 Idempotency-Key 请求头),或写在请求体的 idempotency_key 字段里;两处都写时必须一致。8 至 120 位,只能包含字母、数字、点、下划线、冒号和短横线,首位必须是字母或数字。相同幂等键加相同内容会原样返回上次结果(meta.idempotency_replayed 为 true),相同幂等键加不同内容返回 409。

长度 8–120;格式:^[A-Za-z0-9][A-Za-z0-9._:-]{7,119}$

请求内容 (application/json,必填)

保存外包草稿的请求字段
字段类型必填说明
titlestring是

外包任务标题。

长度 1–200

categorystring是

服务类目,取值见 GET /outsourcing/catalog。

长度 1–80

requirementstring否

需求说明。

最长 10000

countrystring否

国家或地区。

最长 80

citystring否

城市。

最长 128

contactstring否

联系方式。

最长 128

budget_amountnumber否

预算金额。为 0 时按任务拆解方案自动估算。

范围:0 到 1000000000;默认:0

currencystring否

币种代码,返回时转为大写。

长度 3–8;格式:^[A-Za-z]{3,8}$;默认:CNY

delivery_hoursinteger否

交付时限,单位小时。

范围:1 到 4320;默认:48

work_package_keystring否

标准服务包编号,见外包服务目录。

最长 80

work_unitsarray<object>否

自定义工作单元。不传则按服务包自动拆解。单元内的字段由服务目录定义。

最多 200 项

acceptance_criteriastring否

验收标准。

最长 4000

evidence_requirementsstring否

交付证据要求。

最长 4000

response_sla_minutesinteger否

外包商响应时限,单位分钟。

范围:5 到 1440;默认:30

max_assignment_roundsinteger否

最多派单轮数。

范围:1 到 20;默认:5

project_keystring否

关联项目编号。

最长 100

project_namestring否

关联项目名称,不填时用标题。

最长 200

task_prioritystring否

任务优先级。

可选值:low / medium / high / urgent;格式:^(low|medium|high|urgent)$;默认:medium

contributor_pool_ratenumber否

收益池比例,仅收益分成计费时使用。

范围:0.01 到 1;默认:0.2

idempotency_keystring否

幂等键,也可以放在 X-Idempotency-Key 请求头里;两处都写时必须一致。

最长 120

agent_run_idstring否

调用方自己的运行编号,仅用于对账记录。

最长 120

decision_digeststring否

调用方的决策摘要,仅用于对账记录。

最长 128

请求示例
{
  "title": "整理 200 条商品资料并翻译成英文",
  "category": "示例类目",
  "requirement": "按模板整理商品资料,英文翻译需人工校对。",
  "budget_amount": 800,
  "currency": "CNY",
  "delivery_hours": 72,
  "acceptance_criteria": "表格字段完整,抽检 20 条无错译。",
  "evidence_requirements": "提交完成的表格和抽检记录。",
  "idempotency_key": "draft-20261107-0001"
}

返回

201草稿已保存。
201 的返回字段
字段类型必填说明
dataobject否—
data.draftobject否

外包草稿。

data.draft.draft_nostring否

草稿号,发布时使用。

data.draft.statusstring否

草稿状态:draft 表示可发布,published 表示已发布。

data.draft.planobject否

后端整理后的外包方案,字段与预览返回的 plan 相同。

data.draft.plan_digeststring否

方案摘要(64 位十六进制)。发布时必须原样放进 decision_digest。

data.draft.estimated_amountnumber否—
data.draft.currencystring否—
data.draft.order_idinteger | null否

发布后生成的订单 id,未发布时为 null。

data.draft.versioninteger否

草稿版本,发布时放进 expected_version。

data.draft.expires_atstring(date-time) | null否

草稿过期时间,创建后 30 天。

data.draft.created_atstring(date-time) | null否—
data.draft.updated_atstring(date-time) | null否—
metaOutsourcingMeta否—
meta.request_idstring否

请求编号:取请求头 X-Request-Id,没有则由服务生成。

meta.tenant_idinteger否

密钥绑定的企业编号。

meta.idempotency_keystring否

写操作才有:本次使用的幂等键。

meta.idempotency_replayedboolean否

写操作才有:是否是重复提交返回的原结果。

meta.cursorinteger否

列表才有:本次使用的游标。

meta.next_cursorinteger否

列表才有:下一次请求使用的游标。

meta.limitinteger否

列表才有:本次使用的条数上限。

返回示例
{
  "data": {
    "draft": {
      "draft_no": "OD-20261107-0123456789abcdef",
      "status": "draft",
      "plan": {
        "title": "整理 200 条商品资料并翻译成英文",
        "category": "示例类目",
        "requirement": "按模板整理商品资料,英文翻译需人工校对。",
        "country": "",
        "city": "",
        "contact": "",
        "budget_amount": 800,
        "currency": "CNY",
        "delivery_hours": 72,
        "work_package_key": "example_package",
        "work_package_name": "示例服务包",
        "work_units": [],
        "acceptance_criteria": "表格字段完整,抽检 20 条无错译。",
        "evidence_requirements": "提交完成的表格和抽检记录。",
        "response_sla_minutes": 30,
        "max_assignment_rounds": 5,
        "project_key": "",
        "project_name": "整理 200 条商品资料并翻译成英文",
        "task_priority": "medium",
        "contributor_pool_rate": 0.2
      },
      "plan_digest": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      "estimated_amount": 800,
      "currency": "CNY",
      "order_id": null,
      "version": 1,
      "expires_at": "2026-12-07T08:00:00",
      "created_at": "2026-11-07T08:00:00",
      "updated_at": "2026-11-07T08:00:00"
    }
  },
  "meta": {
    "request_id": "req-example-0001",
    "tenant_id": 10,
    "idempotency_key": "draft-20261107-0001",
    "idempotency_replayed": false
  }
}
400请求内容不符合业务要求,例如幂等键格式不对、请求头与请求体幂等键不一致、订单标识不正确、方案缺少标题或类目、版本参数缺失。
400 的返回字段
字段类型必填说明
detailobject是—
detail.codestring是

错误代码,程序判断用。

detail.messagestring是

中文说明。

detail.detailsobject否

部分错误带的补充信息,例如版本冲突时的 current_version。

401未提供有效的 API 密钥(invalid_api_key),或密钥上下文无效(invalid_api_context)。

返回字段同 400。

403密钥已撤销、过期或申请未获批准(api_key_inactive);申请主体不一致(api_actor_mismatch);会员、企业或成员关系已停用(api_actor_inactive);密钥没有该接口需要的权限(api_scope_denied);或业务规则拒绝,例如自动派单授权无效。

返回字段同 400。

409与当前状态冲突,例如版本已变化(version_conflict)、同一幂等键用于不同请求(idempotency_conflict)、相同请求正在处理(command_in_progress)、摘要不一致、文件未通过扫描、草稿已过期或不可发布。details 里通常给出当前版本或期望摘要。

返回字段同 400。

422请求参数或请求体格式不对(FastAPI 默认格式)。
422 的返回字段
字段类型必填说明
detailarray<object>是—
detail[].typestring否—
detail[].locarray<string | integer>否—
detail[].msgstring否—
detail[].inputany否—
428缺少必须的幂等键(idempotency_key_required),或发布时没有回传完整的方案摘要(plan_digest_confirmation_required)。

返回字段同 400。

429当前密钥每分钟请求次数已达上限(120 次)。

返回字段同 400。

错误返回的格式和重试建议见 错误处理。

调用示例

curl -X POST 'https://www.zhugejunshi.com/api/member-api/v1/outsourcing/drafts' \
  -H 'X-Zhuge-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "整理 200 条商品资料并翻译成英文",
  "category": "示例类目",
  "requirement": "按模板整理商品资料,英文翻译需人工校对。",
  "budget_amount": 800,
  "currency": "CNY",
  "delivery_hours": 72,
  "acceptance_criteria": "表格字段完整,抽检 20 条无错译。",
  "evidence_requirements": "提交完成的表格和抽检记录。",
  "idempotency_key": "draft-20261107-0001"
}'

POST发布草稿并自动派单

/outsourcing/drafts/{draft_no}/publish

需要密钥 · 需要权限 outsourcing:dispatch:write

正式发布外包订单并启动外包商自动匹配,会产生真实订单。调用前提:草稿属于当前密钥、状态为 draft 且未过期;expected_version 与草稿当前版本一致;decision_digest 必须是草稿里完整的 plan_digest;企业管理员已设置自动派单授权且这张单没有超出授权额度。重复发布同一草稿会返回 already_published 为 true。需要 outsourcing:dispatch:write 权限,这是高风险权限,需要人工审核批准后才可使用。必须提供幂等键。

请求参数

发布草稿并自动派单的请求参数
参数位置类型必填说明
draft_no路径string是

草稿号,来自保存草稿接口返回的 draft.draft_no。

X-Idempotency-Key请求头string否

幂等键。本接口必须提供幂等键:放在这个请求头里(也接受 Idempotency-Key 请求头),或写在请求体的 idempotency_key 字段里;两处都写时必须一致。8 至 120 位,只能包含字母、数字、点、下划线、冒号和短横线,首位必须是字母或数字。相同幂等键加相同内容会原样返回上次结果(meta.idempotency_replayed 为 true),相同幂等键加不同内容返回 409。

长度 8–120;格式:^[A-Za-z0-9][A-Za-z0-9._:-]{7,119}$

请求内容 (application/json,必填)

发布草稿并自动派单的请求字段
字段类型必填说明
expected_versioninteger否

草稿当前版本,来自草稿的 version。

最小 1;默认:1

idempotency_keystring否

幂等键,也可以放在 X-Idempotency-Key 请求头里;两处都写时必须一致。

最长 120

agent_run_idstring否

调用方自己的运行编号,仅用于对账记录。

最长 120

decision_digeststring是

草稿里完整的 plan_digest,用来确认你看过要发布的方案。

长度 64–64;格式:^[0-9a-fA-F]{64}$

请求示例
{
  "expected_version": 1,
  "decision_digest": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "idempotency_key": "publish-20261107-0001"
}

返回

200发布结果。dispatch 与 automation_policy 的内部结构随业务变化,只写到对象这一层。
200 的返回字段
字段类型必填说明
dataobject否—
data.draftobject否

外包草稿。

data.draft.draft_nostring否

草稿号,发布时使用。

data.draft.statusstring否

草稿状态:draft 表示可发布,published 表示已发布。

data.draft.planobject否

后端整理后的外包方案,字段与预览返回的 plan 相同。

data.draft.plan_digeststring否

方案摘要(64 位十六进制)。发布时必须原样放进 decision_digest。

data.draft.estimated_amountnumber否—
data.draft.currencystring否—
data.draft.order_idinteger | null否

发布后生成的订单 id,未发布时为 null。

data.draft.versioninteger否

草稿版本,发布时放进 expected_version。

data.draft.expires_atstring(date-time) | null否

草稿过期时间,创建后 30 天。

data.draft.created_atstring(date-time) | null否—
data.draft.updated_atstring(date-time) | null否—
data.orderobject否

外包订单。

data.order.idinteger否

订单数字 id。

data.order.order_nostring否

订单号。

data.order.demand_idstring否—
data.order.enterprise_idinteger否—
data.order.requester_user_idinteger否—
data.order.task_idinteger否

关联任务 id,没有时为 0。

data.order.vendor_idinteger否

已匹配的外包商 id,尚未匹配时为 0。

data.order.titlestring否—
data.order.categorystring否—
data.order.descriptionstring否—
data.order.work_unitsarray<object>否—
data.order.budget_amountnumber否—
data.order.currencystring否—
data.order.delivery_hoursinteger否—
data.order.response_sla_minutesinteger否—
data.order.assignment_roundinteger否—
data.order.max_assignment_roundsinteger否—
data.order.statusstring否

订单状态,例如 open;状态值随业务流程扩展。

data.order.current_attempt_idinteger否—
data.order.active_fulfillment_idinteger否—
data.order.versioninteger否

订单版本号。状态变更类接口需要在 expected_version 里带上它。

data.order.delivery_due_atstring(date-time) | null否—
data.order.accepted_atstring(date-time) | null否—
data.order.submitted_atstring(date-time) | null否—
data.order.completed_atstring(date-time) | null否—
data.order.billing_modestring否

计费方式,例如固定报价或收益分成。

data.order.quote_amountnumber否—
data.order.contributor_pool_ratenumber否—
data.order.estimated_share_bpsinteger否—
data.order.pricing_basisstring否—
data.order.pricing_learningobject否—
data.order.metadataobject否

订单附加信息,结构随业务变化,只写到这一层。

data.order.created_atstring(date-time) | null否—
data.order.updated_atstring(date-time) | null否—
data.dispatchobject否

派单启动结果。已发布过的草稿再次发布时没有该字段。

data.automation_policyobject否

发布时使用的授权快照。已发布过的草稿再次发布时没有该字段。

data.already_publishedboolean否—
metaOutsourcingMeta否—
meta.request_idstring否

请求编号:取请求头 X-Request-Id,没有则由服务生成。

meta.tenant_idinteger否

密钥绑定的企业编号。

meta.idempotency_keystring否

写操作才有:本次使用的幂等键。

meta.idempotency_replayedboolean否

写操作才有:是否是重复提交返回的原结果。

meta.cursorinteger否

列表才有:本次使用的游标。

meta.next_cursorinteger否

列表才有:下一次请求使用的游标。

meta.limitinteger否

列表才有:本次使用的条数上限。

返回示例
{
  "data": {
    "draft": {
      "draft_no": "OD-20261107-0123456789abcdef",
      "status": "published",
      "plan": {
        "title": "整理 200 条商品资料并翻译成英文",
        "category": "示例类目",
        "requirement": "按模板整理商品资料,英文翻译需人工校对。",
        "country": "",
        "city": "",
        "contact": "",
        "budget_amount": 800,
        "currency": "CNY",
        "delivery_hours": 72,
        "work_package_key": "example_package",
        "work_package_name": "示例服务包",
        "work_units": [],
        "acceptance_criteria": "表格字段完整,抽检 20 条无错译。",
        "evidence_requirements": "提交完成的表格和抽检记录。",
        "response_sla_minutes": 30,
        "max_assignment_rounds": 5,
        "project_key": "",
        "project_name": "整理 200 条商品资料并翻译成英文",
        "task_priority": "medium",
        "contributor_pool_rate": 0.2
      },
      "plan_digest": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      "estimated_amount": 800,
      "currency": "CNY",
      "order_id": 1001,
      "version": 2,
      "expires_at": "2026-12-07T08:00:00",
      "created_at": "2026-11-07T08:00:00",
      "updated_at": "2026-11-07T08:05:00"
    },
    "order": {
      "id": 1001,
      "order_no": "OUT-20261107-0001",
      "demand_id": "",
      "enterprise_id": 10,
      "requester_user_id": 20,
      "task_id": 0,
      "vendor_id": 0,
      "title": "整理 200 条商品资料并翻译成英文",
      "category": "示例类目",
      "description": "按模板整理商品资料,英文翻译需人工校对。",
      "work_units": [],
      "budget_amount": 800,
      "currency": "CNY",
      "delivery_hours": 72,
      "response_sla_minutes": 30,
      "assignment_round": 0,
      "max_assignment_rounds": 5,
      "status": "open",
      "current_attempt_id": 0,
      "active_fulfillment_id": 0,
      "version": 1,
      "delivery_due_at": null,
      "accepted_at": null,
      "submitted_at": null,
      "completed_at": null,
      "billing_mode": "fixed_price",
      "quote_amount": 800,
      "contributor_pool_rate": 0,
      "estimated_share_bps": 0,
      "pricing_basis": "",
      "pricing_learning": {},
      "metadata": {},
      "created_at": "2026-11-07T08:00:00",
      "updated_at": "2026-11-07T08:00:00"
    },
    "dispatch": {},
    "automation_policy": {},
    "already_published": false
  },
  "meta": {
    "request_id": "req-example-0001",
    "tenant_id": 10,
    "idempotency_key": "draft-20261107-0001",
    "idempotency_replayed": false
  }
}
400请求内容不符合业务要求,例如幂等键格式不对、请求头与请求体幂等键不一致、订单标识不正确、方案缺少标题或类目、版本参数缺失。
400 的返回字段
字段类型必填说明
detailobject是—
detail.codestring是

错误代码,程序判断用。

detail.messagestring是

中文说明。

detail.detailsobject否

部分错误带的补充信息,例如版本冲突时的 current_version。

401未提供有效的 API 密钥(invalid_api_key),或密钥上下文无效(invalid_api_context)。

返回字段同 400。

403密钥已撤销、过期或申请未获批准(api_key_inactive);申请主体不一致(api_actor_mismatch);会员、企业或成员关系已停用(api_actor_inactive);密钥没有该接口需要的权限(api_scope_denied);或业务规则拒绝,例如自动派单授权无效。

返回字段同 400。

404资源不存在或不属于当前密钥;路由不存在或请求方法不对时 code 为 member_api_route_not_found。

返回字段同 400。

409与当前状态冲突,例如版本已变化(version_conflict)、同一幂等键用于不同请求(idempotency_conflict)、相同请求正在处理(command_in_progress)、摘要不一致、文件未通过扫描、草稿已过期或不可发布。details 里通常给出当前版本或期望摘要。

返回字段同 400。

422请求参数或请求体格式不对(FastAPI 默认格式)。
422 的返回字段
字段类型必填说明
detailarray<object>是—
detail[].typestring否—
detail[].locarray<string | integer>否—
detail[].msgstring否—
detail[].inputany否—
428缺少必须的幂等键(idempotency_key_required),或发布时没有回传完整的方案摘要(plan_digest_confirmation_required)。

返回字段同 400。

429当前密钥每分钟请求次数已达上限(120 次)。

返回字段同 400。

错误返回的格式和重试建议见 错误处理。

调用示例

curl -X POST 'https://www.zhugejunshi.com/api/member-api/v1/outsourcing/drafts/{draft_no}/publish' \
  -H 'X-Zhuge-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "expected_version": 1,
  "decision_digest": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "idempotency_key": "publish-20261107-0001"
}'

外包订单与事件

读取外包订单详情和状态事件。

GET读取外包订单列表

/outsourcing/orders

需要密钥 · 需要权限 outsourcing:order:read

按订单 id 升序分页返回当前密钥所属会员创建的外包订单,用游标翻页:把返回的 meta.next_cursor 填进下一次的 cursor。没有更多数据时 next_cursor 等于传入的 cursor。需要 outsourcing:order:read 权限。

请求参数

读取外包订单列表的请求参数
参数位置类型必填说明
cursor查询integer否

游标:只返回 id 大于该值的记录,按 id 升序。第一次用 0,之后用上次返回的 meta.next_cursor。

最小 0;默认:0

limit查询integer否

每页条数。

范围:1 到 100;默认:50

status查询string否

按订单状态筛选,不填返回全部。

最长 32

返回

200订单列表。
200 的返回字段
字段类型必填说明
dataobject否—
data.itemsarray<object>否—
data.items[].idinteger否

订单数字 id。

data.items[].order_nostring否

订单号。

data.items[].demand_idstring否—
data.items[].enterprise_idinteger否—
data.items[].requester_user_idinteger否—
data.items[].task_idinteger否

关联任务 id,没有时为 0。

data.items[].vendor_idinteger否

已匹配的外包商 id,尚未匹配时为 0。

data.items[].titlestring否—
data.items[].categorystring否—
data.items[].descriptionstring否—
data.items[].work_unitsarray<object>否—
data.items[].budget_amountnumber否—
data.items[].currencystring否—
data.items[].delivery_hoursinteger否—
data.items[].response_sla_minutesinteger否—
data.items[].assignment_roundinteger否—
data.items[].max_assignment_roundsinteger否—
data.items[].statusstring否

订单状态,例如 open;状态值随业务流程扩展。

data.items[].current_attempt_idinteger否—
data.items[].active_fulfillment_idinteger否—
data.items[].versioninteger否

订单版本号。状态变更类接口需要在 expected_version 里带上它。

data.items[].delivery_due_atstring(date-time) | null否—
data.items[].accepted_atstring(date-time) | null否—
data.items[].submitted_atstring(date-time) | null否—
data.items[].completed_atstring(date-time) | null否—
data.items[].billing_modestring否

计费方式,例如固定报价或收益分成。

data.items[].quote_amountnumber否—
data.items[].contributor_pool_ratenumber否—
data.items[].estimated_share_bpsinteger否—
data.items[].pricing_basisstring否—
data.items[].pricing_learningobject否—
data.items[].metadataobject否

订单附加信息,结构随业务变化,只写到这一层。

data.items[].created_atstring(date-time) | null否—
data.items[].updated_atstring(date-time) | null否—
metaOutsourcingMeta否—
meta.request_idstring否

请求编号:取请求头 X-Request-Id,没有则由服务生成。

meta.tenant_idinteger否

密钥绑定的企业编号。

meta.idempotency_keystring否

写操作才有:本次使用的幂等键。

meta.idempotency_replayedboolean否

写操作才有:是否是重复提交返回的原结果。

meta.cursorinteger否

列表才有:本次使用的游标。

meta.next_cursorinteger否

列表才有:下一次请求使用的游标。

meta.limitinteger否

列表才有:本次使用的条数上限。

返回示例
{
  "data": {
    "items": [
      {
        "id": 1001,
        "order_no": "OUT-20261107-0001",
        "demand_id": "",
        "enterprise_id": 10,
        "requester_user_id": 20,
        "task_id": 0,
        "vendor_id": 0,
        "title": "整理 200 条商品资料并翻译成英文",
        "category": "示例类目",
        "description": "按模板整理商品资料,英文翻译需人工校对。",
        "work_units": [],
        "budget_amount": 800,
        "currency": "CNY",
        "delivery_hours": 72,
        "response_sla_minutes": 30,
        "assignment_round": 0,
        "max_assignment_rounds": 5,
        "status": "open",
        "current_attempt_id": 0,
        "active_fulfillment_id": 0,
        "version": 1,
        "delivery_due_at": null,
        "accepted_at": null,
        "submitted_at": null,
        "completed_at": null,
        "billing_mode": "fixed_price",
        "quote_amount": 800,
        "contributor_pool_rate": 0,
        "estimated_share_bps": 0,
        "pricing_basis": "",
        "pricing_learning": {},
        "metadata": {},
        "created_at": "2026-11-07T08:00:00",
        "updated_at": "2026-11-07T08:00:00"
      }
    ]
  },
  "meta": {
    "request_id": "req-example-0001",
    "tenant_id": 10,
    "cursor": 0,
    "next_cursor": 1001,
    "limit": 50
  }
}
401未提供有效的 API 密钥(invalid_api_key),或密钥上下文无效(invalid_api_context)。
401 的返回字段
字段类型必填说明
detailobject是—
detail.codestring是

错误代码,程序判断用。

detail.messagestring是

中文说明。

detail.detailsobject否

部分错误带的补充信息,例如版本冲突时的 current_version。

403密钥已撤销、过期或申请未获批准(api_key_inactive);申请主体不一致(api_actor_mismatch);会员、企业或成员关系已停用(api_actor_inactive);密钥没有该接口需要的权限(api_scope_denied);或业务规则拒绝,例如自动派单授权无效。

返回字段同 401。

422请求参数或请求体格式不对(FastAPI 默认格式)。
422 的返回字段
字段类型必填说明
detailarray<object>是—
detail[].typestring否—
detail[].locarray<string | integer>否—
detail[].msgstring否—
detail[].inputany否—
429当前密钥每分钟请求次数已达上限(120 次)。

返回字段同 401。

错误返回的格式和重试建议见 错误处理。

调用示例

curl -X GET 'https://www.zhugejunshi.com/api/member-api/v1/outsourcing/orders' \
  -H 'X-Zhuge-API-Key: YOUR_API_KEY'
在线调试

这里会用你填的密钥向正式接口发一次真实请求。密钥只留在本页内存里,不保存、不上传到别处,刷新页面后要重新填写。

GET读取外包订单详情

/outsourcing/orders/{order_id}

需要密钥 · 需要权限 outsourcing:order:read

返回一张外包订单,以及派单轮次记录(attempts)和最近 100 条时效事件(sla_events,按时间正序)。attempts 里除下列字段外,还会带订单标题、计费说明等展示字段。只能读取当前密钥所属会员创建的订单。需要 outsourcing:order:read 权限。

请求参数

读取外包订单详情的请求参数
参数位置类型必填说明
order_id路径string是

外包订单标识:订单数字 id 或订单号 order_no,最长 128 个字符。只能访问当前密钥所属会员创建的订单。

最长 128

返回

200订单详情。
200 的返回字段
字段类型必填说明
dataobject否—
data.orderobject否

外包订单。

data.order.idinteger否

订单数字 id。

data.order.order_nostring否

订单号。

data.order.demand_idstring否—
data.order.enterprise_idinteger否—
data.order.requester_user_idinteger否—
data.order.task_idinteger否

关联任务 id,没有时为 0。

data.order.vendor_idinteger否

已匹配的外包商 id,尚未匹配时为 0。

data.order.titlestring否—
data.order.categorystring否—
data.order.descriptionstring否—
data.order.work_unitsarray<object>否—
data.order.budget_amountnumber否—
data.order.currencystring否—
data.order.delivery_hoursinteger否—
data.order.response_sla_minutesinteger否—
data.order.assignment_roundinteger否—
data.order.max_assignment_roundsinteger否—
data.order.statusstring否

订单状态,例如 open;状态值随业务流程扩展。

data.order.current_attempt_idinteger否—
data.order.active_fulfillment_idinteger否—
data.order.versioninteger否

订单版本号。状态变更类接口需要在 expected_version 里带上它。

data.order.delivery_due_atstring(date-time) | null否—
data.order.accepted_atstring(date-time) | null否—
data.order.submitted_atstring(date-time) | null否—
data.order.completed_atstring(date-time) | null否—
data.order.billing_modestring否

计费方式,例如固定报价或收益分成。

data.order.quote_amountnumber否—
data.order.contributor_pool_ratenumber否—
data.order.estimated_share_bpsinteger否—
data.order.pricing_basisstring否—
data.order.pricing_learningobject否—
data.order.metadataobject否

订单附加信息,结构随业务变化,只写到这一层。

data.order.created_atstring(date-time) | null否—
data.order.updated_atstring(date-time) | null否—
data.attemptsarray<object>否—
data.attempts[].idinteger否—
data.attempts[].offer_idstring否—
data.attempts[].order_idinteger否—
data.attempts[].vendor_idinteger否—
data.attempts[].round_nointeger否—
data.attempts[].match_scorenumber否—
data.attempts[].score_breakdownobject否—
data.attempts[].statusstring否—
data.attempts[].invitation_expires_atstring(date-time) | null否—
data.attempts[].accepted_atstring(date-time) | null否—
data.attempts[].released_atstring(date-time) | null否—
data.attempts[].release_reasonstring否—
data.sla_eventsarray<object>否—
data.sla_events[].idinteger否—
data.sla_events[].event_typestring否—
data.sla_events[].statusstring否—
data.sla_events[].vendor_idinteger | null否—
data.sla_events[].points_deltainteger否—
data.sla_events[].notestring否—
data.sla_events[].metadataobject否—
data.sla_events[].occurred_atstring(date-time) | null否—
metaOutsourcingMeta否—
meta.request_idstring否

请求编号:取请求头 X-Request-Id,没有则由服务生成。

meta.tenant_idinteger否

密钥绑定的企业编号。

meta.idempotency_keystring否

写操作才有:本次使用的幂等键。

meta.idempotency_replayedboolean否

写操作才有:是否是重复提交返回的原结果。

meta.cursorinteger否

列表才有:本次使用的游标。

meta.next_cursorinteger否

列表才有:下一次请求使用的游标。

meta.limitinteger否

列表才有:本次使用的条数上限。

返回示例
{
  "data": {
    "order": {
      "id": 1001,
      "order_no": "OUT-20261107-0001",
      "demand_id": "",
      "enterprise_id": 10,
      "requester_user_id": 20,
      "task_id": 0,
      "vendor_id": 0,
      "title": "整理 200 条商品资料并翻译成英文",
      "category": "示例类目",
      "description": "按模板整理商品资料,英文翻译需人工校对。",
      "work_units": [],
      "budget_amount": 800,
      "currency": "CNY",
      "delivery_hours": 72,
      "response_sla_minutes": 30,
      "assignment_round": 0,
      "max_assignment_rounds": 5,
      "status": "open",
      "current_attempt_id": 0,
      "active_fulfillment_id": 0,
      "version": 1,
      "delivery_due_at": null,
      "accepted_at": null,
      "submitted_at": null,
      "completed_at": null,
      "billing_mode": "fixed_price",
      "quote_amount": 800,
      "contributor_pool_rate": 0,
      "estimated_share_bps": 0,
      "pricing_basis": "",
      "pricing_learning": {},
      "metadata": {},
      "created_at": "2026-11-07T08:00:00",
      "updated_at": "2026-11-07T08:00:00"
    },
    "attempts": [
      {
        "id": 401,
        "offer_id": "dispatch-401",
        "order_id": 1001,
        "vendor_id": 77,
        "round_no": 1,
        "match_score": 86.5,
        "score_breakdown": {},
        "status": "invited",
        "invitation_expires_at": "2026-11-07T08:30:00",
        "accepted_at": null,
        "released_at": null,
        "release_reason": ""
      }
    ],
    "sla_events": [
      {
        "id": 601,
        "event_type": "invited",
        "status": "open",
        "vendor_id": 77,
        "points_delta": 0,
        "note": "",
        "metadata": {},
        "occurred_at": "2026-11-07T08:00:00"
      }
    ]
  },
  "meta": {
    "request_id": "req-example-0001",
    "tenant_id": 10
  }
}
400请求内容不符合业务要求,例如幂等键格式不对、请求头与请求体幂等键不一致、订单标识不正确、方案缺少标题或类目、版本参数缺失。
400 的返回字段
字段类型必填说明
detailobject是—
detail.codestring是

错误代码,程序判断用。

detail.messagestring是

中文说明。

detail.detailsobject否

部分错误带的补充信息,例如版本冲突时的 current_version。

401未提供有效的 API 密钥(invalid_api_key),或密钥上下文无效(invalid_api_context)。

返回字段同 400。

403密钥已撤销、过期或申请未获批准(api_key_inactive);申请主体不一致(api_actor_mismatch);会员、企业或成员关系已停用(api_actor_inactive);密钥没有该接口需要的权限(api_scope_denied);或业务规则拒绝,例如自动派单授权无效。

返回字段同 400。

404资源不存在或不属于当前密钥;路由不存在或请求方法不对时 code 为 member_api_route_not_found。

返回字段同 400。

429当前密钥每分钟请求次数已达上限(120 次)。

返回字段同 400。

错误返回的格式和重试建议见 错误处理。

调用示例

curl -X GET 'https://www.zhugejunshi.com/api/member-api/v1/outsourcing/orders/{order_id}' \
  -H 'X-Zhuge-API-Key: YOUR_API_KEY'
在线调试

这里会用你填的密钥向正式接口发一次真实请求。密钥只留在本页内存里,不保存、不上传到别处,刷新页面后要重新填写。

GET增量读取外包事件

/outsourcing/events

需要密钥 · 需要权限 outsourcing:events:read

按事件 id 升序返回当前会员外包订单的状态事件,适合轮询。wait_seconds 大于 0 时,没有新事件会等待最多这么多秒再返回(长轮询)。事件的 payload 结构随事件类型变化,这里只写到对象这一层。需要 outsourcing:events:read 权限。

请求参数

增量读取外包事件的请求参数
参数位置类型必填说明
cursor查询integer否

游标:只返回 id 大于该值的记录,按 id 升序。第一次用 0,之后用上次返回的 meta.next_cursor。

最小 0;默认:0

limit查询integer否

每次最多返回的事件数。

范围:1 到 100;默认:50

wait_seconds查询integer否

没有新事件时最多等待的秒数。

范围:0 到 25;默认:0

返回

200事件列表。
200 的返回字段
字段类型必填说明
dataobject否—
data.itemsarray<object>否—
data.items[].idinteger否—
data.items[].event_keystring否

事件唯一键,可用于去重。

data.items[].event_typestring否

事件类型,例如 draft.created、order.published。

data.items[].order_idinteger | null否—
data.items[].payloadobject否—
data.items[].created_atstring(date-time) | null否—
metaOutsourcingMeta否—
meta.request_idstring否

请求编号:取请求头 X-Request-Id,没有则由服务生成。

meta.tenant_idinteger否

密钥绑定的企业编号。

meta.idempotency_keystring否

写操作才有:本次使用的幂等键。

meta.idempotency_replayedboolean否

写操作才有:是否是重复提交返回的原结果。

meta.cursorinteger否

列表才有:本次使用的游标。

meta.next_cursorinteger否

列表才有:下一次请求使用的游标。

meta.limitinteger否

列表才有:本次使用的条数上限。

返回示例
{
  "data": {
    "items": [
      {
        "id": 701,
        "event_key": "order:1001:published",
        "event_type": "order.published",
        "order_id": 1001,
        "payload": {
          "order_id": 1001,
          "order_no": "OUT-20261107-0001",
          "status": "open",
          "version": 1
        },
        "created_at": "2026-11-07T08:00:00"
      }
    ]
  },
  "meta": {
    "request_id": "req-example-0001",
    "tenant_id": 10,
    "cursor": 0,
    "next_cursor": 701,
    "limit": 50
  }
}
401未提供有效的 API 密钥(invalid_api_key),或密钥上下文无效(invalid_api_context)。
401 的返回字段
字段类型必填说明
detailobject是—
detail.codestring是

错误代码,程序判断用。

detail.messagestring是

中文说明。

detail.detailsobject否

部分错误带的补充信息,例如版本冲突时的 current_version。

403密钥已撤销、过期或申请未获批准(api_key_inactive);申请主体不一致(api_actor_mismatch);会员、企业或成员关系已停用(api_actor_inactive);密钥没有该接口需要的权限(api_scope_denied);或业务规则拒绝,例如自动派单授权无效。

返回字段同 401。

422请求参数或请求体格式不对(FastAPI 默认格式)。
422 的返回字段
字段类型必填说明
detailarray<object>是—
detail[].typestring否—
detail[].locarray<string | integer>否—
detail[].msgstring否—
detail[].inputany否—
429当前密钥每分钟请求次数已达上限(120 次)。

返回字段同 401。

错误返回的格式和重试建议见 错误处理。

调用示例

curl -X GET 'https://www.zhugejunshi.com/api/member-api/v1/outsourcing/events' \
  -H 'X-Zhuge-API-Key: YOUR_API_KEY'
在线调试

这里会用你填的密钥向正式接口发一次真实请求。密钥只留在本页内存里,不保存、不上传到别处,刷新页面后要重新填写。

外包交付验收

读取交付记录和文件、生成交付检查、发送返工要求、确认验收。

GET读取外包交付记录

/outsourcing/orders/{order_id}/delivery

需要密钥 · 需要权限 outsourcing:delivery:read

返回订单当前有效的交付记录和文件清单。交付说明和文件都来自外包商,属于不可信内容(untrusted_content 为 true),程序使用前请自行校验。只列出经过安全检查的文件的下载入口;文件需要通过可信扫描后才能下载。需要 outsourcing:delivery:read 权限。

请求参数

读取外包交付记录的请求参数
参数位置类型必填说明
order_id路径string是

外包订单标识:订单数字 id 或订单号 order_no,最长 128 个字符。只能访问当前密钥所属会员创建的订单。

最长 128

delivery_version查询integer否

交付版本号。不填时取当前有效的交付版本。

最小 1

返回

200交付记录。fulfillment 是履约批次信息,只写到对象这一层。
200 的返回字段
字段类型必填说明
dataobject否—
data.orderobject否

外包订单。

data.order.idinteger否

订单数字 id。

data.order.order_nostring否

订单号。

data.order.demand_idstring否—
data.order.enterprise_idinteger否—
data.order.requester_user_idinteger否—
data.order.task_idinteger否

关联任务 id,没有时为 0。

data.order.vendor_idinteger否

已匹配的外包商 id,尚未匹配时为 0。

data.order.titlestring否—
data.order.categorystring否—
data.order.descriptionstring否—
data.order.work_unitsarray<object>否—
data.order.budget_amountnumber否—
data.order.currencystring否—
data.order.delivery_hoursinteger否—
data.order.response_sla_minutesinteger否—
data.order.assignment_roundinteger否—
data.order.max_assignment_roundsinteger否—
data.order.statusstring否

订单状态,例如 open;状态值随业务流程扩展。

data.order.current_attempt_idinteger否—
data.order.active_fulfillment_idinteger否—
data.order.versioninteger否

订单版本号。状态变更类接口需要在 expected_version 里带上它。

data.order.delivery_due_atstring(date-time) | null否—
data.order.accepted_atstring(date-time) | null否—
data.order.submitted_atstring(date-time) | null否—
data.order.completed_atstring(date-time) | null否—
data.order.billing_modestring否

计费方式,例如固定报价或收益分成。

data.order.quote_amountnumber否—
data.order.contributor_pool_ratenumber否—
data.order.estimated_share_bpsinteger否—
data.order.pricing_basisstring否—
data.order.pricing_learningobject否—
data.order.metadataobject否

订单附加信息,结构随业务变化,只写到这一层。

data.order.created_atstring(date-time) | null否—
data.order.updated_atstring(date-time) | null否—
data.fulfillmentobject否

当前履约批次信息。

data.deliveryobject否

交付记录。

data.delivery.idinteger否—
data.delivery.submission_nostring否

交付单号。

data.delivery.order_idinteger否—
data.delivery.fulfillment_idinteger否—
data.delivery.task_idinteger否—
data.delivery.vendor_idinteger否—
data.delivery.vendor_user_idinteger否—
data.delivery.versioninteger否

交付版本号。

data.delivery.statusstring否—
data.delivery.summarystring否

外包商提交的交付说明,属于不可信内容,使用前请自行校验。

data.delivery.manifest_hashstring否

交付清单摘要(64 位十六进制)。检查、返工、验收都要原样带上。

data.delivery.review_statusstring否—
data.delivery.review_scorenumber | null否—
data.delivery.review_reportobject | null否

检查报告,结构较深,只写到这一层。

data.delivery.submitted_atstring(date-time) | null否—
data.delivery.reviewed_atstring(date-time) | null否—
data.delivery.artifactsarray<object>否

交付文件清单。

data.delivery.artifacts[].idinteger否

文件 id,用于下载接口。

data.delivery.artifacts[].original_namestring否—
data.delivery.artifacts[].content_typestring否—
data.delivery.artifacts[].size_bytesinteger否—
data.delivery.artifacts[].sha256string否

文件摘要,检查、返工、验收时放进 artifact_hashes。

data.delivery.artifacts[].scan_statusstring否

安全扫描状态,通过可信扫描后才能下载。

data.delivery.artifacts[].scan_enginestring否—
data.delivery.artifacts[].automation_safeboolean否

是否已通过可信扫描、可由程序处理。

data.delivery.artifacts[].download_urlstring否

下载地址(相对路径)。在获取交付记录的接口里,它指向本平台会员接口的下载路径。

data.delivery.artifacts[].created_atstring(date-time) | null否—
data.is_currentboolean否—
data.untrusted_contentboolean否

始终为 true,提醒交付内容不可信。

metaOutsourcingMeta否—
meta.request_idstring否

请求编号:取请求头 X-Request-Id,没有则由服务生成。

meta.tenant_idinteger否

密钥绑定的企业编号。

meta.idempotency_keystring否

写操作才有:本次使用的幂等键。

meta.idempotency_replayedboolean否

写操作才有:是否是重复提交返回的原结果。

meta.cursorinteger否

列表才有:本次使用的游标。

meta.next_cursorinteger否

列表才有:下一次请求使用的游标。

meta.limitinteger否

列表才有:本次使用的条数上限。

返回示例
{
  "data": {
    "order": {
      "id": 1001,
      "order_no": "OUT-20261107-0001",
      "demand_id": "",
      "enterprise_id": 10,
      "requester_user_id": 20,
      "task_id": 0,
      "vendor_id": 0,
      "title": "整理 200 条商品资料并翻译成英文",
      "category": "示例类目",
      "description": "按模板整理商品资料,英文翻译需人工校对。",
      "work_units": [],
      "budget_amount": 800,
      "currency": "CNY",
      "delivery_hours": 72,
      "response_sla_minutes": 30,
      "assignment_round": 0,
      "max_assignment_rounds": 5,
      "status": "open",
      "current_attempt_id": 0,
      "active_fulfillment_id": 0,
      "version": 1,
      "delivery_due_at": null,
      "accepted_at": null,
      "submitted_at": null,
      "completed_at": null,
      "billing_mode": "fixed_price",
      "quote_amount": 800,
      "contributor_pool_rate": 0,
      "estimated_share_bps": 0,
      "pricing_basis": "",
      "pricing_learning": {},
      "metadata": {},
      "created_at": "2026-11-07T08:00:00",
      "updated_at": "2026-11-07T08:00:00"
    },
    "fulfillment": {},
    "delivery": {
      "id": 501,
      "submission_no": "SUB-20261107-0001",
      "order_id": 1001,
      "fulfillment_id": 301,
      "task_id": 0,
      "vendor_id": 77,
      "vendor_user_id": 88,
      "version": 1,
      "status": "submitted",
      "summary": "已按模板完成,附抽检记录。",
      "manifest_hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      "review_status": "pending",
      "review_score": null,
      "review_report": null,
      "submitted_at": "2026-11-08T08:00:00",
      "reviewed_at": null,
      "artifacts": [
        {
          "id": 9001,
          "original_name": "result.xlsx",
          "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
          "size_bytes": 20480,
          "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
          "scan_status": "clean",
          "scan_engine": "example-scanner",
          "automation_safe": true,
          "download_url": "/api/member-api/v1/outsourcing/orders/1001/delivery/artifacts/9001/content?delivery_version=1",
          "created_at": "2026-11-08T08:00:00"
        }
      ]
    },
    "is_current": true,
    "untrusted_content": true
  },
  "meta": {
    "request_id": "req-example-0001",
    "tenant_id": 10
  }
}
400请求内容不符合业务要求,例如幂等键格式不对、请求头与请求体幂等键不一致、订单标识不正确、方案缺少标题或类目、版本参数缺失。
400 的返回字段
字段类型必填说明
detailobject是—
detail.codestring是

错误代码,程序判断用。

detail.messagestring是

中文说明。

detail.detailsobject否

部分错误带的补充信息,例如版本冲突时的 current_version。

401未提供有效的 API 密钥(invalid_api_key),或密钥上下文无效(invalid_api_context)。

返回字段同 400。

403密钥已撤销、过期或申请未获批准(api_key_inactive);申请主体不一致(api_actor_mismatch);会员、企业或成员关系已停用(api_actor_inactive);密钥没有该接口需要的权限(api_scope_denied);或业务规则拒绝,例如自动派单授权无效。

返回字段同 400。

404资源不存在或不属于当前密钥;路由不存在或请求方法不对时 code 为 member_api_route_not_found。

返回字段同 400。

409与当前状态冲突,例如版本已变化(version_conflict)、同一幂等键用于不同请求(idempotency_conflict)、相同请求正在处理(command_in_progress)、摘要不一致、文件未通过扫描、草稿已过期或不可发布。details 里通常给出当前版本或期望摘要。

返回字段同 400。

422请求参数或请求体格式不对(FastAPI 默认格式)。
422 的返回字段
字段类型必填说明
detailarray<object>是—
detail[].typestring否—
detail[].locarray<string | integer>否—
detail[].msgstring否—
detail[].inputany否—
429当前密钥每分钟请求次数已达上限(120 次)。

返回字段同 400。

错误返回的格式和重试建议见 错误处理。

调用示例

curl -X GET 'https://www.zhugejunshi.com/api/member-api/v1/outsourcing/orders/{order_id}/delivery' \
  -H 'X-Zhuge-API-Key: YOUR_API_KEY'
在线调试

这里会用你填的密钥向正式接口发一次真实请求。密钥只留在本页内存里,不保存、不上传到别处,刷新页面后要重新填写。

GET下载交付文件

/outsourcing/orders/{order_id}/delivery/artifacts/{artifact_id}/content

需要密钥 · 需要权限 outsourcing:delivery:read

下载一个交付文件。文件必须已通过可信病毒扫描且完整性校验通过,否则返回 409。存储在对象存储时返回 307 跳转到 5 分钟有效的临时下载地址(请跟随跳转,且不要把本接口的密钥发给跳转后的地址);存储在本地时直接返回文件内容。响应头 X-Artifact-SHA256 是文件摘要,X-Delivery-Manifest-SHA256 是交付清单摘要。需要 outsourcing:delivery:read 权限。

请求参数

下载交付文件的请求参数
参数位置类型必填说明
order_id路径string是

外包订单标识:订单数字 id 或订单号 order_no,最长 128 个字符。只能访问当前密钥所属会员创建的订单。

最长 128

artifact_id路径integer是

交付文件 id,来自交付记录里 artifacts[].id。

delivery_version查询integer否

交付版本号。不填时取当前有效的交付版本。

最小 1

返回

200文件内容,类型为文件自己的 content type。

返回类型:application/octet-stream

307跳转到临时下载地址,地址在响应头 Location 里,5 分钟内有效。

没有返回内容。

400请求内容不符合业务要求,例如幂等键格式不对、请求头与请求体幂等键不一致、订单标识不正确、方案缺少标题或类目、版本参数缺失。
400 的返回字段
字段类型必填说明
detailobject是—
detail.codestring是

错误代码,程序判断用。

detail.messagestring是

中文说明。

detail.detailsobject否

部分错误带的补充信息,例如版本冲突时的 current_version。

401未提供有效的 API 密钥(invalid_api_key),或密钥上下文无效(invalid_api_context)。

返回字段同 400。

403密钥已撤销、过期或申请未获批准(api_key_inactive);申请主体不一致(api_actor_mismatch);会员、企业或成员关系已停用(api_actor_inactive);密钥没有该接口需要的权限(api_scope_denied);或业务规则拒绝,例如自动派单授权无效。

返回字段同 400。

404资源不存在或不属于当前密钥;路由不存在或请求方法不对时 code 为 member_api_route_not_found。

返回字段同 400。

409与当前状态冲突,例如版本已变化(version_conflict)、同一幂等键用于不同请求(idempotency_conflict)、相同请求正在处理(command_in_progress)、摘要不一致、文件未通过扫描、草稿已过期或不可发布。details 里通常给出当前版本或期望摘要。

返回字段同 400。

422请求参数或请求体格式不对(FastAPI 默认格式)。
422 的返回字段
字段类型必填说明
detailarray<object>是—
detail[].typestring否—
detail[].locarray<string | integer>否—
detail[].msgstring否—
detail[].inputany否—
429当前密钥每分钟请求次数已达上限(120 次)。

返回字段同 400。

错误返回的格式和重试建议见 错误处理。

调用示例

curl -X GET 'https://www.zhugejunshi.com/api/member-api/v1/outsourcing/orders/{order_id}/delivery/artifacts/{artifact_id}/content' \
  -H 'X-Zhuge-API-Key: YOUR_API_KEY'
在线调试

这里会用你填的密钥向正式接口发一次真实请求。密钥只留在本页内存里,不保存、不上传到别处,刷新页面后要重新填写。

POST生成交付检查报告

/outsourcing/orders/{order_id}/review-delivery

需要密钥 · 需要权限 outsourcing:inspection:write

针对指定交付版本生成结构化检查报告:后端按规则核对交付,并结合你提交的检查观察结果给出 ai_passed 或 ai_changes_required。这只是检查,不是验收,不会放款(final_acceptance、funds_released 恒为 false)。调用前提:delivery_version、manifest_hash、artifact_hashes 要和当前交付版本一致,expected_version 要等于订单当前 version。必须提供幂等键。需要 outsourcing:inspection:write 权限。请求体不能包含 enterprise_id、requester_user_id、user_id、api_key_id、application_id 这几个字段,身份只从密钥读取,传了会被拒绝;也不接受未列出的其他字段。

请求参数

生成交付检查报告的请求参数
参数位置类型必填说明
order_id路径string是

外包订单标识:订单数字 id 或订单号 order_no,最长 128 个字符。只能访问当前密钥所属会员创建的订单。

最长 128

X-Idempotency-Key请求头string否

幂等键。本接口必须提供幂等键:放在这个请求头里(也接受 Idempotency-Key 请求头),或写在请求体的 idempotency_key 字段里;两处都写时必须一致。8 至 120 位,只能包含字母、数字、点、下划线、冒号和短横线,首位必须是字母或数字。相同幂等键加相同内容会原样返回上次结果(meta.idempotency_replayed 为 true),相同幂等键加不同内容返回 409。

长度 8–120;格式:^[A-Za-z0-9][A-Za-z0-9._:-]{7,119}$

请求内容 (application/json,必填)

生成交付检查报告的请求字段
字段类型必填说明
delivery_versioninteger是

要检查的交付版本。

最小 1

manifest_hashstring是

交付记录里的 manifest_hash,必须与当前交付版本一致。

长度 64–64;格式:^[0-9a-fA-F]{64}$

artifact_hashesarray<string>是

本次交付全部文件的 sha256 列表,必须与当前交付版本一致,否则请求被拒绝。

最多 200 项

conclusionstring否

你的检查结论。

最长 120

confidencenumber | null否

把握程度。

范围:0 到 1

scorenumber | null否

你的评分。

范围:0 到 100

risksarray<string>否

发现的风险。

最多 100 项

failed_checksarray<string>否

未通过的检查项。

最多 100 项

checksarray<object>否

逐项检查记录。

最多 200 项

unit_reviewsarray<object>否

按工作单元的检查记录。

最多 200 项

criteria_resultsarray<object>否

对照验收标准的结果。

最多 200 项

evidencearray<object | string>否

证据。

最多 200 项

commentstring否

补充说明。

最长 4000

expected_versioninteger是

订单当前版本,来自订单的 version。

最小 1

idempotency_keystring否

幂等键,也可以放在 X-Idempotency-Key 请求头里;两处都写时必须一致。

最长 120

agent_run_idstring否

调用方自己的运行编号,仅用于对账记录。

最长 128

decision_digeststring否

调用方的决策摘要,仅用于对账记录。

最长 128

请求示例
{
  "delivery_version": 1,
  "manifest_hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "artifact_hashes": [
    "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  ],
  "expected_version": 3,
  "conclusion": "通过",
  "confidence": 0.9,
  "score": 92,
  "risks": [],
  "failed_checks": [],
  "comment": "抽检 20 条无错译。",
  "idempotency_key": "review-20261108-0001"
}

返回

200检查结果。report 是检查报告,结构较深,只写到对象这一层。
200 的返回字段
字段类型必填说明
dataobject否—
data.review_idstring否

检查编号,确认验收时要回传。

data.decisionstring否

ai_passed 或 ai_changes_required。

data.reportobject否

检查报告,含得分 score、结论 conclusion、文件是否都已通过扫描 all_artifacts_clean 等。

data.deliveryobject否

交付记录。

data.delivery.idinteger否—
data.delivery.submission_nostring否

交付单号。

data.delivery.order_idinteger否—
data.delivery.fulfillment_idinteger否—
data.delivery.task_idinteger否—
data.delivery.vendor_idinteger否—
data.delivery.vendor_user_idinteger否—
data.delivery.versioninteger否

交付版本号。

data.delivery.statusstring否—
data.delivery.summarystring否

外包商提交的交付说明,属于不可信内容,使用前请自行校验。

data.delivery.manifest_hashstring否

交付清单摘要(64 位十六进制)。检查、返工、验收都要原样带上。

data.delivery.review_statusstring否—
data.delivery.review_scorenumber | null否—
data.delivery.review_reportobject | null否

检查报告,结构较深,只写到这一层。

data.delivery.submitted_atstring(date-time) | null否—
data.delivery.reviewed_atstring(date-time) | null否—
data.delivery.artifactsarray<object>否

交付文件清单。

data.delivery.artifacts[].idinteger否

文件 id,用于下载接口。

data.delivery.artifacts[].original_namestring否—
data.delivery.artifacts[].content_typestring否—
data.delivery.artifacts[].size_bytesinteger否—
data.delivery.artifacts[].sha256string否

文件摘要,检查、返工、验收时放进 artifact_hashes。

data.delivery.artifacts[].scan_statusstring否

安全扫描状态,通过可信扫描后才能下载。

data.delivery.artifacts[].scan_enginestring否—
data.delivery.artifacts[].automation_safeboolean否

是否已通过可信扫描、可由程序处理。

data.delivery.artifacts[].download_urlstring否

下载地址(相对路径)。在获取交付记录的接口里,它指向本平台会员接口的下载路径。

data.delivery.artifacts[].created_atstring(date-time) | null否—
data.orderobject否

外包订单。

data.order.idinteger否

订单数字 id。

data.order.order_nostring否

订单号。

data.order.demand_idstring否—
data.order.enterprise_idinteger否—
data.order.requester_user_idinteger否—
data.order.task_idinteger否

关联任务 id,没有时为 0。

data.order.vendor_idinteger否

已匹配的外包商 id,尚未匹配时为 0。

data.order.titlestring否—
data.order.categorystring否—
data.order.descriptionstring否—
data.order.work_unitsarray<object>否—
data.order.budget_amountnumber否—
data.order.currencystring否—
data.order.delivery_hoursinteger否—
data.order.response_sla_minutesinteger否—
data.order.assignment_roundinteger否—
data.order.max_assignment_roundsinteger否—
data.order.statusstring否

订单状态,例如 open;状态值随业务流程扩展。

data.order.current_attempt_idinteger否—
data.order.active_fulfillment_idinteger否—
data.order.versioninteger否

订单版本号。状态变更类接口需要在 expected_version 里带上它。

data.order.delivery_due_atstring(date-time) | null否—
data.order.accepted_atstring(date-time) | null否—
data.order.submitted_atstring(date-time) | null否—
data.order.completed_atstring(date-time) | null否—
data.order.billing_modestring否

计费方式,例如固定报价或收益分成。

data.order.quote_amountnumber否—
data.order.contributor_pool_ratenumber否—
data.order.estimated_share_bpsinteger否—
data.order.pricing_basisstring否—
data.order.pricing_learningobject否—
data.order.metadataobject否

订单附加信息,结构随业务变化,只写到这一层。

data.order.created_atstring(date-time) | null否—
data.order.updated_atstring(date-time) | null否—
data.final_acceptanceboolean否

恒为 false。

data.funds_releasedboolean否

恒为 false。

metaOutsourcingMeta否—
meta.request_idstring否

请求编号:取请求头 X-Request-Id,没有则由服务生成。

meta.tenant_idinteger否

密钥绑定的企业编号。

meta.idempotency_keystring否

写操作才有:本次使用的幂等键。

meta.idempotency_replayedboolean否

写操作才有:是否是重复提交返回的原结果。

meta.cursorinteger否

列表才有:本次使用的游标。

meta.next_cursorinteger否

列表才有:下一次请求使用的游标。

meta.limitinteger否

列表才有:本次使用的条数上限。

返回示例
{
  "data": {
    "review_id": "AIR-501-0123456789abcdef",
    "decision": "ai_passed",
    "report": {
      "review_id": "AIR-501-0123456789abcdef",
      "decision": "ai_passed",
      "score": 92,
      "conclusion": "通过",
      "all_artifacts_clean": true
    },
    "delivery": {
      "id": 501,
      "submission_no": "SUB-20261107-0001",
      "order_id": 1001,
      "fulfillment_id": 301,
      "task_id": 0,
      "vendor_id": 77,
      "vendor_user_id": 88,
      "version": 1,
      "status": "submitted",
      "summary": "已按模板完成,附抽检记录。",
      "manifest_hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      "review_status": "pending",
      "review_score": null,
      "review_report": null,
      "submitted_at": "2026-11-08T08:00:00",
      "reviewed_at": null,
      "artifacts": [
        {
          "id": 9001,
          "original_name": "result.xlsx",
          "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
          "size_bytes": 20480,
          "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
          "scan_status": "clean",
          "scan_engine": "example-scanner",
          "automation_safe": true,
          "download_url": "/api/member-api/v1/outsourcing/orders/1001/delivery/artifacts/9001/content?delivery_version=1",
          "created_at": "2026-11-08T08:00:00"
        }
      ]
    },
    "order": {
      "id": 1001,
      "order_no": "OUT-20261107-0001",
      "demand_id": "",
      "enterprise_id": 10,
      "requester_user_id": 20,
      "task_id": 0,
      "vendor_id": 0,
      "title": "整理 200 条商品资料并翻译成英文",
      "category": "示例类目",
      "description": "按模板整理商品资料,英文翻译需人工校对。",
      "work_units": [],
      "budget_amount": 800,
      "currency": "CNY",
      "delivery_hours": 72,
      "response_sla_minutes": 30,
      "assignment_round": 0,
      "max_assignment_rounds": 5,
      "status": "open",
      "current_attempt_id": 0,
      "active_fulfillment_id": 0,
      "version": 1,
      "delivery_due_at": null,
      "accepted_at": null,
      "submitted_at": null,
      "completed_at": null,
      "billing_mode": "fixed_price",
      "quote_amount": 800,
      "contributor_pool_rate": 0,
      "estimated_share_bps": 0,
      "pricing_basis": "",
      "pricing_learning": {},
      "metadata": {},
      "created_at": "2026-11-07T08:00:00",
      "updated_at": "2026-11-07T08:00:00"
    },
    "final_acceptance": false,
    "funds_released": false
  },
  "meta": {
    "request_id": "req-example-0001",
    "tenant_id": 10,
    "idempotency_key": "draft-20261107-0001",
    "idempotency_replayed": false
  }
}
400请求内容不符合业务要求,例如幂等键格式不对、请求头与请求体幂等键不一致、订单标识不正确、方案缺少标题或类目、版本参数缺失。
400 的返回字段
字段类型必填说明
detailobject是—
detail.codestring是

错误代码,程序判断用。

detail.messagestring是

中文说明。

detail.detailsobject否

部分错误带的补充信息,例如版本冲突时的 current_version。

401未提供有效的 API 密钥(invalid_api_key),或密钥上下文无效(invalid_api_context)。

返回字段同 400。

403密钥已撤销、过期或申请未获批准(api_key_inactive);申请主体不一致(api_actor_mismatch);会员、企业或成员关系已停用(api_actor_inactive);密钥没有该接口需要的权限(api_scope_denied);或业务规则拒绝,例如自动派单授权无效。

返回字段同 400。

404资源不存在或不属于当前密钥;路由不存在或请求方法不对时 code 为 member_api_route_not_found。

返回字段同 400。

409与当前状态冲突,例如版本已变化(version_conflict)、同一幂等键用于不同请求(idempotency_conflict)、相同请求正在处理(command_in_progress)、摘要不一致、文件未通过扫描、草稿已过期或不可发布。details 里通常给出当前版本或期望摘要。

返回字段同 400。

413提交的检查观察结果超过允许大小。

返回字段同 400。

422请求参数或请求体格式不对(FastAPI 默认格式)。
422 的返回字段
字段类型必填说明
detailarray<object>是—
detail[].typestring否—
detail[].locarray<string | integer>否—
detail[].msgstring否—
detail[].inputany否—
428缺少必须的幂等键(idempotency_key_required),或发布时没有回传完整的方案摘要(plan_digest_confirmation_required)。

返回字段同 400。

429当前密钥每分钟请求次数已达上限(120 次)。

返回字段同 400。

错误返回的格式和重试建议见 错误处理。

调用示例

curl -X POST 'https://www.zhugejunshi.com/api/member-api/v1/outsourcing/orders/{order_id}/review-delivery' \
  -H 'X-Zhuge-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "delivery_version": 1,
  "manifest_hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "artifact_hashes": [
    "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  ],
  "expected_version": 3,
  "conclusion": "通过",
  "confidence": 0.9,
  "score": 92,
  "risks": [],
  "failed_checks": [],
  "comment": "抽检 20 条无错译。",
  "idempotency_key": "review-20261108-0001"
}'

POST发送返工要求

/outsourcing/orders/{order_id}/request-changes

需要密钥 · 需要权限 outsourcing:rework:write

向外包商发送结构化修改要求,订单退回返工。调用前提与检查接口相同:交付版本、清单摘要、文件摘要要和当前交付一致,expected_version 要等于订单当前 version。必须提供幂等键。需要 outsourcing:rework:write 权限,这是高风险权限,需要人工审核批准后才可使用。请求体不能包含 enterprise_id、requester_user_id、user_id、api_key_id、application_id 这几个字段,身份只从密钥读取,传了会被拒绝;也不接受未列出的其他字段。

请求参数

发送返工要求的请求参数
参数位置类型必填说明
order_id路径string是

外包订单标识:订单数字 id 或订单号 order_no,最长 128 个字符。只能访问当前密钥所属会员创建的订单。

最长 128

X-Idempotency-Key请求头string否

幂等键。本接口必须提供幂等键:放在这个请求头里(也接受 Idempotency-Key 请求头),或写在请求体的 idempotency_key 字段里;两处都写时必须一致。8 至 120 位,只能包含字母、数字、点、下划线、冒号和短横线,首位必须是字母或数字。相同幂等键加相同内容会原样返回上次结果(meta.idempotency_replayed 为 true),相同幂等键加不同内容返回 409。

长度 8–120;格式:^[A-Za-z0-9][A-Za-z0-9._:-]{7,119}$

请求内容 (application/json,必填)

发送返工要求的请求字段
字段类型必填说明
delivery_versioninteger是

要求返工的交付版本。

最小 1

manifest_hashstring是

交付记录里的 manifest_hash,必须与当前交付版本一致。

长度 64–64;格式:^[0-9a-fA-F]{64}$

artifact_hashesarray<string>是

本次交付全部文件的 sha256 列表,必须与当前交付版本一致,否则请求被拒绝。

最多 200 项

itemsarray<string>是

修改项,每条 1 到 1000 个字符。

1–50 项

commentstring否

补充说明。

最长 2000

expected_versioninteger是

订单当前版本,来自订单的 version。

最小 1

idempotency_keystring否

幂等键,也可以放在 X-Idempotency-Key 请求头里;两处都写时必须一致。

最长 120

agent_run_idstring否

调用方自己的运行编号,仅用于对账记录。

最长 128

decision_digeststring否

调用方的决策摘要,仅用于对账记录。

最长 128

请求示例
{
  "delivery_version": 1,
  "manifest_hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "artifact_hashes": [
    "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  ],
  "items": [
    "第 37 行英文翻译与原文不符,请更正。"
  ],
  "comment": "其余部分合格。",
  "expected_version": 3,
  "idempotency_key": "changes-20261108-0001"
}

返回

200返工要求已发送。
200 的返回字段
字段类型必填说明
dataobject否—
data.changes_requestedboolean否—
data.itemsarray<string>否

后端整理后的修改项,最多 50 条。

data.orderobject否

外包订单。

data.order.idinteger否

订单数字 id。

data.order.order_nostring否

订单号。

data.order.demand_idstring否—
data.order.enterprise_idinteger否—
data.order.requester_user_idinteger否—
data.order.task_idinteger否

关联任务 id,没有时为 0。

data.order.vendor_idinteger否

已匹配的外包商 id,尚未匹配时为 0。

data.order.titlestring否—
data.order.categorystring否—
data.order.descriptionstring否—
data.order.work_unitsarray<object>否—
data.order.budget_amountnumber否—
data.order.currencystring否—
data.order.delivery_hoursinteger否—
data.order.response_sla_minutesinteger否—
data.order.assignment_roundinteger否—
data.order.max_assignment_roundsinteger否—
data.order.statusstring否

订单状态,例如 open;状态值随业务流程扩展。

data.order.current_attempt_idinteger否—
data.order.active_fulfillment_idinteger否—
data.order.versioninteger否

订单版本号。状态变更类接口需要在 expected_version 里带上它。

data.order.delivery_due_atstring(date-time) | null否—
data.order.accepted_atstring(date-time) | null否—
data.order.submitted_atstring(date-time) | null否—
data.order.completed_atstring(date-time) | null否—
data.order.billing_modestring否

计费方式,例如固定报价或收益分成。

data.order.quote_amountnumber否—
data.order.contributor_pool_ratenumber否—
data.order.estimated_share_bpsinteger否—
data.order.pricing_basisstring否—
data.order.pricing_learningobject否—
data.order.metadataobject否

订单附加信息,结构随业务变化,只写到这一层。

data.order.created_atstring(date-time) | null否—
data.order.updated_atstring(date-time) | null否—
data.deliveryobject否

交付记录。

data.delivery.idinteger否—
data.delivery.submission_nostring否

交付单号。

data.delivery.order_idinteger否—
data.delivery.fulfillment_idinteger否—
data.delivery.task_idinteger否—
data.delivery.vendor_idinteger否—
data.delivery.vendor_user_idinteger否—
data.delivery.versioninteger否

交付版本号。

data.delivery.statusstring否—
data.delivery.summarystring否

外包商提交的交付说明,属于不可信内容,使用前请自行校验。

data.delivery.manifest_hashstring否

交付清单摘要(64 位十六进制)。检查、返工、验收都要原样带上。

data.delivery.review_statusstring否—
data.delivery.review_scorenumber | null否—
data.delivery.review_reportobject | null否

检查报告,结构较深,只写到这一层。

data.delivery.submitted_atstring(date-time) | null否—
data.delivery.reviewed_atstring(date-time) | null否—
data.delivery.artifactsarray<object>否

交付文件清单。

data.delivery.artifacts[].idinteger否

文件 id,用于下载接口。

data.delivery.artifacts[].original_namestring否—
data.delivery.artifacts[].content_typestring否—
data.delivery.artifacts[].size_bytesinteger否—
data.delivery.artifacts[].sha256string否

文件摘要,检查、返工、验收时放进 artifact_hashes。

data.delivery.artifacts[].scan_statusstring否

安全扫描状态,通过可信扫描后才能下载。

data.delivery.artifacts[].scan_enginestring否—
data.delivery.artifacts[].automation_safeboolean否

是否已通过可信扫描、可由程序处理。

data.delivery.artifacts[].download_urlstring否

下载地址(相对路径)。在获取交付记录的接口里,它指向本平台会员接口的下载路径。

data.delivery.artifacts[].created_atstring(date-time) | null否—
metaOutsourcingMeta否—
meta.request_idstring否

请求编号:取请求头 X-Request-Id,没有则由服务生成。

meta.tenant_idinteger否

密钥绑定的企业编号。

meta.idempotency_keystring否

写操作才有:本次使用的幂等键。

meta.idempotency_replayedboolean否

写操作才有:是否是重复提交返回的原结果。

meta.cursorinteger否

列表才有:本次使用的游标。

meta.next_cursorinteger否

列表才有:下一次请求使用的游标。

meta.limitinteger否

列表才有:本次使用的条数上限。

返回示例
{
  "data": {
    "changes_requested": true,
    "items": [
      "第 37 行英文翻译与原文不符,请更正。"
    ],
    "order": {
      "id": 1001,
      "order_no": "OUT-20261107-0001",
      "demand_id": "",
      "enterprise_id": 10,
      "requester_user_id": 20,
      "task_id": 0,
      "vendor_id": 0,
      "title": "整理 200 条商品资料并翻译成英文",
      "category": "示例类目",
      "description": "按模板整理商品资料,英文翻译需人工校对。",
      "work_units": [],
      "budget_amount": 800,
      "currency": "CNY",
      "delivery_hours": 72,
      "response_sla_minutes": 30,
      "assignment_round": 0,
      "max_assignment_rounds": 5,
      "status": "open",
      "current_attempt_id": 0,
      "active_fulfillment_id": 0,
      "version": 1,
      "delivery_due_at": null,
      "accepted_at": null,
      "submitted_at": null,
      "completed_at": null,
      "billing_mode": "fixed_price",
      "quote_amount": 800,
      "contributor_pool_rate": 0,
      "estimated_share_bps": 0,
      "pricing_basis": "",
      "pricing_learning": {},
      "metadata": {},
      "created_at": "2026-11-07T08:00:00",
      "updated_at": "2026-11-07T08:00:00"
    },
    "delivery": {
      "id": 501,
      "submission_no": "SUB-20261107-0001",
      "order_id": 1001,
      "fulfillment_id": 301,
      "task_id": 0,
      "vendor_id": 77,
      "vendor_user_id": 88,
      "version": 1,
      "status": "submitted",
      "summary": "已按模板完成,附抽检记录。",
      "manifest_hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      "review_status": "pending",
      "review_score": null,
      "review_report": null,
      "submitted_at": "2026-11-08T08:00:00",
      "reviewed_at": null,
      "artifacts": [
        {
          "id": 9001,
          "original_name": "result.xlsx",
          "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
          "size_bytes": 20480,
          "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
          "scan_status": "clean",
          "scan_engine": "example-scanner",
          "automation_safe": true,
          "download_url": "/api/member-api/v1/outsourcing/orders/1001/delivery/artifacts/9001/content?delivery_version=1",
          "created_at": "2026-11-08T08:00:00"
        }
      ]
    }
  },
  "meta": {
    "request_id": "req-example-0001",
    "tenant_id": 10,
    "idempotency_key": "draft-20261107-0001",
    "idempotency_replayed": false
  }
}
400请求内容不符合业务要求,例如幂等键格式不对、请求头与请求体幂等键不一致、订单标识不正确、方案缺少标题或类目、版本参数缺失。
400 的返回字段
字段类型必填说明
detailobject是—
detail.codestring是

错误代码,程序判断用。

detail.messagestring是

中文说明。

detail.detailsobject否

部分错误带的补充信息,例如版本冲突时的 current_version。

401未提供有效的 API 密钥(invalid_api_key),或密钥上下文无效(invalid_api_context)。

返回字段同 400。

403密钥已撤销、过期或申请未获批准(api_key_inactive);申请主体不一致(api_actor_mismatch);会员、企业或成员关系已停用(api_actor_inactive);密钥没有该接口需要的权限(api_scope_denied);或业务规则拒绝,例如自动派单授权无效。

返回字段同 400。

404资源不存在或不属于当前密钥;路由不存在或请求方法不对时 code 为 member_api_route_not_found。

返回字段同 400。

409与当前状态冲突,例如版本已变化(version_conflict)、同一幂等键用于不同请求(idempotency_conflict)、相同请求正在处理(command_in_progress)、摘要不一致、文件未通过扫描、草稿已过期或不可发布。details 里通常给出当前版本或期望摘要。

返回字段同 400。

422请求参数或请求体格式不对(FastAPI 默认格式)。
422 的返回字段
字段类型必填说明
detailarray<object>是—
detail[].typestring否—
detail[].locarray<string | integer>否—
detail[].msgstring否—
detail[].inputany否—
428缺少必须的幂等键(idempotency_key_required),或发布时没有回传完整的方案摘要(plan_digest_confirmation_required)。

返回字段同 400。

429当前密钥每分钟请求次数已达上限(120 次)。

返回字段同 400。

错误返回的格式和重试建议见 错误处理。

调用示例

curl -X POST 'https://www.zhugejunshi.com/api/member-api/v1/outsourcing/orders/{order_id}/request-changes' \
  -H 'X-Zhuge-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "delivery_version": 1,
  "manifest_hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "artifact_hashes": [
    "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  ],
  "items": [
    "第 37 行英文翻译与原文不符,请更正。"
  ],
  "comment": "其余部分合格。",
  "expected_version": 3,
  "idempotency_key": "changes-20261108-0001"
}'

POST确认交付验收

/outsourcing/orders/{order_id}/accept

需要密钥 · 需要权限 outsourcing:acceptance:write

确认交付通过并给外包商评分,可能推进托管结算(结算交给现有财务流程处理,settlement 为 submitted_to_existing_finance_controls)。调用前提:已用检查接口生成过检查报告并拿到 review_id;交付版本、清单摘要、文件摘要和 expected_version 要与当前一致;企业管理员已设置允许自动验收的授权,且订单金额在授权额度内。包含受控采购或高风险执行结果的订单必须由发布者人工验收,接口返回 409(human_acceptance_required)。必须提供幂等键。需要 outsourcing:acceptance:write 权限,这是高风险权限,需要人工审核批准后才可使用。请求体不能包含 enterprise_id、requester_user_id、user_id、api_key_id、application_id 这几个字段,身份只从密钥读取,传了会被拒绝;也不接受未列出的其他字段。

请求参数

确认交付验收的请求参数
参数位置类型必填说明
order_id路径string是

外包订单标识:订单数字 id 或订单号 order_no,最长 128 个字符。只能访问当前密钥所属会员创建的订单。

最长 128

X-Idempotency-Key请求头string否

幂等键。本接口必须提供幂等键:放在这个请求头里(也接受 Idempotency-Key 请求头),或写在请求体的 idempotency_key 字段里;两处都写时必须一致。8 至 120 位,只能包含字母、数字、点、下划线、冒号和短横线,首位必须是字母或数字。相同幂等键加相同内容会原样返回上次结果(meta.idempotency_replayed 为 true),相同幂等键加不同内容返回 409。

长度 8–120;格式:^[A-Za-z0-9][A-Za-z0-9._:-]{7,119}$

请求内容 (application/json,必填)

确认交付验收的请求字段
字段类型必填说明
delivery_versioninteger是

要验收的交付版本。

最小 1

review_idstring是

检查报告编号,来自检查接口返回的 review_id。

长度 1–128

manifest_hashstring是

交付记录里的 manifest_hash,必须与当前交付版本一致。

长度 64–64;格式:^[0-9a-fA-F]{64}$

artifact_hashesarray<string>是

本次交付全部文件的 sha256 列表,必须与当前交付版本一致,否则请求被拒绝。

最多 200 项

commentstring否

验收评语。

最长 2000

ratingnumber否

给外包商的评分。

范围:1 到 5;默认:5

expected_versioninteger是

订单当前版本,来自订单的 version。

最小 1

idempotency_keystring否

幂等键,也可以放在 X-Idempotency-Key 请求头里;两处都写时必须一致。

最长 120

agent_run_idstring否

调用方自己的运行编号,仅用于对账记录。

最长 128

decision_digeststring否

调用方的决策摘要,仅用于对账记录。

最长 128

请求示例
{
  "delivery_version": 1,
  "review_id": "AIR-501-0123456789abcdef",
  "manifest_hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "artifact_hashes": [
    "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  ],
  "comment": "交付合格。",
  "rating": 5,
  "expected_version": 3,
  "idempotency_key": "accept-20261108-0001"
}

返回

200验收结果。automation_grant 是验收时使用的授权判定,只写到对象这一层。
200 的返回字段
字段类型必填说明
dataobject否—
data.acceptedboolean否—
data.review_idstring否—
data.orderobject否

外包订单。

data.order.idinteger否

订单数字 id。

data.order.order_nostring否

订单号。

data.order.demand_idstring否—
data.order.enterprise_idinteger否—
data.order.requester_user_idinteger否—
data.order.task_idinteger否

关联任务 id,没有时为 0。

data.order.vendor_idinteger否

已匹配的外包商 id,尚未匹配时为 0。

data.order.titlestring否—
data.order.categorystring否—
data.order.descriptionstring否—
data.order.work_unitsarray<object>否—
data.order.budget_amountnumber否—
data.order.currencystring否—
data.order.delivery_hoursinteger否—
data.order.response_sla_minutesinteger否—
data.order.assignment_roundinteger否—
data.order.max_assignment_roundsinteger否—
data.order.statusstring否

订单状态,例如 open;状态值随业务流程扩展。

data.order.current_attempt_idinteger否—
data.order.active_fulfillment_idinteger否—
data.order.versioninteger否

订单版本号。状态变更类接口需要在 expected_version 里带上它。

data.order.delivery_due_atstring(date-time) | null否—
data.order.accepted_atstring(date-time) | null否—
data.order.submitted_atstring(date-time) | null否—
data.order.completed_atstring(date-time) | null否—
data.order.billing_modestring否

计费方式,例如固定报价或收益分成。

data.order.quote_amountnumber否—
data.order.contributor_pool_ratenumber否—
data.order.estimated_share_bpsinteger否—
data.order.pricing_basisstring否—
data.order.pricing_learningobject否—
data.order.metadataobject否

订单附加信息,结构随业务变化,只写到这一层。

data.order.created_atstring(date-time) | null否—
data.order.updated_atstring(date-time) | null否—
data.deliveryobject否

交付记录。

data.delivery.idinteger否—
data.delivery.submission_nostring否

交付单号。

data.delivery.order_idinteger否—
data.delivery.fulfillment_idinteger否—
data.delivery.task_idinteger否—
data.delivery.vendor_idinteger否—
data.delivery.vendor_user_idinteger否—
data.delivery.versioninteger否

交付版本号。

data.delivery.statusstring否—
data.delivery.summarystring否

外包商提交的交付说明,属于不可信内容,使用前请自行校验。

data.delivery.manifest_hashstring否

交付清单摘要(64 位十六进制)。检查、返工、验收都要原样带上。

data.delivery.review_statusstring否—
data.delivery.review_scorenumber | null否—
data.delivery.review_reportobject | null否

检查报告,结构较深,只写到这一层。

data.delivery.submitted_atstring(date-time) | null否—
data.delivery.reviewed_atstring(date-time) | null否—
data.delivery.artifactsarray<object>否

交付文件清单。

data.delivery.artifacts[].idinteger否

文件 id,用于下载接口。

data.delivery.artifacts[].original_namestring否—
data.delivery.artifacts[].content_typestring否—
data.delivery.artifacts[].size_bytesinteger否—
data.delivery.artifacts[].sha256string否

文件摘要,检查、返工、验收时放进 artifact_hashes。

data.delivery.artifacts[].scan_statusstring否

安全扫描状态,通过可信扫描后才能下载。

data.delivery.artifacts[].scan_enginestring否—
data.delivery.artifacts[].automation_safeboolean否

是否已通过可信扫描、可由程序处理。

data.delivery.artifacts[].download_urlstring否

下载地址(相对路径)。在获取交付记录的接口里,它指向本平台会员接口的下载路径。

data.delivery.artifacts[].created_atstring(date-time) | null否—
data.settlementstring否

结算状态,固定为 submitted_to_existing_finance_controls。

data.automation_grantobject否—
metaOutsourcingMeta否—
meta.request_idstring否

请求编号:取请求头 X-Request-Id,没有则由服务生成。

meta.tenant_idinteger否

密钥绑定的企业编号。

meta.idempotency_keystring否

写操作才有:本次使用的幂等键。

meta.idempotency_replayedboolean否

写操作才有:是否是重复提交返回的原结果。

meta.cursorinteger否

列表才有:本次使用的游标。

meta.next_cursorinteger否

列表才有:下一次请求使用的游标。

meta.limitinteger否

列表才有:本次使用的条数上限。

返回示例
{
  "data": {
    "accepted": true,
    "review_id": "AIR-501-0123456789abcdef",
    "order": {
      "id": 1001,
      "order_no": "OUT-20261107-0001",
      "demand_id": "",
      "enterprise_id": 10,
      "requester_user_id": 20,
      "task_id": 0,
      "vendor_id": 0,
      "title": "整理 200 条商品资料并翻译成英文",
      "category": "示例类目",
      "description": "按模板整理商品资料,英文翻译需人工校对。",
      "work_units": [],
      "budget_amount": 800,
      "currency": "CNY",
      "delivery_hours": 72,
      "response_sla_minutes": 30,
      "assignment_round": 0,
      "max_assignment_rounds": 5,
      "status": "open",
      "current_attempt_id": 0,
      "active_fulfillment_id": 0,
      "version": 1,
      "delivery_due_at": null,
      "accepted_at": null,
      "submitted_at": null,
      "completed_at": null,
      "billing_mode": "fixed_price",
      "quote_amount": 800,
      "contributor_pool_rate": 0,
      "estimated_share_bps": 0,
      "pricing_basis": "",
      "pricing_learning": {},
      "metadata": {},
      "created_at": "2026-11-07T08:00:00",
      "updated_at": "2026-11-07T08:00:00"
    },
    "delivery": {
      "id": 501,
      "submission_no": "SUB-20261107-0001",
      "order_id": 1001,
      "fulfillment_id": 301,
      "task_id": 0,
      "vendor_id": 77,
      "vendor_user_id": 88,
      "version": 1,
      "status": "submitted",
      "summary": "已按模板完成,附抽检记录。",
      "manifest_hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      "review_status": "pending",
      "review_score": null,
      "review_report": null,
      "submitted_at": "2026-11-08T08:00:00",
      "reviewed_at": null,
      "artifacts": [
        {
          "id": 9001,
          "original_name": "result.xlsx",
          "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
          "size_bytes": 20480,
          "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
          "scan_status": "clean",
          "scan_engine": "example-scanner",
          "automation_safe": true,
          "download_url": "/api/member-api/v1/outsourcing/orders/1001/delivery/artifacts/9001/content?delivery_version=1",
          "created_at": "2026-11-08T08:00:00"
        }
      ]
    },
    "settlement": "submitted_to_existing_finance_controls",
    "automation_grant": {}
  },
  "meta": {
    "request_id": "req-example-0001",
    "tenant_id": 10,
    "idempotency_key": "draft-20261107-0001",
    "idempotency_replayed": false
  }
}
400请求内容不符合业务要求,例如幂等键格式不对、请求头与请求体幂等键不一致、订单标识不正确、方案缺少标题或类目、版本参数缺失。
400 的返回字段
字段类型必填说明
detailobject是—
detail.codestring是

错误代码,程序判断用。

detail.messagestring是

中文说明。

detail.detailsobject否

部分错误带的补充信息,例如版本冲突时的 current_version。

401未提供有效的 API 密钥(invalid_api_key),或密钥上下文无效(invalid_api_context)。

返回字段同 400。

403密钥已撤销、过期或申请未获批准(api_key_inactive);申请主体不一致(api_actor_mismatch);会员、企业或成员关系已停用(api_actor_inactive);密钥没有该接口需要的权限(api_scope_denied);或业务规则拒绝,例如自动派单授权无效。

返回字段同 400。

404资源不存在或不属于当前密钥;路由不存在或请求方法不对时 code 为 member_api_route_not_found。

返回字段同 400。

409与当前状态冲突,例如版本已变化(version_conflict)、同一幂等键用于不同请求(idempotency_conflict)、相同请求正在处理(command_in_progress)、摘要不一致、文件未通过扫描、草稿已过期或不可发布。details 里通常给出当前版本或期望摘要。

返回字段同 400。

422请求参数或请求体格式不对(FastAPI 默认格式)。
422 的返回字段
字段类型必填说明
detailarray<object>是—
detail[].typestring否—
detail[].locarray<string | integer>否—
detail[].msgstring否—
detail[].inputany否—
428缺少必须的幂等键(idempotency_key_required),或发布时没有回传完整的方案摘要(plan_digest_confirmation_required)。

返回字段同 400。

429当前密钥每分钟请求次数已达上限(120 次)。

返回字段同 400。

错误返回的格式和重试建议见 错误处理。

调用示例

curl -X POST 'https://www.zhugejunshi.com/api/member-api/v1/outsourcing/orders/{order_id}/accept' \
  -H 'X-Zhuge-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "delivery_version": 1,
  "review_id": "AIR-501-0123456789abcdef",
  "manifest_hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "artifact_hashes": [
    "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  ],
  "comment": "交付合格。",
  "rating": 5,
  "expected_version": 3,
  "idempotency_key": "accept-20261108-0001"
}'

安卓执行器

读取受控安卓设备与任务,创建待主账号激活的执行草案,急停任务。

GET读取安卓设备

/android-executor/devices

需要密钥 · 需要权限 android-executor:read

返回当前会员名下已绑定的安卓设备。不返回设备凭据。需要 android-executor:read 权限。

返回

200设备列表。
200 的返回字段
字段类型必填说明
devicesarray<AndroidDevice>否—
devices[].device_idstring否—
devices[].display_namestring否—
devices[].statusstring否—
devices[].android_versionstring否—
devices[].app_versionstring否—
devices[].capabilitiesarray<string>否—
devices[].credential_versioninteger否—
devices[].last_seen_atstring(date-time) | null否—
devices[].revoked_atstring(date-time) | null否—
devices[].created_atstring(date-time) | null否—
devices[].updated_atstring(date-time) | null否—
返回示例
{
  "devices": [
    {
      "device_id": "dev_0123456789abcdef",
      "display_name": "示例手机",
      "status": "active",
      "android_version": "14",
      "app_version": "1.0.0",
      "capabilities": [
        "EXECUTE_PLAN"
      ],
      "credential_version": 1,
      "last_seen_at": "2026-11-07T08:00:00",
      "revoked_at": null,
      "created_at": "2026-11-01T08:00:00",
      "updated_at": "2026-11-07T08:00:00"
    }
  ]
}
401未提供有效的 API 密钥(invalid_api_key),或密钥上下文无效(invalid_api_context)。
401 的返回字段
字段类型必填说明
detailobject是—
detail.codestring是

错误代码,程序判断用。

detail.messagestring是

中文说明。

detail.detailsobject否

部分错误带的补充信息,例如版本冲突时的 current_version。

403密钥已撤销、过期或申请未获批准(api_key_inactive);申请主体不一致(api_actor_mismatch);会员、企业或成员关系已停用(api_actor_inactive);密钥没有该接口需要的权限(api_scope_denied);或业务规则拒绝,例如自动派单授权无效。

返回字段同 401。

409与当前状态冲突,例如版本已变化(version_conflict)、同一幂等键用于不同请求(idempotency_conflict)、相同请求正在处理(command_in_progress)、摘要不一致、文件未通过扫描、草稿已过期或不可发布。details 里通常给出当前版本或期望摘要。

返回字段同 401。

429当前密钥每分钟请求次数已达上限(120 次)。

返回字段同 401。

错误返回的格式和重试建议见 错误处理。

调用示例

curl -X GET 'https://www.zhugejunshi.com/api/member-api/v1/android-executor/devices' \
  -H 'X-Zhuge-API-Key: YOUR_API_KEY'
在线调试

这里会用你填的密钥向正式接口发一次真实请求。密钥只留在本页内存里,不保存、不上传到别处,刷新页面后要重新填写。

GET读取安卓执行任务

/android-executor/tasks

需要密钥 · 需要权限 android-executor:read

返回当前会员的安卓执行任务和草案。结果、错误信息里的敏感内容已脱敏。需要 android-executor:read 权限。

请求参数

读取安卓执行任务的请求参数
参数位置类型必填说明
limit查询integer否

返回条数。

范围:1 到 100;默认:50

返回

200任务列表。
200 的返回字段
字段类型必填说明
tasksarray<AndroidTask>否—
tasks[].task_idstring否—
tasks[].device_idstring否—
tasks[].titlestring否—
tasks[].action_typestring否—
tasks[].target_appstring否—
tasks[].target_packagestring否—
tasks[].workflow_typestring否—
tasks[].planobject否

已脱敏的执行计划。

tasks[].plan_digeststring否—
tasks[].plan_summaryobject否—
tasks[].policyobject否—
tasks[].statusstring否

任务状态,例如 draft_proposal、stop_requested。

tasks[].decisionstring否—
tasks[].decision_reasonstring否—
tasks[].resultobject否—
tasks[].errorobject否—
tasks[].proposal_sourcestring否

来源,经本接口创建的为 member_api。

tasks[].requires_primary_activationboolean否

状态为 draft_proposal 时为 true,需主账号激活。

tasks[].activated_atstring(date-time) | null否—
tasks[].current_step_indexinteger否—
tasks[].paused_atstring(date-time) | null否—
tasks[].current_checkpointobject | null否

当前检查点,字段同检查点列表里的单项。

tasks[].expires_atstring(date-time) | null否—
tasks[].stop_requestedboolean否—
tasks[].decision_atstring(date-time) | null否—
tasks[].approved_atstring(date-time) | null否—
tasks[].started_atstring(date-time) | null否—
tasks[].completed_atstring(date-time) | null否—
tasks[].created_atstring(date-time) | null否—
tasks[].updated_atstring(date-time) | null否—
返回示例
{
  "tasks": [
    {
      "task_id": "task_0123456789abcdef",
      "device_id": "dev_0123456789abcdef",
      "title": "示例采购任务",
      "action_type": "EXECUTE_PLAN",
      "target_app": "taobao",
      "target_package": "com.example.app",
      "workflow_type": "TAOBAO_PURCHASE",
      "plan": {
        "steps": []
      },
      "plan_digest": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      "plan_summary": {},
      "policy": {},
      "status": "awaiting_approval",
      "decision": "pending",
      "decision_reason": "",
      "result": {},
      "error": {},
      "proposal_source": "member_api",
      "requires_primary_activation": false,
      "activated_at": null,
      "current_step_index": 0,
      "paused_at": null,
      "current_checkpoint": null,
      "expires_at": "2026-11-07T08:10:00",
      "stop_requested": false,
      "decision_at": null,
      "approved_at": null,
      "started_at": null,
      "completed_at": null,
      "created_at": "2026-11-07T08:00:00",
      "updated_at": "2026-11-07T08:00:00"
    }
  ]
}
401未提供有效的 API 密钥(invalid_api_key),或密钥上下文无效(invalid_api_context)。
401 的返回字段
字段类型必填说明
detailobject是—
detail.codestring是

错误代码,程序判断用。

detail.messagestring是

中文说明。

detail.detailsobject否

部分错误带的补充信息,例如版本冲突时的 current_version。

403密钥已撤销、过期或申请未获批准(api_key_inactive);申请主体不一致(api_actor_mismatch);会员、企业或成员关系已停用(api_actor_inactive);密钥没有该接口需要的权限(api_scope_denied);或业务规则拒绝,例如自动派单授权无效。

返回字段同 401。

409与当前状态冲突,例如版本已变化(version_conflict)、同一幂等键用于不同请求(idempotency_conflict)、相同请求正在处理(command_in_progress)、摘要不一致、文件未通过扫描、草稿已过期或不可发布。details 里通常给出当前版本或期望摘要。

返回字段同 401。

422请求参数或请求体格式不对(FastAPI 默认格式)。
422 的返回字段
字段类型必填说明
detailarray<object>是—
detail[].typestring否—
detail[].locarray<string | integer>否—
detail[].msgstring否—
detail[].inputany否—
429当前密钥每分钟请求次数已达上限(120 次)。

返回字段同 401。

错误返回的格式和重试建议见 错误处理。

调用示例

curl -X GET 'https://www.zhugejunshi.com/api/member-api/v1/android-executor/tasks' \
  -H 'X-Zhuge-API-Key: YOUR_API_KEY'
在线调试

这里会用你填的密钥向正式接口发一次真实请求。密钥只留在本页内存里,不保存、不上传到别处,刷新页面后要重新填写。

GET读取加密资料引用

/android-executor/profile-values

需要密钥 · 需要权限 android-executor:read

返回当前会员为安卓执行准备的加密资料引用(value_ref)和脱敏显示值,不返回明文。需要 android-executor:read 权限。

请求参数

读取加密资料引用的请求参数
参数位置类型必填说明
include_revoked查询boolean否

是否包含已撤销的资料。

默认:false

返回

200资料引用列表。
200 的返回字段
字段类型必填说明
profile_valuesarray<object>否—
profile_values[].value_refstring否

资料引用,创建执行草案的步骤里用它引用资料。

profile_values[].value_kindstring否—
profile_values[].labelstring否—
profile_values[].masked_valuestring否

脱敏后的显示值。

profile_values[].statusstring否—
profile_values[].revoked_atstring(date-time) | null否—
profile_values[].created_atstring(date-time) | null否—
profile_values[].updated_atstring(date-time) | null否—
返回示例
{
  "profile_values": [
    {
      "value_ref": "pv_0123456789abcdef",
      "value_kind": "phone",
      "label": "收货电话",
      "masked_value": "138****0000",
      "status": "active",
      "revoked_at": null,
      "created_at": "2026-11-01T08:00:00",
      "updated_at": "2026-11-01T08:00:00"
    }
  ]
}
401未提供有效的 API 密钥(invalid_api_key),或密钥上下文无效(invalid_api_context)。
401 的返回字段
字段类型必填说明
detailobject是—
detail.codestring是

错误代码,程序判断用。

detail.messagestring是

中文说明。

detail.detailsobject否

部分错误带的补充信息,例如版本冲突时的 current_version。

403密钥已撤销、过期或申请未获批准(api_key_inactive);申请主体不一致(api_actor_mismatch);会员、企业或成员关系已停用(api_actor_inactive);密钥没有该接口需要的权限(api_scope_denied);或业务规则拒绝,例如自动派单授权无效。

返回字段同 401。

409与当前状态冲突,例如版本已变化(version_conflict)、同一幂等键用于不同请求(idempotency_conflict)、相同请求正在处理(command_in_progress)、摘要不一致、文件未通过扫描、草稿已过期或不可发布。details 里通常给出当前版本或期望摘要。

返回字段同 401。

422请求参数或请求体格式不对(FastAPI 默认格式)。
422 的返回字段
字段类型必填说明
detailarray<object>是—
detail[].typestring否—
detail[].locarray<string | integer>否—
detail[].msgstring否—
detail[].inputany否—
429当前密钥每分钟请求次数已达上限(120 次)。

返回字段同 401。

错误返回的格式和重试建议见 错误处理。

调用示例

curl -X GET 'https://www.zhugejunshi.com/api/member-api/v1/android-executor/profile-values' \
  -H 'X-Zhuge-API-Key: YOUR_API_KEY'
在线调试

这里会用你填的密钥向正式接口发一次真实请求。密钥只留在本页内存里,不保存、不上传到别处,刷新页面后要重新填写。

POST创建安卓执行草案

/android-executor/proposals

需要密钥 · 需要权限 android-executor:draft:write

为指定设备创建安卓受控执行草案。草案状态为 draft_proposal,必须由主账号在平台上激活后才会派发到手机,本接口不能派发、批准或恢复任务(requires_primary_activation 恒为 true)。步骤 steps 的具体格式由安卓执行器的计划规则校验,不合规返回 4xx 错误。必须提供 X-Idempotency-Key 请求头,相同幂等键加相同内容重复提交返回同一草案(idempotency_replayed 为 true)。需要 android-executor:draft:write 权限。

请求参数

创建安卓执行草案的请求参数
参数位置类型必填说明
X-Idempotency-Key请求头string是

幂等键,8 至 120 位,只能包含字母、数字、点、下划线、冒号和短横线,首位必须是字母或数字。缺失返回 428。

长度 8–120;格式:^[A-Za-z0-9][A-Za-z0-9._:-]{7,119}$

请求内容 (application/json,必填)

创建安卓执行草案的请求字段
字段类型必填说明
device_idstring是

设备编号,来自设备列表。

长度 16–64

titlestring是

任务标题。

长度 1–200

action_typestring否

动作类型,目前只有 EXECUTE_PLAN。

可选值:EXECUTE_PLAN;格式:^EXECUTE_PLAN$;默认:EXECUTE_PLAN

target_appstring是

目标应用。

可选值:taobao / uu_runner;格式:^(taobao|uu_runner)$

workflow_typestring是

流程类型。

可选值:TAOBAO_PURCHASE / UU_ERRAND;格式:^(TAOBAO_PURCHASE|UU_ERRAND)$

stepsarray<object>是

执行步骤。单个步骤的字段由安卓执行器的计划规则校验,包含敏感内容的输入请使用加密资料引用(value_ref),不要放明文。

1–40 项

expires_in_minutesinteger否

草案有效期,单位分钟。

范围:1 到 60;默认:10

请求示例
{
  "device_id": "dev_0123456789abcdef",
  "title": "示例采购任务",
  "action_type": "EXECUTE_PLAN",
  "target_app": "taobao",
  "workflow_type": "TAOBAO_PURCHASE",
  "steps": [
    {
      "id": "step-1",
      "type": "OPEN_APP"
    }
  ],
  "expires_in_minutes": 10
}

返回

201草案已创建。
201 的返回字段
字段类型必填说明
proposalAndroidTask否

安卓执行任务。plan、policy、result、error 的内部结构较深,只写到对象这一层;敏感内容已脱敏。

proposal.task_idstring否—
proposal.device_idstring否—
proposal.titlestring否—
proposal.action_typestring否—
proposal.target_appstring否—
proposal.target_packagestring否—
proposal.workflow_typestring否—
proposal.planobject否

已脱敏的执行计划。

proposal.plan_digeststring否—
proposal.plan_summaryobject否—
proposal.policyobject否—
proposal.statusstring否

任务状态,例如 draft_proposal、stop_requested。

proposal.decisionstring否—
proposal.decision_reasonstring否—
proposal.resultobject否—
proposal.errorobject否—
proposal.proposal_sourcestring否

来源,经本接口创建的为 member_api。

proposal.requires_primary_activationboolean否

状态为 draft_proposal 时为 true,需主账号激活。

proposal.activated_atstring(date-time) | null否—
proposal.current_step_indexinteger否—
proposal.paused_atstring(date-time) | null否—
proposal.current_checkpointobject | null否

当前检查点,字段同检查点列表里的单项。

proposal.expires_atstring(date-time) | null否—
proposal.stop_requestedboolean否—
proposal.decision_atstring(date-time) | null否—
proposal.approved_atstring(date-time) | null否—
proposal.started_atstring(date-time) | null否—
proposal.completed_atstring(date-time) | null否—
proposal.created_atstring(date-time) | null否—
proposal.updated_atstring(date-time) | null否—
idempotency_replayedboolean否—
requires_primary_activationboolean否

恒为 true,需主账号激活。

返回示例
{
  "proposal": {
    "task_id": "task_0123456789abcdef",
    "device_id": "dev_0123456789abcdef",
    "title": "示例采购任务",
    "action_type": "EXECUTE_PLAN",
    "target_app": "taobao",
    "target_package": "com.example.app",
    "workflow_type": "TAOBAO_PURCHASE",
    "plan": {
      "steps": []
    },
    "plan_digest": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "plan_summary": {},
    "policy": {},
    "status": "draft_proposal",
    "decision": "pending",
    "decision_reason": "",
    "result": {},
    "error": {},
    "proposal_source": "member_api",
    "requires_primary_activation": true,
    "activated_at": null,
    "current_step_index": 0,
    "paused_at": null,
    "current_checkpoint": null,
    "expires_at": "2026-11-07T08:10:00",
    "stop_requested": false,
    "decision_at": null,
    "approved_at": null,
    "started_at": null,
    "completed_at": null,
    "created_at": "2026-11-07T08:00:00",
    "updated_at": "2026-11-07T08:00:00"
  },
  "idempotency_replayed": false,
  "requires_primary_activation": true
}
400请求内容不符合业务要求,例如幂等键格式不对、请求头与请求体幂等键不一致、订单标识不正确、方案缺少标题或类目、版本参数缺失。
400 的返回字段
字段类型必填说明
detailobject是—
detail.codestring是

错误代码,程序判断用。

detail.messagestring是

中文说明。

detail.detailsobject否

部分错误带的补充信息,例如版本冲突时的 current_version。

401未提供有效的 API 密钥(invalid_api_key),或密钥上下文无效(invalid_api_context)。

返回字段同 400。

403密钥已撤销、过期或申请未获批准(api_key_inactive);申请主体不一致(api_actor_mismatch);会员、企业或成员关系已停用(api_actor_inactive);密钥没有该接口需要的权限(api_scope_denied);或业务规则拒绝,例如自动派单授权无效。

返回字段同 400。

409与当前状态冲突,例如版本已变化(version_conflict)、同一幂等键用于不同请求(idempotency_conflict)、相同请求正在处理(command_in_progress)、摘要不一致、文件未通过扫描、草稿已过期或不可发布。details 里通常给出当前版本或期望摘要。

返回字段同 400。

422请求参数或请求体格式不对(FastAPI 默认格式)。
422 的返回字段
字段类型必填说明
detailarray<object>是—
detail[].typestring否—
detail[].locarray<string | integer>否—
detail[].msgstring否—
detail[].inputany否—
428缺少必须的幂等键(idempotency_key_required),或发布时没有回传完整的方案摘要(plan_digest_confirmation_required)。

返回字段同 400。

429当前密钥每分钟请求次数已达上限(120 次)。

返回字段同 400。

错误返回的格式和重试建议见 错误处理。

调用示例

curl -X POST 'https://www.zhugejunshi.com/api/member-api/v1/android-executor/proposals' \
  -H 'X-Zhuge-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "device_id": "dev_0123456789abcdef",
  "title": "示例采购任务",
  "action_type": "EXECUTE_PLAN",
  "target_app": "taobao",
  "workflow_type": "TAOBAO_PURCHASE",
  "steps": [
    {
      "id": "step-1",
      "type": "OPEN_APP"
    }
  ],
  "expires_in_minutes": 10
}'

GET读取任务检查点

/android-executor/tasks/{task_id}/checkpoints

需要密钥 · 需要权限 android-executor:read

返回指定安卓执行任务的检查点(需要人工接管或确认的节点)。只能读取当前会员自己的任务。需要 android-executor:read 权限。

请求参数

读取任务检查点的请求参数
参数位置类型必填说明
task_id路径string是

任务编号。

返回

200检查点列表。
200 的返回字段
字段类型必填说明
checkpointsarray<object>否—
checkpoints[].checkpoint_idstring否—
checkpoints[].task_idstring否—
checkpoints[].step_idstring否—
checkpoints[].attempt_nointeger否—
checkpoints[].checkpoint_typestring否—
checkpoints[].resume_modestring否

恢复方式:retry_current 或 advance_next,无法判断时为空字符串。

checkpoints[].statusstring否—
checkpoints[].resolution_reasonstring否—
checkpoints[].requested_atstring(date-time) | null否—
checkpoints[].resolved_atstring(date-time) | null否—
checkpoints[].created_atstring(date-time) | null否—
checkpoints[].updated_atstring(date-time) | null否—
返回示例
{
  "checkpoints": [
    {
      "checkpoint_id": "ckpt_0123456789abcdef",
      "task_id": "task_0123456789abcdef",
      "step_id": "step-1",
      "attempt_no": 1,
      "checkpoint_type": "human_takeover",
      "resume_mode": "advance_next",
      "status": "pending",
      "resolution_reason": "",
      "requested_at": "2026-11-07T08:00:00",
      "resolved_at": null,
      "created_at": "2026-11-07T08:00:00",
      "updated_at": "2026-11-07T08:00:00"
    }
  ]
}
401未提供有效的 API 密钥(invalid_api_key),或密钥上下文无效(invalid_api_context)。
401 的返回字段
字段类型必填说明
detailobject是—
detail.codestring是

错误代码,程序判断用。

detail.messagestring是

中文说明。

detail.detailsobject否

部分错误带的补充信息,例如版本冲突时的 current_version。

403密钥已撤销、过期或申请未获批准(api_key_inactive);申请主体不一致(api_actor_mismatch);会员、企业或成员关系已停用(api_actor_inactive);密钥没有该接口需要的权限(api_scope_denied);或业务规则拒绝,例如自动派单授权无效。

返回字段同 401。

404资源不存在或不属于当前密钥;路由不存在或请求方法不对时 code 为 member_api_route_not_found。

返回字段同 401。

409与当前状态冲突,例如版本已变化(version_conflict)、同一幂等键用于不同请求(idempotency_conflict)、相同请求正在处理(command_in_progress)、摘要不一致、文件未通过扫描、草稿已过期或不可发布。details 里通常给出当前版本或期望摘要。

返回字段同 401。

429当前密钥每分钟请求次数已达上限(120 次)。

返回字段同 401。

错误返回的格式和重试建议见 错误处理。

调用示例

curl -X GET 'https://www.zhugejunshi.com/api/member-api/v1/android-executor/tasks/{task_id}/checkpoints' \
  -H 'X-Zhuge-API-Key: YOUR_API_KEY'
在线调试

这里会用你填的密钥向正式接口发一次真实请求。密钥只留在本页内存里,不保存、不上传到别处,刷新页面后要重新填写。

POST急停安卓执行任务

/android-executor/tasks/{task_id}/stop

需要密钥 · 需要权限 android-executor:stop:write

停止当前会员自己的安卓执行草案或任务,没有请求体。只能停止,不能恢复或批准。需要 android-executor:stop:write 权限。

请求参数

急停安卓执行任务的请求参数
参数位置类型必填说明
task_id路径string是

任务编号。

返回

200停止后的任务。
200 的返回字段
字段类型必填说明
taskAndroidTask否

安卓执行任务。plan、policy、result、error 的内部结构较深,只写到对象这一层;敏感内容已脱敏。

task.task_idstring否—
task.device_idstring否—
task.titlestring否—
task.action_typestring否—
task.target_appstring否—
task.target_packagestring否—
task.workflow_typestring否—
task.planobject否

已脱敏的执行计划。

task.plan_digeststring否—
task.plan_summaryobject否—
task.policyobject否—
task.statusstring否

任务状态,例如 draft_proposal、stop_requested。

task.decisionstring否—
task.decision_reasonstring否—
task.resultobject否—
task.errorobject否—
task.proposal_sourcestring否

来源,经本接口创建的为 member_api。

task.requires_primary_activationboolean否

状态为 draft_proposal 时为 true,需主账号激活。

task.activated_atstring(date-time) | null否—
task.current_step_indexinteger否—
task.paused_atstring(date-time) | null否—
task.current_checkpointobject | null否

当前检查点,字段同检查点列表里的单项。

task.expires_atstring(date-time) | null否—
task.stop_requestedboolean否—
task.decision_atstring(date-time) | null否—
task.approved_atstring(date-time) | null否—
task.started_atstring(date-time) | null否—
task.completed_atstring(date-time) | null否—
task.created_atstring(date-time) | null否—
task.updated_atstring(date-time) | null否—
返回示例
{
  "task": {
    "task_id": "task_0123456789abcdef",
    "device_id": "dev_0123456789abcdef",
    "title": "示例采购任务",
    "action_type": "EXECUTE_PLAN",
    "target_app": "taobao",
    "target_package": "com.example.app",
    "workflow_type": "TAOBAO_PURCHASE",
    "plan": {
      "steps": []
    },
    "plan_digest": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "plan_summary": {},
    "policy": {},
    "status": "stop_requested",
    "decision": "pending",
    "decision_reason": "",
    "result": {},
    "error": {},
    "proposal_source": "member_api",
    "requires_primary_activation": false,
    "activated_at": null,
    "current_step_index": 0,
    "paused_at": null,
    "current_checkpoint": null,
    "expires_at": "2026-11-07T08:10:00",
    "stop_requested": true,
    "decision_at": null,
    "approved_at": null,
    "started_at": null,
    "completed_at": null,
    "created_at": "2026-11-07T08:00:00",
    "updated_at": "2026-11-07T08:00:00"
  }
}
401未提供有效的 API 密钥(invalid_api_key),或密钥上下文无效(invalid_api_context)。
401 的返回字段
字段类型必填说明
detailobject是—
detail.codestring是

错误代码,程序判断用。

detail.messagestring是

中文说明。

detail.detailsobject否

部分错误带的补充信息,例如版本冲突时的 current_version。

403密钥已撤销、过期或申请未获批准(api_key_inactive);申请主体不一致(api_actor_mismatch);会员、企业或成员关系已停用(api_actor_inactive);密钥没有该接口需要的权限(api_scope_denied);或业务规则拒绝,例如自动派单授权无效。

返回字段同 401。

404资源不存在或不属于当前密钥;路由不存在或请求方法不对时 code 为 member_api_route_not_found。

返回字段同 401。

409与当前状态冲突,例如版本已变化(version_conflict)、同一幂等键用于不同请求(idempotency_conflict)、相同请求正在处理(command_in_progress)、摘要不一致、文件未通过扫描、草稿已过期或不可发布。details 里通常给出当前版本或期望摘要。

返回字段同 401。

429当前密钥每分钟请求次数已达上限(120 次)。

返回字段同 401。

错误返回的格式和重试建议见 错误处理。

调用示例

curl -X POST 'https://www.zhugejunshi.com/api/member-api/v1/android-executor/tasks/{task_id}/stop' \
  -H 'X-Zhuge-API-Key: YOUR_API_KEY'

商品采购

浏览允许程序下单的商家商品,创建并查询商务订单。

GET浏览商家商品目录

/commerce/catalog

需要密钥 · 需要权限 commerce:catalog:read

返回已发布、在售、被选中并且所属店铺允许程序下单的商品和有效规格,按更新时间倒序。库存是扣除预留后的可售数量;不含淘宝商品号等内部编号。需要 commerce:catalog:read 权限。

请求参数

浏览商家商品目录的请求参数
参数位置类型必填说明
q查询string否

关键词,匹配标题、归一化品类和描述。

最长 300

family查询string否

按归一化品类精确筛选。

最长 160

limit查询integer否

每页条数,默认 40。

范围:1 到 100;默认:40

offset查询integer否

跳过的条数。

最小 0;默认:0

返回

200商品列表。
200 的返回字段
字段类型必填说明
itemsarray<CommerceProduct>否—
items[].idstring否

商品编号。

items[].titlestring否—
items[].descriptionstring否—
items[].categorystring否—
items[].familystring否

归一化品类,可用于目录筛选。

items[].pricenumber否—
items[].currencystring否—
items[].stockinteger否

可售数量(已扣除预留)。

items[].image_urlstring否—
items[].product_urlstring否—
items[].source_statusstring否—
items[].publication_statusstring否—
items[].is_selectedboolean否—
items[].capability_record_idinteger | null否—
items[].attributesobject否—
items[].skusarray<object>否—
items[].skus[].idstring否

规格编号。

items[].skus[].titlestring否—
items[].skus[].outer_idstring否—
items[].skus[].pricenumber否—
items[].skus[].currencystring否—
items[].skus[].stockinteger否

可售数量(已扣除预留)。

items[].skus[].specsobject否—
items[].skus[].statusstring否—
items[].synced_atstring(date-time) | null否—
items[].updated_atstring(date-time) | null否—
items[].storeobject否—
items[].store.idstring否

店铺编号。

items[].store.namestring否—
items[].store.platformstring否—
limitinteger否—
offsetinteger否—
返回示例
{
  "items": [
    {
      "id": "prod_0123456789ab",
      "title": "示例商品",
      "description": "示例商品说明。",
      "category": "示例品类",
      "family": "示例系列",
      "price": 99.5,
      "currency": "CNY",
      "stock": 120,
      "image_url": "https://example.com/product.jpg",
      "product_url": "",
      "source_status": "onsale",
      "publication_status": "published",
      "is_selected": true,
      "capability_record_id": null,
      "attributes": {},
      "skus": [
        {
          "id": "sku_0123456789ab",
          "title": "默认规格",
          "outer_id": "",
          "price": 99.5,
          "currency": "CNY",
          "stock": 120,
          "specs": {},
          "status": "active"
        }
      ],
      "synced_at": "2026-11-07T08:00:00",
      "updated_at": "2026-11-07T08:00:00",
      "store": {
        "id": "store_0123456789ab",
        "name": "示例店铺",
        "platform": "taobao"
      }
    }
  ],
  "limit": 40,
  "offset": 0
}
401未提供有效的 API 密钥(invalid_api_key),或密钥上下文无效(invalid_api_context)。
401 的返回字段
字段类型必填说明
detailobject是—
detail.codestring是

错误代码,程序判断用。

detail.messagestring是

中文说明。

detail.detailsobject否

部分错误带的补充信息,例如版本冲突时的 current_version。

403密钥已撤销、过期或申请未获批准(api_key_inactive);申请主体不一致(api_actor_mismatch);会员、企业或成员关系已停用(api_actor_inactive);密钥没有该接口需要的权限(api_scope_denied);或业务规则拒绝,例如自动派单授权无效。

返回字段同 401。

422请求参数或请求体格式不对(FastAPI 默认格式)。
422 的返回字段
字段类型必填说明
detailarray<object>是—
detail[].typestring否—
detail[].locarray<string | integer>否—
detail[].msgstring否—
detail[].inputany否—
429当前密钥每分钟请求次数已达上限(120 次)。

返回字段同 401。

错误返回的格式和重试建议见 错误处理。

调用示例

curl -X GET 'https://www.zhugejunshi.com/api/member-api/v1/commerce/catalog' \
  -H 'X-Zhuge-API-Key: YOUR_API_KEY'
在线调试

这里会用你填的密钥向正式接口发一次真实请求。密钥只留在本页内存里,不保存、不上传到别处,刷新页面后要重新填写。

GET读取商品详情

/commerce/catalog/{product_id}

需要密钥 · 需要权限 commerce:catalog:read

返回一个可程序下单的商品及其有效规格。商品已下架或不允许程序下单时返回 404。需要 commerce:catalog:read 权限。

请求参数

读取商品详情的请求参数
参数位置类型必填说明
product_id路径string是

商品编号(目录里的 id)。

返回

200商品详情,字段同目录里的单个商品。
200 的返回字段
字段类型必填说明
idstring否

商品编号。

titlestring否—
descriptionstring否—
categorystring否—
familystring否

归一化品类,可用于目录筛选。

pricenumber否—
currencystring否—
stockinteger否

可售数量(已扣除预留)。

image_urlstring否—
product_urlstring否—
source_statusstring否—
publication_statusstring否—
is_selectedboolean否—
capability_record_idinteger | null否—
attributesobject否—
skusarray<object>否—
skus[].idstring否

规格编号。

skus[].titlestring否—
skus[].outer_idstring否—
skus[].pricenumber否—
skus[].currencystring否—
skus[].stockinteger否

可售数量(已扣除预留)。

skus[].specsobject否—
skus[].statusstring否—
synced_atstring(date-time) | null否—
updated_atstring(date-time) | null否—
storeobject否—
store.idstring否

店铺编号。

store.namestring否—
store.platformstring否—
返回示例
{
  "id": "prod_0123456789ab",
  "title": "示例商品",
  "description": "示例商品说明。",
  "category": "示例品类",
  "family": "示例系列",
  "price": 99.5,
  "currency": "CNY",
  "stock": 120,
  "image_url": "https://example.com/product.jpg",
  "product_url": "",
  "source_status": "onsale",
  "publication_status": "published",
  "is_selected": true,
  "capability_record_id": null,
  "attributes": {},
  "skus": [
    {
      "id": "sku_0123456789ab",
      "title": "默认规格",
      "outer_id": "",
      "price": 99.5,
      "currency": "CNY",
      "stock": 120,
      "specs": {},
      "status": "active"
    }
  ],
  "synced_at": "2026-11-07T08:00:00",
  "updated_at": "2026-11-07T08:00:00",
  "store": {
    "id": "store_0123456789ab",
    "name": "示例店铺",
    "platform": "taobao"
  }
}
401未提供有效的 API 密钥(invalid_api_key),或密钥上下文无效(invalid_api_context)。
401 的返回字段
字段类型必填说明
detailobject是—
detail.codestring是

错误代码,程序判断用。

detail.messagestring是

中文说明。

detail.detailsobject否

部分错误带的补充信息,例如版本冲突时的 current_version。

403密钥已撤销、过期或申请未获批准(api_key_inactive);申请主体不一致(api_actor_mismatch);会员、企业或成员关系已停用(api_actor_inactive);密钥没有该接口需要的权限(api_scope_denied);或业务规则拒绝,例如自动派单授权无效。

返回字段同 401。

404资源不存在或不属于当前密钥;路由不存在或请求方法不对时 code 为 member_api_route_not_found。

返回字段同 401。

429当前密钥每分钟请求次数已达上限(120 次)。

返回字段同 401。

错误返回的格式和重试建议见 错误处理。

调用示例

curl -X GET 'https://www.zhugejunshi.com/api/member-api/v1/commerce/catalog/{product_id}' \
  -H 'X-Zhuge-API-Key: YOUR_API_KEY'
在线调试

这里会用你填的密钥向正式接口发一次真实请求。密钥只留在本页内存里,不保存、不上传到别处,刷新页面后要重新填写。

GET读取商务订单列表

/commerce/orders

需要密钥 · 需要权限 commerce:order:read

按更新时间倒序返回当前密钥所属会员自己创建的商务订单。列表里不含收货明细(只有脱敏的 shipping_mask)。需要 commerce:order:read 权限。

请求参数

读取商务订单列表的请求参数
参数位置类型必填说明
status查询string否

按订单状态筛选,不填返回全部。

最长 32

limit查询integer否

返回条数。

范围:1 到 100;默认:50

返回

200订单列表。
200 的返回字段
字段类型必填说明
itemsarray<CommerceOrder>否—
items[].order_nostring否—
items[].statusstring否

订单状态:awaiting_merchant、merchant_confirmed、awaiting_payment、paid、shipped、completed、rejected、canceled。

items[].status_labelstring否

状态的中文说明。

items[].payment_statusstring否—
items[].currencystring否—
items[].items_amountnumber否—
items[].shipping_amountnumber否—
items[].total_amountnumber否—
items[].buyer_notestring否—
items[].merchant_notestring否—
items[].shipping_maskstring否

脱敏后的收货信息。

items[].trackingobject否—
items[].tracking.companystring否—
items[].tracking.tracking_nostring否—
items[].sourcestring否

订单来源,经本接口创建的为 member_api。

items[].itemsarray<object>否—
items[].items[].product_idstring否—
items[].items[].sku_idstring否—
items[].items[].product_titlestring否—
items[].items[].sku_titlestring否—
items[].items[].outer_idstring否—
items[].items[].quantityinteger否—
items[].items[].unit_pricenumber否—
items[].items[].line_totalnumber否—
items[].merchant_confirmed_atstring(date-time) | null否—
items[].paid_atstring(date-time) | null否—
items[].shipped_atstring(date-time) | null否—
items[].completed_atstring(date-time) | null否—
items[].canceled_atstring(date-time) | null否—
items[].created_atstring(date-time) | null否—
items[].updated_atstring(date-time) | null否—
items[].shippingobject否

解密后的收货信息。只在创建订单和读取订单详情时返回,列表里没有。

返回示例
{
  "items": [
    {
      "order_no": "MO-20261107-0001",
      "status": "awaiting_merchant",
      "status_label": "等待商家确认",
      "payment_status": "unpaid",
      "currency": "CNY",
      "items_amount": 199,
      "shipping_amount": 0,
      "total_amount": 199,
      "buyer_note": "请尽快发货。",
      "merchant_note": "",
      "shipping_mask": "示*人 138****0000",
      "tracking": {
        "company": "",
        "tracking_no": ""
      },
      "source": "member_api",
      "items": [
        {
          "product_id": "prod_0123456789ab",
          "sku_id": "sku_0123456789ab",
          "product_title": "示例商品",
          "sku_title": "默认规格",
          "outer_id": "",
          "quantity": 2,
          "unit_price": 99.5,
          "line_total": 199
        }
      ],
      "merchant_confirmed_at": null,
      "paid_at": null,
      "shipped_at": null,
      "completed_at": null,
      "canceled_at": null,
      "created_at": "2026-11-07T08:00:00",
      "updated_at": "2026-11-07T08:00:00"
    }
  ]
}
401未提供有效的 API 密钥(invalid_api_key),或密钥上下文无效(invalid_api_context)。
401 的返回字段
字段类型必填说明
detailobject是—
detail.codestring是

错误代码,程序判断用。

detail.messagestring是

中文说明。

detail.detailsobject否

部分错误带的补充信息,例如版本冲突时的 current_version。

403密钥已撤销、过期或申请未获批准(api_key_inactive);申请主体不一致(api_actor_mismatch);会员、企业或成员关系已停用(api_actor_inactive);密钥没有该接口需要的权限(api_scope_denied);或业务规则拒绝,例如自动派单授权无效。

返回字段同 401。

422请求参数或请求体格式不对(FastAPI 默认格式)。
422 的返回字段
字段类型必填说明
detailarray<object>是—
detail[].typestring否—
detail[].locarray<string | integer>否—
detail[].msgstring否—
detail[].inputany否—
429当前密钥每分钟请求次数已达上限(120 次)。

返回字段同 401。

错误返回的格式和重试建议见 错误处理。

调用示例

curl -X GET 'https://www.zhugejunshi.com/api/member-api/v1/commerce/orders' \
  -H 'X-Zhuge-API-Key: YOUR_API_KEY'
在线调试

这里会用你填的密钥向正式接口发一次真实请求。密钥只留在本页内存里,不保存、不上传到别处,刷新页面后要重新填写。

POST创建商务订单

/commerce/orders

需要密钥 · 需要权限 commerce:order:write

创建待商家确认的商品订单并预留库存,不会自动付款。商品编号和规格编号来自商品目录。必须提供幂等键:放在 X-Idempotency-Key 请求头,或请求体的 idempotency_key(请求头优先),8 到 160 个字符;相同幂等键加不同内容返回 409。需要 commerce:order:write 权限,这是高风险权限,需要人工审核批准后才可使用。

请求参数

创建商务订单的请求参数
参数位置类型必填说明
X-Idempotency-Key请求头string否

幂等键,8 到 160 个字符。请求头和请求体的 idempotency_key 至少提供一个,两者都有时以请求头为准。

最长 160

请求内容 (application/json,必填)

创建商务订单的请求字段
字段类型必填说明
idempotency_keystring否

幂等键,也可以放在 X-Idempotency-Key 请求头里(请求头优先)。8 到 160 个字符。

最长 160

itemsarray<OrderItemInput>是

订购的商品,1 到 50 项。

1–50 项

items[].product_idstring是

商品编号,来自商品目录的 id。

长度 8–64

items[].sku_idstring否

规格编号,来自商品目录 skus[].id;商品只有默认规格时可以不填。

最长 64

items[].quantityinteger是

数量。

范围:1 到 1000000

shippingShippingInput是—
shipping.namestring是

收货人。

长度 1–120

shipping.phonestring是

联系电话。

长度 5–40

shipping.regionstring是

省市区。

长度 2–160

shipping.addressstring是

详细地址。

长度 3–500

buyer_notestring否

买家留言。

最长 2000

请求示例
{
  "items": [
    {
      "product_id": "prod_0123456789ab",
      "sku_id": "sku_0123456789ab",
      "quantity": 2
    }
  ],
  "shipping": {
    "name": "示例收货人",
    "phone": "13800000000",
    "region": "示例省 示例市",
    "address": "示例路 1 号"
  },
  "buyer_note": "请尽快发货。"
}

返回

200订单已创建(含重复提交时返回的原订单)。
200 的返回字段
字段类型必填说明
orderCommerceOrder否—
order.order_nostring否—
order.statusstring否

订单状态:awaiting_merchant、merchant_confirmed、awaiting_payment、paid、shipped、completed、rejected、canceled。

order.status_labelstring否

状态的中文说明。

order.payment_statusstring否—
order.currencystring否—
order.items_amountnumber否—
order.shipping_amountnumber否—
order.total_amountnumber否—
order.buyer_notestring否—
order.merchant_notestring否—
order.shipping_maskstring否

脱敏后的收货信息。

order.trackingobject否—
order.tracking.companystring否—
order.tracking.tracking_nostring否—
order.sourcestring否

订单来源,经本接口创建的为 member_api。

order.itemsarray<object>否—
order.items[].product_idstring否—
order.items[].sku_idstring否—
order.items[].product_titlestring否—
order.items[].sku_titlestring否—
order.items[].outer_idstring否—
order.items[].quantityinteger否—
order.items[].unit_pricenumber否—
order.items[].line_totalnumber否—
order.merchant_confirmed_atstring(date-time) | null否—
order.paid_atstring(date-time) | null否—
order.shipped_atstring(date-time) | null否—
order.completed_atstring(date-time) | null否—
order.canceled_atstring(date-time) | null否—
order.created_atstring(date-time) | null否—
order.updated_atstring(date-time) | null否—
order.shippingobject否

解密后的收货信息。只在创建订单和读取订单详情时返回,列表里没有。

idempotency_replayedboolean否

是否是重复提交返回的原订单。

返回示例
{
  "order": {
    "order_no": "MO-20261107-0001",
    "status": "awaiting_merchant",
    "status_label": "等待商家确认",
    "payment_status": "unpaid",
    "currency": "CNY",
    "items_amount": 199,
    "shipping_amount": 0,
    "total_amount": 199,
    "buyer_note": "请尽快发货。",
    "merchant_note": "",
    "shipping_mask": "示*人 138****0000",
    "tracking": {
      "company": "",
      "tracking_no": ""
    },
    "source": "member_api",
    "items": [
      {
        "product_id": "prod_0123456789ab",
        "sku_id": "sku_0123456789ab",
        "product_title": "示例商品",
        "sku_title": "默认规格",
        "outer_id": "",
        "quantity": 2,
        "unit_price": 99.5,
        "line_total": 199
      }
    ],
    "merchant_confirmed_at": null,
    "paid_at": null,
    "shipped_at": null,
    "completed_at": null,
    "canceled_at": null,
    "created_at": "2026-11-07T08:00:00",
    "updated_at": "2026-11-07T08:00:00",
    "shipping": {
      "name": "示例收货人",
      "phone": "13800000000",
      "region": "示例省 示例市",
      "address": "示例路 1 号"
    }
  },
  "idempotency_replayed": false
}
400请求内容不符合业务要求,例如幂等键格式不对、请求头与请求体幂等键不一致、订单标识不正确、方案缺少标题或类目、版本参数缺失。
400 的返回字段
字段类型必填说明
detailobject是—
detail.codestring是

错误代码,程序判断用。

detail.messagestring是

中文说明。

detail.detailsobject否

部分错误带的补充信息,例如版本冲突时的 current_version。

401未提供有效的 API 密钥(invalid_api_key),或密钥上下文无效(invalid_api_context)。

返回字段同 400。

403密钥已撤销、过期或申请未获批准(api_key_inactive);申请主体不一致(api_actor_mismatch);会员、企业或成员关系已停用(api_actor_inactive);密钥没有该接口需要的权限(api_scope_denied);或业务规则拒绝,例如自动派单授权无效。

返回字段同 400。

409与当前状态冲突,例如版本已变化(version_conflict)、同一幂等键用于不同请求(idempotency_conflict)、相同请求正在处理(command_in_progress)、摘要不一致、文件未通过扫描、草稿已过期或不可发布。details 里通常给出当前版本或期望摘要。

返回字段同 400。

422请求参数或请求体格式不对(FastAPI 默认格式)。
422 的返回字段
字段类型必填说明
detailarray<object>是—
detail[].typestring否—
detail[].locarray<string | integer>否—
detail[].msgstring否—
detail[].inputany否—
429当前密钥每分钟请求次数已达上限(120 次)。

返回字段同 400。

错误返回的格式和重试建议见 错误处理。

调用示例

curl -X POST 'https://www.zhugejunshi.com/api/member-api/v1/commerce/orders' \
  -H 'X-Zhuge-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "items": [
    {
      "product_id": "prod_0123456789ab",
      "sku_id": "sku_0123456789ab",
      "quantity": 2
    }
  ],
  "shipping": {
    "name": "示例收货人",
    "phone": "13800000000",
    "region": "示例省 示例市",
    "address": "示例路 1 号"
  },
  "buyer_note": "请尽快发货。"
}'

GET读取商务订单详情

/commerce/orders/{order_no}

需要密钥 · 需要权限 commerce:order:read

返回一张商务订单,包含解密后的收货信息 shipping。只能读取当前密钥所属会员自己创建的订单。需要 commerce:order:read 权限。

请求参数

读取商务订单详情的请求参数
参数位置类型必填说明
order_no路径string是

订单号。

返回

200订单详情。
200 的返回字段
字段类型必填说明
order_nostring否—
statusstring否

订单状态:awaiting_merchant、merchant_confirmed、awaiting_payment、paid、shipped、completed、rejected、canceled。

status_labelstring否

状态的中文说明。

payment_statusstring否—
currencystring否—
items_amountnumber否—
shipping_amountnumber否—
total_amountnumber否—
buyer_notestring否—
merchant_notestring否—
shipping_maskstring否

脱敏后的收货信息。

trackingobject否—
tracking.companystring否—
tracking.tracking_nostring否—
sourcestring否

订单来源,经本接口创建的为 member_api。

itemsarray<object>否—
items[].product_idstring否—
items[].sku_idstring否—
items[].product_titlestring否—
items[].sku_titlestring否—
items[].outer_idstring否—
items[].quantityinteger否—
items[].unit_pricenumber否—
items[].line_totalnumber否—
merchant_confirmed_atstring(date-time) | null否—
paid_atstring(date-time) | null否—
shipped_atstring(date-time) | null否—
completed_atstring(date-time) | null否—
canceled_atstring(date-time) | null否—
created_atstring(date-time) | null否—
updated_atstring(date-time) | null否—
shippingobject否

解密后的收货信息。只在创建订单和读取订单详情时返回,列表里没有。

返回示例
{
  "order_no": "MO-20261107-0001",
  "status": "awaiting_merchant",
  "status_label": "等待商家确认",
  "payment_status": "unpaid",
  "currency": "CNY",
  "items_amount": 199,
  "shipping_amount": 0,
  "total_amount": 199,
  "buyer_note": "请尽快发货。",
  "merchant_note": "",
  "shipping_mask": "示*人 138****0000",
  "tracking": {
    "company": "",
    "tracking_no": ""
  },
  "source": "member_api",
  "items": [
    {
      "product_id": "prod_0123456789ab",
      "sku_id": "sku_0123456789ab",
      "product_title": "示例商品",
      "sku_title": "默认规格",
      "outer_id": "",
      "quantity": 2,
      "unit_price": 99.5,
      "line_total": 199
    }
  ],
  "merchant_confirmed_at": null,
  "paid_at": null,
  "shipped_at": null,
  "completed_at": null,
  "canceled_at": null,
  "created_at": "2026-11-07T08:00:00",
  "updated_at": "2026-11-07T08:00:00",
  "shipping": {
    "name": "示例收货人",
    "phone": "13800000000",
    "region": "示例省 示例市",
    "address": "示例路 1 号"
  }
}
401未提供有效的 API 密钥(invalid_api_key),或密钥上下文无效(invalid_api_context)。
401 的返回字段
字段类型必填说明
detailobject是—
detail.codestring是

错误代码,程序判断用。

detail.messagestring是

中文说明。

detail.detailsobject否

部分错误带的补充信息,例如版本冲突时的 current_version。

403密钥已撤销、过期或申请未获批准(api_key_inactive);申请主体不一致(api_actor_mismatch);会员、企业或成员关系已停用(api_actor_inactive);密钥没有该接口需要的权限(api_scope_denied);或业务规则拒绝,例如自动派单授权无效。

返回字段同 401。

404资源不存在或不属于当前密钥;路由不存在或请求方法不对时 code 为 member_api_route_not_found。

返回字段同 401。

429当前密钥每分钟请求次数已达上限(120 次)。

返回字段同 401。

错误返回的格式和重试建议见 错误处理。

调用示例

curl -X GET 'https://www.zhugejunshi.com/api/member-api/v1/commerce/orders/{order_no}' \
  -H 'X-Zhuge-API-Key: YOUR_API_KEY'
在线调试

这里会用你填的密钥向正式接口发一次真实请求。密钥只留在本页内存里,不保存、不上传到别处,刷新页面后要重新填写。