平台简介
新手指南
API协议
API文档
单点登录集成
小程序插件
常见问题
开放平台API接口调用常见报错以及解决方法汇总
帮助中心 / 开放平台帮助文档 / 用模板添加合同文档
用模板添加合同文档
使用模板文件添加合同文档,模板文件需提前在契约锁云平台上维护,仅草稿状态的合同可添加合同文档。

用模板添加合同文档

描述

使用模板文件添加合同文档,模板文件需提前在契约锁云平台上维护,仅草稿状态的合同可添加合同文档。

请求地址

/v2/document/addbytemplate

请求方法

POST

请求格式

application/json;charset=UTF-8

请求参数

Y:必填 N:非必填 CY:条件必填,即其他参数的输入情况会影响当前参数是否必填(具体逻辑参照各参数的描述)

参数 类型 是否必传 长度 描述 示例
contractId String CY 19 合同ID,合同ID与业务ID二选一,不能同时为空 2966238833119273012
bizId String CY 50 业务ID,合同ID与业务ID二选一,不能同时为空 6326238833119273365
tenantName String CY 100 子公司名称,若使用业务ID添加合同文件,且合同是以子公司身份创建的,则需要传递该值,用于确定合同主体 阿里巴巴子公司
title String Y 100 名称 我的模板
templateId String Y 19 模板ID 2966238833119273289
templateParams List<TemplateParam> N 模板参数;如果是参数模板,则必填(支持格式为文本、单选框、多选框格式的参数) 详见TemplateParam
documentSort Integer N 指定文档排序 2
stampers List<Stamper> N 指定签署位置 详见Stamper

Stamper(签署位置):

参数 类型 是否必传 长度 描述 示例
actionId String N 签署节点ID;公司的签署位置必须(创建合同草稿接口的返回值) 2931411786447082239
signatoryId String N 签署方ID;个人的签署位置必传(创建合同草稿接口的返回值) 2931411786447082239
type String Y 签署类型:
COMPANY(公章),PERSONAL(个人签名),
LP(法人章),TIMESTAMP(时间戳),ACROSS_PAGE(骑缝章)
COMPANY
keyword String N 关键字
keywordIndex Integer N 关键字索引:1代表第1个关键字,0代表所有关键字
,-1代表倒数第1个关键字;默认为1
0
page Integer N 坐标页码,0代表所有 ,-1代表最后一页 0
offsetX Decimal N 横坐标/关键字偏移量 0.1
offsetY Decimal N 纵坐标/关键字偏移量 0
datePatterns List N 时间戳格式:
HYPHEN(yyyy-mm-dd),Chinese(yyyy年mm月dd日(阿拉伯数字)
ALL_Chinese(yyyy年mm月dd日(中文)),ENGLISH(dd MMM yyyy(英文))
仅type为TIMESTAMP时生效,可指定多个格式
["HYPHEN"]

TemplateParam(模板参数):

参数 类型 是否必传 长度 描述 示例
name String Y 100 参数名称 grade
value String Y 一、PDF模板、Word模板、旧版本HTML模板编辑器不同参数类型的传参规则如下:
1)普通文本:大小不超过300
2)日期:格式为yyyy-MM-dd,如:2019-06-04
3)身份证号:只能是15或18位的数字或字母,如:123456789123456789
4)单选:只能是单选的选项名称,如:val1
多选:只能是多选的选项名称,传入多个值时,用逗号隔开,如:val1,val2
5)图片,图片的base64格式加前缀「data:image/png;base64,」,其中image/png为实际的图片格式,示例如下:data:image/png;base64,/9j/4AAQSk
6)动态表格,value是一个Map(键值对)数组,每个Map对应表格的每行,Map的key和value对应列名和值,示例如下:
[{"column1":"1","column2":"2","column3":"3","column4":"4"},{"column1":"5","column2":"6","column3":"7","column4":"8"}]表示一个2行4列的表格

