1. V1接口通用说明

1.1.1. 调用限制

访问 微丰 开放接口（v1），需要遵循以下规则：

• 所有API都是为服务器端调用设计，请不要在客户端（Web前端页面、手机应用等调用），否则可能会存在鉴权泄漏的风险。
• 常规API默认的频次限制为 60次/分钟，所以任何API在1分钟内最多可调用60次。
• 统计分析类API由于涉及计算量较大，仅支持单线程串行调用，禁止并发调用。

1.1.2. 调用格式

HTTP方法

微丰开放接口（v1）可能会使用到以下HTTP方法：

• GET：用于获取数据的接口
• POST：用于创建接口
• PUT：用于修改接口
• DELETE：用于删除接口

我们会在每个接口的文档中注明所使用的 HTTP 方法，调用接口时请以具体的接口文档为准。

调用地址

微丰开放接口的调用地址都符合以下格式之一：

https://[saas子域名].wefeng360.com/api/v1/[接口相对地址]?[URL参数]&timestamp=[时间戳]&sign=[签名]
OR
https://[个性化域名+前缀]/api/v1/[接口相对地址]?[URL参数]&timestamp=[时间戳]&sign=[签名]

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

每个接口文档中都会给出类似以下的调用方法： 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 。

返回结果

• 微丰开放接口（v1）的返回数据同样为JSON格式格式编码的 UTF-8 字符串。
• 微丰开放接口在Response的header中会返回X-Request-Id标识一次唯一请求，如需微丰工程师协助定位接口调用疑问，请务必提供Response中的X-Request-Id。

1.1.3. 鉴权方法

规则说明

所有接口调用需要携带签名参数 sign，只有当 sign 值合法时请求才会被接受。 sign 的计算方法如下：

sign=SHA256(secretKey&timestamp)

其中：

• secretKey 为租户秘钥，在微丰系统后台系统对接处获取；
• timestamp 为Unix time，即从“1970-01-01 00:00:00”至今的秒数。
• 注：timestamp有效期为10分钟

示例

假设要调用以下接口：

https://[调用域名]/api/v1/external_contact/:externalUserId

鉴权所需数据如下：

计算sign：

sha256("5480583a6494445897pa3s1241&1619143576")

27aa4b58a5eff9d006c974d62a4b0837e1be1cc90e5a3578aeadbe61d4914220

​

最终请求URL：

https://[调用域名]/api/v1/external_contact/wm_3b_XXXXXX?sign=fbdd2e45e3bd9d1f1e4915863cff62c2d6f901490070741b821ad55d7e231552&timestamp=1619143576

python3示例

from hashlib import sha256
import time

if __name__ == '__main__':
    secrekey = "5480583a6494445897pa3s1241"
    timestamp = str(int(time.time()))
    key = str(secrekey + '&' + timestamp)
    sign = sha256(key.encode("utf-8")).hexdigest()
    print(sign)

java示例

public class SignUtil {


  public static String createSign(String timestamp, String appKey) {
    String signStr = appKey + "&" + timestamp;
    return createSignWithStr(signStr);
  }

  public static String createSignWithStr(String signStr) {
    String sign = null;
    MessageDigest instance;
    try {
      instance = MessageDigest.getInstance("SHA-256");
      instance.update(signStr.getBytes());
      sign = byte2Hex(instance.digest());
    } catch (Exception e) {
      log.error("生成接口签名失败!", e);
    }
    return sign;
  }

  /**
   * 将byte转为16进制
   *
   * @param bytes
   * @return
   */
  private static String byte2Hex(byte[] bytes) {
    StringBuffer stringBuffer = new StringBuffer();
    String temp = null;
    for (int i = 0; i < bytes.length; i++) {
      temp = Integer.toHexString(bytes[i] & 0xFF);
      if (temp.length() == 1) {
        //1得到一位的进行补0操作
        stringBuffer.append("0");
      }
      stringBuffer.append(temp);
    }
    return stringBuffer.toString();
  }

}