跳到主要内容

v1 API 创建表单视图

API 使用者，可以通过本接口，在指定表单下创建自定义视图

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

认证方式​

V1 Basic 认证方式

headers 设置​

需要在请求中设置如下 headers

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

接口说明​

  • API 使用者可以在自己创建或有管理权限的共享表单下创建视图。
  • 创建自定义视图需要账户套餐支持自定义视图能力。
  • 单个表单下最多支持 100 个视图。
  • view_type 默认为 grid。
  • prefer_columns 为空时，服务端会根据表单默认展示字段生成视图展示列。
  • filter 使用数组形式传入；传空数组表示没有筛选条件。

接口描述​

Request​

POST https://jinshuju.net/api/v1/forms/FORM_TOKEN/views

{
    "name": "待跟进客户",
    "view_type": "kanban",
    "prefer_columns": ["serial_number", "field_1", "field_2", "field_3"],
    "kanban_group_by_api_code": "field_3",
    "kanban_card_title_api_code": "field_1",
    "sort": [
        { "api_code": "serial_number", "order": "desc" }
    ],
    "filter": [
        { "field": "field_3", "operator": "eq", "value": "待跟进" }
    ]
}
参数名称是否必须类型说明
FORM_TOKEN是String表单 Token（URL 路径参数）
name是String视图名称，最长 120 个字符
view_type否String视图类型：grid / kanban / stats。默认 grid
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 关系。

元素类型说明
fieldString字段的 api_code（如 field_3），或系统字段名 created_at
operatorString操作符，见下方表格
value取决于 operator比较值；null / not_null 不需要传

支持的 operator：

类别operatorvalue 形式示例
等值eq / ne标量{"field":"field_1","operator":"eq","value":"张三"}
比较gt / gte / lt / lte标量{"field":"field_3","operator":"gte","value":6}
区间between / not_between2 元素数组 [min, max]（闭区间）{"field":"field_3","operator":"between","value":[80,100]}
集合any_in / none_in数组{"field":"field_2","operator":"any_in","value":["北京","上海"]}
文本like / not_like子串{"field":"field_2","operator":"like","value":"张"}
是否为空null / not_null省略{"field":"field_4","operator":"not_null"}

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

Response​

创建成功时返回新创建的视图结构。

{
    "token": "vD3e4F",
    "name": "待跟进客户",
    "view_type": "kanban",
    "position": 1,
    "predefined": false,
    "prefer_columns": ["serial_number", "field_1", "field_2", "field_3"],
    "sort": [
        { "api_code": "serial_number", "order": "desc" }
    ],
    "filter": [
        { "field": "field_3", "operator": "eq", "value": "待跟进" }
    ],
    "created_at": "2026-05-26T03:00:00.000Z",
    "updated_at": "2026-05-26T03:00:00.000Z"
}

状态码​

状态码说明
201创建成功
401未认证
402当前套餐不支持 V1 API，或当前账户不支持自定义视图
404表单不存在或无权访问
422参数校验失败、视图数量达到上限、筛选条件不合法

示例代码​

HTTP​

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

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

{
  "name": "待跟进客户",
  "view_type": "kanban",
  "filter": [{ "field": "field_3", "operator": "eq", "value": "待跟进" }]
}

Python​

import requests

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

payload = {
    "name": "待跟进客户",
    "view_type": "kanban",
    "filter": [{"field": "field_3", "operator": "eq", "value": "待跟进"}]
}

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

print(response.text)