* **权限类型**：read / manage / execute

## 开始调用
1. **创建应用**：在开放平台创建或选择应用。

2. **授权权限项**：按用途独立勾选需要的读取、管理或执行权限项。

3. **创建 API Key**：凭据只在创建成功时完整展示，请立即安全保存。

4. **构造请求**：按接口文档构造请求，并使用请求 ID 排查问题。

* **认证方式**：API Key、Scope 与组织边界。

* **通用约定**：Host、格式与请求追踪。

* **错误处理**：通用状态码与排查顺序。

## 认证方式
服务端应用使用开放平台创建的 API Key 调用接口。API Key 代表应用身份，服务端据此确定可信组织和应用已获授权的 Scope。

### 认证与请求头

所有接口适用公共认证与追踪请求头。Authorization 必填，X-Request-Id 可选；Idempotency-Key 仅在单接口参数表明确声明时适用，是否必填以该接口为准。

读取（read）、管理（manage）和执行（execute）权限互不隐含，必须按所调用接口分别授权。
<table> <thead> <tr> <td><p><b><b>名称</b></b></p></td> <td><p><b><b>位置</b></b></p></td> <td><p><b><b>类型</b></b></p></td> <td><p><b><b>必填</b></b></p></td> <td><p><b><b>说明</b></b></p></td> <td><p><b><b>示例</b></b></p></td> </tr> </thead> <tbody> <tr> <td><p><code>Authorization</code></p></td> <td><p>header</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>应用 API Key，使用 Bearer 方式传递。</p></td> <td><p><code>Bearer \&lt;API_KEY\&gt;</code></p></td> </tr> <tr> <td><p><code>X-Request-Id</code></p></td> <td><p>header</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>可选的调用追踪标识；未传入时由服务端生成。</p></td> <td><p><code>req-20260831-001</code></p></td> </tr> <tr> <td><p><code>Content-Type</code></p></td> <td><p>header</p></td> <td><p>string</p></td> <td><p>按单接口请求体</p></td> <td><p>按单接口声明设置媒体类型；JSON 使用 application/json，文件上传按该接口使用 multipart/form-data，勿将 JSON 头套用于上传。</p></td> <td><p><code>application/json</code></p></td> </tr> <tr> <td><p><code>Idempotency-Key</code></p></td> <td><p>header</p></td> <td><p>string</p></td> <td><p>按单接口文档</p></td> <td><p>仅用于单接口明确支持的幂等请求；是否必填、长度及字符限制以该接口为准，相同输入重试时复用原值。</p></td> <td><p><code>idem-20260831-001</code></p></td> </tr> </tbody> </table>

API Key 和其他密钥只能保存在服务端密钥系统中，不得写入浏览器代码、日志、文档或截图。

## 错误处理
先按 HTTP 状态和稳定业务错误码判断认证、授权、参数、资源或依赖服务问题。

### 错误码

业务服务错误响应使用 error、detail、code 和可选 details 字段。

请求追踪标识通过响应头 X-Request-Id 返回；经公共错误中间件处理且请求上下文中已有追踪标识时，错误正文还可能包含可选的 request_id（string）。

它不是成功响应的通用必填字段，也不能与审批等接口中同名的业务申请 ID 混淆。
<table> <thead> <tr> <td><p><b><b>HTTP</b></b></p></td> <td><p><b><b>错误类型</b></b></p></td> <td><p><b><b>错误码</b></b></p></td> <td><p><b><b>说明</b></b></p></td> <td><p><b><b>可重试</b></b></p></td> </tr> </thead> <tbody> <tr> <td><p>400</p></td> <td><p><code>BadRequest</code></p></td> <td><p><code>request_validation_failed</code></p></td> <td><p>Content-Type、JSON、revision 等请求格式无效。</p></td> <td><p>否</p></td> </tr> <tr> <td><p>401</p></td> <td><p><code>Unauthorized</code></p></td> <td><p><code>openapi_invalid_api_key</code></p></td> <td><p>API Key 缺失或无效。</p></td> <td><p>否</p></td> </tr> <tr> <td><p>403</p></td> <td><p><code>Forbidden</code></p></td> <td><p><code>openapi_scope_denied</code></p></td> <td><p>API Key 未获得当前接口要求的独立 Scope。</p></td> <td><p>否</p></td> </tr> <tr> <td><p>404</p></td> <td><p><code>NotFound</code></p></td> <td><p><code>authn_openapi_not_enabled</code></p></td> <td><p>OpenAPI 接口未启用或未在网关目录注册。</p></td> <td><p>否</p></td> </tr> <tr> <td><p>404</p></td> <td><p><code>NotFound</code></p></td> <td><p><code>department_not_found</code></p></td> <td><p>指定部门不存在；这是当前部门接口已实现的资源错误码示例。</p></td> <td><p>否</p></td> </tr> <tr> <td><p>422</p></td> <td><p><code>UnprocessableEntity</code></p></td> <td><p><code>request_validation_failed</code></p></td> <td><p>UUID、分页、字段或 Idempotency-Key 等语义校验失败。</p></td> <td><p>否</p></td> </tr> <tr> <td><p>503</p></td> <td><p><code>ServiceUnavailable</code></p></td> <td><p><code>iam_openapi_execution_unavailable</code></p></td> <td><p>IAM 内部执行链路或相关 OpenAPI 能力暂时不可用。</p></td> <td><p>是</p></td> </tr> </tbody> </table>

### 错误响应示例

