金数据API Playground

查看文档 >>

示例代码

cURL
Ruby - RestClient

# 假设redirect_uri配置为 https://yourdomain.com/oauth/jinshuju/callback
# CLIENT_ID和CLIENT_SECRET以及其他参数请替换成你自己的参数

# 1. 转向到金数据申请验证
# HTTP Request GET 'https://account.jinshuju.net/oauth/authorize?client_id=CLIENT_ID&redirect_uri=https://yourdomain.com/oauth/jinshuju/callback&response_type=code&scope=public%20profile&state=PRXzeHPtE3D'

# 验证授权通过后，金数据会转向到redirect_uri，并带有code和state参数，如
# https://yourdomain.com/oauth/jinshuju/callback?code=b0b995f68ccfd43065e183033bf527b8a3a2b9767ed01f4310374a381a41e145&state=PRXzeHPtE3D

# 2. 验证及授权通过后获取access_token
curl --request POST 'https://account.jinshuju.net/oauth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
	"client_id": CLIENT_ID,
	"client_secret": CLIENT_SECRET,
	"code": "b0b995f68ccfd43065e183033bf527b8a3a2b9767ed01f4310374a381a41e145",
	"redirect_uri": "https://yourdomain.com/oauth/jinshuju/callback",
	"grant_type": "authorization_code",
	"state": "PRXzeHPtE3D"
}'

# 返回结果示例：
# {
#     "access_token": "96911675c420e22f8f214831e1673253a57d336cfe7d672aba853e6899103249",
#     "token_type": "bearer",
#     "expires_in": 7200,
#     "refresh_token": "80154effb41528d684f7309d281b4a4309d1fe0709c4cfffea9f9edc25feb11b",
#     "scope": "public profile",
#     "created_at": 1591842271
# }

# 2.1 当access_token过期时，通过refresh_token刷新
curl --request POST 'https://account.jinshuju.net/oauth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
	"client_id": CLIENT_ID,
	"client_secret": CLIENT_SECRET,
	"refresh_token": "80154effb41528d684f7309d281b4a4309d1fe0709c4cfffea9f9edc25feb11b",
	"grant_type": "refresh_token"
}'

# 返回结果示例：
# {
#     "access_token": "35edcf066303af7760b0757407ad580bdd9e98c739a78c71be0a06ff4dc0e408",
#     "token_type": "bearer",
#     "expires_in": 7200,
#     "refresh_token": "9efe2d300af77c4cf4a82e89e90df58bee06afe5fe778f2ead55a93545a8a671",
#     "scope": "public profile",
#     "created_at": 1591843739
# }

# 假设redirect_uri配置为 https://yourdomain.com/oauth/jinshuju/callback
# CLIENT_ID和CLIENT_SECRET以及其他参数请替换成你自己的参数

# 1. 转向到金数据申请验证
# HTTP Request GET 'https://account.jinshuju.net/oauth/authorize?client_id=CLIENT_ID&redirect_uri=https://yourdomain.com/oauth/jinshuju/callback&response_type=code&scope=public%20profile&state=PRXzeHPtE3D'

# 验证授权通过后，金数据会转向到redirect_uri，并带有code和state参数，如
# https://yourdomain.com/oauth/jinshuju/callback?code=b0b995f68ccfd43065e183033bf527b8a3a2b9767ed01f4310374a381a41e145&state=PRXzeHPtE3D

# 2. 验证及授权通过后获取access_token
require 'rest-client'

payload = {
	client_id: CLIENT_ID,
	client_secret: CLIENT_SECRET,
	code: 'b0b995f68ccfd43065e183033bf527b8a3a2b9767ed01f4310374a381a41e145',
	redirect_uri: 'https://yourdomain.com/oauth/jinshuju/callback',
	grant_type: 'authorization_code',
	state: 'PRXzeHPtE3D'
}
response = RestClient.post 'https://account.jinshuju.net/oauth/token', payload, content_type: :json, accept: :json
puts JSON.parse(response.body)

# 结果示例：
# {
#     "access_token": "96911675c420e22f8f214831e1673253a57d336cfe7d672aba853e6899103249",
#     "token_type": "bearer",
#     "expires_in": 7200,
#     "refresh_token": "80154effb41528d684f7309d281b4a4309d1fe0709c4cfffea9f9edc25feb11b",
#     "scope": "public profile",
#     "created_at": 1591842271
# }

# 2.1 当access_token过期时，通过refresh_token刷新
payload = {
	client_id: CLIENT_ID,
	client_secret: CLIENT_SECRET,
	refresh_token: '80154effb41528d684f7309d281b4a4309d1fe0709c4cfffea9f9edc25feb11b',
	grant_type: 'refresh_token'
}
response = RestClient.post 'https://account.jinshuju.net/oauth/token', payload, content_type: :json, accept: :json
puts JSON.parse(response.body)

