变更记录

产品版本	更新内容	更新日期
V5.0.001	初始版本	2022年1月1日

本文档适用于苍穹版本为V6.0以下，通过access_token或JWT调用OpenAPI。

1 简介

Token认证是指客户端登陆完成之后，服务端会生成一个有时效性的token返回给客户端，以后每次请求客户端都需要带上token。它可以当作URL参数或在请求头中发送，如“http://demo.com/users?accessToken=xxxxxx”，服务端以此来控制身份。当token过期后，服务端会销毁token，客户端需要重新请求获得token。

1.1 AccessToken认证流程

1、在金蝶云苍穹开放平台注册第三方应用，注册后就会生成一个appId（系统编码）和appSecret（系统密码）；

2、请求参数中输入appId和appSecret，通过客户端发送请求给服务器，获取临时appToken；

3、客户端通过请求发送用户名和上一步获取的appToken等信息给服务器，正确的话就返回access_token；

4、客户端拿到这个access_token，后续每次请求中，客户端会把token放在请求Header中发送给服务器，服务器验证签名是否有效，如果有效那么认证就成功，可以返回客户端需要的数据。

appId和appSecret

appId是第三方应用的唯一标识，appSecret是第三方应用的密钥，它们相当于用户名和密码。注册第三方应用之后就会生成一个appId和appSecret。另外appSecret和密码一样也可以重置，在第三方应用的编辑页面可以重置密钥。

app_token

即应用临时令牌。当用户在开放平台访问API前，需对应用进行授权，授权后第三方应用可访问用户的隐私数据。app_token为一次性令牌，有效期为2小时。

access_token

即用户授权令牌，为用户一次会话的授权标识，有效期2小时。在获得app_token后，通过调用开放平台后台接口getAppToken来获取access_token。第三方应用在调用API服务时，需要带上access_token信息作为访问的凭证。

1）获取app_token

请求Body参数

传入参数	字段类型	是否必输	字段说明
appId	string	是	第三方appId，即例子中的：test
appSecret	string	是	第三方app的密码，即例子中的：123456789Asd!@123456789
tenantid	string	否	租户ID
accountId	string	否	数据中心ID，如果不输入，默认会选取租户下的缺省数据中心

请求示例

URL:http://{{localhost:}}/api/getAppToken.do
 
请求Header参数：
Content-Type=application/json
 
请求BODY参数：
{
    "appId": "test",
    "appSecret": "123456789Asd!@123456789",
    "tenantid": "tenant_devother_dev",
    "accountId": "666522411780278272"
}
 
请求结果：
{
    “data”: {
        "app_token": "d1106e34-8766-47cf-a75c-cd6b24a00c62",
        "success": true,
        "error_desc": "",
        "expire_time": 1621249899783,
        "error_code": "0"
    },
    "state": "success"
}

2）获取access_token

请求Body参数

传入参数	字段类型	是否必输	字段说明
user	string	是	用户手机号
apptoken	string	是	上一个接口的应用令牌（app_token）
tenantid	string	否	租户ID
accountId	string	否	数据中心ID，如果不输入，默认会选取租户下的缺省数据中心
usertype	String	否	Mobile：标识为手机，默认为手机 Email：标识为email UserName：标识为用户名
language	String	否	语言字串： zh_CN，zh_TW等。默认系统默认语言

请求示例

URL：http://{{localhost:}}/api/login.do
 
请求Header参数：
Content-Type=application/json
 
请求Body参数：
{
    "user": "130****2580",
    "apptoken": "9c13aa2f-d99b-4884-8a52-d1a065a392cc",
    "tenantid": "",
    "accountId": "666522411780278272",
    "usertype": "Mobile",
    "language":"zh_CN"
}
请求结果：
{
    "data": {
        "access_token": "666522411780278272_ZOmaYoNRmT4XRl9k8RHlt1xuyxJ5fDhf0vFxNpN4EVb37eSAawuQN9RgfuO8hsSGuPHtEb849W5Y0RQxp6CR9Qcm9E4l15h6Cs2B",
        "success": true,
        "error_desc": "",
        "expire_time": 1621250199609,
        "error_code": "0"
    },
    "state": "success"
}

1.2 JWT认证流程

JWT(全称是JSON WEB TOKEN)是一种用于双方之间传递安全信息表述性声明规范，和access_token一样，都是访问资源的令牌。

金蝶云苍穹JWT认证流程:

