金数据帮助中心

数据API

目录


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

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

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

1.1 金数据企业版目前支持增加的数据字段有:

字段类型 数据结构
姓名|单行文字 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

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

1.2 数据API样例

首先确保你有访问 API的能力。获得 API Key & Secret 后,即可通过 API 提交数据。 需要注意的是,无论是 GET 还是 POST 请求,Authorization 的类型都是 Basic Auth, Username 和 Password 分别对应 API Key 和 API Secret:

参数名称 Code
Username API Key
Password API Secret

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

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

Authorization: Basice 后的信息为 API key: Secret 通过 Base64 转码后的样式

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

1.3 各字段推送样例:

{
    //姓名/单行文字字段
    "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保存在数据库或构造成列表或者字典,以便于后续编码使用。

1.4 完整推送数据案例(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.使用规则

用量规则

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

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

4.常见报错操作案例

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

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

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

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


👉联系技术咨询

有帮助(5) 未解决问题?