数据API

接口认证

首先确保你有访问 API的能力。获得 API Key & Secret 后,即可通过 API 提交数据。 金数据 API v1 使用 HTTP 基本验证方式(HTTP Basic Authentication)

操作流程

1)API 调用者,通过金数据系统后台,生成 API Key 和 API Secret 。

2)将 API Key 和 API Secret 拼接成为字符串( api_key + ":" + api_secret)。

3)将字符串进行 Base64 编码。

4)将编码后的字符串拼接 Basic 头("Basic " + encoded_string)。

5)将最终字符串,放置在 HTTP 请求头的 Authorization 中。

6)发送 HTTP 请求到 API 接口,完成 API 调用。

样例(python)

API key: Secret 通过 Base64 转码

 import base64                #引入包
s ="Dz-prR233UB9PR42323DJg:S7-75sjOLdsdfuesdf123Ryg"         # key:Secret
encoded_string = base64.b64encode(s.encode('utf-8')).decode('utf-8')  
print(encoded_string)

———————encoded_string 输入内容—————————
RHotcHJSMjMzVUI5UFI0MjMyM0RKZzpTNy03NXNqT0xkc2RmdWVzZGYxMjNSeWc=

Headers 需要传两个参数,Accept 和 Content-Type,值都是 application/json。如下图(Python样例):

key Value
Accept application/json
Content-Type application/json
Authorization Basic encoded_string
headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Authorization': 'Basic RHotcHJSMjMzVUI5UFI0MjMyM0RKZzpTNy03NXNqT0xkc2RmdWVzZGYxMjNSeWc='
}

1.向金数据表单推送新数据(POST)

POST 地址 : https://jinshuju.net/api/v1/forms/``xxx(表单 token)``/entries

注意:表单 token 可通过表单填写 URL 地址获取,例如表单填写链接为:https://jinshuju.net/f/``ABC123``,则表单tokenABC123,表单 POST 地址为:https://jinshuju.net/api/v1/forms/``ABC123``/entries

企业版支持增加的数据字段

字段类型 数据结构
姓名|单行文字 String
手机 String
邮箱 String
电话 String
地址 Hash
数字 Float
多行文字 String
文字单选|图片单选|下拉框 String
文字多选|图片多选 Array
多级下拉框 Hash
日期 Date
时间 Hash
网址 String
地理位置 Hash
配图商品|无图商品 Hash
矩阵填空 Hash
矩阵单选 Hash
矩阵多选 Hash
表格 Hash
评分 Integer
NPS Integer
排序 Hash
预约 Hash
横向填空 Hash

注:除开 [表单关联] 字段之外,其他字段新增数据都支持,以上是部分字段示例。

各字段推送样例

