如何调用集成API?

安知系统可以作为后台软件，支持与如OA、ERP、LIMS等信息系统的集成对接，调用安知系统中预配置签章方案，实现对pdf文件的自动签章。

1. 调用签章API进行自动化签署

本api通过调用安知系统中的预配置签章方案，对pdf文件进行自动签章。

API调用条件

采购并本地化安装安知系统，购买模块需包含“自动批量签章”、“API调用”模块。
获取安知系统服务的host, app_id, app_secret参数值。
预配置自动签章方案，获取方案的plan_id编号。
调用API接口进行签章。

详细操作步骤如下：

获取签章服务的app_id与app_secret参数

采购并本地化安装安知系统后，供应商将根据您的公司名称与域名设置进行授权，提供授权参数app_id、app_secret，以及授权文件license.txt。

获取签章方案plan_id参数

登录安知系统，点击左侧菜单 > 配置签章防伪 > 配置自动模式 > 管理方案，查看自动签章方案列表。预配置签章方案，设定各类细节，请参考如何配置自动签章方案？。

方案列表

在列表中，点击目标方案后的"修改"链接进入方案修改页面，查看地址栏中的URL地址，did参数值即要调用的plan_id。

planid

1.1 调用API接口进行签章

API接口路由

安知签章API调用URL如下：

https://[host]/api/sign?app_id={app_id}&plan_id={plan_id}

请求头

需要在headers中添加以下内容：

timestamp: 请求时间戳，unix标准时间戳。精确到秒。如 1714377376
token: 请求签名，具体计算方式如下

token = md5({app_id} + {app_secret} + {timestamp} + {plan_id})

其中app_id和app_secret在需要从供应商处获取。

请求体

使用multipart/form-data格式上传。

form-data 所含参数

file: 待签章文件，每次只支持1个文件，必须填写。
metadata: 文件元数据，json格式。可以不填写。
audit_is_done: T/F 审批是否已经完成。T 审核已完成 F 审批未完成。为T的话，系统自动完成该文件的签署盖章。不为T，则需要在该系统手动审核。
auditors： dict类型。指定该文件的审批人。如果已经完成审批（audit_is_done=T），可以在该参数中添加审批信息。

示例如下

    {
        "审核": {"who":"王小二", "intro":"审批意见", "when": "2019-09-09T10:01:10"},
        "批准": {"who":"王小四", "intro":"审批意见", "when": "2019-09-10T10:01:10"},
        "盖章": {"who":"王小六", "intro":"审批意见", "when": "2019-09-11T10:01:10"},
    }

when 字段为时间戳，格式为：yyyy-MM-ddTHHss，表示该步骤审批时间。who 表示签署人名称，该用户在签署系统必须已经存在。 auditors的key为审核步骤，必须和方案中已经设置的步骤名称一致。

digit_stamp_sign_at: dict类型。指定该方案中“数字签名的图章”签署的时间。格式为:{"签章id": "年-月-日T时:分:秒"}，签章id为该签章在安知系统中的id编号，用字符串表示。

响应体

正确请求响应

{
    "success": 1,
    "status": "success",
    "code": 200,
    "data": {
        "msg": "已经将文件加入签章队列",
        "plan_id": 21,
        "report_id": 375,
        "sn": "9Q67NDUV3",
        "auth": "ee3f54f3a04333c83c4425010f9dbd44"
    }
}

响应中的data.report_id 字段可用户查询签署状态。

错误请求响应

HTTP status code 为 非 200的响应均为错误响应

测试用例(python版)

python

import requests
import hashlib
import time
import json

HOST = "http://fw.anzhi.ink"

# 定义请求参数  
timestamp = int(time.time())
plan_id = 8 
appid = 'appid'
appsecret = 'appsecret'
token = str(appid) + str(appsecret) + str(timestamp) + str(plan_id)

# 定义请求头  
headers = {
    'timestamp': str(timestamp),  # 自定义的请求头内容  
    'token': hashlib.md5(token.encode()).hexdigest()  # 自定义的请求头内容  
}

# 定义要上传的文件  
files = {
    'file': ('before-fangwei.pdf', open(r'D:\code\assets\stamp\sign\before-fangwei.pdf', 'rb'))
}

auditors =  {
    "审核": {"who":"王小二", "intro":"审批意见", "when": "2019-09-09T10:01:10"},
    "批准": {"who":"王小四", "intro":"审批意见", "when": "2019-09-10T10:01:10"},
    "盖章": {"who":"王小六", "intro":"审批意见", "when": "2019-09-11T10:01:10"},
}
audit_is_done = "T"
digit_stamp_sign_at = {
    "12": "2021-01-01T10:01:10",
    "19": "2021-01-11T10:31:52",
}

