表格 API

通过开放 API v1 读写「表格」数据:准备 Access Token、查到表格 token 和字段 api_code、查询数据、新增修改删除数据,以及错误码对照。

「表格」的数据可以通过开放 API v1 查询和修改,接口都在 /tables/{table_token} 下,用法和表单的数据接口一致。本文用几个请求带你从拿到 Token 走到读写第一条数据,接口的完整定义见开放中心文档。

调用「表格」API 前要准备什么

调用前需要一个 Access Token。API 向所有套餐开放,免费版也可以调用。

Token 有三种,按用途选:

Token能操作的表格适合
个人 Access Token你创建的、或别人共享给你的表格,权限跟你在表格上的角色一致个人脚本、单人集成
企业 Access Token(企业基础版及以上)账号下所有表格,不受协作角色限制公司内部系统对接
OAuth 2.0 Token授权用户能访问的表格,且只能调用授权范围(scope)内的接口给其他金数据用户用的第三方应用

个人 Access Token 在「个人中心」→「个人 API」创建,企业 Access Token 在「系统设置」→「企业 API」创建,创建步骤见金数据对外接口文档。OAuth 应用读表格数据需要 read_entries,写数据需要 write_entries,建表、改表结构需要 forms。

所有请求的地址都以 https://jinshuju.net/api/v1 开头,并且每个请求都要带上这些请求头:

Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
Accept: application/json
Jinshuju-Version: 2026-11-12

Jinshuju-Version 一定要带。

「表格」API 的调用额度

调用次数按账号每小时计算,账号下所有 Token 共用一份额度:

套餐API 调用额度
免费版100 次/小时
专业版1,000 次/小时
专业增强版1,000 次/小时
企业基础版20,000 次/小时
企业协作版30,000 次/小时
企业高级版50,000 次/小时

每个响应都带 X-RateLimit-Remaining 和 X-RateLimit-Reset,超出后返回 429,按 Retry-After 等待后重试。

怎么拿到表格的 token 和字段的 api_code

接口里用 token 指定表格,用字段的 api_code 指定列,两样都从接口里读。下面的示例把 Token 放在环境变量 $TOKEN 里,GET 请求省略了 Content-Type。

  1. 列出你能访问的表格,拿到 token:
curl https://jinshuju.net/api/v1/tables \
  -H "Authorization: Bearer $TOKEN" \
  -H "Jinshuju-Version: 2026-11-12"
{
  "total": 1,
  "count": 1,
  "next": null,
  "data": [
    { "name": "客户台账", "token": "AbCd1234", "kind": "table", "entries_count": 128 }
  ]
}
  1. 读表格结构,拿到每个字段的 api_code:
curl https://jinshuju.net/api/v1/tables/AbCd1234 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Jinshuju-Version: 2026-11-12"
{
  "name": "客户台账",
  "token": "AbCd1234",
  "kind": "table",
  "fields": [
    { "api_code": "field_1", "type": "TextArea", "label": "客户名称" },
    { "api_code": "field_2", "type": "RadioButton", "label": "跟进状态" },
    { "api_code": "field_3", "type": "NumberField", "label": "合同金额" }
  ],
  "views": [
    { "token": "Vw5678", "name": "我负责的客户" }
  ]
}

两个响应都省略了部分键。fields 按表格里的列顺序排列,单项选择、多项选择字段还会带 choices;views 是你能看到的视图,按视图查数据时用它的 token。

如果把表单的 token 传给 /tables/... 接口,会返回 404 Table not found。

怎么查询「表格」数据

列表接口支持筛选、排序、关键词搜索和只返回部分字段。下面的请求查「跟进状态是跟进中、合同金额不低于 10,000」的客户,按金额从高到低排:

curl -G https://jinshuju.net/api/v1/tables/AbCd1234/entries \
  -H "Authorization: Bearer $TOKEN" \
  -H "Jinshuju-Version: 2026-11-12" \
  --data-urlencode 'filters=[{"field":"field_2","operator":"eq","value":"跟进中"},{"field":"field_3","operator":"gte","value":10000}]' \
  --data-urlencode 'sort=[{"api_code":"field_3","order":"desc"}]' \
  --data-urlencode 'fields=field_1,field_3' \
  --data-urlencode 'limit=100'
{
  "total": 23,
  "count": 23,
  "next": null,
  "data": [
    { "serial_number": 12, "field_1": "星河科技", "field_3": 58000 }
  ]
}

