金数据高级API文档 (jinshuju.net)

注意高级API限通用型saas平台产品和金数据企业高级版及以上版本使用,且仅支持这两种类型的用户开通

本文档适用于您的金数据账号位于 jinshuju.net,如有疑问请联系客服或者销售

金数据API使用OAuth 2标准进行用户验证。

发送请求

所有的URL需要以https://api.jinshuju.net/v4/开头。仅支持SSL。目前API版本为v4版本。例如,想获得当前用户的基本信息情况:

  1. curl https://api.jinshuju.net/v4/me?access_token=...

OAuth 2验证

v4版本的金数据API支持OAuth 2。你可以使用标准的OAuth交互协议进行访问。相关URL如下:

1. 转向到金数据申请验证

  1. GET https://account.jinshuju.net/oauth/authorize

参数

参数名称 类型 备注
client_id string 必须,注册的金数据应用ID,目前仅对金数据商业合作伙伴开放。
redirect_uri string 必须,金数据应用的callback URI,当授权完成之后要转向的地址。
response_type string 必须,OAuth 2中必须将其指定为code
scope string 空格隔开的列表。目前支持的scope包括:public profile forms read_entries form_setting,默认为public。
state string 唯一随机的的字符串,用来防止跨站攻击。

2. 获得访问的access token

用户同意之后,金数据将会转向到你的网站,并带上code和之前提供的state参数。如果state不匹配,你可以终止这个请求。

拿到code之后,就可以交换access token:

  1. POST https://account.jinshuju.net/oauth/token

参数

参数名称 类型 备注
client_id string 必须,注册的金数据应用ID,目前仅对金数据商业合作伙伴开放。
client_secret string 必须,金数据应用的secret。
code string 必须,在第一步获得的code。
redirect_uri string 必须,金数据应用的callback URI,当授权完成之后要转向的地址。
grant_type string 必须,指定为 authorization_code
state string 在第一步使用的唯一随机的的字符串。

默认情况下,返回的response的形式如下:

  1. {
  2. "access_token": "2994eec8c8b19c2a2103ae2a335dc781220bb701d4c2c7d1b4cc7c629353f8a4",
  3. "token_type": "bearer",
  4. "expires_in": 7200,
  5. "refresh_token": "a563ed398b919388bc2e87b29f8d3b6e42a1195cdc1d9e36c6e9bcaa153bc6d3",
  6. "scope": "public forms read_entries",
  7. "created_at": 1455680792
  8. }

使用refresh token获得新的access_token

目前access_token有效期为7200秒,当access_token过期时,可以使用refresh_token来获得新的access_token。

  1. POST https://account.jinshuju.net/oauth/token

参数

参数名称 类型 备注
client_id string 必须,注册的金数据应用ID,目前仅对金数据商业合作伙伴开放
client_secret string 必须,金数据应用的secret
refresh_token string 必须,获取access_token时得到的refresh_token。
grant_type string 必须,指定为 refresh_token

返回的response的形式如下,得到新的access_token 和refresh_token:

  1. {
  2. "access_token": "0909a26c330883cf2cd44f8926c663ac1d639ed2940d879fb2bf4a62e06ff4a8",
  3. "token_type": "bearer",
  4. "expires_in": 7200,
  5. "refresh_token": "648478764ff94d09d62f78c8fad8c2b7886ee93c59090ececacd6dfe1b648949",
  6. "scope": "public forms read_entries",
  7. "created_at": 1455710364
  8. }

3. 使用access token访问API

  1. GET https://api.jinshuju.net/v4/forms?access_token=...

你可以把token放在URL中。也可以使用Authorization header如下:

  1. Authorization: bearer OAUTH-TOKEN

例如使用curl

  1. curl -H "Authorization: bearer OAUTH-TOKEN" https://api.jinshuju.net/v4/forms

Redirect URL

redirect_uri是必须的。如果你使用omniauth-jinshuju,就可以使用类似于https://domain.com/auth/jinshuju/callback的地址。

Scopes

