如果你具有开发能力,可以通过API获取表单定义及数据、提交新数据、也可提供自己平台的API来实时获取表单中新提交的数据。 首先,需要在 [增值服务] —> [OpneAPi] 中通过设置appSecret,开启你的API支持。

番茄表单OpenApi功能概述

使用场景

如果你具有开发能力,可以通过API获取表单定义及数据、提交新数据、也可提供自己平台的API来实时获取表单中新提交的数据。

首先,需要在 [增值服务] —> [OpneAPi] 中通过设置appSecret,开启你的API支持。

432.png

目前番茄表单分钉钉版网页版两个版本

钉钉版

钉钉版番茄表单,只能在钉钉容器内使用,或是在浏览器上手机钉钉扫码登录。

钉钉版访问:ding.fanqier.cn

网页版

网页版番茄表单,需在非钉钉浏览器上用邮箱、手机号、微信扫码登录使用,或通过微信公众号进入使用。

网页版访问:fanqier.cn

使用限制

1. 仅对企业版用户开放API接口
2. 钉钉版中如果你对表单进行了加密,则无法正常使用该功能

安全性

除了数据推送到第三方平台之外,番茄表单提供的API都需要授权认证。默认情况下,你在 [增值服务] —> [OpneAPi] 中会获取到一个appid(它是你在番茄系统中的唯一标识符),但为了调用的安全,还需设置一个appSecret,并使用该appSecret和appid生成token。

token生成规则

创建如下的JSON对象的String类型,一定是严格的JSON字符串的String格式

  tokenJson = {
    appid: ${APPID},
    now: //当前时间戳
    expired: //过期时间戳, expired - now 必须小于 2小时
  }
1. 将上述String类型通过Base64编码
2. 将str与APPSecret拼接并将拼接结果使用sha1散列算法加密,加密结果全部转成小写
3. 将上述编码结果与加密结果通过'.'拼接,结果便是api接口需要的token
4. token = SafeBase64(str) + '.'+sha1(str + APPSecret).toLowerCase()

示例代码: NodeJS示例:

const crypto = require('crypto')
//expired为token有效期,单位ms,最长为2小时(7200000ms)
const expiredTime = 7200000,
  appid = '5a265f50fb3d5b2d2da7bca2'
  appSecret = 'testing',
  sha1Code = crypto.createHash("sha1"),
    tokenJson = {
      appid,
      now: Date.now(),
      expired: Date.now()+expiredTime
    },
    str = JSON.stringify(tokenJson)

const token = new Buffer(str).toString('base64')+'.'+sha1Code.update(str + appSecret, 'utf-8').digest("hex").toLowerCase()

Java示例:

import java.util.Date;

import javax.xml.bind.DatatypeConverter;

import java.io.UnsupportedEncodingException;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;

public class Main {
   public static void main(String[] args) throws UnsupportedEncodingException, NoSuchAlgorithmException {

      MessageDigest crypt = MessageDigest.getInstance("SHA-1");

      String appid = "5a265f50fb3d5b2d2da7bca2";
      String appSecret = "testing";
      long expired = new Date().getTime()+180000;
      //严格的json字符串
      String str = "{\"appid\":\""+appid+"\",\"now\":"+new Date().getTime()+",\"expired\":"+expired+"}";

      String base64 = Base64.getEncoder().encodeToString(str.getBytes());
      crypt.update((str+appSecret).getBytes("UTF-8"));

      String token = base64+'.'+DatatypeConverter.printHexBinary(crypt.digest()).toLowerCase();

  }
}

Python 示例:

import json
import hashlib
import base64

expired = 1800000
t = 1552455085642 # 时间,毫秒值
appid = "5b91130e1243c61f731ae69d"
appSecret = "Z1Kh1gdjXUcfmRkF3T1Q"
tokenJson = {
  "appid": appid,
  "now": t,
  "expired": t + expired
}
jstr = json.dumps(tokenJson)
b = base64.b64encode(jstr)
s = hashlib.sha1(jstr + appSecret).hexdigest().lower()
token = b+'.'+s

token的传递规则

* http请求头header中添加key为x-open-api-token字符串,value为token
* http请求body域中添加key为token字符串,value为token
* http请求query域中添加key为token字符串,value为token

我们为你提供的API

获取表单列表接口

获取表单结构接口

获取表单回复数据列表接口

提交数据接口

表单回复数据推送接口

备注:番茄表单API接口频率限制------默认5000/hour