# 结果示例：
# {
#     "access_token": "35edcf066303af7760b0757407ad580bdd9e98c739a78c71be0a06ff4dc0e408",
#     "token_type": "bearer",
#     "expires_in": 7200,
#     "refresh_token": "9efe2d300af77c4cf4a82e89e90df58bee06afe5fe778f2ead55a93545a8a671",
#     "scope": "public profile",
#     "created_at": 1591843739
# }

OAuth 2验证

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

认证域: https://account.jinshuju.net
接口域: https://api.jinshuju.net/v4

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 write_entries form_setting`，默认为`public`。
state	string	唯一随机的的字符串，用来防止跨站攻击。

2. 获得访问的access token

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

拿到code之后，就可以交换access_token:

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的形式如下：

{
    "access_token": "2994eec8c8b19c2a2103ae2a335dc781220bb701d4c2c7d1b4cc7c629353f8a4",
    "token_type": "bearer",
    "expires_in": 7200,
    "refresh_token": "a563ed398b919388bc2e87b29f8d3b6e42a1195cdc1d9e36c6e9bcaa153bc6d3",
    "scope": "public forms read_entries",
    "created_at": 1455680792
}

2.1 使用refresh_token获得新的access_token

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

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：

{
    "access_token": "0909a26c330883cf2cd44f8926c663ac1d639ed2940d879fb2bf4a62e06ff4a8",
    "token_type": "bearer",
    "expires_in": 7200,
    "refresh_token": "648478764ff94d09d62f78c8fad8c2b7886ee93c59090ececacd6dfe1b648949",
    "scope": "public forms read_entries",
    "created_at": 1455710364
}

3. 使用access_token访问API

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

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

Authorization: Bearer ACCESS-TOKEN

例如使用curl

curl -H "Authorization: Bearer ACCESS-TOKEN" https://api.jinshuju.net/v4/forms

查看文档 >>

# 使用「认证」后取得的 access_token 发送请求
# 该API返回结果为带有分页的表单列表，你可以通过 per_page 参数定义每页获取的表单数

curl --request GET 'https://api.jinshuju.net/v4/forms?access_token=ACCESS_TOKEN&per_page=5'

# 使用「认证」后取得的 access_token 发送请求
# 该API返回结果为带有分页的表单列表，你可以通过 per_page 参数定义每页获取的表单数

RestClient.get 'https://api.jinshuju.net/v4/forms', params: {access_token: ACCESS_TOKEN, per_page: 5}, content_type: :json, accept: :json

返回结果

Headers

Body

获取表单列表

需要的Scope: forms

该API返回结果带有分页信息，关于分页参考这里

请求参数说明

KEY	类型	说明
per_page	number	大于0的数字，用于设定单次请求的表单数
cursor	string	分页请求的游标，在发出第一次查询请求后，如果返回了Link Header，可以从next的访问地址中获取到

返回结果说明

Response Body

表单结构的JSON数组，其中每个表单的结构如下：

KEY	类型	说明
id	string	表单ID
token	string	表单链接上的短token
name	string	表单对外名称
entries_count	number	表单收集到的数据量
shared	boolean	是否他人共享的表单
description	string	表单描述
created_at	timestamp	表单创建时间
updated_at	timestamp	表单最后更新时间
`setting`	json	表单设置
cooperator_emails	array	表单协作者的邮箱列表

其中setting的结构如下：

KEY	类型	说明
icon	string	表单图标
color	string	表单图标颜色
open_rule	open/closed/time_based	表单当前的开放规则，`open`表单开放，`closed`表单已关闭，`time_based`表单在设置的时间段内开放
permission	public/login/private	表单谁可以填写，可能的值：`public`所有人可填, `login`仅金数据用户可填, `private`仅管理员可填
push_url	url	数据推送地址
success_redirect_url	url	表单填写后的跳转地址
success_redirect_fields	array	表单填写后跳转到其他地址时附加的参数
show_field_number	boolean	表单填写时是否显示字段序号
open_in_weixin_limited	boolean	是否仅限在微信/企业微信中填写
collect_weixin_info	boolean	是否收集填写者微信信息
gen_code_enabled	boolean	是否开启了确认码
payment_enabled	boolean	是否绑定了支付

Response Header

在返回的HTTP Header中需要关注跟分页相关的Header：

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

例如返回如下Link Header：

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

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

链接中的cursor是查询的游标，查询表单列表时，代表下一次要取的表单的id。

查看文档 >>

返回结果

Headers

Body

获取表单详情

需要Scope: forms

TODO

查看文档 >>

返回结果

Headers

Body

获取表单当前状态

需要Scope: forms

返回值说明

KEY	类型	说明
is_open	boolean	当前表单是否开放填写
permission	string	表单谁可以填写，可能的值：`public`所有人可填, `login`仅金数据用户可填, `private`仅管理员可填
entries_count	number	已收集到多少数据

查看文档 >>

返回结果

Headers

Body

复制表单

需要Scope: forms

个人授权复制给当前授权的用户,企业授权复制给openid对应的用户

请求参数说明

KEY	类型	说明
openid	string	可选，获取的用户列表中的openid。使用个人的acces token无需填写；使用企业的access token必须填写。
name	string	可选，复制出来的表单命名。如果不提供或者为空字符串，将使用“[新]”+原表单名作为复制后的表单的名字

返回结果说明

表单结构的JSON数组

查看文档 >>

返回结果

Headers

Body

获取表单设置

需要Scope: form_setting

返回值说明

KEY	类型	说明

查看文档 >>

返回结果

Headers

Body

更新表单设置

需要Scope: form_setting

参数说明

KEY	类型	说明
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

返回值说明

KEY	类型	说明

查看文档 >>

返回结果

Headers

Body

删除表单

需要Scope: forms

请求参数说明

返回结果说明

返回删除结果

KEY	类型	说明
token	string	被删除表单的token
deleted_at	timestamp	删除时间

查看文档 >>

返回结果

Headers

Body

为表单添加协作成员

需要Scope: forms

请求参数说明

KEY	类型	说明
openid	string	必须，获取的用户列表中的openid。这里需填写加为协作成员的用户openid。
role	string	必须，指定的角色，仅支持 manager, data_maintainer, data_viewer。

返回结果说明

KEY	类型	说明
openid	string	新添加协作成员的openid
role	string	新添加协作成员的角色名称

查看文档 >>

返回结果

Headers

Body

为表单变更协作成员角色

需要Scope: forms

请求参数说明

KEY	类型	说明
openid	string	必须，获取的用户列表中的openid。这里需填写加为协作成员的用户openid。
role	string	必须，指定的角色，仅支持 manager, data_maintainer, data_viewer。

返回结果说明

KEY	类型	说明
openid	string	协作成员的openid
role	string	协作成员的当前角色名称

查看文档 >>

返回结果

Headers

Body

为表单移除协作成员

需要Scope: forms

请求参数说明

返回结果说明

KEY	类型	说明
openid	string	新添加协作成员的openid
role	string	新添加协作成员的角色名称

查看文档 >>

返回结果

Headers

Body

获取多条数据

需要Scope： read_entries

数据查询

文本、单选、多选、下拉框、评分、商品、序号(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

查看文档 >>

返回结果

Headers

Body

获取单条数据

需要Scope: read_entries

查看文档 >>

返回结果

Headers

Body

获取当前用户基本信息

需要Scope: public 或者默认

查看文档 >>

返回结果

Headers

Body

获取当前账户信息

需要Scope: profile

返回值说明

KEY	类型	说明
email	string	用户邮箱地址，全局唯一
paid	boolean	是否为付费用户
custom_domain	string	自定义域名信息，该功能可用时返回用户在个人中心设置的值，否则为空

查看文档 >>

返回结果

Headers

Body

获取企业中用户列表

需要Scope： users

该API返回结果带有分页信息，关于分页参考这里

请求参数说明

KEY	类型	说明
per_page	number	大于0的数字，用于设定单次请求的表单数
cursor	string	分页请求的游标，在发出第一次查询请求后，如果返回了Link Header，可以从next的访问地址中获取到

返回结果说明

用户结构的JSON数组

Response Header

在返回的HTTP Header中需要关注跟分页相关的Header：

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

例如返回如下Link Header：

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

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

链接中的cursor是查询的游标，查询列表时，代表下一次要取的对象的id。

API V4

示例代码

OAuth 2验证

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

2. 获得访问的access token

2.1 使用refresh_token获得新的access_token

3. 使用access_token访问API

示例代码

返回结果

获取表单列表

请求参数说明

返回结果说明

Response Body

Response Header

返回结果

获取表单详情

返回结果

获取表单当前状态

返回值说明

返回结果

复制表单

请求参数说明

返回结果说明

返回结果

获取表单设置

返回值说明

返回结果

更新表单设置

参数说明

返回值说明

返回结果

删除表单

请求参数说明

返回结果说明

返回结果

为表单添加协作成员

请求参数说明

返回结果说明

返回结果

为表单变更协作成员角色

请求参数说明

返回结果说明

返回结果

为表单移除协作成员

请求参数说明

返回结果说明

返回结果

获取多条数据

数据查询

返回结果

获取单条数据

返回结果

获取当前用户基本信息

返回结果

获取当前账户信息

返回值说明

返回结果

获取企业中用户列表

请求参数说明

返回结果说明

Response Header