表格 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-12Jinshuju-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。
- 列出你能访问的表格,拿到
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 }
]
}- 读表格结构,拿到每个字段的
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 |
| 复选框 | BooleanField | true / false | true |
| 日期 | 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 修改请求 |
401 | Token 无效或已撤销 | 重新创建 Token |
402 | 套餐不包含 API 访问,或套餐已到期 | 升级或续费套餐 |
403 | 你在表格上的角色缺少对应权限、写了你不能填的字段、OAuth scope 不够、数据条数到了套餐上限,或表格、账号被冻结 | error_description 会说明缺的是哪项权限或哪个字段 |
404 | 表格或数据不存在,或不在你能访问的范围内;把表单 token 传给了 /tables 接口 | 核对 token 和序号,确认表格已共享给你 |
415 | 请求体不是 JSON | 加上 Content-Type: application/json |
429 | 超出本小时的调用次数 | 按 Retry-After 等待后重试 |