表单&数据API

开发准备

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

注:以下所有接口路径中的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": {       
                "_id": "59e9a2fe283ffa7c11b1ddc2", 
                "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": {     
                "_id": "59e9a2fe283ffa7c11b1ddc2", 
                "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 {"_id": “5af263d45e67aaf5b09033c7”, “username”: “jane”, “name”: “小简”}
修改时间 String “2018-01-01T10:10:10.000Z”
修改人 JSON {"_id": “5af263d45e67aaf5b09033c7”, “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 流程状态,仅对流程表单有效
日期时间 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": "like",
		  "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": {     
            "_id": "59e9a2fe283ffa7c11b1ddc2", 
            "username": "luming",
            "name": "陆明"
        },
        "updater": {      
            "_id": "59e9a2fe283ffa7c11b1ddc3",
            "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": [ // 成员多选
            {
                "_id": "5af263d45e67aaf5b09033c7",
    		  "username": "jane",
                "name": "小简"
            },
            {
                "_id": "5af263d45e67aaf5b09033c8",
                "username": "dao",
                "name": "小道"
            }
        ]
        "_widget_1432728651408": [ // 子表单
            {
                "_widget_1432728651402": "简道云", 
        	  "_widget_1432728651403": 100, 
            }, {
                "_widget_1432728651402": "云", 
        	  "_widget_1432728651403": 200, 
            }
        ]
    }
}

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

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

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

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

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

请求参数:

参数 必需 类型 说明
data JSON 数据内容
is_start_workflow Bool 是否发起流程(仅流程表单有效)

请求示例:

{
    "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": { // 成员控件(成员id)
            "value": "583bb59759f10c3209a2754b"
        },
        "_widget_1432728651599": { // 多部门控件(部门id数组)
            "value": ["583bb59759f10c3209a2754c", "583bb59759f10c3209a2754a"]
        },
        "_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
}

响应参数:

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

响应数据样例:

{
    "data": {}
}

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

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

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

请求参数:

参数 必需 类型 说明
data_id String 数据ID
data JSON 数据内容,同新建单条数据接口

请求示例:

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

响应参数:

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

响应数据样例:

{
    "data": {}
}

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

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

请求参数:

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

响应数据样例:

{
    "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 {"_id": “5af263d45e67aaf5b09033c7”,“username”: “jane”, “name”: “小简”} 成员信息中_id表示简道云中的用户id;username表示简道云中的用户名,如果是企业集成模式下同步的用户,使用{corp_id}-{钉钉或者企业微信的user_id}的格式来组成用户名;name表示用户昵称
成员多选 usergroup Array [{"_id":“5af263d45e67aaf5b09033c7”,“username”: “jane” , “name”:“小简”},{"_id":“5af263d45e67aaf5b09033c9”,“username”:“dao”, “name”:“小道”}]
部门单选 dept JSON {"_id": “5af263d45e67aaf5b09033c7”,“name”: “经理部”}
部门多选 deptgroup Array [{"_id":“5af263d45e67aaf5b09033c7”,“name”:“经理部”},{"_id":“5af263d45e67aaf5b09033c9”,“name”:“市场部”}]
手机 phone JSON {“phone”: “13566666666”, verified: true} phone表示手机号,verified为布尔型,表示是否已验证。注:提交数据时verified不需要提交。

API操作关联关系

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

代码示例

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


立刻开通API接口

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

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

在线咨询:商务咨询

申请试用:接口试用

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