开放平台

协同平台电子签章二次开发集成

附件：电子签章标准图框制作流程

# 1. 电子签章组件接口

# 1.1 上传图纸并自动转换（SDK 专用）

简要描述

上传图纸并自动转换，SDK（非二合一）下使用

请求 URL

  • /api/file/upload

请求方式

  • POST

请求示例

file:(二进制)
folderId:0

参数（form-data）

参数名 必选 类型 说明
file 是 binary 文件二进制数据
folderId 是 int 文件夹 id，SDK 场景下默认为根目录 0

返回示例

{
"code":0,
"msg":"操作成功",
"data":
    {
        "docId":"1776856440984698881",
        "name": "文件名"
    }
}

返回参数说明

参数名 类型 说明
code int 返回参数
msg int 返回消息
data object 数据对象
docId string 文档 id
name string 文档名称

# 1.2 资源上传

电子签名,电子签章以及 CA 证书文件上传.

请求方式

POST

请求 URL

/api/sign/upload

参数

request Params

参数名 是否必填 参数类型 说明
dwgPath 是 string 图纸名(docId.dwg)
docId 是 string 图纸 Id（调用图纸上传接口后获取）
uploadId 是 int 上传 id 时间戳
file 是 file 用于签名，签章的文件

请求示例

Request URL: http://127.0.0.1:9080/api/sign/upload
Request Method: POST
Content-Type: multipart/form-data
Request Body(form-data)：
{
    "dwgPath":"1778249593215836161.dwg",
    "docId":"1778249593215836161",
    "uploadId": "17645321321",
    "file": test.dwg（dwg签名文件）/test.png(签章图文件)
}

返回示例

{
    "code": 0,
    "msg": "操作成功",
    "data": {
    "fileId":"123456789123456789"
    }
}

返回参数说明

参数名 参数类型 说明
code int 消息代码
msg string 消息
data object 数据对象
fileId string 文件 id

# 1.3 获取标准图框属性列表

电子签章 websdk 获取图框，属性块，属性信息列表

请求方式

GET

请求 URL

/api/sign/properties

参数

request Params

参数名 是否必填 参数类型 说明
dwgPath 是 string 图纸名(docId.dwg)
docId 是 string 图纸 Id

请求示例

Request URL: http://127.0.0.1:9080/api/sign/properties?dwgPath=1778249593215836161.dwg&docId=1778249593215836161
Request Method: GET
Content-Type: application/json

返回示例

{
    "code": 0,
    "msg": "操作成功",
    "data": [
        {
            "blockId": "1782600233333350401",
            "blockName": "标准图框_建筑",    //图框块名
            "blockRefHandle": 1421,         //图框handle
            "layoutHandle": 34,             //图框所属空间handle
            "blockData": [
                {
                    "refUvector": "",
                    "refVvector": "",
                    "refInsertPoint": "",
                    "refHandle": "",
                    "refName": "",
                    "refData": [
                        {
                            "signId": "1782600233333350400",//数据库的签名主键
                            "type": 1,
                            "attrHandle": -1,
                            "attrName": "设计_机打信息",     //属性名
                            "attrValue": "",                //属性值
                            "attrUvector": "",
                            "attrVvector": "",
                            "attrInsertPoint": "",
                            "signFileId": "",
                            "certFileId": "",
                            "certPassword": "",
                            "signTime": ""
                        },
                        {
                            "signId": "1782600233333350405",//数据库的签名主键
                            "type": 3,
                            "attrHandle": -4,
                            "attrName": "设计_签章图",      //属性名
                            "attrValue": "",               //属性值
                            "attrUvector": "",
                            "attrVvector": "",
                            "attrInsertPoint": "",
                            "signFileId": "",
                            "certFileId": "",
                            "certPassword": "",
                            "signTime": ""
                        },
                        {
                            "signId": "1782600233333350407",//数据库的签名主键
                            "type": 4,
                            "attrHandle": -5,
                            "attrName": "检验_DWG签名",     //属性名
                            "attrValue": "",                //属性值
                            "attrUvector": "",
                            "attrVvector": "",
                            "attrInsertPoint": "",
                            "signFileId": "",
                            "certFileId": "",
                            "certPassword": "",
                            "signTime": ""
                        }
                    ]
                }
            ]
        }
    ]
}

