表單基礎 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 Key/Secret

您每次進行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

查詢類 API

所有查詢類 API 均有請求頻率限制，短時間內大量請求會返回頻率過高錯誤。

表單 API

1.獲取表單信息

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

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

訪問方式
GET

參數

參數名	數據類型	是否必須	示例值	默認值	描述
formId	String	是	55b639212e8f3685227bf154		表單ID

返回值

參數名	描述
status	執行狀態。”success”表示成功，”error”表示失敗
message	如果失敗，用此字段描述失敗原因。如果成功，此字段為空。
form	表單的詳細信息

返回示例


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

表單列表字段說明

字段名	描述
id	表單ID
form_name	表單名稱
form_desc	表單描述
group_id	表單分組ID
group_name	表單分組名稱
create_by	創建人
create_time	創建時間
update_by	最后修改人
update_time	最后修改時間

curl示例


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

2.獲取表單列表

描述
獲取某分組下的所有表單。

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

訪問方式
GET

參數

參數名	數據類型	是否必須	示例值	默認值	描述
groupId	String	是	55b639212e8f3685227bf154		分組Id。可選擇值為”all”：獲取所有表單列表；指定的groupId：獲取指定分組的表單列表；”nogroup”：獲取未分組的表單列表

返回值

參數名	描述
status	執行狀態。”success”表示成功，”error”表示失敗
message	如果失敗，用此字段描述失敗原因。如果成功，此字段為空
rows	所有表單列表

返回示例


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

表單列表字段說明

字段名	描述
ID	表單ID
form_name	表單名稱
form_desc	表單描述
group_id	表單分組ID
group_name	表單分組名稱
create_by	創建人
create_time	創建時間
update_by	最后修改時間

curl示例


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

3.獲取表單字段對照表

描述
獲取某個表單的字段名稱與數據表中的字段對應關系。

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

訪問方式
GET

參數無

返回值

參數名	描述
status	執行狀態。”success”表示成功，”error”表示失敗
message	如果失敗，用此字段描述失敗原因。如果成功，此字段為空
fields	所有字段的名稱與字段名的對應關系

返回示例


{
    "status":"success",
    "fields":{
        "field1":{
            "data_type":"String",
            "label":"單行文本"
        },
        "field2":{
            "data_type":"Number",
            "label":"數字"
        }
    }
}

表單列表字段說明
見每個表單的API字段說明

curl示例


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

4.獲取表單分組

描述
獲取表單分組信息。

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

訪問方式
GET

參數無

返回值

參數名	描述
status	執行狀態。”success”表示成功，”error”表示失敗
message	如果失敗，用此字段描述失敗原因。如果成功，此字段為空
groups	所有表單的分組

返回示例


{
    "status":"success",
    "groups":[
        {
            "id":"55ae4e9d2e8f1176ff21453f",
            "name":"分組1"
        },
        {
            "id":"55ae4ea62e8f1176ff214540",
            "name":"分組2"
        }
    ]
}

curl示例


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

報表API

1.根據報表分組獲取報表列表

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

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

訪問方式
GET

參數

參數名	數據類型	是否必須	示例值	默認值	描述
groupId	String	是	55b639212e8f3685227bf154		分組Id。可選擇值為”all”：獲取所有報表列表；[groupId]：獲取指定分組的報表列表；”nogroup”：獲取未分組的報表列表。

返回值

參數名	描述
status	執行狀態。”success”表示成功，”error”表示失敗
message	如果失敗，用此字段描述失敗原因。如果成功，此字段為空
groups	所有報表列表

返回示例


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

報表列表字段說明

字段名	描述
ID	報表ID
report_name	報表名稱
report_desc	報表描述
form_id	數據源對應的表單ID
create_by	創建人
create_time	創建時間
update_by	最后修改人
update_time	最后修改時間
group_id	分組ID
group_name	分組名稱

curl示例


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

2.獲取報表分組

描述
獲取報表分組信息。

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

訪問方式
GET

參數無

返回值

參數名	描述
status	執行狀態。”success”表示成功，”error”表示失敗
message	如果失敗，用此字段描述失敗原因。如果成功，此字段為空
groups	所有報表的分組

返回示例


{
    "status":"success",
    "groups":[
        {
            "id":"55ae4e9d2e8f1176ff21453f",
            "name":"分組1"
        },
        {
            "id":"55ae4ea62e8f1176ff214540",
            "name":"分組2"
        }
    ]
}

curl示例


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

3.根據表單ID獲取對應的報表列表

描述
獲取報表分組信息。

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

訪問方式
GET

參數

參數名	數據類型	是否必須	示例值	默認值	描述
formId	String	是	55b639212e8f3685227bf154		表單ID
、

返回值

參數名	描述
status	執行狀態。”success”表示成功，”error”表示失敗
message	如果失敗，用此字段描述失敗原因。如果成功，此字段為空
groups	匹配到的報表列表

返回示例


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

報表列表字段說明

字段名	描述
ID	報表ID
report_name	報表名稱
report_desc	報表描述
form_id	數據源對應的表單ID
create_by	創建人
create_time	創建時間
update_by	最后修改人
update_time	最后修改時間

curl示例


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

表單數據API

1.查詢單條數據

描述
根據數據記錄id查詢一條數據。

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

訪問方式
GET

參數