data = {
    "audit_is_done": audit_is_done,
    "auditors": json.dumps(auditors),
    "digit_stamp_sign_at": json.dumps(digit_stamp_sign_at),
}

# 拼接请求url  
url = f"{HOST}/api/sign?app_id={appid}&plan_id={plan_id}" 

# 发送POST请求  
response = requests.post(url, headers=headers, data=data, files=files)  

# 输出响应内容  
print(response.text)

1.2 调用API接口进行签署状态查询

安知系统是异步签署。系统提供接口查询文件的签署状态。

API接口路由

安知签章API调用URL如下：

https://[host]/api/query?app_id={appid}&plan_id={plan_id}&report_id={report_id}

report_id: 由签章接口返回

请求头

需要在headers中添加以下内容：

timestamp: 请求时间戳，unix标准时间戳。精确到秒。如 1714377376
token: 请求签名，具体计算方式如下

token = md5({app_id} + {app_secret} + {timestamp} + {plan_id})

其中app_id和app_secret在需要从供应商处获取。

请求方式

使用GET进行请求

响应体

正确请求响应

{
    "success": 1,
    "status": "success",
    "code": 200,
    "data": {
        "logs": [
            {
                "id": 2873,
                "step": "文件上传",
                "success": "T",
                "intro": "机器人上传文件：before-fangwei.pdf",
                "ctime": "2024-12-24 21:31:13",
                "stamp_name": null,
                "stamp_type": null
            },
            {
                "id": 2874,
                "step": "审核",
                "success": "T",
                "intro": "审批意见",
                "ctime": "2019-09-09 10:01:10",
                "stamp_name": null,
                "stamp_type": null
            },
            {
                "id": 2875,
                "step": "批准",
                "success": "T",
                "intro": "审批意见",
                "ctime": "2019-09-10 10:01:10",
                "stamp_name": null,
                "stamp_type": null
            },
            {
                "id": 2876,
                "step": "盖章",
                "success": "T",
                "intro": "审批意见",
                "ctime": "2019-09-11 10:01:10",
                "stamp_name": null,
                "stamp_type": null
            }
        ],
        "output": {},
        "stamped": false
    }
}

响应中的data.stamped 为true时表示文件已经签署盖章。data.output中包含签署结果。

错误请求响应

HTTP status code 为 非 200的响应均为错误响应

测试用例(python版)

python

import requests
import hashlib
import time
import json

HOST = "http://127.0.0.1:3000"

# 定义请求参数  
timestamp = int(time.time())
plan_id = 21 
appid = 'rr16vt69h9a3av00pfgnzei3l2'
appsecret = 'u8taf3f4hfd221mlky48awp1ec'
token = str(appid) + str(appsecret) + str(timestamp) + str(plan_id)

# 定义请求头  
headers = {
    'timestamp': str(timestamp),  # 自定义的请求头内容  
    'token': hashlib.md5(token.encode()).hexdigest()  # 自定义的请求头内容  
}

# query_status
report_id = "371"
url = f"{HOST}/api/query?app_id={appid}&plan_id={plan_id}&report_id={report_id}" 
'''
        app_id = self.get_query("app_id")
        timestamp = self.request.headers.get("timestamp")
        token = self.request.headers.get("token")
        report_id = self.get_query("report_id", "")
        plan_id = self.get_query("plan_id", "")
'''
response = requests.get(url, headers=headers) 
print(response.text)

2. 和其它系统进行账号集成

安知系统支持与其它系统进行账号集成，如OA、ERP、LIMS等。安知系统提供API接口，供其它系统调用。将其它系统的账号与安知系统进行集成，可以方便地使用安知系统中签章功能。

同步方式

第三方系统的账号同步到安知系统。不是安知系统的账号同步到第三方系统。请务必确保账号的唯一性 。

账号只同步登录信息，不同步账号在第三方系统的密码。安知系统的账号密码由安知系统生成，并存储在数据库中。

做任何操作之前，请确保账号在安知系统中存在。

API调用条件

采购并本地化安装安知系统，购买模块需包含“API调用”模块。
第三方系统有能力开发接口调用功能。

账号同步API

URL地址如下

/api/user

请求介质：用户浏览器请求方式：GET 请求响应：直接跳转到安知签章系统的主页面

请求参数

参数名称	类型	说明
login	str, 必填	登录账号，确保唯一性，不能超过30个字节，英文字母或者数字，也可以是邮箱或者手机号码，一旦不是唯一，系统做更新操作，utf8编码
name	str, 必填	用户姓名，不能超过30个字。系统会将login用户的名字设置成name。如果login不唯一，那么系统将更新已存在用户的name, utf8编码
timestamp, 必填	int	1970-01-01距离此刻的秒数，取整数
app_id	string, 必填	供应商分配的app_id
token	string, 必填	签名值, 具体获得方式见如下
goto	string	登陆后跳转到哪个地址。默认是系统主页。