1、通过请求指定参数如appId、appSecret、keytype一次性获取JWT。

2、客户端拿到这个JWT，后续每次请求中，客户端会把token放在请求Header中发送给服务器，服务器验证签名是否有效，如果有效那么认证就成功，可以返回客户端需要的数据。

1）获取JWT

请求Body参数

传入参数	字段类型	是否必输	字段说明
user	string	是	用户手机号
appId	string	是	第三方appId，即例子中的：test
appSecret	string	是	第三方app的密码，即例子中的：123456789123456789
tenantid	string	否	租户ID
accountId	string	否	数据中心ID，如果不输入，默认会选取租户下的缺省数据中心
usertype	String	否	Mobile：标识为手机，默认为手机 Email：标识为email UserName：标识为用户名
keytype	String	是	声明认证方式，如jwt

请求示例

URL:http://{{localhost:}}/api/login.do
 
请求Header参数：
Content-Type=application/json
 
请求BODY参数：
{
    "user": "130****2580",
    "appId": "test",
    "appSecret": "123456789123456789",
    "tenantid": "baseline_a",
    "accountId": "1173910536060928000",
    "usertype": "Mobile",
    "keytype":"JWT"
}
 
 
请求结果：
{
    "data": {
        "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmaWQiOiIxMzQ2NjczOSIsInN1YiI6Imtkand0IiwiZnBob25lIjoiMTcyOTk5OTk5OTkiLCJlaWQiOiIxMTQ3NTYxNyIsImZ0cnVlbmFtZSI6IklFUlAiLCJmb3JnaWQiOiIxMDAwMDAiLCJpc3MiOiJrZCIsInVzZXJpZCI6IjEzNDY2NzM5IiwiZmxhc3Rsb2dpbmlwIjoiMTcyLjIwLjIwMC41NCIsImZpc2FjdGl2ZWQiOiIxIiwiZm9wZW5pZCI6IjVhMmRlZmNiZTRiMDk1N2ZhMDhmOGM3MiIsImZsYXN0bG9naW50aW1lIjoiMjAyMS0wOC0yMCAwMDowMDowMCIsImZlbmFibGUiOiIxIiwiZnVpZCI6IjEzNDY2NzM5IiwidXNlclR5cGUiOiIxIiwiZXhwIjoxNjI5NDQ3MDM1LCJpYXQiOjE2Mjk0Mzk4MzUsImZpc3JlZ2lzdGVkIjoiMSIsInVzZXJvcGVuaWQiOiI1YTJkZWZjYmU0YjA5NTdmYTA4ZjhjNzIiLCJ1c2VybmFtZSI6IklFUlAifQ.kf_UfkQuAPb_qHZAc2ovB7nzpnWIKpl_7eXw42UjNYM",
        "success": true,
        "error_desc": "",
        "expire_time": 1629447035019,
        "error_code": "0"
    },
    "state": "success"
}

下面详细介绍如何通过JWT调用API服务。

2）GET API 实例

请求示例

URL：https://feature.kingdee.com:2024/baseline_a/kapi/sys/isc_demo_basedata_1/query?select=name,number&filter=name eq 123asd&jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmaWQiOiIxMzQ2NjczOSIsInN1YiI6Imtkand0IiwiZnBob25lIjoiMTcyOTk5OTk5OTkiLCJlaWQiOiIxMTQ3NTYxNyIsImZ0cnVlbmFtZSI6IklFUlAiLCJmb3JnaWQiOiIxMDAwMDAiLCJpc3MiOiJrZCIsInVzZXJpZCI6IjEzNDY2NzM5IiwiZmxhc3Rsb2dpbmlwIjoiMTcyLjIwLjIwMC41NCIsImZpc2FjdGl2ZWQiOiIxIiwiZm9wZW5pZCI6IjVhMmRlZmNiZTRiMDk1N2ZhMDhmOGM3MiIsImZsYXN0bG9naW50aW1lIjoiMjAyMS0wOC0yMCAwMDowMDowMCIsImZlbmFibGUiOiIxIiwiZnVpZCI6IjEzNDY2NzM5IiwidXNlclR5cGUiOiIxIiwiZXhwIjoxNjI5NDQ3MDM1LCJpYXQiOjE2Mjk0Mzk4MzUsImZpc3JlZ2lzdGVkIjoiMSIsInVzZXJvcGVuaWQiOiI1YTJkZWZjYmU0YjA5NTdmYTA4ZjhjNzIiLCJ1c2VybmFtZSI6IklFUlAifQ.kf_UfkQuAPb_qHZAc2ovB7nzpnWIKpl_7eXw42UjNYM&appId=TEST&accountId=1173910536060928000
 
