Skip to main content

处理席位申请接口

通过或拒绝一条席位申请，并可记录审批意见。当前实现只接受 approve 和 reject，要求应用的人员范围为全部用户；响应返回处理后的申请状态。

  • Scope：admin.v1.user-approvals.execute
  • 权限项：用户与席位审批执行（user-approvals）
  • 权限类型：执行
  • 接口：POST/api/openapi/v1/seat-requests/{requestId}/decision
IAM 在受理新的授席操作前校验权威容量。无剩余席位时返回 HTTP 409 和 directory_user_seat_capacity_exceeded，不登记新的授席任务，审批申请保持待处理。 若预检后容量被其他操作耗尽，中心的明确容量拒绝同样返回该错误并停止席位目标自动重试， 不会把 IAM 实际席位标记为已授权。已提交的审批事实不回滚，应先查询申请和用户席位状态。 释放或增加席位后重新提交授席操作；有幂等键的已完成操作使用新键，已批准的申请通过用户授席接口处理。 网络超时等未知结果仍沿用 HTTP 503 和 iam_openapi_execution_unavailable，已保存的任务继续核验恢复； 组织余量为零时仍检查该用户在中心是否已经拥有席位，避免误判已成功但响应丢失的授予。 重复提交未确认的同一目标不会重置已有重试进度。只有中心确认授予成功后，IAM 才更新实际席位。

认证与请求头

使用应用 API Key 调用。当前接口只校验上方独立 Scope；读取、管理与执行权限互不隐含。
名称位置类型必填说明示例
Authorizationheaderstring是应用 API Key，使用 Bearer 方式传递。Bearer qwk_***
X-Request-Idheaderstring否可选的调用追踪标识；未传入时由服务端生成。req-20260831-001

请求参数

名称位置类型必填说明示例
requestIdpathstring · uuid必填申请 ID"<uuid>"
Idempotency-Keyheaderstring必填幂等键，用于避免重复提交"<string>"
decisionbodystring必填审批操作"approve"
review_reasonbodystring否审批意见"<string>"

请求示例

curl --request POST \
  --url 'https://example.invalid/api/openapi/v1/seat-requests/<requestId>/decision' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Idempotency-Key: <UNIQUE_REQUEST_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
  "decision": "approve",
  "review_reason": "<string>"
}'

响应

200 OK

名称类型必填说明示例
request_idstring是申请 ID"<string>"
statusstring是状态"<string>"
{
  "request_id": "<string>",
  "status": "<string>"
}

default Flat business error

名称类型必填说明示例
codestring否Stable business error code"<string>"
detailstring是Human-readable error description"<string>"
detailsOpenapiErrorDetails否错误详情-
errorstring是Stable HTTP error type"<string>"

details 字段

以下必填性针对对象存在时的子字段；父对象可否省略或为 null，以上层字段表为准。
字段类型必填说明
committedboolean否本地写入是否已提交；不表示下游同步成功
fieldstring否校验失败的请求字段
reasonstring否校验失败的原因代码
recoveryobject否同步恢复状态与重试信息
resultsarray<object> ｜ null否各用户的处理结果
suggestionstring否建议使用的规范化值

details.recovery 字段

以下必填性针对对象存在时的子字段；父对象可否省略或为 null，以上层字段表为准。
字段类型必填说明
automatic_retryboolean是是否自动重试
next_retry_atstring · date-time否下次重试时间
requires_actionboolean是是否需要人工处理
statestring是同步恢复状态；可选值：succeeded, processing, retrying, action_required, unconfirmed

details.results[] 字段

以下必填性针对对象存在时的子字段；父对象可否省略或为 null，以上层字段表为准。
字段类型必填说明
codestring否Stable business error code
recoveryobject是同步恢复状态与重试信息
user_idstring是用户 ID

details.results[].recovery 字段

以下必填性针对对象存在时的子字段；父对象可否省略或为 null，以上层字段表为准。
字段类型必填说明
automatic_retryboolean是是否自动重试
next_retry_atstring · date-time否下次重试时间
requires_actionboolean是是否需要人工处理
statestring是同步恢复状态；可选值：succeeded, processing, retrying, action_required, unconfirmed
{
  "code": "<string>",
  "detail": "<string>",
  "details": {
    "field": "<string>",
    "reason": "<string>",
    "suggestion": "<string>"
  },
  "error": "<string>"
}

提交与同步结果

本地业务提交后最多等待 10 秒，同步确认成功立即返回本接口原成功响应，不固定等待满 10 秒。 同步仍在处理时保留 HTTP 503 / iam_openapi_execution_unavailable，增加已提交状态和恢复结果。 committed=true 表示本地写入已执行，不表示同步已完成；不要据此重新创建一笔写操作。 已有幂等键的操作应复用原键及原请求；先通过现有查询接口核对业务状态。 提交前校验失败仍返回原错误；确定业务拒绝保留相应状态和错误码，已提交的拒绝结果同样携带提交信息。 传输中断且没有收到提交证据时，不能推断已回滚。 错误示例（已提交、同步处理中）： 
{
  "error": "ServiceUnavailable",
  "code": "iam_openapi_execution_unavailable",
  "detail": "The operation was saved; review synchronization results before submitting another write.",
  "details": {
    "committed": true,
    "results": [{
      "user_id": "46ba2b7d-0a1d-50c4-a309-e1be8fb310f3",
      "recovery": { "state": "processing", "automatic_retry": false, "requires_action": false }
    }]
  }
}
recovery.state 为 succeeded、processing、retrying、action_required 或 unconfirmed。 automatic_retry 与 requires_action 描述实际恢复安排；next_retry_at 仅在已安排自动重试时提供。 results[].code 可选，用于解释需处理原因；结果待确认不等于操作未执行。