1.1. 概述

1.1.1. 调用地址

  • S1请求格式
    https://crm.udesk.cn/api/v1/{relative address}?{URL params}&email={administrator email}&timestamp={timestamp}&sign={signature}
  • S4请求格式
    https://crm.s4.udesk.cn/api/v1/{relative address}?{URL params}&email={administrator email}&timestamp={timestamp}&sign={signature}

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

变量 说明
域名地址 需要区分是S1/S4，见上面的请求格式
relative address: 接口相对地址 API的相对URL
URL params: URL参数 请求接口所需参数
administrator email: 管理员邮箱 超级管理员邮箱
timestamp: 时间戳 发起请求时的时间戳，'1970-01-01 00:00:00'至今的秒数。如无特别说明，默认过期时间五分钟
signature: 签名 身份认证签名，除非特别说明，否则每次API请求均需要附加此参数，详细生成算法请查阅鉴权方法

  • 参数

    三种参数类型

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

  • 返回

    UTF-8编码JSON字符串

1.1.2. 鉴权方法

  • 公式
sign=SHA1(email&api_token&timestamp)

其中:
 email: 管理员邮箱地址
 api_token: 鉴权私钥，在crm系统`管理设置 - 系统设置 - 基本设置 - 秘钥`查看
 timestamp: 时间戳，'1970-01-01 00:00:00'至今的秒数
  • 示例
https://crm.udesk.cn/api/v1/leads

鉴权所需数据：

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

计算签名:

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

请求URL:

https://crm.udesk.cn/api/v1/leads?email=email@udesk.cn&timestamp=1496631984&sign=a32be53bb42314850715f8b9ab92542f5ed54c5e

1.1.3. 一般原则

HTTP 请求方式

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

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

分页

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

参数 类型 是否可空 描述
paging Object true 分页对象
paging.pageNum Integer true 页码
paging.pageSize Integer true 页码大小
paging.total Integer true 总数

HTTP 状态码

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

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

results matching ""

    No results matching ""