用模板添加合同文档
描述
使用模板文件添加合同文档,模板文件需提前在契约锁云平台上维护,仅草稿状态的合同可添加合同文档。
请求地址
/v2/document/addbytemplate
请求方法
POST
请求格式
application/json;charset=UTF-8
请求参数
参数 | 类型 | 是否必传 | 长度 | 描述 | 示例 |
---|---|---|---|---|---|
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 | 公司不存在 |