表单&数据接口

开发准备

开发前,请仔细阅读 开发指南

注:以下所有接口路径中的app_identry_id分别表示应用ID和该应用内的表单ID,因此app_id+entry_id表示全局唯一的表单ID,前往会员中心的API文档进行查看。

应用举例

API & 订单管理

在简道云中建立了一个订单表单,用于统计订单信息。销售渠道一般分为线上商城销售和线下销售,线下销售通常需要销售手动在简道云中录入订单。但是线上渠道用户自主下单后会生成一个订单,此时这个订单可以通过新增单条数据API接口直接在简道云中生成一条订单记录,这样我们就不需要一个人专门把网上的订单一条条手动录入简道云。手动录入不仅工作量很大,而且容易出错。

API & 项目管理

当使用简道云做项目管理流程控制时,一般财务收款都是有单独的一套系统,此时可以通过修改单条数据API接口将财务软件中的收款信息推送到简道云来,从而修改对应的项目信息。

字段名

表单控件一旦添加,会以_widget_为前缀的固定控件ID来表示控件,无论修改控件的任何信息都不会变更控件ID。

每个控件都对应着一个字段。用户可以自己设置字段别名如果设置了别名,则在之后所有的API中,控件所对应的字段名都将以字段别名作为实际字段名;如果没有设置别名,则控件将采用控件ID作为实际字段名。

表单API

POST - /api/v1/app/{app_id}/entry/{entry_id}/widgets 表单字段查询接口

获取指定表单的控件/字段信息, 分割线控件关联查询控件以外。具体可以查阅文档最后的 控件与数据类型对照表

请求参数:

响应内容:

参数 含义
widgets 控件信息
widgets[].items 仅子表单控件有;数组里包含了每个子控件的信息
widgets[].label 控件标题
widgets[].name 字段名(设置了字段别名则采用别名,未设置则采用控件ID)
widgets[].type 控件类型;每种控件类型都有对应的数据类型

响应数据样例:

{
    "widgets": [
        {
            "name": "_widget_1529400746031",
            "label": "单行文本",
            "type": "text"
        },
        {
            "name": "_widget_1529400746045",
            "label": "多行文本",
            "type": "textarea"
        },
        {
            "name": "_widget_1529400746056",
            "label": "数字",
            "type": "number"
        },
        {
            "name": "_widget_1529400746068",
            "label": "日期",
            "type": "datetime"
        },
        {
            "name": "_widget_1529400746221",
            "label": "子表单",
            "type": "subform",
            "items": [
                {
            		"name": "_widget_1529400746259",
	            	"label": "手写签名",
	            	"type": "signature"
	             },{
            		"name": "_widget_1529400746077",
            		"label": "日期",
            		"type": "datetime"
        	    }
            ]
        }
    ]
}

数据API

POST - /api/v1/app/{app_id}/entry/{entry_id}/data 查询多条数据接口

该接口的返回数据,始终按照数据ID正序排列

请求参数:

参数 必需 类型 说明
data_id String 上一次查询数据结果的最后一条数据的ID,没有则留空
fields Array 需要查询的数据字段
filter JSON 数据筛选器
limit Number 查询的数据条数,1~100,默认100

请求示例:

POST /api/v1/app/59264073a2a60c0c08e20bfb/entry/59264073a2a60c0c08e20bfd/data
  
{
    "data_id": "59e9a2fe283ffa7c11b1ddbf",
    "limit": 100,
    "fields": ["_widget_1508400000001", "_widget_1508400000002", "_widget_1508400000003"],
    "filter": {
        "rel": "and", // 或者 "or"
        "cond": [
            {
                "field": "_widget_1508400000001",
                "type": "text",
                "method": "empty"
            },
            {
                "field": "_widget_1508400000002",
                "type": "number",
                "method": "not_empty"
            },
            {
                "field": "flowState",
                "type": "flowstate",
                "method": "eq",
                "value": [0]
            }
        ]
    }
}

响应参数:

参数 类型 说明
data Array 多条数据的集合

响应数据样例:

{
    "data": [
        {
            "_id": "59e9a2fe283ffa7c11b1ddbe", 
            "appId": "59264073a2a60c0c08e20bfb",
            "entryId": "59264073a2a60c0c08e20bfd",
            "creator": {
                "username": "luming",
                "name": "陆明"
            },
            "createTime": "2017-10-20T22:41:51.430Z",
            "updateTime": "2017-10-20T11:12:15.293Z",
            "_widget_1432728651402": "A班"    
        },
        {
            "_id": "59e9a2fe283ffa7c11b1ddbf",  
            "appId": "59264073a2a60c0c08e20bfb",
            "entryId": "59264073a2a60c0c08e20bfd",
            "creator": {
                "username": "jay",
                "name": "林杰"
            }
            "createTime": "2017-10-20T22:41:51.430Z",
            "updateTime": "2017-10-20T11:12:15.293Z",
            "_widget_1432728651402": "B班"  
        }
    ]
}