token 获得方式

token = md5({app_id} + {app_secret} + {timestamp} + {urlencode(login)} + {urlencode(name)})

其中app_id 和 app_secret在需要从供应商处获取。login 和 name 参数值，请使用urlencode进行编码。

响应体

登录成功，则直接进入系统首页
登录失败，则出现提示错误信息

3. 文件召回

安知系统支持对文件进行召回。通过该功能，解决文件难以召回的问题。即便文件被打印、复印、复制，也能通过安知系统进行召回。一个文件不能多次被召回。召回后，可以取消召回。

API调用条件

采购并本地化安装安知系统，购买模块需包含“API调用”模块。
第三方系统有能力开发接口调用功能。
购买了召回功能。

API接口路由

安知签章API调用URL如下：

https://[host]/api/dead

请求头

需要在headers中添加以下内容：

timestamp: 请求时间戳，unix标准时间戳。精确到秒。如 1714377376
token: 请求签名，具体计算方式如下

token = md5({app_id} + {app_secret} + {timestamp} + {plan_id})

其中app_id和app_secret在需要从供应商处获取。

请求体

使用multipart/form-data格式上传。

form-data 所含参数

app_id: 分配的app_id，必填。
plan_id: 待签章文件所属的方案id，必填。
did: 文件的编号id，必填。
reason: 召回原因，可不填写。

响应体

正确请求响应

{
    "success": 1,
    "status": "success",
    "code": 200,
    "data": {
        "msg": "文件已经被召回",
        "plan_id": 23,
        "did": 12,
        "reason": ""
    }
}

错误请求响应

HTTP status code 为 非 200的响应均为错误响应

测试用例(python版)

python

import requests
import hashlib
import time

HOST = "http://fw.anzhi.ink"

# 定义请求参数  
timestamp = int(time.time())
data = {
    "plan_id": 8,
    "appid": 'appid',
    "did": 34,
    "reason": "召回原因说明"
}
appsecret = 'appsecret'
token = str(data["appid"]) + str(appsecret) + str(timestamp) + str(data["plan_id"])

# 定义请求头  
headers = {
    'timestamp': str(timestamp),  # 自定义的请求头内容  
    'token': hashlib.md5(token.encode()).hexdigest()  # 自定义的请求头内容  
}



# 拼接请求url  
url = f"{HOST}/api/dead" 

# 发送POST请求  
response = requests.post(url, headers=headers, data=data)  

# 输出响应内容  
print(response.text)

4. 文件撤销召回

安知系统支持对文件进行召回。通过该功能，解决文件难以召回的问题。即便文件被打印、复印、复制，也能通过安知系统进行召回。一个文件不能多次被召回。召回后，可以取消召回。

API调用条件

采购并本地化安装安知系统，购买模块需包含“API调用”模块。
第三方系统有能力开发接口调用功能。
购买了召回功能。

API接口路由

安知签章API调用URL如下：

https://[host]/api/restore

请求头

需要在headers中添加以下内容：

timestamp: 请求时间戳，unix标准时间戳。精确到秒。如 1714377376
token: 请求签名，具体计算方式如下

token = md5({app_id} + {app_secret} + {timestamp} + {plan_id})

其中app_id和app_secret在需要从供应商处获取。

请求体

使用multipart/form-data格式上传。

form-data 所含参数

app_id: 分配的app_id，必填。
plan_id: 待签章文件所属的方案id，必填。
did: 文件的编号id，必填。
reason: 取消召回原因，可不填写。

响应体

正确请求响应

{
    "success": 1,
    "status": "success",
    "code": 200,
    "data": {
        "msg": "文件已经被取消召回",
        "plan_id": 23,
        "did": 12,
        "reason": ""
    }
}

错误请求响应

HTTP status code 为 非 200的响应均为错误响应

测试用例(python版)

python

import requests
import hashlib
import time

HOST = "http://fw.anzhi.ink"

# 定义请求参数  
timestamp = int(time.time())
data = {
    "plan_id": 8,
    "appid": 'appid',
    "did": 34,
    "reason": "撤销召回原因说明"
}
appsecret = 'appsecret'
token = str(data["appid"]) + str(appsecret) + str(timestamp) + str(data["plan_id"])

# 定义请求头  
headers = {
    'timestamp': str(timestamp),  # 自定义的请求头内容  
    'token': hashlib.md5(token.encode()).hexdigest()  # 自定义的请求头内容  
}



# 拼接请求url  
url = f"{HOST}/api/restore" 

# 发送POST请求  
response = requests.post(url, headers=headers, data=data)  

# 输出响应内容  
print(response.text)