表单基础 API

API 是表单大师对外提供的编程接口，允许其他应用开发者调用指定帐号内的表单相关资源。例如，在表单新提交的数据时推送到自己的平台，或在自己的平台查询表单提交的数据和评论等。

API 访问约定

• 所有的数据格式为 JSON
• 所有的数据传输编码为UTF-8
• 目前，API 访问的地址前缀均为 http://api.jsform.com/api/v1/
• 除了数据推送 API 外，所有的 API 都需要HTTP Basic验证。使用方法可参见：http://www.cnblogs.com/QLeelulu/archive/2009/11/22/1607898.html

获取HTTP Basic验证参数 (API Key/Secret)

在开始使用之前，您需要在表单大师账户内获取API Key 和 Secret，只有通过这两个参数才能获取API的访问权限。

您每次进行API调用时，都需要构造HTTP Basic验证的请求头。API Key 对应于 Basic验证的用户名， API Secret 对应于 Basic 验证的密码。例如，使用curl来获得某个表单的数据：

curl -u 51470abd078d49c496fda859:vWXVAWXeEQKfLlerFDMD3rsekBQzU5tz \
     --header "Content-Type:application/json" \
     -d "{\"form_id\":\"552b4ffe0cf2ba60b5b6825b\",\"fields\":[\"field1\",\"field5\",\"field6\",\"id\"],\"order_by\":{\"field1\":1}}" \
     --url http://api.jsform.com/api/v1/entry/query 
Copy to clipboardErrorCopied

查询类 API

所有查询类 API 均有请求频率限制，短时间内大量请求会返回频率过高错误。

表单 API

1.获取表单信息

描述
根据表单id获取表单信息（表单名称、表单描述等）

访问地址
http://api.jsform.com/api/v1/form/{formId}

访问方式
GET

参数

返回值

返回示例

{
    "status":"success",
    "form":{
        "id":"55b639212e8f3685227bf154",
        "form_desc":"表单描述", 
        "update_time":1438453044305, 
        "form_name":"表单名称", 
        "create_by":"apidemo@jsform.com", 
        "group_id":"55bc8d0c2e8f4d363ba991c9",
        "group_name":"分组名称",
        "create_time":1438005537663,
        "update_by":"apidemo@jsform.com"
    }
}
Copy to clipboardErrorCopied

表单列表字段说明

curl示例

curl -u 51470abd078d49c496fda859:vWXVAWXeEQKfLlerFDMD3rsekBQzU5tz \
     --header "Content-Type:application/json" \
     --url http://api.jsform.com/api/v1/form/55b639212e8f3685227bf154
Copy to clipboardErrorCopied

2.获取表单列表

描述
获取某分组下的所有表单。

访问地址
http://api.jsform.com/api/v1/formlist/{groupId}

访问方式
GET

参数

返回值

返回示例

{
    "status":"success",
    "rows":[
        {
            "id":"55b639212e8f3685227bf154",
            "form_desc":"表单描述", 
            "update_time":1438453044305, 
            "form_name":"表单名称", 
            "create_by":"apidemo@jsform.com", 
            "group_id":"55bc8d0c2e8f4d363ba991c9",
            "group_name":"分组1", 
            "create_time":1438005537663,
            "update_by":"apidemo@jsform.com"
        }
    ]
}
Copy to clipboardErrorCopied

表单列表字段说明

curl示例

curl -u 51470abd078d49c496fda859:vWXVAWXeEQKfLlerFDMD3rsekBQzU5tz \
     --header "Content-Type:application/json" \
     --url http://api.jsform.com/api/v1/formlist/55b639212e8f3685227bf154
Copy to clipboardErrorCopied

3.获取表单字段对照表

描述
获取某个表单的字段名称与数据表中的字段对应关系。

访问地址
http://api.jsform.com/api/v1/fields/{formId}

访问方式
GET

参数 无

返回值

返回示例

{
    "status":"success",
    "fields":{
        "field1":{
            "data_type":"String",
            "label":"单行文本"
        },
        "field2":{
            "data_type":"Number",
            "label":"数字"
        }
    }
}
Copy to clipboardErrorCopied

表单列表字段说明
见每个表单的API字段说明

curl示例

curl -u 51470abd078d49c496fda859:eWfALrToAuQvo47zDYFfaRxTVaeNsEIL \
     --header "Content-Type:application/json" \
     --url http://api.jsform.com/api/v1/fields/558e7b63926e2436667227fb
Copy to clipboardErrorCopied

4.获取表单分组

描述
获取表单分组信息。

访问地址
http://api.jsform.com/api/v1/form/grouplist

访问方式
GET

参数 无

返回值

返回示例