```
HELPCODEESCAPE-json
{
  "error": "UnprocessableEntity",
  "detail": "Idempotency-Key is required.",
  "code": "request_validation_failed"
}
```

### 排查与重试顺序

先校验请求格式和 API Key，再核对接口 Scope，随后确认资源状态。

仅在 503 或明确可重试的网关错误下退避重试；仅对明确支持幂等重放的接口复用原 Idempotency-Key 和完全相同的请求内容；其他写操作应先查询实际结果，再按该接口说明决定是否重试。

使用响应头 X-Request-Id 关联日志和排查调用链。

## 字段表阅读约定
* 请求字段的"必填"表示调用方必须提交；响应字段的"必填"表示对应响应分支保证包含该键，不是需要填写的参数。

* 必填性与可空性分别判断：可省略不等于允许 `null`，允许 `null` 也不等于可以省略。以字段表的"必填"和"类型"为准。

* 嵌套字段要求仅在父对象存在且非 `null` 时适用；对象数组的字段要求逐个应用于非 `null` 元素，仅凭子字段必填不能推断数组非空；minItems 等数组数量约束仍独立适用。数组本身和数组元素是否允许 `null` 分别以其类型为准。

* 可选对象的出现条件、条件必填及特殊业务约束在对应接口字段说明中列明；同名字段在不同响应分支的含义以该分支为准。

`{key}`、`{locale}` 等路径表示动态字典键，`[]` 表示数组元素；具体允许的键和扩展属性以接口说明为准。 示例域名及 `<...>` 均为占位符，调用前替换为实际地址和业务值。版本号使用查询返回的当前值；配置发布前先读取现有配置，按接口的合并或替换语义保留不需修改的字段。示例不包含真实凭据。

## 公共错误响应
仅在状态表明确引用本结构时适用。特殊业务详情见对应接口；不得将冲突或同步恢复字段视为所有错误共有字段。request_id 是错误中间件可能附加的可选追踪字段，现有生成协议未声明，参见本页错误处理说明。

### 公共错误字段

<table> <thead> <tr> <td><p><b><b>名称</b></b></p></td> <td><p><b><b>类型</b></b></p></td> <td><p><b><b>必填</b></b></p></td> <td><p><b><b>说明</b></b></p></td> <td><p><b><b>示例</b></b></p></td> </tr> </thead> <tbody> <tr> <td><p><code>detail</code></p></td> <td><p><code>string</code></p></td> <td><p>是</p></td> <td><p>错误说明；客户端分支应使用 code。</p></td> <td><p><code>"Request rejected"</code></p></td> </tr> <tr> <td><p><code>error</code></p></td> <td><p><code>string</code></p></td> <td><p>是</p></td> <td><p>稳定的 HTTP 错误类型。</p></td> <td><p><code>"Conflict"</code></p></td> </tr> </tbody> </table>

### 通用错误

复用结构：见本文"公共错误字段"
<table> <thead> <tr> <td><p><b><b>名称</b></b></p></td> <td><p><b><b>类型</b></b></p></td> <td><p><b><b>必填</b></b></p></td> <td><p><b><b>说明</b></b></p></td> <td><p><b><b>示例</b></b></p></td> </tr> </thead> <tbody> <tr> <td><p><code>code</code></p></td> <td><p><code>string</code></p></td> <td><p>否</p></td> <td><p>稳定业务错误码；没有业务码时可省略。</p></td> <td><p><code>"request_rejected"</code></p></td> </tr> <tr> <td><p><code>details</code></p></td> <td><p><code>object</code></p></td> <td><p>否</p></td> <td><p>仅在该错误分支有结构化详情时出现。</p></td> <td><p><code>-</code></p></td> </tr> </tbody> </table>

#### details

<table> <thead> <tr> <td><p><b><b>字段</b></b></p></td> <td><p><b><b>类型</b></b></p></td> <td><p><b><b>必填</b></b></p></td> <td><p><b><b>说明</b></b></p></td> </tr> </thead> <tbody> <tr> <td><p><code>field</code></p></td> <td><p><code>string</code></p></td> <td><p>否</p></td> <td><p>相关的公开请求字段名。</p></td> </tr> <tr> <td><p><code>reason</code></p></td> <td><p><code>string</code></p></td> <td><p>否</p></td> <td><p>校验失败原因。</p></td> </tr> <tr> <td><p><code>suggestion</code></p></td> <td><p><code>string</code></p></td> <td><p>否</p></td> <td><p>建议修正值或处理方式。</p></td> </tr> </tbody> </table>

## 公共错误示例
以下仅示意公共必填字段；可选业务码、详情及追踪标识按实际错误场景返回。

```
HELPCODEESCAPE-json
{
  "error": "Bad Request",
  "detail": "Request validation failed"
}
```

## 用户写入的同步等待与重试
适用于创建、更新、删除用户、调整用户席位/状态及入组织/席位申请审批：本地业务提交后最多等待 10 秒，同步确认成功立即返回该接口的成功响应，不固定等待满 10 秒。

同步仍在处理时可能返回 HTTP 503 / `iam_openapi_execution_unavailable`，具体详情以接口的特殊响应结构为准。

`committed=true` 表示本地写入已执行，不表示同步完成；不要因此另起一笔写操作。先通过查询接口核对业务状态；声明了幂等键的操作应复用原键和原请求。

提交前校验失败仍按原错误处理；普通 503 不代表已经提交，也不代表已经回滚。