1. V2接口通用说明
1.1.1. 调用限制
访问 微丰 开放接口（v2），需要遵循以下规则：
- 所有API都是为服务器端调用设计，请不要在客户端（Web前端页面、手机应用等调用），否则可能会存在鉴权泄漏的风险。
- 常规API默认的频次限制为 60次/分钟，所以任何API在1分钟内最多可调用60次。
- 统计分析类API由于涉及计算量较大，仅支持单线程串行调用，请勿并发调用。
1.1.2. 调用格式
HTTP方法
微丰开放接口（v2）可能会使用到以下HTTP方法：
- GET：用于获取数据的接口
- POST：用于创建接口
- PUT：用于修改接口
- DELETE：用于删除接口
我们会在每个接口的文档中注明所使用的 HTTP 方法，调用接口时请以具体的接口文档为准。
调用地址
微丰开放接口的调用地址都符合以下格式之一：
https://[saas子域名].wefeng360.com/api/v2/[接口相对地址]?[URL参数]×tamp=[时间戳]&sign=[签名]
OR
https://[个性化域名+前缀]/api/v2/[接口相对地址]?[URL参数]×tamp=[时间戳]&sign=[签名]
其中被中括号包含部分的含义如下：
| 变量 | 说明 |
|---|---|
| saas子域名 | 您访问微丰系统被分配的专属二级域名 |
| 个性化域名+前缀 | 您访问微丰私有化系统的个性化二级域名和前缀 |
| 接口相对地址 | 您调用的具体API的相对URL，会在每个API中注明 |
| URL参数 | 接口所需的Query String参数 |
| 时间戳 | 发起请求时的时间戳，格式为Unix Time，即从“1970-01-01 00:00:00”至今的秒数 |
| 签名 | 身份验证签名，除非明确说明，否则每次API调用都需要携带，计算方法参见下文 [鉴权方法] |
每个接口文档中都会给出类似以下的调用方法： GET /customers 其中包含了 HTTP 方法及接口相对地址，其他部分则需要根据具体情况替换。
参数
接口文档中可能会出现以下三种参数类型：
- URL 中：嵌入在调用地址中的参数，如
/customers/:id中的:id； - Query String：调用地址 Query String 部分的参数，如
/customers?page=2中的page； - Request Body：请求体中的内容。 当调用创建、修改类接口时，需要将请求数据按照 JSON 格式转换为 UTF-8 文本，将编码后的字符串作为 Request Body 类参数传给对应的接口。 同时将请求头中的 Content-Type 字段设置为 application/json 。
返回结果
- 微丰开放接口（v2）的返回数据同样为JSON格式格式编码的 UTF-8 字符串。
- 微丰开放接口在Response的header中会返回X-Request-Id标识一次唯一请求，如需微丰工程师协助定位接口调用疑问，请务必提供Response中的X-Request-Id。
1.1.3. 鉴权方法
规则说明
所有接口调用需要携带签名参数 sign，只有当 sign 值合法时请求才会被接受。 sign 的计算方法如下：
sign=SHA256(secretKey×tamp)
其中：
- secretKey 为租户秘钥，在微丰系统后台系统对接处获取；
- timestamp 为Unix time，即从“1970-01-01 00:00:00”至今的秒数。
- 注：timestamp有效期为10分钟
示例
假设要调用以下接口：
https://[调用域名]/api/v2/external_contact/:externalUserId
鉴权所需数据如下：
| 名称 | 数据 |
|---|---|
| secretKey | 5480583a6494445897pa3s1241 |
| timestamp | 1619143576 |
计算sign：
sha256("5480583a6494445897pa3s1241&1619143576")
27aa4b58a5eff9d006c974d62a4b0837e1be1cc90e5a3578aeadbe61d4914220
最终请求URL：
https://[调用域名]/api/v2/external_contact/wm_3b_XXXXXX?sign=fbdd2e45e3bd9d1f1e4915863cff62c2d6f901490070741b821ad55d7e231552×tamp=1619143576