应用程序编程接口（Application Programming Interface，API接口），是应用程序重要的组成部分，就是应用程序对外提供了一个操作数据的入口，这个入口可以是一个函数或类方法，也可以是一个url地址或者一个网络地址。当客户端调用这个入口，应用程序则会执行对应代码操作，给客户端完成相对应的功能。

通过苍穹OpenAPI进行接口开发，从设计API阶段开始，需要进行优雅的设计，帮助API使用者更好地了解、使用和集成，同时可以有效地维护它，才能让我们在集成项目中事半功倍。本篇文档作为API开发指导手册，包含四部分规范：API配置规范、API调用规范、API错误码规范和API安全规范。

苍穹平台OpenAPI开发规范.pdf

1. API配置规范

部署OpenAPI时其传输协议应选择 HTTPS 协议，以确保传输数据的安全性。 默认报文格式为JSON，报文格式由具体服务接口定义。

1.1 请求URL

开放平台注册的接口地址为URI，拼接域名/kapi 组成完整请求地址，如：https://feature.kingdee.com:1026/dev/kapi/v2/kdtest/pm/pm_purorderbill/save。

1.2 请求方式

调用接口的请求方式主要有GET和POST。

• GET请求主要用于向指定的资源发出“显示"请求。使用GET方法应该只用在获取数据，但是传递的参数则显示在地址栏，安全性低，且参数的长度也有限制（2048字符）；

• POST请求则用于向指定资源提交数据，请求服务器进行处理例如保存单据或基础资料。这个请求可能会创建新的资源或修改现有资源，或二者皆有。将传递的参数放在request body中，不会在地址栏显示，安全性比get请求高，参数没有长度限制。

1.3 整体规范

同时为保证API兼容性，接口维护时还有以下注意事项：

1) API一旦发布，新版本必须保证向下兼容。业务逻辑的变动，不应影响接口的调用，以避免引发生产事故。

2) API出入参名、类型在新版本中不得更改，不可删除。如果要变更参数类型 或 新增必填参数时应当创建一个新版本的API。如在API编码上增加版本标识如：save/ver2。

3) 所有二开的API接口，建议打开第三方应用授权开关；查询操作API，建议打开启用查询权限控制开关

4) API升级如果需要增加入参，必须设置默认值，否则无法做到向下兼容性。

5) API校验逻辑必须写在操作插件中，不可以写在页面插件中。API引擎不会执行页面插件逻辑。

6) 每个接口应开发配套的自动化单元测试用例。

2. API调用规范

在客户端调用API接口过程中常见的有高频调用、大批量数据和幂等性问题，其中大批量数据保存，由于一次查询或保存的数据量太大，很可能会造成接口超时问题。

幂等性是指任意多次请求的执行结果和一次请求的执行结果所产生的影响相同。查询操作无论查询多少次都不会影响数据本身，因此查询操作本身就是幂等的。但是新增操作，每执行一次数据库就会发生变化，所以它是非幂等的。

在实际的项目上，如果出现高并发或网络异常的情况，例如Nginx在网络异常时会重复转发请求，可能会生成重复生成数据或多次提交请求的。比如订单创建时，我们需要去减库存，这时接口发生了超时，调用方进行了重试，很可能就出现多扣一次库存的情况。

因此为保证接口可靠性和稳定性，客户端在调用时应遵守相关规范。

3. API错误码规范

业务插件和规则校验器均应抛出具体错误代码，平台标准错误码从 0 到999，业务各领域异常应遵循错误码编码规范，前缀为应用编码，方便快速定位接口问题，保证用户统一的API使用体验。

4. API安全规范

4.1 认证鉴权

开放平台OpenAPI认证鉴权主要是通过token认证实现的，其中获取token一般会涉及到几个参数：appId，appSecret，accountId和user，通过以上几个参数来获取调用接口的凭证。

appId和appSecret通过开放平台第三方应用申请。appId全局唯一的，每个appId将对应一个外部系统，appSecret需要客户端高度保密。

token作为系统调用的唯一凭证，可以通过MC参数apptoken.timeout来设置token的时效性。token推荐加到请求头上，这样可以跟业务参数完全区分开来。

注意：accessToken客户端应做缓存（默认2小时有效），每小时重新获取token的次数不应超过100次。

建议外部系统统一通过第三方应用获取token的方式调用API，这样能够充分保证API接口的安全性。

详见：OpenAPI认证指南

4.2 IP白名单

IP白名单是指将接口的访问权限对指定IP进行开放，这样就能避免其他非法IP进行访问。设置IP白名单的方式很多，除了传统的防火墙和网关之外，还可以在开放平台的第三方应用中，为外部系统访问设置IP白名单，提升系统整体安全性。

详见：第三方应用

4.3 限流策略

限流是为了更好的维护系统稳定性，在高并发时，避免瞬间高峰接口压垮系统服务。

开放平台支持配置限流策略，按第三方应用和API维度维护单位时间内的访问次数上限，高频的接口调用系统会自动拒绝。 例如可限制某客户端每秒最多30次请求。

详见：限流策略

4.4 接口防篡改

API参数篡改就是恶意人通过抓包的方式获取到请求的接口的参数，通过修改相关的参数，达到欺骗服务器的目的，常用的防止篡改的方式是用签名以及加密的方式。

苍穹开放平台签名认证是目前第三方系统和金蝶云苍穹安全性最高的认证方式，采用双向签名认证+加密/解密的模式，解决了第三方系统和金蝶云苍穹安全高效的接口交互，支持接口参数防篡改，数据完整性和隐私安全性，可支持金融交易，海关等高安全性应用场景。

详见：OpenAPI认证指南

4.5 数据加密与脱敏

在接口调用过程中有些敏感参数（如登录密码、支付密码）通常需要加密处理等，而最后响应结果中若包含用户手机号、用户邮箱、身份证号等信息，则需要进行脱敏处理。通过开放平台第三方应用加密策略和隐私中心，可对敏感信息进行加密和脱敏，保证API数据安全。

详见：API数据脱敏

5. 更多资讯

    金蝶云苍穹开放平台OpenAPI调用流程

    金蝶云苍穹开放平台OpenAPI开发认证指南