{
    "status":"success",
    "groups":[
        {
            "id":"55ae4e9d2e8f1176ff21453f",
            "name":"分组1"
        },
        {
            "id":"55ae4ea62e8f1176ff214540",
            "name":"分组2"
        }
    ]
}
Copy to clipboardErrorCopied

curl示例

curl -u 51470abd078d49c496fda859:eWfALrToAuQvo47zDYFfaRxTVaeNsEIL \
     --header "Content-Type:application/json" \
     --url http://api.jsform.com/api/v1/form/grouplist
Copy to clipboardErrorCopied

报表API

1.根据报表分组获取报表列表

描述
获取某账户下的所有报表。

访问地址
http://api.jsform.com/api/v1/reportlist/{groupId}

访问方式
GET

参数

返回值

返回示例

{
    "status":"success",
    "rows":[
        {
            "id":"54af9a2e0cf2e0a29dcd82d7",
            "update_time":1436102269097, 
            "create_by":"apidemo@jsform.com", 
            "group_name":"分组1", 
            "report_name":"1",
            "group_id":"55ae4ea62e8f1176ff214540",
            "create_time":1420794414952, 
            "form_id":"545b974a0cf2ba5432bebe75", 
            "report_desc":"报表描述1",
            "update_by":"apidemo@jsform.com"
        },
        {
            "id":"54af9a2e0cf2e0a29dcd82d7",
            "update_time":1436102269097, 
            "create_by":"apidemo@jsform.com",             
            "group_name":"分组1", 
            "report_name":"报表名称2",
            "group_id":"55ae4ea62e8f1176ff214540",
            "create_time":1420794414952, 
            "form_id":"545b974a0cf2ba5432bebe75", 
            "report_desc":"报表描述2",
            "update_by":"apidemo@jsform.com"
        }
    ]
}
Copy to clipboardErrorCopied

报表列表字段说明

curl示例

curl -u 51470abd078d49c496fda859:vWXVAWXeEQKfLlerFDMD3rsekBQzU5tz \
     --header "Content-Type:application/json" \
     --url http://api.jsform.com/api/v1/reportlist/55b639212e8f3685227bf154
Copy to clipboardErrorCopied

2.获取报表分组

描述
获取报表分组信息。

访问地址
http://api.jsform.com/api/v1/report/grouplist

访问方式
GET

参数 无

返回值

返回示例

{
    "status":"success",
    "groups":[
        {
            "id":"55ae4e9d2e8f1176ff21453f",
            "name":"分组1"
        },
        {
            "id":"55ae4ea62e8f1176ff214540",
            "name":"分组2"
        }
    ]
}
Copy to clipboardErrorCopied

curl示例

curl -u 51470abd078d49c496fda859:eWfALrToAuQvo47zDYFfaRxTVaeNsEIL \
     --header "Content-Type:application/json" \
     --url http://api.jsform.com/api/v1/report/grouplist
Copy to clipboardErrorCopied

3.根据表单ID获取对应的报表列表

描述
获取报表分组信息。

访问地址
http://api.jsform.com/api/v1/report/grouplist

访问方式
GET

参数

返回值

返回示例

{
    "status": "success",
    "rows": [
    {
        "id": "54af9a2e0cf2e0a29dcd82d7",
        "update_time": 1436102269097,
        "create_by": "apidemo@jsform.com",
        "report_name": "报表名称1",
        "group_id": "55ae4ea62e8f1176ff214540",
        "create_time": 1420794414952,
        "form_id": "545b974a0cf2ba5432bebe75",
        "report_desc": "报表描述1",
        "update_by": "apidemo@jsform.com"
    },
    {
        "id": "54af9a2e0cf2e0a29dcd82d7",
        "update_time": 1436102269097,
        "create_by": "apidemo@jsform.com",
        "report_name": "报表名称2",
        "group_id": "55ae4ea62e8f1176ff214540",
        "create_time": 1420794414952,
        "form_id": "545b974a0cf2ba5432bebe75",
        "report_desc": "报表描述2",
        "update_by": "apidemo@jsform.com"
    }]
}
Copy to clipboardErrorCopied

报表列表字段说明

curl示例

curl -u 51470abd078d49c496fda859:vWXVAWXeEQKfLlerFDMD3rsekBQzU5tz \
     --header "Content-Type:application/json" \
     --url http://api.jsform.com/api/v1/reportlistbyfomid/55b639212e8f3685227bf154
Copy to clipboardErrorCopied

表单数据API

1.查询单条数据

描述
根据数据记录id查询一条数据。

访问地址
http://api.jsform.com/api/v1/entry/query/{entryId}

访问方式
GET

参数

返回值

comments数据结构

返回示例