參數名	數據類型	是否必須	示例值	默認值	描述
entryId	String	是	558226580cf22a4f82d7b49a		數據記錄id

返回值

參數名	描述
status	執行狀態。”success”表示成功，”error”表示失敗
message	如果失敗，用此字段描述失敗原因。如果成功，此字段為空
entry	數據結構參考API中的描述，其中評論(comments)的結構如下

comments數據結構

參數名	描述
form_id	表單ID
entry_id	數據ID
comment	評論內容
create_name	創建人姓名
create_time	創建時間

返回示例


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

2.查詢表單數據

描述
根據指定的條件查詢表單提交的數據。

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

訪問方式
POST

參數

參數名	數據類型	是否必須	示例值	默認值	描述
form_id	String	是	558226580cf22a4f82d7b49a		表單ID
page_number	Number	否	1	0	查詢頁碼，整數，從0開始計數
page_size	Number	否	21	15	頁碼大小，整數，最大值為100
fields	Array	否	[“field1”,”field2”]		需要查詢的字段，可以在表單的API頁面查詢到字段名稱
order_by	Object	否	{“field1”:1}		排序依據。1為正序,-1為倒序。比如示例表示的含義為“按field1正序排列”
filters	Array	否	[{“field”:”field1” ,”compare_type”:”eq” ,”data_type”:”string” ,”value”:”123”}]		過濾條件，每個條件是一個Object對象，各個條件將以and連接。示例中的條件用SQL表示，其含意為“field1=’123’”。對象描述如下表格中所示。

過濾條件數據結構

參數名	描述
field	條件字段名
compare_type	比較類型，值可以為”eq”（等于），”gt”（大于），”lt”（小于）
data_type	字段數據類型，值可以為”string”（文本），”number”（數字），“date”（日期）
value	條件值

返回值

參數名	描述
status	執行狀態。”success”表示成功，”error”表示失敗
message	如果失敗，用此字段描述失敗原因。如果成功，此字段為空
total	滿足查詢條件的總記錄數
rows	滿足查詢條件的當前頁記錄明細

返回示例


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

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

3.查詢評論

描述
查詢某條數據的所有評論。

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

訪問方式
GET

參數

參數名	數據類型	是否必須	示例值	默認值	描述
entryId	String	是	552b4ffe0cf2ba60b5b6825b		數據ID

返回值

參數名	描述
status	執行狀態。”success”表示成功，”error”表示失敗
message	如果失敗，用此字段描述失敗原因。如果成功，此字段為空
rows	所有評論內容

返回示例


{
    "status": "success",
    "rows": [
    {
        "create_by": "test@jsform.com",
        "create_time": 1434424845679,
        "comment": "評論內容"
    }]
}

評論列表字段說明

字段名	描述
create_by	創建人
create_time	創建時間
comment	評論內容

curl示例


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

4.添加評論

描述
對某條數據添加評論。

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

訪問方式
POST

參數

參數名	數據類型	是否必須	示例值	描述
form_id	String	是	55afcbc9ba875d5d6e445988	表單ID
entry_id	String	是	558226580cf22a4f82d7b49a	數據ID
comment	String	是	這里是評論內容	評論內容
comment_name	String	是	張三	發表評論人的姓名

返回值

參數名	描述
status	執行狀態。”success”表示成功，”error”表示失敗
message	如果失敗，用此字段描述失敗原因。如果成功，此字段為空
comment_id	評論ID

返回示例


{
    "comment_id":"55affa6a2e8fe3f27e969429",
    "status":"success"
}

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

5.電子合同

描述
獲取已簽署完成的電子合同。

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

訪問方式
GET

返回值

參數名	描述
status	執行狀態。”success”表示成功，”error”表示失敗
url	如果失敗，用此字段描述失敗原因。如果成功，此字段為電子合同的下載地址

返回示例


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

curl示例


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

PowerBI接入

準備條件

Power BI桌面版
含有數據的表單

1.通過API獲取

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

表單id獲取方式

appkey和appsecret獲取方式

2.打開提供的powerbi模板文件（聯系客服獲取）

點擊編輯查詢，進入power query

點擊高級編輯器，進入代碼編輯頁面

3.修改表單id/appkey/appsecret

修改表單id/appkey/appsecret

4.點擊保存，則數據全部調用過來

修改查詢名稱，比如按表單名稱命名

5.關閉powerbi query（彈框內容需點擊是）

然后進入powerbi則可在powerbi中對數據進行報表分析

2.通過Web獲取

1.開啟Power BI后，點擊從web獲取數據源

從web獲取數據源

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

URL格式： https://www.jsform.com/web/entries/griddata/ 后面加上表單ID+?p=x&q=xxx

表單ID

APPKey和APP Secret

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

參數

參數名	數據類型	是否必須	示例值	默認值	描述
{formid}	String	是	55b639212e8f3685227bf154		所需數據的表單ID
p	int	否	1	1	第1頁數據，一頁有500條數據
q	String	否	方案1		查詢方案名
username	String	是	13111111111		登陸名
appKey	String	是	5dfb389c7c5f38666cb72be0		開發者ID中API Key
appSecret	String	是	LPoKvOaY5GpTLiD78bLVVfc9NBpAVmek		開發者ID中API Secret

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();
            }
        }
    }
}

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())

推送類 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",
        //...其他字段
    }

數據自定義顏色

表單增強 API

本篇目錄