数据写入与网关
写入前通过查询确认目标、字段和权限；写入后按返回 ID 回查。产品 API 文档展示 V1 与 V2 两类格式，不能混用请求体。新的语义写入优先使用 V2，既有 V1 集成按兼容协议维护。
以下示例展示请求结构，使用前替换占位值并核对目标表单协议。
V1：按列与值提交
这些相对路径使用 POST、JSON，以及当前业务请求的 Bearer、租户、应用和签名。
| 页面入口 | 相对路径 | 数据结构 |
|---|---|---|
| 新建行记录 | /open-api/openapi/form/insert | columns.metadata 与一行 values |
| 批量新建行记录 | /open-api/openapi/form/insert | 同一端点，多行 values |
| 新增或修改行记录 | /open-api/openapi/form/upsert | columns；按实际唯一约束匹配 |
| 更新记录详情 | /open-api/openapi/form/update | columns 和定位目标的 conditions |
| 删除行记录 | /open-api/openapi/form/delete | table 与明确 conditions |
| 批量删除行记录 | /open-api/openapi/form/batchDelete | 目标记录条件，核对选择范围 |
新增一条或多条
{
"table": "YOUR_FORM_ID",
"columns": {
"metadata": ["YOUR_FORM_ID.YOUR_TEXT_COLUMN", "YOUR_FORM_ID.YOUR_NUMBER_COLUMN"],
"values": [["事项甲", 10], ["事项乙", 20]]
}
}
本例 values 中有两行，因此表示两条记录。只有一行时为单条新增。metadata 中字段的顺序与每行值的位置一一对应；字段标识按当前表单映射替换，不能使用中文标题。
更新与删除
更新仅提交需要变更的列，并使用明确 conditions 限定目标。删除同样要明确目标，执行前先用相同条件查询数量和 ID。
页面的部分删除示例将 compare=40 说明成等于，与当前比较协议不符，不能直接照搬。单记录标量 ID 的等值条件参见读取详情，多 ID 条件应按当前比较协议选择，不把多个 ID 塞进任意比较码。
没有可靠定位条件时先停止操作。upsert 的唯一匹配也必须来自真实表单约束，不能按任意中文名称自行推断去重。
V2：按语义字段提交
直接 V2 HTTP 写入使用以下签名接口：
| 操作 | 相对路径 | 必要内容 |
|---|---|---|
| 新增 | /open-api/openapi/form/v2/insert | app_id、table、data |
| 新增或修改 | /open-api/openapi/form/v2/upsert | app_id、table、data 与真实唯一字段 |
| 修改 | /open-api/openapi/form/v2/update | app_id、table、id、data |
| 删除 | /open-api/openapi/form/v2/delete | app_id、table，至少 id 或 ids |
修改示例：
{
"app_id": "YOUR_APPLICATION_ID",
"table": "YOUR_FORM_ID",
"id": "YOUR_RECORD_ID",
"data": {"YOUR_TEXT_FIELD": "新的事项说明"}
}
data 的键使用该接口支持的真实语义字段映射；选项使用 options[].field，开关使用 activeId/inactiveId，上传为文件数组。详见字段协议。V2 校验失败时定位错误，不自动改发 V1。
文档页的 Basic 网关
产品文档 V2版本 → 网关调用 还提供单独入口：POST /open-api/openapi/whitelist/gateway/invoke。仅在目标部署已启用并授权该调用方式时使用，不把它与直接 V2 签名入口混为一谈。
请求头为管理员交付的 Basic 认证信息、TENANT-ID、X-APPLICATION-ID 与 application/json。此入口的认证方式不同，不代表匿名可写；页面中的历史默认 Basic 值不作为正式凭据。
嵌套结构示例：
{
"username": "YOUR_AUTHORIZED_USERNAME",
"api": "/open-api/openapi/form/v2/insert",
"table": "YOUR_FORM_ID",
"data": {"YOUR_TEXT_FIELD": "事项甲"}
}
页面也支持扁平结构，将同一业务字段写成根级键 "data.YOUR_TEXT_FIELD"。选择一种格式后核对生成的请求体，不同时发送两种互相冲突的值。Basic 密码与 Access Secret 的用途不同，不能替换。
回查与重复提交
正常响应后检查业务成功状态、影响数量及返回记录 ID，再查询业务值。批量部分失败时分别记录成功与失败项，只处理失败范围。
超时或响应不可解析时，先按原业务键、ID 或幂等合同确认结果，不直接重复新增。删除后没有通用的自动恢复承诺。任何测试应使用授权的演示数据，并提前确定保留或清理方式。