openApi 概述

14751 上次更新时间：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 白名单内，将拒绝提供服务。

以上内容是否对你有帮助？