易企办开发者 / REST API

REST API 请求示例

使用易企办中国版 API 查询用户和业务记录，写入列表，并配置工作流任务事件回调。

读取列表信息

curl --fail-with-body "https://api.yeeoffice.cn/v1/lists/APP_ID/LIST_ID" \
  -H "apiKey: ${YEEOFFICE_API_KEY}" \
  -H "Accept: application/json"

分页查询用户

SearchKey 可按需填写。以下请求从第一页读取最多 20 个匹配用户。

curl --fail-with-body -X POST "https://api.yeeoffice.cn/v1/users/search" \
  -H "apiKey: ${YEEOFFICE_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{
  "PageIndex": 1,
  "PageSize": 20,
  "SearchKey": "示例用户"
}'

查询符合条件的记录

替换应用和列表标识，并确认示例字段存在且支持当前筛选与排序条件。

curl --fail-with-body -X POST "https://api.yeeoffice.cn/v1/lists/APP_ID/LIST_ID/items/query" \
  -H "apiKey: ${YEEOFFICE_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{
  "Fields": [
    "Title",
    "Created"
  ],
  "Filters": [
    {
      "Field": "Title",
      "Type": 8,
      "Value": "采购"
    }
  ],
  "Sorts": [
    {
      "Field": "Created",
      "Desc": true
    }
  ],
  "PageIndex": 1,
  "PageSize": 20
}'

新增列表记录

Data 里的键是目标列表的字段名，值按接口规范传为字符串。以下 Text1 代表测试列表中的业务说明字段。

curl --fail-with-body -X POST "https://api.yeeoffice.cn/v1/lists/APP_ID/LIST_ID/items" \
  -H "apiKey: ${YEEOFFICE_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{
  "Data": {
    "Title": "示例采购申请",
    "Text1": "办公设备"
  }
}'

更新指定字段

PATCH 只更新请求中提供的字段。用从目标记录读到的版本号替换示例中的 RowVersion。版本不一致时，重新读取记录并核对改动。规范中省略版本号或传入 0 会强制更新。

curl --fail-with-body -X PATCH "https://api.yeeoffice.cn/v1/lists/APP_ID/LIST_ID/items/ITEM_ID" \
  -H "apiKey: ${YEEOFFICE_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{
  "RowVersion": 7,
  "Data": {
    "Title": "已复核的采购申请"
  }
}'

按记录版本扣减单件商品库存

先读取当前库存和 RowVersion，确认库存足够，再把同一版本随 PATCH 发送。若另一个请求先更新了记录，旧版本的写入会被拒绝。测试时先确认列表能够返回这两个字段，并使用目标列表的字段名。

此示例处理同一商品记录的并发扣减。多商品、付款及会员余额涉及多条记录，需要另外验收部分写入、订单去重和失败恢复。遇到超时或结果不明确时，先核对库存和订单，再决定是否重试。

// 在服务端运行。Decimal1 是零售门店示例中的库存字段。
export async function deductStock({ appId, listId, itemId, quantity, apiKey }) {
  if (![appId, listId, itemId].every(id => typeof id === "string" && /^[0-9]+$/.test(id))) {
    throw new Error("请传入字符串形式的应用、列表和记录 ID");
  }
  if (!Number.isSafeInteger(quantity) || quantity < 1 || typeof apiKey !== "string" || !apiKey) {
    throw new Error("请提供正整数数量和服务端密钥");
  }
  const url = "https://api.yeeoffice.cn/v1/lists/" + appId + "/" + listId + "/items/" + itemId;
  const headers = { apiKey, "Content-Type": "application/json" };
  const snapshot = await fetch(url + "?fields=Decimal1,RowVersion", {
    headers, redirect: "error", cache: "no-store",
  });
  const current = await snapshot.json();
  if (!snapshot.ok || current.Status !== 0) throw new Error("读取库存失败");

  const stock = Number(current.Data?.Decimal1 ?? NaN);
  const version = Number(current.Data?.RowVersion ?? 0);
  if (!/^[0-9]+(?:\.0+)?$/.test(String(current.Data?.Decimal1 ?? "")) ||
      !Number.isSafeInteger(stock) || !Number.isInteger(version) ||
      version < 1 || version > 2147483647) {
    throw new Error("库存或记录版本无效，未提交扣减");
  }
  if (stock < quantity) throw new Error("库存不足，未提交扣减");

  const remaining = stock - quantity;
  const response = await fetch(url, {
    method: "PATCH", headers, redirect: "error",
    body: JSON.stringify({ RowVersion: version, Data: { Decimal1: String(remaining) } }),
  });
  const update = await response.json();
  if (!response.ok || update.Status !== 0 || update.Data !== itemId) {
    throw new Error("扣减结果未确认，请重新读取库存并核对订单");
  }
  return remaining;
}

订阅工作流任务事件

Resource 使用 workflow/tasks。示例的 Type 为 3，由创建（1）和更新（2）组合。将 callbackUrl 换成你自己的 HTTPS 回调地址。

curl --fail-with-body -X POST "https://api.yeeoffice.cn/v1/hooks" \
  -H "apiKey: ${YEEOFFICE_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{
  "Resource": "workflow/tasks",
  "Channel": "purchase-task-sync",
  "Type": 3,
  "Settings": {
    "callbackUrl": "https://example.com/webhooks/yeeoffice"
  }
}'

读取回调中的事件信息

回调使用 POST，事件渠道与类型放在 Channel 和 Type 请求头，事件主体为 JSON。接收服务还需核验来源、验证任务字段并处理重复事件，再交给下游系统。

export async function readTaskEvent(request: Request, expectedChannel: string) {
  const channel = request.headers.get("Channel");
  const type = request.headers.get("Type");
  if (request.method !== "POST" || channel !== expectedChannel ||
      (type !== "1" && type !== "2" && type !== "4")) {
    throw new Error("回调方法、渠道或事件类型不匹配");
  }
  const event: unknown = await request.json();
  if (!event || typeof event !== "object" || Array.isArray(event)) {
    throw new Error("任务事件需要 JSON 对象");
  }
  return { channel, type: Number(type), event };
}

从读取走向业务操作

新建或更新记录时先确认目标列表的必填字段和字段类型。
发起工作流前确认表单、发起身份和变量。用测试申请验证审批人及流转。
处理 Webhook 时校验回调类型与载荷，并设计重试、去重和失败追踪。
调用智能体前确认输入、权限及需要人工审核的动作范围。

接口定义以易企办中国版公开 OpenAPI v1 为准。

查看完整规范查看官方接口文档