openApi 概述

4234 上次更新时间:2021-02-21 19:51:46

Document

API (应用程序接口)是为了在多方系统中传递数据而制定的通讯接口,速融云官方 API,可以帮助用户,以 HTTP 方式对速融云中的数据,进行数据推送和拉取,实现速融云与第三方系统的数据对接。

1.已开放 openAPI 功能

  • 账户体系:开放速融云用户注册体系,支持第三方账户用户系统的兑换
  • 流程待办接口:支持发起流程、处理流程、查看流程待办详情、以及待办列表等。
  • 表单API :智能 API 针对表单数据的 CRUD
  • 智能连接控件:实时读入第三方系统数据或者推送数据到第三方系统
  • WEBHOOK 推送数据 :流程流转或智能工作流中,使用 webhook 推送到第三方服务。

2.名词解释

2.1 应用

在速融云中应用是最小逻辑单元,或者应用是你创建或创建的「系统」,你可以理解为手机上的一个个软件,如 微信、飞书、钉钉 等等都是应用。 一个 速融云应用通常由一个或多个有联系的表单、流程、仪表盘和数据协作组成。

2.2 表单

  • 速融云中,承载数据收集、展示的载体就是「表单」。
  • 在日常工作中,在纸质时代制式表单的语义与我们的表单一样。 数据的格式填写、上报、汇总都是通过表单来实现。
  • 表单有唯一标识formId,查询表单信息,使用formId

2.3 流程

  • 表单数据提交后流转的方式。一个表单对应一个流程。
  • 一个表单对应一套流程,查询表单的流程信息也使用 formId 来查询

2.4 记录

或称为(数据)当填写一张表单后,就会产生一条该表单的记录,类似于 excel 的一行数据。

2.5 instanceId (流程时使用)

表单提交的一条数据,就是一个数据实例,对应一个唯一标识 instanceId.

2.6 recordId(智能 api 时使用)

与instanceId 含义相同,主要是在智能 api 相关接口使用。他俩都可以标识唯一标识一个记录。

2.7 节点

流程处理的每一步就是 1 个节点。一个流程包含多个节点。节点具有自己的 nodeId

彼此之间的关系

  • 1 个应用可以有多个表单
  • 1 个表单对应 1 个流程
  • 1个流程有多个节点(可以有 1 个)
  • 1个表单可以有多条记录

3. 开放平台介绍

3.1 设计原则

  • 速融云 OpenAPI 将部分网站服务封装成一系列 API(Application Programming Interface,应用编程接口)开放出来,供第三方开发者使用。
  • 速融云 OpenAPI 采用 RESTFul 风格设计。
  • 所有的 OpenAPI 请求地址都是 可预期的 以及 面向资源 的,并且使用规范的 HTTP 响应代码 来标识请求结果的正确与错误信息。
  • 所有的 OpenAPI 请求都会以规范友好的 JSON 对象格式返回(包括错误信息),并且使用「访问令牌」Personal Access Token 作为鉴权方法。
  • 所有请求和响应的编码均为 UTF-8。

3.2 调用地址

基础地址(Base URL)为: https://api.pro.surongyun.cn/ 地址如果有更新,会第一时间进行通知到您。

3.3 鉴权方法

  • 「访问令牌」Personal Access Token 类似某些系统中的应用专用密码。生成后可根据设置的权限访问特定的 OpenAPI。
  • 通过 HTTP Headers 设置 Authorization 的值为 “Bearer YOUR_APIKEY” 来进行安全性验证,
curl --location --request POST 'https://api.pro.surongyun.cn/openapi/form/smart/5fe702563595c000066c5d72/create' \ --header 'authorization: Bearer jK1ocYAQDI6n38eVbX6JGsNRtgkRHlOW' \ --header 'Content-Type: application/json' \

4. 错误对照表

所有API使用 状态码+错误码 的响应方式来表示错误原因。接口正确统一返回HTTP状态码为 2xx 的正确响应。接口错误统一返回HTTP状态码为 400 的错误响应,同时响应内容会返回错误码(code)和错误信息(message)。具体请在各数据中展示。

5.频率限制

  • 根据不同的付费等级,我们所允许的接口访问频率(QPS)不一样。具体可在 团队管理–> 使用概览中进行查看。

  • 接口频率限制基本按照,每分钟最大的请求数来实现。

6.申请Access Token

1. 前置条件

创建者或者超级管理员,其余人无法申请管理。

2.设置路径

1.点击团队管理,开发者选项

2.点击创建 同时设置相关的配置信息,保存即可。

注意:

  • 1.AccessToken如果不慎泄露,您可以重新生成。
  • 2.如果您设置了白名单 IP,其余 IP 的请求都将返回错误。
  • 3.授权范围:如果 token 的授权范围没有相关权限,平台将会返回错误,错误码见说明。

7. 优雅的调试

为了更好的与第三方对接,我们提供了 API 记录日志的功能。可以非常方便的查看到自己的请求参数和系统返回参数。

1.查看方式:

团队设置–》 API日志查看

2.根据类别进行查看

不同模块可以在相应的tab 中进行查看

  • 智能 API 可查看, 用户、流程、表单智能 api 日志。
  • webhook 为流程或者智能工作流的日志
  • 智能连接:智能连接控件产生的相关支持。
  • 注意:请求记录只保存7天或者2000条。

3.查看具体一条请求日志

1.定位到日志行

2.点击查看详情。这里支持查看,Request 和 Reponse 所有信息。

3.方便查看 请求头部 请求数据体 等信息。

8.安全性

  1. 所有请求都采用高安全性的 HTTPS 请求,避免中间人攻击。 HTTP 请求会被自动升级为HTTPS 或者是拒绝请求。
  2. 每次请求都对 Token 进行验证,系统确保 Token 是否合法。同时确保 Token 仅能访问所所设置的资源权限。
  3. 开放平台可以开启 IP 白名单,如果不在 IP 白名单内,将拒绝提供服务。