Scope定义了资源范围。目前支持五个:publicprofileformsread_entriesform_setting

  • public, 获取用户的头像、昵称、邮箱、是否为付费用户等信息(邮箱、是否付费将会在后面的版本中移除,如需要,请使用profile scope
  • profile, 获取用户的账户信息,邮箱、是否为付费用户(只读)、自定义域名(只读)
  • forms, 获取用户所有表单信息、单个表单详情、表单当前状态(是否开启,填写权限,已收集数据量)
  • read_entries, 获取某表单下的数据信息,批量获取或单条获取,并且可基于查询条件获取想要的数据
  • form_setting, 获取、更新表单的设置

访问限制

访问API是基于金数据授权的用户来做频率限制的,目前免费用户1,000次/小时,专业版用户10,000次/小时,专业增强版用户20,000次/小时。

HTTP Header中会留下相应的信息。

  1. X-RateLimit-Limit:1000
  2. X-RateLimit-Remaining:999

如果用户有特别高的访问频率需求,可以联系我们。

分页

当请求返回多个条目时,如表单列表、数据列表时,默认每次(per_page)返回20个条目,可以设定per_page参数来单次获得更多的数据,但目前最多支持50条。

例如:

  1. GET https://api.jinshuju.net/v4/forms?access_token=...&per_page=50

在每一次请求返回的header里会包含分页信息,如下表所示:

Header Name Description
X-Total 符合条件的总数,例如X-Total:50
X-Count 当前请求返回的数量,例如X-Count:20
Link 包含上一页(prev)或下一页(next)的访问地址,rel目前仅支持next和prev。

例如获取表单列表时,request header里会返回如下:

  1. Link:<https://api.jinshuju.net/v4/forms?access_token=...&per_page=20&cursor=xxxxx>; rel="prev",
  2. <https://api.jinshuju.net/v4/forms?access_token=...&per_page=20&cursor=xxxxx>; rel="next"

在发出第一次查询请求后,不断的检查返回的Link Header里的next列表,如果存在则直接使用链接去获取,不存在则代表批量获取完成。

链接中的cursor是查询的游标,在访问不同的api时,含义不同。查询表单列表时,代表下一次要取的表单的id;查询数据列表时,代表下一次要取的数据的序号,数据序号是一个递增的整数,由于存在数据删除的情况,所以可能是不连贯的,不建议采用分页数值和序号来拼cursor值。

API列表

获取当前用户基本信息

需要Scope: public或者默认

  1. GET https://api.jinshuju.net/v4/me?access_token=...
  1. {
  2. "email": "email@mail.com",
  3. "nickname": "email@mail.com",
  4. "avatar": "https://dn-jsjpub.qbox.me/av/517aa4fe24290aa13800001395.jpg",
  5. "paid": false,
  6. "uid": "fk3a9EvKTu3KKmTqa2CisQ"
  7. }
参数名 类型 参数说明
email String 用户邮箱地址,全局唯一
nickname String 用户昵称
avatar String 头像地址
paid Boolean 是否为付费用户
uid String 用户id

获取当前用户账户信息

需要Scope: profile

  1. GET https://api.jinshuju.net/v4/profile?access_token=...
  1. {
  2. "email": "email@mail.com",
  3. "paid": false,
  4. "custom_domain": 'forms.example.com'
  5. }
参数名 类型 参数说明
email String 用户邮箱地址,全局唯一
paid Boolean 是否为付费用户
custom_domain String 自定义域名信息,该功能可用时返回用户在个人中心设置的值,否则为空

获取表单列表

需要Scope: forms

  1. GET https://api.jinshuju.net/v4/forms?access_token=...
  1. [
  2. {
  3. "id": "56c28b33c02f6713aa000092",
  4. "token": "E2FBnj",
  5. "name": "市场调查表",
  6. "entries_count": 0,
  7. "shared": false,
  8. "description": "这是一个市场调查表",
  9. "created_at": "2016-02-16T02:36:35.756Z",
  10. "updated_at": "2016-02-16T02:37:35.756Z",
  11. "setting": {
  12. "icon": "fontello-paper-plane",
  13. "color": "#659199",
  14. "open_rule": "open",
  15. "permission": "public",
  16. "result_state": "closed",
  17. "result_url": null,
  18. "search_state": "closed",
  19. "search_url": null,
  20. "push_url": null
  21. }
  22. },
  23. {
  24. "id": "56b2f86ca3f5206d76000143",
  25. "token": "TivBsE",
  26. "name": "小金俱乐部活动报名",
  27. "entries_count": 0,
  28. "shared": false,
  29. "description": "2016年小金俱乐部第一站来到了上海",
  30. "created_at": "2016-02-04T07:06:20.559Z",
  31. "created_at": "2016-02-04T07:09:20.559Z",
  32. "setting": {
  33. "icon": "fontello-pencil",
  34. "color": "#659199",
  35. "open_rule": "open",
  36. "permission": "public",
  37. "result_state": "closed",
  38. "result_url": null,
  39. "search_state": "closed",
  40. "search_url": null,
  41. "push_url": null
  42. }
  43. }
  44. ]

获取表单详情

需要Scope: forms

  1. GET https://api.jinshuju.net/v4/forms/RygpW3?access_token=...
  1. {
  2. "id": "56b2f86ca3f5206d76000143",
  3. "token": "TivBsE",
  4. "name": "小金俱乐部活动报名",
  5. "entries_count": 0,
  6. "shared": false,
  7. "description": "2016年小金俱乐部第一站来到了上海,这一次我们把上海当成主场。如果你之前遗憾没有参加小金的北京发布会",
  8. "created_at": "2016-02-04T07:06:20.559Z",
  9. "updated_at": "2016-02-04T07:10:20.559Z",
  10. "fields": [
  11. {
  12. "type": "single_line_text",
  13. "label": "姓名",
  14. "api_code": "field_1",
  15. "notes": "",
  16. "predefined_value": "",
  17. "private": false,
  18. "validations": {
  19. "required": true
  20. }
  21. },
  22. {
  23. "type": "single_line_text",
  24. "label": "公司、团队或者组织名称",
  25. "api_code": "field_16",
  26. "notes": "",
  27. "predefined_value": "",
  28. "private": false,
  29. "validations": {}
  30. },
  31. {
  32. "type": "single_choice",
  33. "label": "称呼",
  34. "api_code": "field_2",
  35. "notes": "",
  36. "predefined_value": null,
  37. "private": false,
  38. "validations": {
  39. "required": true
  40. },
  41. "choices": [
  42. {
  43. "name": "先生",
  44. "value": "2jYk"
  45. },
  46. {
  47. "name": "女士",
  48. "value": "pIjs"
  49. },
  50. {
  51. "name": "保密",
  52. "value": "yofb"
  53. }
  54. ],
  55. "allow_other": false
  56. },
  57. {
  58. "type": "phone",
  59. "label": "手机",
  60. "api_code": "field_4",
  61. "notes": "",
  62. "predefined_value": "",
  63. "private": false,
  64. "validations": {
  65. "required": true
  66. }
  67. },
  68. {
  69. "type": "multiple_choice",
  70. "label": "您所在的行业",
  71. "api_code": "field_3",
  72. "notes": "",
  73. "predefined_value": null,
  74. "private": false,
  75. "validations": {
  76. "required": true
  77. },
  78. "choices": [
  79. {
  80. "name": "餐饮",
  81. "value": "vXHU"
  82. },
  83. {
  84. "name": "娱乐",
  85. "value": "0yrs"
  86. },
  87. {
  88. "name": "教育",
  89. "value": "zI63"
  90. },
  91. {
  92. "name": "IT/互联网/计算机",
  93. "value": "uN9L"
  94. },
  95. {
  96. "name": "微信营销",
  97. "value": "0tKd"
  98. },
  99. {
  100. "name": "零售",
  101. "value": "1eS0"
  102. },
  103. {
  104. "name": "旅游",
  105. "value": "zFay"
  106. },
  107. {
  108. "name": "汽车",
  109. "value": "iYs5"
  110. },
  111. {
  112. "name": "金融",
  113. "value": "rmIa"
  114. },
  115. {
  116. "name": "房地产",
  117. "value": "KzHg"
  118. },
  119. {
  120. "name": "电子商务",
  121. "value": "yP93"
  122. },
  123. {
  124. "name": "家居",
  125. "value": "51UD"
  126. },
  127. {
  128. "name": "文化/媒体",
  129. "value": "Gdyw"
  130. },
  131. {
  132. "name": "服饰",
  133. "value": "e5dJ"
  134. },
  135. {
  136. "name": "医疗",
  137. "value": "0vZh"
  138. },
  139. {
  140. "name": "服务行业",
  141. "value": "etAf"
  142. },
  143. {
  144. "name": "学生",
  145. "value": "ArtE"
  146. }
  147. ],
  148. "allow_other": true
  149. },
  150. {
  151. "type": "email",
  152. "label": "邮箱",
  153. "api_code": "field_17",
  154. "notes": "",
  155. "predefined_value": null,
  156. "private": false,
  157. "validations": {
  158. "required": true
  159. }
  160. },
  161. {
  162. "type": "multiple_choice",
  163. "label": "此行目的",
  164. "api_code": "field_5",
  165. "notes": "<p>我们会与您分享金数据的行业使用情况,也欢迎您来与我们分享自己的使用体会</p>",
  166. "predefined_value": null,
  167. "private": false,
  168. "validations": {},
  169. "choices": [
  170. {
  171. "name": "听听金数据官方的使用案例分享",
  172. "value": "7oLf"
  173. },
  174. {
  175. "name": "听听其他金数据用户的使用情况",
  176. "value": "vQki"
  177. },
  178. {
  179. "name": "分享我自己使用金数据的情况",
  180. "value": "6qHO"
  181. },
  182. {
  183. "name": "与其他金数据用户交流使用心得",
  184. "value": "MCkX"
  185. }
  186. ],
  187. "allow_other": true
  188. },
  189. {
  190. "type": "single_choice",
  191. "label": "您是否愿意分享一个话题?",
  192. "api_code": "field_10",
  193. "notes": "<p>与现场观众分享金数据的使用体验,可能获得意想不到的商机,或者朋友</p>",
  194. "predefined_value": null,
  195. "private": false,
  196. "validations": {},
  197. "choices": [
  198. {
  199. "name": "是,我想与其他人分享",
  200. "value": "1lq3"
  201. },
  202. {
  203. "name": "不是,我更乐意当听众",
  204. "value": "J2RP"
  205. }
  206. ],
  207. "allow_other": false
  208. },
  209. {
  210. "type": "single_line_text",
  211. "label": "话题名称",
  212. "api_code": "field_11",
  213. "notes": "<p>我们与您联系并且通知您是否通过审核(您可能会接到来自金数据的电话)</p>",
  214. "predefined_value": "",
  215. "private": false,
  216. "validations": {
  217. "required": true
  218. }
  219. },
  220. {
  221. "type": "paragraph_text",
  222. "label": "话题简介",
  223. "api_code": "field_12",
  224. "notes": "<p>亲爱的,如果你想要在活动上分享,我们希望你的话题是精心准备的,所以请告诉我们话题简介吧。</p>",
  225. "predefined_value": "",
  226. "private": false,
  227. "validations": {
  228. "required": true
  229. }
  230. },
  231. {
  232. "type": "paragraph_text",
  233. "label": "对于这次活动,您有什么想要问我们的?",
  234. "api_code": "field_6",
  235. "notes": "",
  236. "predefined_value": "",
  237. "private": false,
  238. "validations": {}
  239. },
  240. {
  241. "type": "drop_down",
  242. "label": "是否已经联系",
  243. "api_code": "field_7",
  244. "notes": "",
  245. "predefined_value": null,
  246. "private": true,
  247. "validations": {},
  248. "choices": [
  249. {
  250. "name": "是",
  251. "value": "SoG1"
  252. },
  253. {
  254. "name": "否",
  255. "value": "iyh7"
  256. },
  257. {
  258. "name": "没打通",
  259. "value": "9m1q"
  260. }
  261. ],
  262. "allow_other": false
  263. },
  264. {
  265. "type": "paragraph_text",
  266. "label": "联系情况",
  267. "api_code": "field_8",
  268. "notes": "",
  269. "predefined_value": "1. 能否参加\n2. 哪个公司?\n3. 金数据的使用情况",
  270. "private": true,
  271. "validations": {}
  272. },
  273. {
  274. "type": "single_choice",
  275. "label": "签到",
  276. "api_code": "field_15",
  277. "notes": "",
  278. "predefined_value": null,
  279. "private": true,
  280. "validations": {},
  281. "choices": [
  282. {
  283. "name": "是 ",
  284. "value": "303X"
  285. },
  286. {
  287. "name": "否",
  288. "value": "2Y8V"
  289. }
  290. ],
  291. "allow_other": false
  292. },
  293. {
  294. "type": "paragraph_text",
  295. "label": "备注",
  296. "api_code": "field_18",
  297. "notes": "",
  298. "predefined_value": "",
  299. "private": true,
  300. "validations": {}
  301. }
  302. ],
  303. "setting": {
  304. "icon": "fontello-pencil",
  305. "color": "#659199",
  306. "open_rule": "open",
  307. "permission": "public",
  308. "result_state": "closed",
  309. "result_url": null,
  310. "search_state": "closed",
  311. "search_url": null,
  312. "push_url": null
  313. }
  314. }

获取表单当前状态

需要Scope: forms

  1. GET https://api.jinshuju.net/v4/forms/RygpW3/status?access_token=...
  1. {
  2. "is_open": true,
  3. "permission": "public",
  4. "entries_count": 60
  5. }

获取多条数据

需要Scope: read_entries

  1. GET https://api.jinshuju.net/v4/forms/RygpW3/entries?access_token=...
  1. [
  2. {
  3. "serial_number": 1,
  4. "field_1": "小金",
  5. "field_16": "金数据",
  6. "field_2": "2jYk",
  7. "field_4": {
  8. "value": "18629058968",
  9. "verified": true
  10. },
  11. "field_3": [
  12. "zI63",
  13. "uN9L"
  14. ],
  15. "field_17": "roody@jinshuju.net",
  16. "field_5": [
  17. "7oLf",
  18. "vQki"
  19. ],
  20. "field_10": "1lq3",
  21. "field_11": "小金的应用场景",
  22. "field_12": "金数据在各行各业的用法",
  23. "field_6": "金数据有没有一些更加高级的技巧呢?",
  24. "field_7": "",
  25. "field_8": "1. 能否参加\n2. 哪个公司?\n3. 金数据的使用情况",
  26. "field_15": "",
  27. "field_18": "",
  28. "creator_name": "o王琰o",
  29. "updater_name": "",
  30. "created_at": "2016-02-17T11:40:31.524Z",
  31. "updated_at": "2016-02-17T11:40:31.524Z",
  32. "info_remote_ip": "123.139.21.4",
  33. "info_platform": "Macintosh",
  34. "info_os": "OS X 10.11.3",
  35. "info_browser": "Chrome 48.0.2564.109"
  36. }
  37. ]

数据查询

查询数据,支持与现有数据列表查询类似的接口

  • 文本、单选、多选、下拉框、评分、商品、序号(serial_number)、扩展属性(x_field_1) http://api.jinshuju.net/v4/forms/aJSON8/entries?access_token=<token>&field_1=xxx 注:获取表单结构中暂无商品字段的item信息 注:全匹配查询,不支持模糊查询

  • 同一字段的多个条件取并集查询 http://api.jinshuju.net/v4/forms/aJSON8/entries?access_token=<token>&field_1[]=xxx&field_1[]=yyy

  • 多个字段取交集查询 http://api.jinshuju.net/v4/forms/aJSON8/entries?access_token=<token>&field_1=xxx&field_2=yyy

  • 矩阵单选查询 http://api.jinshuju.net/v4/forms/aJSON8/entries?access_token=<token>&field_1[<题目code>][]=<选项code>

  • 二级下拉框查询 http://api.jinshuju.net/v4/forms/aJSON8/entries?access_token=<token>&field_1[<一级选项code>]=<二级选项code>

  • 微信省市查询 http://api.jinshuju.net/v4/forms/aJSON8/entries?access_token=<token>&x_field_weixin_province_city[陕西]=西安

  • 数据提交时间查询 指定日期:http://api.jinshuju.net/v4/forms/aJSON8/entries?access_token=<token>&created_at=2016-1-22 某一日期之后:http://api.jinshuju.net/v4/forms/aJSON8/entries?access_token=<token>&created_at[start]=2016-1-22 某一日期之前:http://api.jinshuju.net/v4/forms/aJSON8/entries?access_token=<token>&created_at[end]=2016-1-22 某个日期区间:http://api.jinshuju.net/v4/forms/aJSON8/entries?access_token=<token>&created_at[start]=2015-12-15&created_at[end]=2016-1-22

获取单条数据

需要Scope: read_entries

  1. GET https://api.jinshuju.net/v4/forms/RygpW3/entries/<序列号>?access_token=...

JSON Load:

  1. {
  2. "serial_number": 1,
  3. "field_1": "小金",
  4. "field_16": "金数据",
  5. "field_2": "2jYk",
  6. "field_4": {
  7. "value": "18629058968",
  8. "verified": true
  9. },
  10. "field_3": [
  11. "zI63",
  12. "uN9L"
  13. ],
  14. "field_17": "roody@jinshuju.net",
  15. "field_5": [
  16. "7oLf",
  17. "vQki"
  18. ],
  19. "field_10": "1lq3",
  20. "field_11": "小金的应用场景",
  21. "field_12": "金数据在各行各业的用法",
  22. "field_6": "金数据有没有一些更加高级的技巧呢?",
  23. "field_7": "",
  24. "field_8": "1. 能否参加\n2. 哪个公司?\n3. 金数据的使用情况",
  25. "field_15": "",
  26. "field_18": "",
  27. "creator_name": "o王琰o",
  28. "updater_name": "",
  29. "created_at": "2016-02-17T11:40:31.524Z",
  30. "updated_at": "2016-02-17T11:40:31.524Z",
  31. "info_remote_ip": "123.139.21.4",
  32. "info_platform": "Macintosh",
  33. "info_os": "OS X 10.11.3",
  34. "info_browser": "Chrome 48.0.2564.109"
  35. }

获取、更新表单设置

需要Scope: form_setting

获取表单设置

  1. get https://api.jinshuju.net/v4/forms/RygpW3/setting?access_token=...

Json Load:

  1. {
  2. "icon": "fontello-sound",
  3. "color": "#afa373",
  4. "open_rule": "open",
  5. "permission": "public",
  6. "result_state": "closed",
  7. "result_url": null,
  8. "search_state": "closed",
  9. "search_url": null,
  10. "push_url": null,
  11. "success_redirect_url": "https://baidu.com",
  12. "success_redirect_fields": [
  13. "field_2",
  14. "field_1"
  15. ]
  16. }

更新表单设置

  1. put https://api.jinshuju.net/v4/forms/RygpW3/setting
参数名称 类型 备注
access_token string 必须,通过oauth认证所得到的access_token
success_redirect_url string 提交成功后的跳转网址
success_redirect_fields string 提交成功后的跳转网址附加字段参数,以及提交给该字段的信息,最多三个参数,多个参数以空格分隔,如”serial_number x_field_1”,超过三个参数会回应报错信息。参数必须为表单里字段,会自动过滤非表单字段,目前支持:序号、单/多行文本、单选、多选、数字、邮箱、电话、日期以及网址等字段。如果表单中包含商品字段,则还可以附带序号和总价。可参考 https://help.jinshuju.net/articles/redirect-with-params.html
push_url string 数据以JSON格式推送的网址,使用请参考https://help.jinshuju.net/articles/http-push
publish_form_embed_js string 设置官方应用中心嵌入到金数据发布表单页面的js
publish_form_embed_styles string 设置官方应用中心嵌入到金数据发布表单页面的style