返回参数说明

参数名 参数类型 说明
code int 消息代码
msg string 消息
data object 数据对象
data.blockName string 图框块名
data.layoutHandle int 图框所属空间 handle
data.blockRefHandle int 图框 handle
data.blockData.refHandle int 属性块 handle
data.blockData.refVvector string 属性块纵向矢量
data.blockData.refInsertPoint string 属性块插入点
data.blockData.refUvector string 属性块横向矢量
data.blockData.refData.signId string 签名主键
data.blockData.refData.attrHandle int 属性 handle
data.blockData.refData.attrUvector string 属性横向矢量
data.blockData.refData.attrInsertPoint string 属性插入点
data.blockData.refData.attrVvector string 属性纵向矢量
data.blockData.refData.attrName string 属性名
data.blockData.refData.attrValue string 属性值
data.blockData.refData.type int 属性签章类型(1:机打签名;2:电子签名;3:公章;4:dwg 图纸签章)

# 1.4 写入机打签名和电子签章

机打签名，电子签名，签章批量保存到数据库

请求方式

POST

请求 URL

/api/sign/save

参数

request Params

参数名 是否必填 参数类型 说明
data.attrName 是 string 属性名
data.blockRefHandle 是 int 图框 handle
data.signId 是 string 签名 id
data.attrHandle 是 string 属性 Handle
data.attrValue 是 string 机打信息的属性值（值为空时则为清空操作）
data.type 是 int 签名类型，1：机打信息 3.签章图 4.dwg 签名
data.signFileId 是 string 签名，签章图片文件 id（通过/api/sign/upload 接口上传签章图或 dwg 签名文件后获取到）
data.certFileId 否 string 签章图片 PFX 证书文件 id
data.certPassword 否 string 签章图片 PFX 正式秘钥

请求示例

Request URL: http://127.0.0.1:9080/api/sign/save
Request Method: POST
Content-Type: application/json
Request Body：
{
    "dwgPath": "1782600213989220353.dwg",
    "docId": "1782600213989220353",
    "data": [
        {
            "attrValue": "张三",        //机打信息的新值
            "attrHandle": -1,
            "signId": "1782600233333350400",
            "type": 1,
            "attrName": "设计_机打信息",
            "blockRefHandle": 1421
        },
        {
            "certPassword": "123456",               //证书密钥
            "certFileId": "260023333",              //签章图片PFX证书文件id
            "signFileId": "1782600233333350408",    //签名，签章图片文件id
            "signId": "1782600233333350403",
            "type": 3,                              //签名类型，1：机打信息 3.签章图 4.dwg签名
            "attrName": "出图章_签章图",
            "blockRefHandle": 1421
        },
        {
            "signFileId": "",
            "signId": "1782600233333350407",
            "type": 4,                              //签名类型，1：机打信息 3.签章图 4.dwg签名
            "attrName": "检验_DWG签名",
            "blockRefHandle": 1421
        }
    ]
}

返回示例

{
    "code": 0,
    "msg": "操作成功",
    "data": null
}

# 1.5 电子签章 websdk 打印

打印接口，用于生成 PDF/JPG/PNG

请求方式

POST

请求 URL

/api/document/print

参数

request Params

