## 一、开通接口 需先从卡平台获得接口交互的appId和appSecret； api服务地址：http://ip:port/oauth/service， >[danger] > 1、api服务地址+api的url组合，构成了客户端api请求的完整地址； > 2、比如平台内置提供了一个用于测试验证的api，其url是/test/validation，那么实际完整的请求地址应当为：http://ip:port/oauth/service/test/validation > 3、开户的过程参考：[https://www.kancloud.cn/fang2099/erp-scm-mes-hr-oa/1589749](https://www.kancloud.cn/fang2099/erp-scm-mes-hr-oa/1589749) ## 二、技术要求 1.所有接口的请求，采用httpPost方式提交，发出http请求的时候，请求content-type需设定为：application/x-www-form-urlencoded;charset=UTF-8 ，参数按照普通表单参数传值，不必包裹成一个json字符串； 2.所有接口的响应，采用json格式，编码为UTF-8，响应的content-type为：application/json;charset=UTF-8）； 3.提供ip白名单功能，仅供授权的ip调用； 4.每个对外提供服务的api，都必须包含的参数为appId及timeStamp，为了确保不被外部不法分子恶意篡改请求，请求参数中绝对不能包含appSecret； 5.每个对外提供服务的api，都必须包含一个sign参数，该参数是通过算法计算出来的值，具体算法参考后续签名算法章节； 6.考虑服务器承载量，目前限制每个ip访问接口频率不得超过1秒10次，超过这个次数，该ip将会被禁止调用，程序中不得做高频率轮询； 7.接口服务自身的设计与开发是基于BASE理论。因此，也强烈建议代码编写者遵循该理论；程序开发者必需考虑接口服务器因机房网络故障、域名解析故障、例行检修、程序升级、依赖服务中断等因素导致当前服务不可用。因此，业务逻辑的编写必须严格的核对响应码，并且必须编写消费接口服务的异常分支逻辑； >[danger] 只有responseCode为1，才能说明这个api执行成功了，否则，都是失败，只是失败原因各不相同； ## 三、时间戳格式 1.获取从1970, 00:00:00开始到当前的毫秒数(13位) 2.每个api请求的有效时间为3分钟,所以,务必确保当前服务请求的时间是准确的； ## 四、签名算法 假设：paramstrings = 当前api的所有参数(除sign外)，根据参数名升序排序，以“参数名=值&”的方式连接起来； 结果：sign = md5(md5(paramstrings)+appSecret) >[danger] 注意：是双层md5加密，中间那个"+"仅表示两段字符相连,并不包括该符号本身； ## 五、接口限流 对外服务的每个API接口当访问频率或者并发量超过其承受范围时候,我们就必须考虑限流来保证接口的可用性或者降级可用性.以防止非预期的请求对系统压力过大而引起的系统瘫痪； ### 算法 平台采用令牌桶算法进行限流，针对每个appId（客户端），都限制其每秒钟可以接收的请求数，确保整个对外服务正常有序； 令牌桶算法的原理是系统会以一个恒定的速度往桶里放入令牌，而如果请求需要被处理，则需要先从桶里获取一个令牌，当桶里没有令牌可取时，则拒绝服务；  ### 设置 系统参数配置中，可以设定每个appId每秒请求数限制：  ### 注意 >[danger]正常的访问平台是通过接口限流策略，实现了业务可用性保障；对应非正常的访问，平台则通过DDOS防御设施，实现业务可用性保障； ## 六、例程 为了方便客户端编程，这里提供了一个完整的客户端调用api示范，基于java代码编写，您可以直接复制过去，修改参数运行；您可以向我们索取代码； 具体接口，请参考下面的章节；