Teams OpenAPI：接入点、命名、时间、分页、错误与认证约定。
本节为所有 Teams OpenAPI 的通用约定。各接口的特殊规则以对应章节为准。
服务接入点
生产环境 Base URL：
完整请求地址示例：
https://api.qoder.com.cn/v1/organizations/{organization_id}/members
企业专属版（Enterprise VPC）用户请使用专属实例的 Base URL：https://{实例标识}-api.vpc.qoder.com.cn
{实例标识} 为企业专属实例的唯一标识。例如实例标识为 acme 时，Base URL 为 https://acme-api.vpc.qoder.com.cn。 字段命名
JSON 请求与响应字段统一使用 lowerCamelCase（小驼峰），例如：organizationId、repositoryUrl、createdAt、maxResults、nextToken。
时间格式
时间戳采用 ISO 8601（RFC 3339），例如：
部分接口同时支持 Unix 毫秒时间戳，以该接口参数说明为准。
分页（游标）
列表类接口通常使用游标分页，通过查询参数控制。
请求查询参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|
maxResults | integer | 否 | 20 | 每页最大条数，上限 100 |
nextToken | string | 否 | — | 上一页响应中的下一页游标；首屏不传 |
nextToken 进行游标分页，接口另有说明时除外。
响应字段
| 字段 | 类型 | 说明 |
|---|
maxResults | integer | 本页请求的每页条数 |
nextToken | string | 下一页游标；省略或为空表示无更多数据 |
列表响应不保证返回总条数（totalCount）；需翻页直至游标为空。
错误响应
错误时 HTTP 状态码为非 2xx，响应体为 JSON，不包含名为 status 的顶层字段。结构如下：
{
"requestId": "req_abc123",
"code": "NotFound",
"message": "resource not found",
"details": ["the requested resource does not exist"]
}
错误体字段
| 字段 | 类型 | 必填 | 说明 |
|---|
requestId | string | 是 | 请求追踪 ID，排错时请提供给支持方 |
code | string | 是 | 稳定错误码，供程序分支处理 |
message | string | 是 | 人类可读说明 |
details | array | 否 | 附加信息；无内容时可省略 |
常见 HTTP 与 code 对照
| HTTP 状态码 | code（示例） | 说明 |
|---|
| 400 | BadRequest | 参数不合法 |
| 401 | Unauthorized | 未携带或 API Key 无效 |
| 403 | Forbidden | 无权访问该组织或资源 |
| 404 | NotFound | 资源不存在 |
| 409 | AlreadyExists | 资源冲突 |
| 500 | InternalError | 服务端错误 |
部分错误经网关或服务层转换后，HTTP 状态码与 code 的组合以实际响应为准；请勿仅依赖状态码做唯一判断。
Authorization: Bearer <api_key>
api_key 替换为控制台创建的密钥。勿将真实 Key 写入客户端可公开反编译的包或公共仓库。如何创建密钥，参见获取 API Key。
组织级基础路径
多数接口在以下路径下扩展：
/v1/organizations/{organization_id}
organization_id 为路径参数，表示目标组织。具体子路径参见成员、用量和 AI 代码指标相关文档。 