参数名 是否必填 参数类型 说明
docId 是 string 图纸 id
handleId 是 string 句柄 id
ptType 是 string 输出文件类型 0:pdf; 1:ofd; 2:png; 3:jpg
plotLayers 否 array 设置图层是否打印，可以设置多个；如果不需要设置打印图层，则不需要传输 plotLayers 字段
canvasWidth 是 string canvas 的宽
canvasHeight 是 string canvas 的高
plotSettings 是 object 打印相关配置
plotType 是 string 打印方式 1:直接打印; 4:窗口打印
minPoint 是 array 窗口打印左下角的点，只需要 x 和 y 值
maxPoint 是 array 窗口打印右上角的点，只需要 x 和 y 值
centered 是 boolean 是否为中心打印
fullScale 是 boolean 是否铺满纸张
denominator 是 int fullScale 为 false 是配置该属性，表示打印比例
scaleType 是 string 缩放比例， 默认为 0，实际配置方式有很多
plotRotation 是 int 打印方向 0:纵向; 1:横向; 2:纵向+反向; 3:横向+反向
pageIndex 是 int 纸张配置索引
xCoordinate 否 int 打印偏移，centered 为 false 时配置
yCoordinate 否 int 打印偏移，centered 为 false 时配置
plotStamps 否 object 打印戳记相关配置
selection1 否（存在打印戳记的场合必填） string 前端拼接的戳记
selection2 否（存在打印戳记的场合必填） string 用户自定义的戳记 (打印电子签章,签名)
openElecSignSeal 否 int 设置是否打印电子签章 0 不显示(默认),1 显示
lineWeights 否 boolean 是否打印线宽
stampLocation 否（存在打印戳记的场合必填） int 戳记相对于图纸的位置 (0:左下; 1:左上; 2:右上;3:右下)
stampOrientation 否（存在打印戳记的场合必填） int 戳记显示的方向 0:纵向; 1:横向

请求示例

Request URL: http://127.0.0.1:5121/api/document/print
Request Method: POST
Content-Type: application/json
Request Body：
{
    "docId": "1782600213989220353",
    "canvasHeight": "692",
    "canvasWidth": "837",
    "functionType": 27,
    "handleId": "211",
    "plotLayers": [
        {
            "isPlottable": 1,
            "layerId": "16"
        },
        {
            "isPlottable": 1,
            "layerId": "605"
        }
    ],
    "plotSettings": {
        "maxPoint": [
            0,
            0
        ],
        "minPoint": [
            0,
            0
        ],
        "plotType": 1,
        "centered": true,
        "fullScale": true,
        "denominator": 1,
        "plotRotation": 1,
        "pageIndex": 63,
        "xCoordinate": 0,
        "yCoordinate": 0
    },
    "plotStamps": {
        "selection1": "Circle10_1585228118872739840.dwg, dwg to pdf.pc5, 布局1,ISO A4(210.00 x 297.00 毫米), 2023-05-04 18:48:11, 1:1",
        "selection2": "",
        "stampLocation": 0,
        "stampOrientation": 1
    },
    "ptType": 0,
    "lineWeights": true,
    "openElecSignSeal": 0,
}

返回示例

字节流

# 2. 电子签章使用流程

# 2.1 前置条件

1.图纸存放路径就绪(data 目录下的 dwgs 文件夹中) 通过 1.1 上传图纸并自动转换接口上传图纸 2.开图功能正常

# 2.2 电子签章资源获取方式（签章图/DWG 签名需用户提供）

# 2.2.1 资源上传方式（方式一）

该方式下,集成方把电子签名,签章所需要的图片资源通过电子签名,签章接口上传到电子签章组件中供其所用.

# 2.2.1 资源对接方式（方式二）

集成方只有自己的资源管理体系, 能够按照电子签章组件提供的接口文档标准自行实现其接口. 电子签章组件通过接口建立资源对接, 电子签章组件通过其集成方的资源 id 获取相应的图片资源用于签署电子签章.

注意: 资源都是通过 Id 的方式对接,电子签章保存签署记录接口中的 signFileId(签名文件 id) 和 certFileId (签名证书 id) 必须用集成方的资源 id.

# 3.电子签章组件包部署

# 3.1 硬件和系统要求

推荐服务器配置
服务器配置要求：x86 / ARM，内存：32G
操作系统：Ubuntu 20.04.03 或 CentOS 7.9
软件环境：docker-ce 20.10.14; docker compose

# 3.2 部署说明

本文档部署的 docker 网络模式为 host 模式(大部分私有云情况), dockercompose 的 yaml 文件中是 network_mode: host 如果是桥接模式,请自行去掉,建立端口映射调整或者联系开发人员协助.

# 3.3 websdk 基础服务部署

电子签章是 websdk 一个组件,前提条件是 websdk 部署成功,采用继承的部署方式;如果已经部署过 sdk 服务,需要使用电子签章功能,则首先需要升级部署 sdk 服务.