{
    //姓名/单行文字字段
    "field_1": "张三"

    //手机字段
    "field_2": "13812345678",

    //邮箱字段
    "field_3": "support@jinshuju.net",

    //电话字段
    "field_4": "400-6606-892",

    //地址字段
    "field_5": {
        "province": "陕西省",  //省、自治区、直辖市级
        "city": "西安市",       //市级别
        "district": "雁塔区",  //区县级别
        "street": "高新路"    //text可自定义输入
    },

    //数字字段
    "field_6": 123,

    //多行文字字段
    "field_7": "这是一段文字"

    //文字单选字段(下拉框、单项选择、图片单选)
    "field_8": "BW12"   //其中[BW12]为选项的value

    //文字多选字段(多项选择、图片多选)
    "field_9": [
        "0rSa",        //选项的value
        "nqhN"        //选项的value
    ],

    //多级下拉框
    "field_10": {
        "level_1": "ebsK",   //第一级的选项
        "level_2": "q5jM",   //第二级的选项
        "level_3": "QqvJ",   //第三级的选项
        "level_4": "4xVN"   //第四级的选项
    },

    //日期字段
    "field_11": "2021-04-10",

    //时间字段
    "field_12":{
        "hour":19,    //小时
        "minute":55,  //分钟
        "second":30    //秒,可有可无
    },

    //网址字段
    "field_13": "https://jinshuju.net",

    //地理位置字段
    "field_14": {
        //详细地理位置写法:
        "address": "四川省成都市武侯区桂溪街道天府三街太平洋保险金融大厦"

         //经纬度写法:
        "latitude": "30.5468",   
        "longitude": "104.06274"
    },

    //商品字段(配图商品、无图商品、报名费)
    "field_15": [
    {
        "value": "11Vo",    //商品1项目的value
        "number": 2         //商品数量
    },
    {
        "value": "YckV",  //商品2项目的value
        "number": 2         //商品数量
    }
    ],

    //矩阵填空字段
    "field_16":{
        "hM8z":{        //题目(行)的value
            "field_1":"第一列单元格内容",
            "field_2":"第二列单元格内容",
            "field_3":"第三列单元格内容"
        },
        "wbXV":{        //题目(行)的value
            "field_1":"第一列单元格内容",
            "field_2":"第二列单元格内容",
            "field_3":"第三列单元格内容"
        },
        "VWLv":{      //题目(行)的value
            "field_1":"第一列单元格内容",
            "field_2":"第二列单元格内容",
            "field_3":"第三列单元格内容"
        }
    },

    //矩阵单选
    "field_17": {
        "iyE5": "aPQx"  //题目(行)的value:选项的value           
    },

    //矩阵多选
     "field_18": {
        "OwY5":  [   //题目(行)的value
            "kPeU",     //选项的value
            "kr8F"
        ]
    },

    //表格字段
    "field_19": [
        { //第一行
        "field_1":"1111111",//第一个字段
        "field_2":"2222222",//第二个字段
        "field_3":"333333"//第三个字段
        },
        { //第二行
        "field_1":"1111111_2",//第一个字段
        "field_2":"2222222_2",//第二个字段
        "field_3":"333333_2"//第三个字段
        }
    ]

    //评分字段
    "field_20": 3

    //NPS字段
    "field_21": 10

    //排序字段
    "field_22": [
        "BPeU",//选项2value,第一
        "KnX5",//选项3value,第二
        "11OL"//选项1value,第三
    ]

    //预约字段
    "field_23":[
        { //按天预约项目
        "api_code":"fOwM",   //「fOwM」为项目的value
        "scheduled_at": "2021-04-26",//按天预约
        "number": 1  //预约名额数量
        },
        {//按时间段预约项目
        "api_code": "jofm", // 预约项目
        "scheduled_at": "2021-04-18T00:00:00+08:00",//开始时间
        "end_at": "2021-04-18T15:00:00+08:00",//结束时间段
        "number": 2//预约名额数量
    }
        ]

    //横向填空
    "field_24":{
        "field_1": "把酒问青天",     
        "field_2": "今夕是何年"
     }

}

⚠️注意:

如果表单使用了矩阵填空、图片单选、图片多选、多级下拉框、商品、预约、排序等有 name 和 value 的字段类型,在 JSON 数据时,以 value 提交。value 可通过 get 表单结构获取如下( python 示例):

import requests

url = "https://jinshuju.net/api/v1/forms/xxxxxx(表单token)"

