新增或修改记录

V2 语义写入协议；这是直接签名接口，与 Basic 网关的入口及认证不同。

项目	内容
方法	POST
路径	/open-api/openapi/form/v2/upsert
认证	用户 Bearer + 当前请求签名 + 租户与应用上下文
请求格式	application/json

调用准备

按公共请求约定替换地址和占位值，按生成签名计算本次请求的签名。以下 JSON 保存为 UTF-8 的 request.json；签名必须使用同一份实际参数。示例为命令行 cURL；Windows PowerShell 可使用 curl.exe 并将多行命令合为一行。

请求参数

参数	类型 / 必填	说明
app_id	字符串 / 是	目标应用 ID；与 Header 中的应用一致。
table	字符串 / 是	目标表单 ID；与当前应用归属一致。
data	对象或对象数组 / 是	带实际唯一字段的行数据；匹配后更新，否则新增。

请求示例

request.json

{
  "app_id": "YOUR_APPLICATION_ID",
  "table": "YOUR_FORM_ID",
  "data": {
    "YOUR_UNIQUE_INPUT_FIELD": "EXTERNAL-001",
    "YOUR_TEXT_FIELD": "事项甲"
  }
}

curl --request POST "https://admin.duoge.work/api/open-api/openapi/form/v2/upsert" \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "TENANT-ID: YOUR_NUMERIC_TENANT_ID" \
  --header "X-APPLICATION-ID: YOUR_APPLICATION_ID" \
  --header "app_id: YOUR_APPLICATION_ID" \
  --header "timestamp: CURRENT_MILLISECONDS" \
  --header "signature: SIGNATURE_FOR_THIS_REQUEST" \
  --header "Content-Type: application/json" \
  --data-binary "@request.json"

返回说明

返回业务包装；成功的 data 为写入结果，通常包含影响数量 number、结果数据集 dataSet 等。数据集内容随操作和部署变化，不承诺固定的 ids、updatedIds 或 deletedIds 字段。先检查业务状态与影响数量，再按实际 ID 或唯一业务键查询核对。删除后的 dataSet 可能为空，不能据此单独判断失败。

使用说明与排错

YOUR_UNIQUE_INPUT_FIELD 必须替换为当前表单实际声明 unique=true 的 input 字段；示例名称不会创建唯一约束。没有可用唯一字段，或本行没有提供唯一值时，当前实现会走新增，不能依赖 upsert 名称防重。存在多个唯一字段时需核对实际匹配记录，不作复合键承诺。批量按行处理，中途失败前面的行可能已成功；先核查再补失败项。