{
    "status": "success",
    "entry":
    {
        "id": "55afebb42e8f8f0998d4c463",
        "field3": "item2",
        "update_time": 1437592500470,
        "create_by": "apidemo@jsform.com",
        "create_time": 1437592500470,
        "form_id": "55afcbc9ba875d5d6e445988",
        "comments": [
        {
            "id": "55afed2c2e8f8f0998d4c465",
            "create_by": "apidemo@jsform.com",
            "create_time": 1437592876585,
            "form_id": "55afcbc9ba875d5d6e445988",
            "comment": "评论内容1"
        },
        {
            "id": "55aff4bb2e8fe09ae58e3d95",
            "create_by": "apidemo@jsform.com",
            "create_time": 1437594811672,
            "form_id": "55afcbc9ba875d5d6e445988",
            "comment": "评论内容2"
        }],
        "timeout": 1.0,
        "update_by": "apidemo@jsform.com",
        "ip": "192.168.0.110"
    }
}


curl示例

``` java

curl -u 51470abd078d49c496fda859:eWfALrToAuQvo47zDYFfaRxTVaeNsEIL  \
     --header "Content-Type:application/json"  \
     --url http://api.jsform.com/api/v1/entry/query/55afebb42e8f8f0998d4c463
Copy to clipboardErrorCopied

2.查询表单数据

描述
根据指定的条件查询表单提交的数据。

访问地址
http://api.jsform.com/api/v1/entry/query

访问方式
POST

参数

过滤条件数据结构

返回值

返回示例

{
    "status": "success",
    "total": 2,
    "rows": [
    {
        "field5": 1434297600000,
        "id": "552b51160cf2ba60b5b68289",
        "field6": 123.0,
        "field1": "文本1"
    },
    {
        "field5": 1434297600000,
        "id": "552b51160cf2ba60b5b68290",
        "field6": 124.0,
        "field1": "文本2"
    }]
}
Copy to clipboardErrorCopied

curl示例

curl -u 51470abd078d49c496fda859:vWXVAWXeEQKfLlerFDMD3rsekBQzU5tz \
     --header "Content-Type:application/json" \
     -d "{\"form_id\":\"552b4ffe0cf2ba60b5b6825b\",\"fields\":[\"field1\",\"field5\",\"field6\",\"id\"], \"filters\":[{\"field\":\"field1\" ,\"compare_type\":\"eq\" ,\"data_type\":\"string\" ,\"value\":\"123\"}],\"order_by\":{\"field1\":1}}" \
     --url http://api.jsform.com/api/v1/entry/query
Copy to clipboardErrorCopied

3.查询评论

描述
查询某条数据的所有评论。

访问地址
http://api.jsform.com/api/v1/comment/query/{entryId}

访问方式
GET

参数

返回值

返回示例

{
    "status": "success",
    "rows": [
    {
        "create_by": "test@jsform.com",
        "create_time": 1434424845679,
        "comment": "评论内容"
    }]
}
Copy to clipboardErrorCopied

评论列表字段说明

curl示例

curl -u 51470abd078d49c496fda859:vWXVAWXeEQKfLlerFDMD3rsekBQzU5tz \
     --header "Content-Type:application/json" \
     --url http://api.jsform.com/api/v1/comment/query/552b51160cf2ba60b5b68289
Copy to clipboardErrorCopied

4.添加评论

描述
对某条数据添加评论。

访问地址
http://api.jsform.com/api/v1/comment/add

访问方式
POST

参数

返回值

返回示例

{
    "comment_id":"55affa6a2e8fe3f27e969429",
    "status":"success"
}
Copy to clipboardErrorCopied

curl示例

curl -u 51470abd078d49c496fda859:eWfALrToAuQvo47zDYFfaRxTVaeNsEIL \
     --header "Content-Type:application/json" \
     -d "{\"form_id\":\"55afcbc9ba875d5d6e445988\", \"entry_id\":\"55afebb42e8f8f0998d4c463\",\"comment\":\"评论内容\",\"comment_name\":\"张三\"}" \
     --url http://api.jsform.com/api/v1/comment/add
Copy to clipboardErrorCopied

5.电子合同

描述
获取已签署完成的电子合同。

访问地址
http://api.jsform.com/api/v1/contract/query/{entryId}

访问方式
GET

返回值

返回示例

{
    "url":"https://oss.esign.cn/1111563786/1838f7e0-41e3-4caa-b08c-17b8a61b232e/6065293a703c3283fcfeb1.pdf?Expires=1617248373&OSSAccessKeyId=LTAI4G5MrqtY4Moi&Signature=mQZAmkfF%2BbDLHnIAjrtmTtmPEt8%3D",
    "status":"success"
}
Copy to clipboardErrorCopied

curl示例

curl -u 51470abd078d49c496fda859:vWXVAWXeEQKfLlerFDMD3rsekBQzU5tz \
     --header "Content-Type:application/json" \
     --url http://api.jsform.com/api/v1/contract/query/552b51160cf2ba60b5b68289
Copy to clipboardErrorCopied

PowerBI接入

准备条件

• Power BI桌面版
• 含有数据的表单

1.通过API获取

1.查看表单，获取表单id/appkey和appsecret

2.打开提供的powerbi模板文件（联系客服获取）

3.修改表单id/appkey/appsecret

4.点击保存，则数据全部调用过来

5.关闭powerbi query（弹框内容需点击是）

2.通过Web获取

1.开启Power BI后，点击从web获取数据源

2.切换到高级，按如下填写

访问地址
https://www.jsform.com/web/entries/griddata/{formid}?p=x&q=xxx

参数

3.点击确认后，则会看到数据都进入powerbi表格中，这样就可以在powerbi中对表单收集的数据进行分析了

API 查询数据示例代码

java

public class ApiTest {
    public static void main(String[] args) throws Exception {
        String apiKey = ""; //替换为自己的apiKey
        String apiSecret = ""; //替换为自己的apiSecret
        String apiAuth = apiKey + ":" + apiSecret;
        //api请求发送的json数据，根据实际情况替换form_id等
        String postJsonData = "{\"form_id\":\"58fffa51bb7c7c0723f5ed3a\",\"fields\":[\"field1\",\"field5\",\"field6\",\"id\"],\"order_by\":{\"field1\":1}}";

        OutputStreamWriter writer = null;
        InputStream is = null;
        try {
            URL apiUrl = new URL("http://api.jsform.com/api/v1/entry/query");
            HttpURLConnection conn = (HttpURLConnection)apiUrl.openConnection();
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Authorization", "Basic " + Base64.getEncoder().encodeToString(apiAuth.getBytes()));
            conn.setDoInput(true);
            conn.setDoOutput(true);
            writer = new OutputStreamWriter(conn.getOutputStream(), "UTF-8");
            writer.write(postJsonData);
            writer.close();

            is = conn.getInputStream();
            ByteArrayOutputStream baos = new ByteArrayOutputStream();
            byte[] buffer = new byte[512];
            int readLen = 0;
            while ((readLen = is.read(buffer)) > 0) {
                baos.write(buffer, 0, readLen);
            }

            String json = new String(baos.toByteArray(), "UTF-8");
            //返回的json字符串
            System.out.println(json);
        } finally {
            if (writer != null) {
                writer.close();
            }
            if (is != null) {
                is.close();
            }
        }
    }
}
Copy to clipboardErrorCopied

Python3

# -*- coding: utf-8 -*-
# python3，需要requests库
import requests

if __name__ == '__main__':
    postJson = {
        'form_id': '58fffa51bb7c7c0723f5ed3a',
        'fields': ['field1', 'field5', 'field6', 'id'],
        'order_by': {'field1': 1}
    }
    # 下面xxx，yyy需要对应替换为apiKey，apiSecret
    auth = ('xxx', 'yyy')
    r = requests.post('http://api.jsform.com/api/v1/entry/query', json=postJson, auth=auth)
    print(r.json())Copy to clipboardErrorCopied

推送类 API

查询类 API 具有频率限制，若需要实时获取最新数据，不宜反复查询，而应该用数据推送类 API 。

配置开启推送

需进入表单的规则设置界面，在 API - POST 参数页面，勾选 ”将数据Post到第三方服务器“，并选择需要的推送时机(增、改、删)和数据格式。

推送数据格式和示例

• 推送请求数据格是JSON，请求方法是HTTP POST
• 在数据提交频繁的情况下， 建议接收数据和处理数据分开异步处理以加快接收
• 增、改、删都会推送整条数据，在删除数据的情况下，HTTP head中有特殊头部action=DELETE
• 目前推送数据始终是以单条数据为单位的。若选择数据格式为对象，则推送数据是下面的格式。若选择数据格式为数组，则推送数据是JSON数组，数组里面的元素是下面的示例格式。

    {
        "ID" : 99 ,    
        "field1" :"aBcd" ,    
        "field2" :"张三" ,    
        "field3" :"13800138000" ,    
        "field4" :123.45 ,    
        "amount" :123.45 ,    
        "create_by" :"test@yourcompany.com" ,    
        "create_time" : 1000800800, //距离1970 年 1 月 1 日的毫秒数 ,    
        "update_by" :"test@yourcompany.com" ,    
        "update_time" : 1000800800, //距离1970 年 1 月 1 日的毫秒数 ,
        "form_id" :"5f0d4d1790245636a812a803",    
        "id" :"543c06f2926ea4ee544766b5",
        //...其他字段
    }Copy to clipboardErrorCopied