payload={}
headers = {
  'Authorization': 'Basic RHotcHJSb05TUlZVQjlQUjRyTURKZzpTNy03NXNqT0xkdWVxQ0JSbU9mUnln'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

获取到文字单选字段结构样例:

"field_9": {
                "label": "文字单选-星期",
                "type": "single_choice",
                "notes": "",
                "private": false,
                "validation": {},
                "choices": [
                    {
                        "name": "星期一",
                        "value": "BW12",
                        "hidden": false
                    },
                    {
                        "name": "星期二",
                        "value": "Jdfv",
                        "hidden": false
                    },
                    {
                        "name": "星期三",
                        "value": "Ztsh",
                        "hidden": false
                    },
                    {
                        "name": "星期四",
                        "value": "MxeC",
                        "hidden": false
                    },
                    {
                        "name": "星期五",
                        "value": "4za9",
                        "hidden": false
                    },
                    {
                        "name": "星期六",
                        "value": "d9O6",
                        "hidden": false
                    },
                    {
                        "name": "星期日",
                        "value": "TChl",
                        "hidden": false
                    }
                ],
                "allow_other": false
            }

因此建议在先获取数据结构,并将字段的 API code,name,value 保存在数据库或构造成列表或者字典,以便于后续编码使用。

完整推送数据案例(Python样例)

import requests
import json

url = "https://jinshuju.net/api/v1/forms/nNqdAU"

#多选类型需要用列表的形式传递参数
list=[]

#定义一个数据推送的函数
def data_json(name,email,date,sex,list,Array_value):
    #将参数传输到字典data
      data1={
    "field_1": name,
      "field_2": email,
      "field_4": date,
      "field_3": sex,
      "field_5": list,
      "field_6": Array_value  #图片单选等字段需要传递选项对应的VALUE值,不能传name
      }
    #将字典转化为JSON格式
payload = json.dumps(data1)

#Authorization为API KEY和API Secret生成,可以用APIPOST或者POSTMAN来测试。
headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Authorization': 'Basic RHotcHJSb05TUlZVQjlQUjRyTURKZzpTNy03NXNqT0xkdWVxQ0JSbU9mUnln'}

    #调用request函数,将数据推送到金数据表单中
      response = requests.request("POST", url, headers=headers, data=payload)

    #可要可不要
      print(response.text)



2.获取金数据表单中的数据(GET)

除去新增数据外,数据 API 还可以通过以下请求获取表单已收集的数据:

https://jinshuju.net/api/v1/forms/xxx(表单token)/entries

如果已收集数据超出 50 条时,会在底部 next 这里出现数值。反之则为 null 。

超出50条数据示例:

"total": 160,
    "count": 50,
    "data": [
        {
        ··············
        }
    ],
    "next": 51

未超出50条数据示例:

"total": 10,
    "count": 10,
    "data": [
        {
        ··············
        }
    ],
    "next": null

获取 50 条后的数据使用以下请求:

https://jinshuju.net/api/v1/forms/xxx(表单token)/entries?next=xx(next值)

如果信息正确,系统会返回 201 作为响应,并返回整个表单的数据( JSON 格式)给调用者。

请求示例

import requests
import json

url = "https://jinshuju.net/api/v1/forms/QiMJwJ/entries"

payload={}
files={}
headers = {
  'Accept': 'application/json',
  'Content-Type': 'application/json',
  'Authorization': 'Basic RHotcHJSb05TUlZVQjlQUjRyTURKZzpTNy03NXNqT0xkdWVQRJsSbU9mUnln'}

response = requests.request("GET", url, headers=headers, data=payload, files=files)

print(response.text)


3.获取表单单条数据(get)

token:表单token可通过表单填写url地址获取,例如表单填写链接为 https://jinshuju.net/f/ABC123,则表单 tokenABC123

SERIAL_NUMBER: 需要查询某一条数据的序号


使用规则

用量规则

API:v1 和 v4 速率限制(按小时): 注:批量抓取 1 次最多 50 条

  • 免费版(试用企业版)-20,000
  • 专业版(试用企业版)-20,000
  • 专业增强版(试用企业版)-20,000
  • 企业基础版-20,000
  • 企业协作版-30,000
  • 企业高级版-50,000
  • 商业合作版-50,000

常见报错操作案例

注:只有「表单创建者」才能使用数据 API 相关功能,「表单协作者」身份下使用相关功能会出现以下提示:

{
    "error_description": "form cannot be found"
}

1.张三创建了表单 A,张三将表单 A 共享给李四,李四使用自己账号的 Key/Secret 进行获取表单信息。

2.张三在企业版版本身份下创建的表单,张三使用的是自己个人版账号的 Key/Secret 进行获取表单信息。


👉联系技术咨询

资费介绍

免费版 专业版 专业增强版 企业基础版 企业协作版 企业高级版
价格 免费 599 元/年 2,399 元/年,299 元/月 4,399 元/年 7,399 元/年 23,999 元/年
是否支持此功能 - - - ✔️ ✔️ ✔️
联系客服