几个容易踩的点:

  • filters 和 sort 传的是 JSON 字符串:先把数组 JSON.stringify,再作为一个参数值传,不要直接传数组。
  • 多个条件默认是「且」。要表达「或」,给条件加 group_index 分组:同一组内是「且」,组与组之间是「或」。
  • 常用的 operator:eq、ne、any_in、none_in、gt / gte / lt / lte、between、like、null / not_null、within_last。每种字段只支持其中一部分,传了不支持的会返回 400 并列出可用的。GET /tables/{token}/condition_triggerable_fields 会列出哪些字段能用来筛选。
  • 单项选择、多项选择字段的筛选值可以写选项文字,也可以写选项的 api_code。
  • 翻页:每页默认 50 条,limit 最大 1,000。把上一页返回的 next 原样传回,其余参数不变,直到 next 为 null;也可以用 page 直接跳页。
  • 其他参数:keyword 在所有可搜索的字段里模糊搜索;include_labels=true 会把每个值变成 {"label": 字段名, "value": 值},不用再对照表结构。

除了列表,还有这些查询方式:

要做什么接口
按序号读一条数据GET /tables/{token}/entries/{serial_number}
读某个视图里的数据GET /tables/{token}/views/{view_token}/entries
统计条数GET /tables/{token}/entries/count
分组聚合(求和、平均等)GET /tables/{token}/entries/aggregate
数据概览GET /tables/{token}/entries/summary

统计类接口接受和列表一样的 filters,也都有按视图查的版本(路径里加 /views/{view_token})。

怎么新增、修改和删除数据

写入时请求体是一个对象:键是字段的 api_code,值按字段类型写(见各类型字段的写入格式)。不认识的键会被忽略,一个有效键都没有时返回 400。

新增一条:

curl https://jinshuju.net/api/v1/tables/AbCd1234/entries \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Jinshuju-Version: 2026-11-12" \
  -H "Content-Type: application/json" \
  -d '{"field_1": "星河科技", "field_2": "跟进中", "field_3": 58000}'

成功返回 201,entry 是写入后的数据,serial_number 是这条数据的序号,后面修改和删除都用它:

{
  "form": "AbCd1234",
  "form_name": "客户台账",
  "entry": { "serial_number": 129, "field_1": "星河科技", "field_3": 58000 }
}

响应省略了部分键,其中 url 可以在金数据里直接打开这条数据。

修改一条:

curl https://jinshuju.net/api/v1/tables/AbCd1234/entries/129 \
  -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Jinshuju-Version: 2026-11-12" \
  -H "Content-Type: application/json" \
  -d '{"field_2": "已签约"}'
  • PATCH 只改请求里出现的字段,其余字段保持不变。调用方发不了 PATCH 时,可以改用 POST 请求同一地址,效果相同。
  • PUT 是整条替换:请求里没有的可写字段会被清空。不确定时用 PATCH。
  • 收集附件字段是整体替换的:要保留已有文件,把读到的文件地址和新文件一起传。

删除一条:

curl https://jinshuju.net/api/v1/tables/AbCd1234/entries/129 \
  -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Jinshuju-Version: 2026-11-12"

成功返回被删除数据的序号 {"serial_number": 129}。

各类型字段的写入格式

写入时值按字段类型写,接口里用 type 标识字段类型:

字段类型接口中的 type写法示例
文本TextArea字符串"星河科技"
手机MobileField字符串"13888888888"
邮箱EmailField字符串"hi@example.com"
网址LinkField字符串"https://example.com"
单项选择RadioButton选项文字或选项的 api_code"跟进中"
多项选择CheckBox数组,每项同上["汽车", "金融"]
数字NumberField数字或数字字符串58000
复选框BooleanFieldtrue / falsetrue
日期DateTimeField日期或日期时间,按北京时间解析"2026-11-18 14:30:00"
收集附件AttachmentField数组,每项是已有文件的下载地址,或 base64 对象(单个文件不超过 5MB)[{"base64": "...", "file_name": "合同.pdf", "content_type": "application/pdf"}]
计算字段FormulaField自动计算,不能写,传了会被忽略—
流水号SequenceField按编号规则自动生成—

写入时会校验字段的设置。校验失败返回 400,error_description 是一个 JSON 字符串,形如 {"field_3": ["错误说明"]},按字段给出原因。

字段类型本身的说明见表格的字段与格式。

常见错误码与处理

出错时响应体是 {"error_description": "..."},用 HTTP 状态码判断错误类型。请求格式不对的 400 还会带 errors 数组,逐条指出是哪个参数、哪个位置出了问题。

状态码常见原因怎么处理
400参数不对,或写入的值没通过字段的校验按 error_description 和 errors 修改请求
401Token 无效或已撤销重新创建 Token
402套餐不包含 API 访问,或套餐已到期升级或续费套餐
403你在表格上的角色缺少对应权限、写了你不能填的字段、OAuth scope 不够、数据条数到了套餐上限,或表格、账号被冻结error_description 会说明缺的是哪项权限或哪个字段
404表格或数据不存在,或不在你能访问的范围内;把表单 token 传给了 /tables 接口核对 token 和序号,确认表格已共享给你
415请求体不是 JSON加上 Content-Type: application/json
429超出本小时的调用次数按 Retry-After 等待后重试

本页内容