(1)升级 SDK 服务
在原 SDK 部署录中替换 zwcadcoreservicesdk-compose-b-r.yaml; 在环境配置文件.env 中加入新的配置,或者备份原文件,直接覆盖. 注意端口是否和原来一致.

停止原有服务
docker compose -f zwcadcoreservicesdk-compose-b-r.yaml stop coreservice;
删除原有容器;
docker compose -f zwcadcoreservicesdk-compose-b-r.yaml rm coreservice;
删除原有镜像; docker images |grep sdk
docker rmi 镜像 id

导入新的 zwcadcoreservicesdk.tar 镜像.
docker load -i ./zwcadcoreservicesdk.tar
查看是否导入成功 docker images |grep sdk

重新运行的新的服务. docker compose -f zwcadcoreservicesdk-compose-b-r.yaml up -d coreservice ;
升级完成后继续扩展组件安装和 sdk_portal 安装.

(2)全新安装

1.确定安装位置; 在 websdk 部署机器上建立 websdk 的部署目录
将提供的安装资料解压到当前目录,形成 websdk_deploy 文件夹.
进入到当前文件夹. cd ./websdk_deploy
在 docker 运行环境安装完好的情况下;首先依次导入 4 个镜像,如果不需要支持演示(做文件上传,则电子签章扩展组件 zwsoft-sdk-expand.tar 不需要导入安装. )
导入 4 个镜像包: (带有版本号的,请按照版本的文件导入)
docker load -i ./zwcadcoreservicesdk.tar
docker load -i ./zwcad-sdk-electric-signature.tar
docker load -i ./zwcadcoreservicesdk-portal.tar
导入完成后.
docker images |grep sdk

导入新的 zwcadcoreservicesdk.tar 镜像(已导入,忽略此步) docker load -i ./zwcadcoreservicesdk.tar 查看是否导入成功 docker images |grep sdk

查看.env 文件 的端口是否占用,决定是否修改端口

sudo netstat -ano |grep 5121
如果占用则需要修改.

修改配置文件./websdk_deploy/setting/appsettings.json

重新运行的新的服务.
docker compose -f zwcadcoreservicesdk-compose-b-r.yaml up -d coreservice ;

# 3.4 部署电子签章后端组件

1.导入镜像;以管理员执行 docker load -i ./zwcad-sdk-electric-signature.tar (已导入,忽略此步) 将镜像加载至部署机器中;检查环境配置文件;由于 .env 文件是共用的,检查里面的 HOST_VOLUMN 值的目录的地址是否存在.(确保和当前发布目录一致)

2.导入数据库脚本;使用数据库连接工具(Navicat,sqlclient),以普通用户连接数据库,执行./db/ddl/ddl_electric_signature.sql (可创建独立数据库,也可以使用已经存在的数据库)

3.配置应用程序数据库链接; 修改 bootstrap-prod.yml 文件,在./websdk_deploy/webservice/config/signature/下,修改数据库链接配置. 包含数据库名和用户,密码

修改 websdk 的调用地址

修改安全访问配置

core-service-sdk 为 coreservice 的部署机器的 ip 和端口.
4.启动 docker 容器;以管理员执行 docker compose -f sdk-signature-compose.yaml up -d zwcad-signature 启动镜像容器，运行 docker 服务

# 3.5 部署电子签章前端组件

1.导入镜像;以管理员执行 docker load -i ./zwcadcoreservicesdk-portal.tar 将镜像加载至部署机器中(已导入,忽略此步);
2.修改 websdk_deploy/nginx/conf/conf.d/cloud2d_sdk.conf 配置文件. 按照实际情况修改电子签章服务各个组件的代理设置.
如果 80 端口未使用,不存在与其他服务端口冲突 ;请使用默认配置文件(下面的配置忽略),需要调整请参考如下截图修改.


老版本用的 5510 端口, 新版本修改为 5121 或者自定义的端口

添加网站安全授权
注意:websdk 核心服务的端口由配置文件.env ;SVC_PORT=5121 配置决定 修改容器端口映射
3.启动 docker compose -f zwcadcoreservicesdk-compose-b-r.yaml up -d coreservice-portal

# 3.6 测试是否成功

在浏览器地址栏输入 192.168.56.178:8085/index_upload.html

ZRX相关接口