调用限制

使用 ServiceGo 开放接口，需要遵循以下规则：

概述

一般原则

HTTP 请求方式

ServiceGo服务尽量坚持尽可能接近标准HTTP和REST

请求方式 用法
GET 取回资源
POST 创建一个新的资源或查询一个资源
PUT 更新一个存在的资源
DELETE 删除一个存在的资源

分页

ServiceGo服务需要分页返回的对象会符合以下报文格式

属性名 类型 说明
paging 对象 分页对象
paging.pageNum 整型 页码
paging.pageSize 整型 页码大小
paging.total 整型 总数

HTTP 状态码

ServiceGo服务尽量坚持尽可能接近标准HTTP和REST

状态码 说明
200 OK HTTP请求成功的标准响应。实际的响应将取决于请求的方法。在GET请求，响应将包含对应于请求的资源实体。在POST请求，响应将包含一个实体的说明或包含的行动的结果。
201 Created 该请求已完成，并创建一个新的资源。
204 No Content 服务器成功处理了请求，但未返回任何内容。
400 Bad Request 由于客户端错误（例如，错误的请求语法，无效的请求消息帧，或欺骗性请求路由），服务器不能或不会处理请求。
401 Unauthorized 未认证。
404 Not Found 找不到请求的资源，但将来可能再次可用。客户的后续请求是允许的。
500 Internal Server Error 服务器内部错误。

调用地址

格式

https://servicego.udesk.cn/api/v1/[接口相对地址]?[URL参数]&email=[管理员邮箱]&timestamp=[时间戳]&sign=[签名]

其中括号包含的部分含义如下:

变量 说明
接口相对地址 API的相对URL，每个API中都会单独标明
URL参数 请求地址中参数，多个时使用&分隔
管理员邮箱 您的超级管理员邮箱
时间戳 发起请求时的时间戳，'1970-01-01 00:00:00'至今的秒数。如无特别说明，默认过期时间五分钟
签名 身份认证签名，除非特别说明，否则每次API请求均需要附加此参数，详细生成算法请查阅鉴权方法

参数

三种参数类型:

类型 说明
嵌入URL中 作为请求URL的一部分，如/contacts/:id中的:id
URL param 请求接口时的参数，如/contacts?page=10中的page
Request Body 请求体

返回

UTF-8编码的JSON字符串

鉴权方法（适用2021年6月3日之前的租户）

公式

sign=SHA1(email&api_token&timestamp)

其中:

示例

https://servicego.udesk.cn/api/v1/contacts

鉴权所需数据:

名称 值
email admin@udesk.cn
api_token 221b368d7f5f597867f525971f28ff75
timestamp 1496631984

计算签名:

sha1("email@udesk.cn&221b368d7f5f597867f525971f28ff75&1496631984") -> a32be53bb42314850715f8b9ab92542f5ed54c5e

请求URL:

https://servicego.udesk.cn/api/v1/contacts?email=admin@udesk.cn&timestamp=1496631984&sign=a32be53bb42314850715f8b9ab92542f5ed54c5e

新鉴权方法（适用2021年6月3日之后的租户）

公式

sign=SHA256(email&api_token&timestamp)

其中:

示例

https://servicego.udesk.cn/api/v1/contacts

鉴权所需数据:

名称 值
email admin@udesk.cn
api_token 221b368d7f5f597867f525971f28ff75
timestamp 1496631984

计算签名:

sha256("email@udesk.cn&221b368d7f5f597867f525971f28ff75&1496631984") -> d0eb64920d4cee192427ea43acfdb00cdc56acb79a2012bb96a1c5d5fa1df36f

请求URL:

https://servicego.udesk.cn/api/v1/contacts?email=admin@udesk.cn&timestamp=1496631984&sign=d0eb64920d4cee192427ea43acfdb00cdc56acb79a2012bb96a1c5d5fa1df36f