概述

平台 API 采用 RESTful 风格设计。所有接口请求地址都是可预期的以及面向资源的。使用规范的 HTTP 响应代码来表示请求结果的正确或错误信息。使用 HTTP 内置的特性，如 HTTP Authentication 和 HTTP 请求方法让接口易于理解。所有的 API 请求都会以规范友好的 JSON 对象格式返回（包括错误信息）

基本概念

1、企业/客户：跟我们平台有合作的企业客户，目前开放平台只面向企业开放。

2、服务商：服务商是平台落地的园区服务公司，平台上有多服务商，很多企业可能会跟多家服务商有合作，在接口中通过providerId参数来区分不同的服务商。

3、人员/个人/自由职业者：承接具体业务的个人，一般指业务推广个人、网红、主播等自由职业工作个人。

4、项目：企业、个人、服务商三者会基于具体的某一个合作内容来进行业务的分包、转包，具体的合作内容、业务在平台定义为项目。

5、业务签约：由于业务模型原因，个人需要与服务商在线签署电子协议，个人与服务商在线签署协议的过程叫业务签约。

认证

调用凭据：平台 API使用accessToken为接口调用凭据,来调用接口，所有接口的调用需要先获取accessToken，accessToken在2小时内有效，过期需要重新获取，但1天内获取次数有限，开发者需自行存储，详见获取accessToken章节。

身份标识：获取 accessToken 需要 appKey 和appSecret。appKey 和appSecret 是企业在API中的身份标识，请安全存储，确保其不要被泄露。

令牌使用：在发起HTTPS请求头(Https Headers)中添加 JWT Access_token (注意accessToken前面有常量 Bearer和空格)：

安全签名

API接口在访问的过程中需要使用签名算法来保障API交互过程中的参数安全未被篡改，详见安全规范章节。

协议规则

企业客户接入API，调用API必须遵循以下规则：

标题	说明
传输方式	为保证交易安全性，采用HTTPS传输
提交方式	采用POST或GET方法提交
数据格式	提交和返回数据都为JSON格式
字符编码	统一采用UTF-8字符编码
签名算法	统一采用HMAC-SHA256签名方式
签名要求	请求与接收需要校验签名，详细方法请参考安全规范-签名算法
证书要求	调用申请退款、撤销订单接口需要企业证书

环境

版本：v1.1\ 正式：https://openapi.zkysass.com

所有的 API 请求必须通过 HTTPS 发送，使用 HTTP 会被 API服务器拒绝。

示例

java代码示例：https://github.com/carryliuz/open-demo-java\ postman请求示例：openapi.gzlle.com-v1.1.postman_collection

错误

API 使用 HTTP 状态码 (status code) 来表明一个 API 请求的成功或失败状态。返回 HTTP 2XX 表明 API 请求成功。返回 HTTP 4XX 表明在请求 API 时提供了错误信息，例如参数缺失、参数错误、支付渠道错误等。返回 HTTP 5XX 表明 API 请求时， API 服务器发生了错误。

状态码	描述
200-OK	一切正常
400-BadRequest	错误的请求，一般由参数错误引发
401-Unauthorized	请求需要授权
402-Failed	失败的操作，参数正确但业务逻辑错误
403-Forbidden	禁止访问，权限不够等引发
404-NotFound	未找到目标对象
408-RequestTimeout	请求超时
409-Conflict	指令冲突，主键冲突,目标已经存在
480-ExpiredVersion	版本过期，程序过期，API过期
481-ExistUndo	存在未处理的事项

概述

概述#

概述