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

本文档适用于外部系统与金蝶云苍穹间的系统集成场景。当外部系统调用金蝶云苍穹OpenAPI时，金蝶云苍穹会对每个API进行身份鉴权，判断其请求合法性，最后响应API请求。

2 认证方式

路径：【开放服务云】→【OpenAPI】→【第三方应用】，在第三方应用中为外部系统选择合适的认证方式。

金蝶云苍穹OpenAPI共支持五种认证方式，分别是：

• AccessToken 认证

• JWT认证

• 摘要认证

• 基本认证

• 签名认证

其中，AccessToken认证应用最广泛，基本认证则最方便。从安全和易用性的角度进行分析，不同的认证方式各有特点，用户可以根据具体需求，选择合适的认证方式。

2.1 AccessToken认证/JWT认证

功能描述

    Token（令牌）是第三方应用调用OpenAPI的身份凭证，每次请求时，客户端都需要通过请求头发送token，服务端以此来控制身份，当token过期后，服务端会销毁token，客户端需要重新请求才能获得token。

    JWT(全称是JSON WEB TOKEN)是一种用于双方之间传递安全信息表述性声明规范，和access_token一样，都是访问资源的令牌。access_token需要查库验证access_token是否有效，而JWT不用查库，直接在服务端进行校验，用户可按需选择。

• 请求 URL：http://{{localhost}}/kapi/oauth2/getToken

• 调用方式：HTTP调用

• 请求方式：POST

• 请求类型：Content-Type:application/json

• 调用频率：1分钟30次

• token有效期：2小时

时序图：

注意事项：

• 令牌的获取是有限制的，每个令牌的有效期为 2 小时，用户需要做好令牌的管理，在令牌快过期时，重新调用接口获取请求令牌或调用刷新令牌接口，延长请求令牌的有效期。

• 获取Token请求，同时支持在Header和Body中传输数据中心accountId。

• 获取access_token前需注册第三方应用，详见第三方应用介绍、金蝶云苍穹OpenAPI增强型Token认证。

• 若金蝶云苍穹版本低于V6.0，获取token参考API认证方式-AccessToken认证/JWT认证。

请求Body参数

请求参数示例

{
    "client_id": "thirdappunittest_003",
    "client_secret": "Abcdrty@1234567890#@2",
    "username":"zhangSan",
    "accountId": "1355633519610561531",
    "language": "zh_CN",
    "nonce": "123",
    "timestamp": "2023-09-08 11:47:00"
}

返回参数

返回参数示例

{
"data": {
    "access_token":"OPENAPIAUTH_MTMzMTIwNDQ0NTk5NTc5NDQzMl9FZ3h4MXU1Zzd2Qk9kRjR4MzIxQXZKcXU5c2hpbzNCaTRtTGIzbEsyM3JnbmFJUUJEMEltZUt3UURYQmFFdDJIVnc3MWtyaTVUR01ZbTRDUGVETDVSamE2R0F1a2g5SGpVcmwx",
    "token_type": "Bearer",
    "refresh_token": "d367106c-de46-4fc4-9e1a-59cbcfc430d2",
    "scope": "API",
    "expires_in": "7199977",
    "id_token": "OPE1MGFXMWxJam9pTWpBeU15MHdPQzB5T1NBd01Eb3dNRG93TUM0d0lpd2labVZ1WVdKc1pTSTZJakVpTENKbWRXbGtJam9pTVRNME5qWTNNemtpTENKMWMyVnlWSGx3WlNJNklqRWlMQ0psZUhBaU9qRTJPVFEyTURReU1UZ3NJbWxoZENJNk1UFYTjBaV1FpT2lJeElpd2labkJ6ZDNOMGNtRjBaV2Q1YVdRaU9pSTNOakk1TnpjM09UVTNOekl3TURVek56WWlMQ0oxYzJWeWIzQmxibWxrSWpvaU5XRXlaR1ZtWTJKbE5HSXdPVFUzWm1Fd09HWTRZemN5SWl3aWRYTmxjbTVoYldVaU9pSkpSVkpRSW4wLi1ZZEd1cWhIX25Mcm5ibURnQTlfU2FvQkZsTGJWTTJEUmp2cnR4NXZwckk=",
    "id_token_expires_in": "7199977",
    "language": "zh_CN"
        },
    "errorCode": "0",
    "message": "",
    "status": true
}