二、新版本HTML编辑器的单多选、动态表格参数传参格式有调整,其他与旧版保持一致:
1)单选、多选、下拉选择:支持传入多选的选项名或对应的选项value值,传入多个值时,用逗号隔开,参数对应选项的value值可在模板详情接口(/v2/template/detail)进行查询
2)动态表格:提供了2种传参方式:
-以key-value的形式传参,与旧版传参规则相同,在模板编辑页面维护好动态表格每1列的key值之后,按列进行传参
-以二维数组的形式传参,示例如下: [["1","2","3","4"],["1","2","3","4"]]表示一个2行4列的表格,如若需要合并单元格,传参示例如下: [["1",""#.1","3""4"],[#.2","6","7","#.3"]], #.1表示向左合并单元格,#.2表示向上合并单元格,#.3表示向左上合并单元格
详见描述
signatoryId String N 19 参数填写方 2966238833119273572
readOnly Boolean N 参数是否只读,默认为false;传入true时,在页面上进行合同填参时该参数不可编辑 false

签署位置说明:

签署位置有以下两种表现方式:

1、用关键字确定坐标:
keyword:关键字。
offsetX:横坐标偏移量;默认合同页的宽为1,所以取值范围是(-1, 1)。
offsetY:纵坐标偏移量;默认合同页的高为1,所有取值范围是(-1, 1)。
找到keyword的坐标(x, y),再加上偏移量(offsetX, offsetY),最终得到的坐标是(x+offsetX, y+offsetY)。
坐标原点是合同页的左下角,坐标是指印章图片的左下角的坐标。

2、直接确定坐标:
page:印章所在页码;从1开始。
offsetX:横坐标;默认合同页的宽为1,所以取值范围是(0, 1)。
offsetY:纵坐标;默认合同页的高为1,所以取值范围是(0, 1)。
由page确定页码,由(offsetX, offsetY)确定坐标。
坐标原点是合同页的左下角,坐标是指印章图片的左下角的坐标。

请求示例

Http示例

POST /v2/document/addbytemplate HTTP/1.1
Host: [host]
x-qys-open-timestamp: [替换为请求头生成的Timestamp]
x-qys-open-signature: [替换为请求头生成的Signature]
x-qys-open-accesstoken: [替换为请求头生成的Token]
Content-Type: application/json
{
    "contractId": "2593815518218461185",
    "bizId": null,
    "title": "V2添加模板文档",
    "templateId": "2560778409594396776",
    "templateParams": [
        {
            "name": "乙方姓名",
            "value": "张三"
        }
    ]
}
Java示例

// 初始化sdkClient
String serverUrl = "https://openapi.qiyuesuo.cn";
String accessKey = "替换为您申请的开放平台App Token";
String accessSecret = "替换为您申请的开放平台App Secret";
SdkClient sdkClient = new SdkClient(serverUrl, accessKey, accessSecret);
// 添加合同文档
List<TemplateParam> params = new ArrayList<>();
params.add(new TemplateParam("param1", "val1"));
params.add(new TemplateParam("param2", "val2"));
DocumentAddByTemplateRequest request = new DocumentAddByTemplateRequest(contractId,
        templateId, params, "文件二");
String response = sdkClient.service(request);
SdkResponse<DocumentAddResult> responseObj = JSONUtils.toQysResponse(response, DocumentAddResult.class);
if(responseObj.getCode() == 0) {
    DocumentAddResult result = responseObj.getResult();
    logger.info("添加合同文档成功,文档ID:{}", result.getDocumentId());
} else {
    logger.info("请求失败,错误码:{},错误信息:{}", responseObj.getCode(), responseObj.getMessage());
}
C#示例

string serverUrl = "https://openapi.qiyuesuo.cn";
string accessKey = "替换为您申请的开放平台App Token";
string accessSecret = "替换为您申请的开放平台App Secret";
SDKClient client = new SDKClient(accessKey, accessSecret, serverUrl);
string contractId = "2589012016299597907";
string templateId = "2562841550577214123";
// 组装根据模板创建文档请求
DocumentAddByTemplateRequest request = new DocumentAddByTemplateRequest(contractId, "添加模板", templateId);
// 设置模板参数内容
request.AddTemplateParam(new TemplateParam("Sender", "契约锁"));
request.AddTemplateParam(new TemplateParam("Reciver1", "开放平台"));
request.AddTemplateParam(new TemplateParam("Reciver2", "对接方公司"));
string response = null;
try
{
    response = client.Service(request);
}
catch (Exception e)
{
    throw new Exception(e.Message);
}
// 解析返回内容
SdkResponse<DocumentAddResult> responseObject = HttpJsonConvert.DeserializeResponse<DocumentAddResult>(response);
if (!responseObject.Code.Equals(0))
{
    throw new Exception("请求失败,失败原因:" + responseObject.Message);
}
Console.WriteLine(“请求接口成功”);
Console.WriteLine(HttpJsonConvert.SerializeObject(responseObject));
PHP示例

// 初始化$sdkClient
class Util {
    const     url = "https://openapi.qiyuesuo.cn";
    const     accessKey = "替换为您申请的开放平台App Token";
    const     accessSecret = "替换为您申请的开放平台App Secret";
}
$sdkClient = Util::getSDk();
$documentAddByTemplateRequest = new DocumentAddByTemplateRequest();
$documentAddByTemplateRequest->setContractId('2590758386643734529');
$documentAddByTemplateRequest->setBizId("1111111");
$documentAddByTemplateRequest->setTitle('V2添加模板文档');
$documentAddByTemplateRequest->setTemplateId('2558597440364655396');
/\*\*填写模板参数\*\*/
$templateParam1 = new TemplateParam();
$templateParam1->setName("乙方姓名");
$templateParam1->setValue("张三");
$templateParams = array();
array_push($templateParams, $templateParam1);
$documentAddByTemplateRequest->setTemplateParams($templateParams);
$result = $sdkClient->service($documentAddByTemplateRequest);
print_r($result);
return $result;
Python示例

#初始化SdkClient
url = "https://openapi.qiyuesuo.cn"
accessToken = '替换为您申请的开放平台App Token'
accessSecret = '替换为您申请的开放平台App Secret'
sdkClient = SdkClient(url, accessToken, accessSecret)
documentbytemplate_request = DocumentAddByTemplateRequest()
documentbytemplate_request.set_title('模板上传文档')
documentbytemplate_request.set_contractId(draft_contractid)
documentbytemplate_request.set_templateId('2492236993899110515')
# 若模板为参数模板,设置模板中的参数值
documentbytemplate_request.set_templateParams(
    [TemplateParam('接收方1', '契约锁'), TemplateParam('接收方2', '电子合同')])
# 请求服务器
documentbytemplate_response = sdkClient.request(documentbytemplate_request)
# 解析返回数据
documentbytemplate_mapper = json.loads(documentbytemplate_response)
if documentbytemplate_mapper['code'] != 0:
    raise Exception('根据模板添加合同文档失败,失败原因:', documentbytemplate_mapper['message'])
documentbytemplate_result = documentbytemplate_mapper['result']
template_documentId = documentbytemplate_result['documentId']
print('根据模板添加合同文档成功,文档ID:', template_documentId)
Go示例

sdkClient := http.NewSdkClient("https://openapi.qiyuesuo.cn", "替换为您申请的开放平台App Token", "替换为您申请的开放平台App Secret")
req := request.DocumentAddByTemplateRequest{}
req.ContractId = "3119917770918068335"
req.Title = "goTemplateFile5"
req.TemplateId = "2766933842559242287"
var templateParams []*model.TemplateParam
param1 := model.TemplateParam{}
param1.Name = "param1"
param1.Value = "v1"
param2 := model.TemplateParam{}
param2.Name = "param2"
param2.Value = "v2"
templateParams = append(templateParams, ¶m1)
templateParams = append(templateParams, ¶m2)
req.TemplateParams = templateParams
sort := -2
req.DocumentSort = &sort
response, err := sdkClient.Service(req)
if err != nil {
    fmt.Println("request failed,", err.Error())
    return
}
fmt.Println(response)

返回参数

参数 类型 长度 描述
responseCode String 响应码
message String 200 响应消息
result Response 返回数据

Response(返回数据):

参数 类型 长度 描述
documentId String 19 合同文档ID

响应码

(全局响应码请查看文档末“全局响应码”):

响应码 描述
11101003 合同不存在
11011101 无效的合同状态
11041801 公司不存在