请求结果：
{
    "success": "true",
    "data": {
        "count": 1,
        "header": [
            {
                "name": "name",
                "caption": "名称",
                "type": "String"
            },
            {
                "name": "number",
                "caption": "编码",
                "type": "String"
            }
        ],
        "rows": [
            [
                "123asd",
                "123asd"
            ]
        ]
    }
}

请求参数

传入参数	字段类型	是否必输	字段说明
select	string	是	定义查询类服务的返回参数，如id、name、number等
filter	string	否	过滤参数，可以设置查询条件如filter=name eq 123asd
jwt	string	是	用SHA-256算法和JWT非对称加密key对参数进行加密后生成的token。公式：HMACSHA256(base64UrlEncode(header) + "." +base64UrlEncode(payload),key)
appId	string	是	第三方appId
accountId	string	否	数据中心ID，如果不输入，默认会选取租户下的缺省数据中心

3）POST API 实例

请求示例

URL：http://localhost:8080/ierp/kapi/sys/pm_purorderbill/save
 
请求Header参数：
jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmaWQiOiIxMzQ2NjczOSIsInN1YiI6Imtkand0IiwiZnBob25lIjoiMTcyOTk5OTk5OTkiLCJlaWQiOiIxMTQ3NTYxNyIsImZ0cnVlbmFtZSI6IklFUlAiLCJmb3JnaWQiOiIxMDAwMDAiLCJpc3MiOiJrZCIsInVzZXJpZCI6IjEzNDY2NzM5IiwiZmxhc3Rsb2dpbmlwIjoiMTcyLjIwLjIwMC41NCIsImZpc2FjdGl2ZWQiOiIxIiwiZm9wZW5pZCI6IjVhMmRlZmNiZTRiMDk1N2ZhMDhmOGM3MiIsImZsYXN0bG9naW50aW1lIjoiMjAyMS0wOC0yMCAwMDowMDowMCIsImZlbmFibGUiOiIxIiwiZnVpZCI6IjEzNDY2NzM5IiwidXNlclR5cGUiOiIxIiwiZXhwIjoxNjI5NDQ3MDM1LCJpYXQiOjE2Mjk0Mzk4MzUsImZpc3JlZ2lzdGVkIjoiMSIsInVzZXJvcGVuaWQiOiI1YTJkZWZjYmU0YjA5NTdmYTA4ZjhjNzIiLCJ1c2VybmFtZSI6IklFUlAifQ.kf_UfkQuAPb_qHZAc2ovB7nzpnWIKpl_7eXw42UjNYM
appId=TEST
accountId=1173910536060928000    //有默认数据中心可以不传
 
请求BODY参数：
{
    "data": {
        "number": "cugk",
        "name": "cugk",
        "alias_name": "cugk"
    }
}
 
请求结果：
{
    "data": {
        "success": true,
        "needSign": false,
        "needWfAssignPersons": false,
        "cancelWriteLog": true,
        "showMessage": true,
        "billCount": 1,
        "successPkIds": [
            1226640481962735668
        ],
        "billNos": {
            "1226640481962735668": "cugk"
        },
        "validateResult": {
            "validateErrors": [],
            "success": true,
            "message": "",
            "errorPkIds": [],
            "errorDataIndexs": []
        },
        "runSecond": 0,
        "allErrorOrValidateInfo": [],
        "allErrorInfo": []
    },
    "success": true,
    "errorCode": "success",
    "message": null
}

请求头参数

传入参数	字段类型	是否必输	字段说明
jwt	string	是	用SHA-256算法和JWT非对称加密key对参数进行加密后生成的token。公式：HMACSHA256(base64UrlEncode(header) + "." +base64UrlEncode(payload),key)
appId	string	是	第三方appId
accountId	string	否	数据中心ID，如果不输入，默认会选取租户下的缺省数据中心

备注：Secret是保存在服务器端的，JWT的签发生成也是在服务器端的，secret就是用来进行JWT的签发和JWT的验证，所以，它就是你服务端的私钥，在任何场景都不应该流露出去。

2 更多资讯

金蝶云苍穹OpenAPI增强型Token认证

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

API认证方式-Accesstoken认证/JWT认证

API认证方式-Accesstoken认证/JWT认证

恭喜您！