请注意: 查询到的数据内容中,除了控件字段以外,还有一些系统字段

如下表:

系统字段 字段名 数据类型 数据样例 备注
appId appId String “5b237267b22ab14884086c49” appId+entryId保证表单ID的唯一性
entryId entryId String “5b237267b22ab14884086cc9” appId+entryId保证表单ID的唯一性
数据ID _id String “5b237267b22ab14884086c50” 全局唯一
扩展字段 ext String “广州”
提交时间 String “2018-01-01T10:10:10.000Z”
提交人 JSON {“username”: “jane”, “name”: “小简”}
修改时间 String “2018-01-01T10:10:10.000Z”
修改人 JSON {“username”: “jane”, “name”: “小简”}
流程状态(仅流程表单) flowState 0 该字段仅流程表单支持。2表示流程手动结束;1表示流程已结束;0表示流程进行中

数据筛选器

查询多条数据接口同时也支持过滤。可通过filter参数进行数据过滤。

筛选参数结构如下:

参数 必需 类型 说明
rel String 筛选组合关系;“and”(满足所有过滤条件), “or”(满足任一过滤条件)
cond [JSON] 过滤条件列表

过滤条件参数如下:

参数 必需 类型 说明
field String 字段名
method String 过滤方法;“not_empty”(不为空),“empty”(为空),“eq”(等于),“in”(等于任意一个),“range”(在x与y之间,并且包含x和y本身),“nin”(不等于任意一个),“ne”(不等于), “like”(文本包含)
value Array 过滤值

目前支持如下字段:

字段类型 支持的过滤方式 说明
flowState eq,ne 流程状态,仅对流程表单有效
日期时间 eq,ne,range,empty,not_empty
数字 eq,ne,range,empty,not_empty
文本 eq,ne,in,nin,empty,not_empty
手机 like, verified, unverified, empty, not_empty verified表示填写了手机号且已验证的值;unverified表示填写了手机号但未验证值
其他表单字段(子表单字段除外) empty,not_empty

筛选示例:

{
    "filter": {
        "rel": "and", // 或者 "or"
        "cond": [
            // 过滤条件
            {
                "field": "flowState",
                "method": "eq",
                "value": [1]
            }, {
                "field": "_widget_1508400000001",
                "method": "empty"
            }, {
                "field": "_widget_1508400000002",
                "method": "in",
		  "value": ["apple", "pen"]
            }, {
               "field": "_widget_1508400000003",
               "method": "range",
		  "value": [null, 5] //小于等于5的数据
	     }, {
               "field": "_widget_1508400000007",
               "method": "in",
		  "value": "江苏" //包含[“江苏”]的数据
	     }
        ]
    }
}

POST - /api/v1/app/{app_id}/entry/{entry_id}/data_retrieve 查询单条数据接口

按照指定数据ID获取表单中的数据。

请求参数:

参数 必需 类型 说明
data_id String 数据ID

请求示例:

POST /api/v1/app/59264073a2a60c0c08e20bfb/entry/59264073a2a60c0c08e20bfd/data_retrieve
  
{
    "data_id": "59e9a2fe283ffa7c11b1ddbf"
}

响应参数:

参数 类型 说明
data JSON 单条数据

响应数据样例:

{
    "data": {
        "_id": "59e9a2fe283ffa7c11b1ddbf",  
        "appId": "59264073a2a60c0c08e20bfb",
        "entryId": "59264073a2a60c0c08e20bfd",
        "creator": {
            "username": "luming",
            "name": "陆明"
        },
        "updater": {
            "username": "jay",
            "name": "林杰"
        },
        "createTime": "2017-10-20T22:41:51.430Z",
        "updateTime": "2017-10-20T11:12:15.293Z",
        "_widget_1432728651402": "简道云",  // 单行文本
        "_widget_1432728651403": 100, // 数字
        "_widget_1432728651404": "简道云是一个强大易用的应用搭建工具,可以快速把你的想法变成应用", // 多行文本
        "_widget_1432728651405": "选项一", // 单选按钮组、下拉框
        "_widget_1432728651406": [ // 复选框组、下拉复选框
            "选项一、选项二、选项三"
        ],
        "_widget_1432728651413": { // 定位
            "province": "江苏省",
            "city": "无锡市",
            "district": "梁溪区",
            "detail": "清扬路138号茂业天地",
            "lnglatXY": [
                120.31237,
                31.49099
            ]
        },
        "_widget_1432728651415": [ // 成员多选
            {
    		  "username": "jane",
                "name": "小简"
            },
            {
                "username": "dao",
                "name": "小道"
            }
        ]
        "_widget_1432728651408": [ // 子表单
            {
                "_widget_1432728651402": "简道云", 
        	  "_widget_1432728651403": 100, 
            }, {
                "_widget_1432728651402": "云", 
        	  "_widget_1432728651403": 200, 
            }
        ]
    }
}

POST - /api/v2/app/{app_id}/entry/{entry_id}/data_create 新建单条数据接口

在指定表单中添加一条数据。

请注意: 使用API添加数据时,会触发的事件有新数据提交提醒、聚合表计算&校验、数据操作日志、数据量统计。也可以通过请求参数来控制是否发起流程。但是不会触发重复值校验、必填校验。

另外,系统字段以下所列举的控件 不支持添加和修改数据:

  • 分割线
  • 图片、附件、手写签名
  • 关联数据、关联查询
  • 流水号(提交后系统生成)

请求参数:

参数 必需 类型 说明 默认
data JSON 数据内容
is_start_workflow Bool 是否发起流程(仅流程表单有效) false
is_start_trigger Bool 是否触发智能助手 false

请求示例:

{
    "data": {
        "_widget_1432728651402": { // 单行文本
            "value": "简道云"
        },
        "_widget_1432728651403": { // 数字
            "value": 100
        },
        "_widget_1432728651404": { // 多行文本
            "value": "简道云是一个强大易用的应用搭建工具,\n可以快速把你的想法变成应用"
        },
        "_widget_1432728651405": { // 单选按钮组、下拉框
            "value": "选项一"
        },
	"_widget_1432728651499": { // 手机
            "value": {
			"phone": "13566666666"
		}
        },
        "_widget_1432728651406": { // 复选框组、下拉复选框
            "value": [
                "选项一、选项二、选项三"
            ]
        },
	 "_widget_1432728651599": { // 成员控件(成员编号)
            "value": "jian"
        },
        "_widget_1432728651599": { // 多部门控件(部门编号数组)
            "value": [12, 13, 14]
        },
        "_widget_1432728651407": { // 日期时间
            "value": "2018-01-01T10:10:10.000Z"
        },
        "_widget_1432728651412": {  // 地址
            "value": {
                "province": "江苏省",
                "city": "无锡市",
                "district": "梁溪区",
                "detail": "清扬路138号茂业天地"
            }
        },
        "_widget_1432728651413": { // 定位
            "value": {
                "province": "江苏省",
                "city": "无锡市",
                "district": "梁溪区",
                "detail": "清扬路138号茂业天地",
                "lnglatXY": [
                    120.31237,
                    31.49099
                ]
            }
        },
        "_widget_1528854613291": { // 子表单
            value: [
                { // 子表单子记录结构跟主表一直
                    "_widget_1528854614409": {
                        value: "子表单数据1"
                    },
                    "_widget_1528854615499": {
                        value: 1001
                    }
                },
                {
                    "_widget_1528854614410": {
                        value: "子表单数据2"
                    },
                    "_widget_1528854615419": {
                        value: 1002
                    }
                }
            ]
        }
    },
    "is_start_workflow": false,
    "is_start_trigger": false
}

响应参数:

参数 类型 说明
data JSON 返回提交后的完整数据,内容同查询单条数据接口

响应数据样例:

{
    "data": {}
}

POST - /api/v2/app/{app_id}/entry/{entry_id}/data_update 修改单条数据接口

按照指定数据ID修改表单中的数据。

请注意: 使用API修改数据时,会触发的事件有聚合表计算&校验、数据操作日志、数据量统计。不进行重复值校验、必填校验等。

请求参数:

参数 必需 类型 说明 默认
data_id String 数据ID
data JSON 数据内容,同新建单条数据接口
is_start_trigger Bool 是否触发智能助手 false

请求示例:

{
    "data_id": "59264073a2a60c0c08e20bfb",
    "data": {}
}

响应参数:

参数 类型 说明
data JSON 返回修改后的新数据,内容同查询单条数据接口