错误码说明

通过getToken接口获取的JWT，也可用于调用OpenAPI服务，接口示例如下：

请求头参数

URL：http://{{localhost}}/kapi/v2/kdtest/basedata/bd_supplier/save


请求Header参数：
Content-Type=application/json
client_id={第三方应用编码}
accountId={数据中心Id}
JWT={上面获取的id_token}


请求Body参数：

{
    "data":[
        {
            "number":"Sup-001012",
            "name":"金蝶瑞杰汽车有限公司",
            "createorg_number":"00"
                }
           ]
}

请求结果：
{
    "data": {
        "failCount": "0",
        "result": [
            {
                "billIndex": 0,
                "billStatus": true,
                "errors": [],
                "id": "1698490236113273856",
                "keys": {
                    "number": "Sup-001012"
                },
                "number": "Sup-001012",
                "type": "Update"
            }
        ],
        "successCount": "1"
    },
    "errorCode": "0",
    "message": null,
    "status": true
}

2.2 摘要认证

摘要认证使用摘要代替token的传输，并采用MD5、SHA等不可逆哈希算法对参数摘要。首先，客户端通过指定的加密算法将随机数、时间戳等信息生成摘要。然后，调用请求时，将摘要放在请求头中发送给服务器；最后，服务器拿到摘要后，使用同样的算法和数据库密钥进行摘要并对比，匹配则身份验证通过。

金蝶云苍穹摘要认证流程：

  1. 生成第三方appId和第三方app的摘要认证加密秘钥；

  2. API调用过程中加入验证信息。

摘要签名可以通过java工具类指定默认算法（如sha-256）直接生成签名。

• POST方式请求的API，验证内容都在请求体中；

• GET方式请求的API，验证内容都在url的参数中。

生成摘要后，后续只需要在请求的参数中带上签名信息就可以完成API调用。摘要认证详细方法和demo见附件。

请求示例（GET）

URL：http://{{localhost}}/kapi/v2/kdtest/basedata/bd_supplier/getNumber?name=Kingdeecar&pageSize=10&pageNo=1&appId=TEST&timestamp=2021-08-18 14:19:08&signatureNonce=iksiertoidkwek;oitdwudysletwsuej&signature=32beeebfc277817a80bb9371ff367f8b487a5&parameters=name,pageSize,pageNo&user=17299999999&usertype=Mobile&accountId=1173910536060928000



请求Header参数：
Content-Type=application/json

请求结果：
{
    "data": {
        "filter": "[name = 'kingdeecar']",
        "lastPage": true,
        "pageNo": 1,
        "pageSize": 10,
        "rows": [
            {
                "id": "968563370657601536",
                "number": "KDC"
            }
        ],
        "totalCount": 1
    },
    "errorCode": "0",
    "message": null,
    "status": true
}

URL请求参数说明

请求示例（POST）

URL：http://{{localhost}}/kapi/v2/kdtest/basedata/bd_supplier/save



请求Header参数：
appId=test
signature=32beeebfc277817a80b01d5787242c51ca5295f5edcf2eb9371ff367f8b487a5
timestamp=2023-08-19 15:31:59
signatureNonce=iksiertoidkwek;oitdwudysletwsues
user=130****2580
usertype= Mobile
accountId=1173910536060920000   


请求BODY参数：
{
    "data": {
        "number": "kingdeeCuS",
        "name": "供应商测试001",
        "alias_name": "供应商001"
    }
}



请求结果：
{
    "data": {
        "failCount": "0",
        "result": [
            {
                "billIndex": 0,
                "billStatus": true,
                "errors": [],
                "id": "1908634934143101952",
                "keys": {
                    "number": "kingdeeCuS"
                },
                "number": "kingdeeCuS",
                "type": "add"
            }
        ],
        "successCount": "1"
    },
    "errorCode": "0",
    "message": null,
    "status": true
}

请求头参数说明

 如果报文内容为空，则在body中输入固定值，如：

2.3 基本认证

苍穹OpenAPI基本认证，是结合了HTTPS Basic Authentication 的一种认证方式，通过基本认证调用接口时，需要在URL参数或请求头中携带openApiSign凭证，格式如下： {{localhost}}/{apiuri}?openApiSign=xxx，该凭证是由第三方应用、代理用户和当前数据中心ID组合