API 概述与快速开始
OpenAPI 用于把 Duogex 的应用、工作表与外部系统连接起来。先取得目标应用的授权信息，再读取字段和少量记录，最后按业务需要写入。
本组教程整理自产品中的 API 文档 使用说明，适用于 Duogex v0.9。接口方法与参数可以公开阅读；实际访问仍由目标组织授权。示例使用占位值，没有公开任何组织的账号、密钥、记录或分享令牌。
1. 打开目标工作表的 API 文档
由有权人员打开目标工作表的 API 文档，确认 当前表单。页面左侧提供概述、生成签名、获取 token、应用信息、表单信息、字段对照表，以及 V1、V2 和匿名调用入口。
切换表单会刷新文档上下文。发送请求前重新检查应用 ID、表单 ID 和 完整请求 URL，不要沿用上一张表的字段或授权信息。
2. 选择调用方式
| 方式 | 身份与格式 | 使用场景 |
|---|---|---|
| 直接 HTTP OpenAPI | 用户 Bearer、业务签名、租户与应用上下文 | 外部服务按公开协议读取或维护记录 |
| 文档页的 V2 网关调用 | 部署允许的 Basic 网关配置、username、api、table、data | 已启用该入口的集成；与直接 V2 接口分开核对 |
| 匿名分享 | share token，按需填写访问密码 | 仅访问该分享允许的资源 |
| 受管 MCP | 客户端工具及绑定身份 | AI 调用工具，由运行时承载认证与上下文 |
本组示例主要介绍 HTTP。MCP 的 name/arguments 是工具调用封装，不能直接当作 HTTP 请求体发送。
3. 准备调用资料
向目标组织取得：对外 API 基础地址、数字租户 ID、应用 ID、表单 ID、授权用户、Access ID、Access Secret，以及该部署要求的认证客户端配置。
基础地址可能已包含 /api 等反向代理前缀，本文路径均相对该基础地址。使用页面显示的完整 URL 核对，不能把浏览器的 #/… 路由当作 API，也不要重复拼接前缀。
4. 完成第一次读取
- 按生成签名计算签名，再获取 Token。
- 读取应用信息、表单信息及字段对照表，确认表标识和字段。
- 发送V1 分页查询，先取 10 条以内记录。
- 检查 HTTP 状态和业务响应，再按 ID 查询一条详情。
- 确认读取正确后，才接入新增与更新。
页面中的“成功响应示例”用于说明协议结构，实际结果以目标环境的响应为准。
怎样判断成功
普通业务接口常见响应形态：
{
"code": 0,
"msg": "success",
"data": {},
"ok": true
}
Token 响应则读取 access_token、token_type、expires_in，不要套用同一种 data 结构。写入后还要查询目标记录，核对实际业务值。
| 问题 | 先检查 |
|---|---|
| Failed to fetch | API 地址、网络、浏览器 CORS；不能仅凭此提示确定是跨域 |
| 租户格式错误 | TENANT-ID 是否为数字 ID，不能传租户 CODE 或公司名称 |
| 请求已过期 | 毫秒时间戳与服务器时钟；当前页面说明的校验窗口为 5 分钟 |
| 签名失败 | Access Secret、签名参数与实际发送值是否一致 |
| Token 失效 | 按实际 expires_in 管理有效期，重新授权后核对主体 |
| 查询为空 | 条件、页码、字段映射及记录权限 |
| 写入超时 | 先查询原结果，避免重复新增或整批重放 |
接口文档的公开阅读权限不会增加实际业务权限。使用匿名入口时，继续阅读匿名分享调用。
按菜单查找接口
| 分组 | 阅读入口 |
|---|---|
| 公共接入 | 公共约定、生成签名、获取 Token、应用信息、应用表单信息、字段对照表 |
| V1版本 | 分页、列表、详情、新建、批量新建、新增或修改、更新、删除、批量删除 |
| V2版本 | Basic 网关、直接新增、新增或修改、更新、删除 |
| 匿名调用 | 公开信息、分页、列表、详情、WRITE 追加提交 |
| 使用参考 | 查询条件与排序、写入协议选择、分享边界 |
具体接口页分别列出方法、路径、认证、参数、请求示例、返回说明及排错要点。V1 和 V2 版本号用于区分接口协议；匿名调用是另一种访问授权方式，不是 V1 / V2 的免鉴权入口。