响应数据样例:

{
    "data": {}
}

POST - /api/v1/app/{app_id}/entry/{entry_id}/data_delete 删除单条数据接口

按照指定数据ID从表单中删除数据。

请求参数:

参数 必需 类型 说明 默认
data_id String 数据ID
is_start_trigger Bool 是否触发智能助手 false

响应数据样例:

{
    "status": "success"
}

控件与数据类型对照表


控件名称 控件类型 数据类型 数据样例 备注
单行文本 text String “张三”
多行文本 textarea String “我爱简道云”
流水号 sn String “00001”
数字 number Number 10
日期时间 datetime String “2018-01-01T10:10:10.000Z” UTC统一时间格式的字符串
单选按钮组 radiogroup String “一年级”
复选框组 checkboxgroup Array [“选项1”,“选项2”]
下拉框 combo String “女”
下拉复选框 combocheck Array [“选项1”,“选项2”]
地址 address JSON {“province”: “江苏省”,“city”: “无锡市”,“district”: “梁溪区”,“detail”: “清扬路138号茂业天地”}
定位 location JSON {“province”: “江苏省”,“city”: “无锡市”,“district”: “梁溪区”,“detail”: “清扬路138号茂业天地”,“lnglatXY”: [120.31237,31.49099]} lnglatXY表示[经度, 纬度]
图片 image Array [{“name”:“image1.png”,“size”:262144,“mime”:“image/png”,“url”:“url/cqbrmcwhxm”},{“name”:“image2.png”,“size”:262100,“mime”:“image/png”,“url”:“url/cqbrywmwh”}] 数据中包含的url为图片链接,7天内有效
附件 upload Array [{“name”:“产品说明文档.pdf”,“size”:524288,“mime”:“application/pdf”,“url”:“url/ojiwvfeyt”},[{“name”:“开发架构文档.pdf”,“size”:524288,“mime”:“application/pdf”,“url”:“url/mst”}] 数据中包含的url为附件链接,7天内有效
子表单 subform Array
关联数据 linkdata JSON {“id”:“5b237548b22ab14884086cc0”,“key”:“简道云”} id表示所关联数据的ID;key表示主键字段的值
手写签名 signature JSON {“name”:“signature_1238921857.png”,“size”:1024,“mime”:“image/png”,“url”:“url/ojiwsdf”} 数据中包含的url为手写签名的图片链接,7天内有效
成员单选 user JSON {“username”: “jane”, “name”: “小简”} 成员信息中username表示通讯录的成员编号(企业内唯一),如果是企业集成模式下同步的用户,相当于是钉钉或者企业微信的user_id;name表示用户昵称
成员多选 usergroup Array [{“username”: “jane” , “name”:“小简”},{“username”:“dao”, “name”:“小道”}]
部门单选 dept JSON {“dept_no”: 12, “name”: “经理部”} 部门信息中dept_no表示通讯录的部门编号(企业内唯一),如果是企业集成模式下同步的用户,相当于是钉钉或者企业微信的部门编号;name表示部门名称
部门多选 deptgroup Array [{“dept_no”:12, “name”:“经理部”},{“dept_no”:13, “name”:“市场部”}]
手机 phone JSON {“phone”: “13566666666”, verified: true} phone表示手机号,verified为布尔型,表示是否已验证。注:提交数据时verified不需要提交。

API操作关联关系

create update delete
数据工厂延时计算 触发 触发 触发
数据消息推送 触发 触发 不触发
触发聚合表 触发 触发 触发
数据操作日志 记录 记录 记录
webhook数据推送 不触发 不触发 不触发
智能助手 可触发 可触发 可触发
重复值校验 不校验 不校验 -
表单校验 不校验 不校验 -
必填校验 不校验 不校验 -
流程节点校验 不校验 不校验 -
触发流程 可触发 不触发 -
聚合表校验 校验 校验 -
字段联动、公式 不触发 不触发 -

代码示例

我们为开发者提供了一些不同语言版本的代码样例,仅供参考:


立刻开通API接口

API接口包含数据推送API、表单API和数据API,可以轻松对接简道云和外部的其他系统/产品,打通二者间的数据和业务。

目前仅提供给标准版及以上版本的用户,且需额外开通,如有功能使用需求可以通过下方的途径联系我们:

在线咨询:商务咨询

申请试用:接口试用

Peach是此帮助页面的作者。如果您对此页面的内容有任何意见,请在下方给她反馈。如需获取即时帮助,请联系技术支持。
本文是否对您有帮助?