1.API 使用

马克对外开放平台通过Http协议对外提供数据开放服务，支持Get、Post两种方式调用接口。通过签名的方式来进行接口调用权限校验，签名生成方式及签名key的申请方式见下述。

header设置

在header中有部分公共参数需要添加,目前有4个公共参数需要在请求时添加在header中

key	value	description	是否必须
sign	f5c864500f223c7c8d02377a02a5131a	签名	是
orgId	12345	组织id	是
timestamp	1635160057	接口调用的时间戳(单位s),必须填写在header中,与到达服务器的时间差超过10s会直接返回错误	是
traceId	a1635160057	跟踪id，方便后续日志查询	否

API Key配置

API key获取方式

1.api key针对组织粒度,每一个组织需要组织的主管理员申请一个对应的key进行使用

2.申请api key地址 (opens new window)

API key如何使用

使用api key采用对应的生成规则生成sign，将sign附带到请求接口的header中，服务器在收到请求后， 使用相同的方式生成签名，并与请求中附带的签名进行比对，当一致时即为校验通过，反之则拒绝。

GET方法签名计算

通过下面的例子进行讲解(获取团队的成员列表接口)

    https://open-api.markiapp.com/marki/moment?teamId=123&start=2020-01-20 00:00:00&end=2020-10-20 00:00:00
    header中的信息:
    sign:f5c864500f223c7c8d02377a02a5131a
    orgId:12345
    timestamp:1635160057
    traceId:a1635160057

1.GET请求中用于签名计算的有参数--'teamId=123&start=2020-01-20 00:00:00&end=2020-10-20 00:00:00'、 header中的'orgId'、'timestamp'、'traceId'以及申请的api key

2.首先对参数进行排序：按'k=v'升序（本例结果为end、start、teamId）：

    end=2020-10-20 00:00:00&start=2020-01-20 00:00:00&teamId=123

3.签名计算

orgId=$orgId&key=$key&timestamp=$timestamp&traceId=$traceId&data=$param 进行拼接，并计算拼接后字符串md5值，即为签名(sign)： 要求：请求参数必须是未进行任何编码（如urlencode）的原始数据

    md5(orgId=12345&key=key123&timestamp=1635160057&traceId=a1635160057&data=end=2020-10-20 00:00:00&start=2020-01-20 00:00:00&teamId=123)

最后生成的结果为f5c864500f223c7c8d02377a02a5131a

POST方法签名计算

通过下面的例子进行讲解(获取团队的成员列表接口)

// POST请求地址
        https://open-api.markiapp.com/marki/moment 
        请求头：
        content-type:application/json
        sign:3d98774688237fb831d16ba13ac5341c
        orgId:12345
        timestamp:1635160057
        traceId:a1635160057       
         
        //Post方法提交数据
        {"teamId":123,"start":"2020-01-20 00:00:00","end":"2020-10-20 00:00:00"}

1.POST请求中用于签名计算的有参数--整个json字符串、header中的'orgId'、'timestamp'、'traceId'以及申请的api key

2.签名计算

orgId=$orgId&key=$key&timestamp=$timestamp&traceId=$traceId&data=$jsonBody进行拼接，并计算拼接后字符串md5值，即为签名(sign)：

    md5(orgId=12345&key=key123&timestamp=1635160057&traceId=a1635160057&data={"teamId":123,"start":"2020-01-20 00:00:00","end":"2020-10-20 00:00:00"})

最后生成的结果为3d98774688237fb831d16ba13ac5341c

响应参数说明

响应参数组成部分

响应参数主体由四个部分组成分别是code、msg、traceId、data

名称	含义	类型
code	响应结果状态值,成功返回0, 其他值请查看下方响应状态码	int
msg	返回错误信息	string
traceId	日志追踪id(header中有则返回 原有的,否则返回新生成的)	string
data	返回结果信息	可以是任意类型(简单数据结构或者object)

响应状态码说明

响应状态码	说明
0	正常
-4	内部错误
-109	输入不合法
404	请求不存在
601	签名校验失败
602	body解析失败
603	header中orgId或者sign不合法
604	header中时间戳不合法
605	key不存在
606	超过请求次数
701	内部错误