表單基礎(chǔ) API

API 是表單大師對外提供的編程接口，允許其他應(yīng)用開發(fā)者調(diào)用指定帳號內(nèi)的表單相關(guān)資源。例如，在表單新提交的數(shù)據(jù)時推送到自己的平臺，或在自己的平臺查詢表單提交的數(shù)據(jù)和評論等。

API 訪問約定

• 所有的數(shù)據(jù)格式為 JSON
• 所有的數(shù)據(jù)傳輸編碼為UTF-8
• 目前，API 訪問的地址前綴均為 http://api.jsform.com/api/v1/
• 除了數(shù)據(jù)推送 API 外，所有的 API 都需要HTTP Basic驗證。使用方法可參見：http://www.cnblogs.com/QLeelulu/archive/2009/11/22/1607898.html

獲取HTTP Basic驗證參數(shù) (API Key/Secret)

在開始使用之前，您需要在表單大師賬戶內(nèi)獲取API Key 和 Secret，只有通過這兩個參數(shù)才能獲取API的訪問權(quán)限。

您每次進行API調(diào)用時，都需要構(gòu)造HTTP Basic驗證的請求頭。API Key 對應(yīng)于 Basic驗證的用戶名， API Secret 對應(yīng)于 Basic 驗證的密碼。例如，使用curl來獲得某個表單的數(shù)據(jù)：

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 均有請求頻率限制，短時間內(nèi)大量請求會返回頻率過高錯誤。

表單 API

1.獲取表單信息

描述
根據(jù)表單id獲取表單信息（表單名稱、表單描述等）

訪問地址
http://api.jsform.com/api/v1/form/{formId}

訪問方式
GET

參數(shù)

返回值

返回示例

{
    "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

參數(shù)

返回值

返回示例

{
    "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.獲取表單字段對照表

描述
獲取某個表單的字段名稱與數(shù)據(jù)表中的字段對應(yīng)關(guān)系。

訪問地址
http://api.jsform.com/api/v1/fields/{formId}

訪問方式
GET

參數(shù) 無

返回值

返回示例

{
    "status":"success",
    "fields":{
        "field1":{
            "data_type":"String",
            "label":"單行文本"
        },
        "field2":{
            "data_type":"Number",
            "label":"數(shù)字"
        }
    }
}
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

參數(shù) 無

返回值

返回示例

{
    "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.根據(jù)報表分組獲取報表列表

描述
獲取某賬戶下的所有報表。

訪問地址
http://api.jsform.com/api/v1/reportlist/{groupId}

訪問方式
GET

參數(shù)

返回值

返回示例

{
    "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

參數(shù) 無

返回值

返回示例

{
    "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.根據(jù)表單ID獲取對應(yīng)的報表列表

描述
獲取報表分組信息。

訪問地址
http://api.jsform.com/api/v1/report/grouplist

訪問方式
GET

參數(shù)

返回值

返回示例

{
    "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

表單數(shù)據(jù)API

1.查詢單條數(shù)據(jù)

描述
根據(jù)數(shù)據(jù)記錄id查詢一條數(shù)據(jù)。

訪問地址
http://api.jsform.com/api/v1/entry/query/{entryId}

訪問方式
GET

參數(shù)

返回值

comments數(shù)據(jù)結(jié)構(gòu)

返回示例

{
    "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": "評論內(nèi)容1"
        },
        {
            "id": "55aff4bb2e8fe09ae58e3d95",
            "create_by": "apidemo@jsform.com",
            "create_time": 1437594811672,
            "form_id": "55afcbc9ba875d5d6e445988",
            "comment": "評論內(nèi)容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.查詢表單數(shù)據(jù)

描述
根據(jù)指定的條件查詢表單提交的數(shù)據(jù)。

訪問地址
http://api.jsform.com/api/v1/entry/query

訪問方式
POST

參數(shù)

過濾條件數(shù)據(jù)結(jié)構(gòu)

返回值

返回示例

{
    "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.查詢評論

描述
查詢某條數(shù)據(jù)的所有評論。

訪問地址
http://api.jsform.com/api/v1/comment/query/{entryId}

訪問方式
GET

參數(shù)

返回值

返回示例

{
    "status": "success",
    "rows": [
    {
        "create_by": "test@jsform.com",
        "create_time": 1434424845679,
        "comment": "評論內(nèi)容"
    }]
}
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.添加評論

描述
對某條數(shù)據(jù)添加評論。

訪問地址
http://api.jsform.com/api/v1/comment/add

訪問方式
POST

參數(shù)

返回值

返回示例

{
    "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\":\"評論內(nèi)容\",\"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接入

準(zhǔn)備條件

• Power BI桌面版
• 含有數(shù)據(jù)的表單

1.通過API獲取

1.查看表單，獲取表單id/appkey和appsecret

2.打開提供的powerbi模板文件（聯(lián)系客服獲?。?/p>

3.修改表單id/appkey/appsecret

4.點擊保存，則數(shù)據(jù)全部調(diào)用過來

5.關(guān)閉powerbi query（彈框內(nèi)容需點擊是）

2.通過Web獲取

1.開啟Power BI后，點擊從web獲取數(shù)據(jù)源

2.切換到高級，按如下填寫

訪問地址
http://www.91mvp.cn/web/entries/griddata/{formid}?p=x&q=xxx

參數(shù)

3.點擊確認(rèn)后，則會看到數(shù)據(jù)都進入powerbi表格中，這樣就可以在powerbi中對表單收集的數(shù)據(jù)進行分析了

API 查詢數(shù)據(jù)示例代碼

java

public class ApiTest {
    public static void main(String[] args) throws Exception {
        String apiKey = ""; //替換為自己的apiKey
        String apiSecret = ""; //替換為自己的apiSecret
        String apiAuth = apiKey + ":" + apiSecret;
        //api請求發(fā)送的json數(shù)據(jù)，根據(jù)實際情況替換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需要對應(yīng)替換為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 具有頻率限制，若需要實時獲取最新數(shù)據(jù)，不宜反復(fù)查詢，而應(yīng)該用數(shù)據(jù)推送類 API 。

配置開啟推送

需進入表單的規(guī)則設(shè)置界面，在 API - POST 參數(shù)頁面，勾選 ”將數(shù)據(jù)Post到第三方服務(wù)器“，并選擇需要的推送時機(增、改、刪)和數(shù)據(jù)格式。

推送數(shù)據(jù)格式和示例

• 推送請求數(shù)據(jù)格是JSON，請求方法是HTTP POST
• 在數(shù)據(jù)提交頻繁的情況下， 建議接收數(shù)據(jù)和處理數(shù)據(jù)分開異步處理以加快接收
• 增、改、刪都會推送整條數(shù)據(jù)，在刪除數(shù)據(jù)的情況下，HTTP head中有特殊頭部action=DELETE
• 目前推送數(shù)據(jù)始終是以單條數(shù)據(jù)為單位的。若選擇數(shù)據(jù)格式為對象，則推送數(shù)據(jù)是下面的格式。若選擇數(shù)據(jù)格式為數(shù)組，則推送數(shù)據(jù)是JSON數(shù)組，數(shù)組里面的元素是下面的示例格式。

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