跳到主要内容

v1 API 更新表单视图

API 使用者，可以通过本接口，更新指定表单下的视图配置

功能免费版专业版/专业增强版企业基础版企业协作版企业高级版
更新表单视图✔️✔️✔️

认证方式​

V1 Basic 认证方式

headers 设置​

需要在请求中设置如下 headers

  • Content-Type: application/json
  • Accept: application/json
  • Authorization: 放入上一步骤生成的 CODE

接口说明​

  • API 使用者可以更新自己创建或有管理权限的共享表单下的视图。
  • VIEW_TOKEN 可以从获取表单视图列表接口取得。
  • 只会更新请求中传入的字段；未传入的字段保持原值。
  • 更新自定义视图、或修改系统预设视图的类型，需要账户套餐支持自定义视图能力。
  • 系统预设视图的 view_type 不允许修改，但可以更新名称等其他配置。
  • filter 传空数组会清空筛选条件；不传 filter 则保持原筛选条件。

接口描述​

Request​

PATCH https://jinshuju.net/api/v1/forms/FORM_TOKEN/views/VIEW_TOKEN

{
    "name": "重点客户",
    "prefer_columns": ["serial_number", "field_1", "field_2"],
    "sort": [
        { "api_code": "serial_number", "order": "desc" }
    ],
    "filter": [
        { "field": "field_2", "operator": "not_null" }
    ]
}
参数名称是否必须类型说明
FORM_TOKEN是String表单 Token（URL 路径参数）
VIEW_TOKEN是String视图 Token（URL 路径参数）
name否String视图名称，最长 120 个字符
view_type否String视图类型：grid / kanban / stats。系统预设视图不允许修改该字段
prefer_columns否Array(String)视图展示的字段 api_code 列表
kanban_group_by_api_code否String看板视图分组字段的 api_code。字段必须支持看板分组
kanban_card_title_api_code否String看板卡片标题字段的 api_code
sort否Array排序规则数组。传空数组会清空排序规则
sort[].api_code是String排序字段的 api_code，可包含系统字段如 serial_number
sort[].order是String排序方向：asc / desc
filter否Array视图筛选条件数组。传空数组会清空筛选条件
filter[].field是String筛选字段的 api_code
filter[].operator是String筛选操作符
filter[].value否取决于 operator筛选值；null / not_null 不需要传

filter 字段过滤​

filter 的格式同创建表单视图。每个元素是 {field, operator, value} 三元组，多个条件之间是 AND 关系。

filter 必须传数组；不要传 { "scope_conditions": [] } 这类内部存储结构。

Response​

更新成功时返回更新后的视图结构。

{
    "token": "vD3e4F",
    "name": "重点客户",
    "view_type": "grid",
    "position": 1,
    "predefined": false,
    "prefer_columns": ["serial_number", "field_1", "field_2"],
    "sort": [
        { "api_code": "serial_number", "order": "desc" }
    ],
    "filter": [
        { "field": "field_2", "operator": "not_null" }
    ],
    "created_at": "2026-05-26T03:00:00.000Z",
    "updated_at": "2026-05-26T03:10:00.000Z"
}

状态码​

状态码说明
200更新成功
401未认证
402当前套餐不支持 V1 API，或当前账户不支持自定义视图
404表单或视图不存在，或无权访问
422参数校验失败、筛选条件不合法、系统预设视图类型不允许修改

示例代码​

HTTP​

PATCH https://jinshuju.net/api/v1/forms/$FORM_TOKEN/views/$VIEW_TOKEN

Content-Type: application/json
Accept: application/json
Authorization: Basic BASE_64_ENCODED_CREDENTIALS

{
  "name": "重点客户",
  "filter": [{ "field": "field_2", "operator": "not_null" }]
}

Python​

import requests

api_key = 'YOUR_API_KEY'
api_secret = 'YOUR_API_SECRET'
form_token = 'YOUR_FORM_TOKEN'
view_token = 'YOUR_VIEW_TOKEN'

payload = {
    "name": "重点客户",
    "filter": [{"field": "field_2", "operator": "not_null"}]
}

response = requests.patch(
    f'https://jinshuju.net/api/v1/forms/{form_token}/views/{view_token}',
    auth=(api_key, api_secret),
    json=payload
)

print(response.text)