平台简介
新手指南
API协议
API文档
单点登录集成
小程序插件
公告
常见问题
开放平台使用操作手册
帮助中心 / 开放平台帮助文档 / 用文件添加合同文档
用文件添加合同文档
使用本地文件添加合同文档,仅草稿状态的合同可添加合同文档。

用文件添加合同文档

描述

使用本地文件添加合同文档,仅草稿状态的合同可添加合同文档。

请求地址

/v2/document/addbyfile

请求方法

POST

请求格式

multipart/form-data;charset=UTF-8

请求参数

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

参数 类型 是否必传 长度 描述 示例
contractId String CY 19 合同ID,合同ID与业务ID二选一,不能同时为空 2931411786447082239
bizId String CY 50 业务ID,合同ID与业务ID二选一,不能同时为空 6331411786447082982
tenantName String CY 100 子公司名称,若使用业务ID添加合同文件,且合同是以子公司身份创建的,则需要传递该值,用于确定合同主体 阿里巴巴子公司
title String Y 100 名称 合同文档abc
file MultipartFile Y 合同文件 ,文件大小:<=30MB C://文件/合同文档.docx
fileSuffix String Y 文件类型(文件后缀):
doc,docx,pdf,jpeg,png,jpg,gif,tiff,html,htm,xls,xlsx
docx
documentSort Integer N 文档指定排序 1
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"]

签署位置说明:

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

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/addbyfile HTTP/1.1
Host: [host]
x-qys-open-timestamp: [替换为请求头生成的Timestamp]
x-qys-open-signature: [替换为请求头生成的Signature]
x-qys-open-accesstoken: [替换为请求头生成的Token]
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="contractId"
2591540368898105360
------WebKitFormBoundary7MA4YWxkTrZu0gW--
Content-Disposition: form-data; name="title"
文件文档
------WebKitFormBoundary7MA4YWxkTrZu0gW--
Content-Disposition: form-data; name="file"; filename="/C:/Users/QYS/Desktop/Test/授权.pdf
------WebKitFormBoundary7MA4YWxkTrZu0gW--
Content-Disposition: form-data; name="fileSuffix"
pdf
------WebKitFormBoundary7MA4YWxkTrZu0gW--
Java示例

// 初始化sdkClient
String serverUrl = "https://openapi.qiyuesuo.cn";
String accessKey = "替换为您申请的开放平台App Token";
String accessSecret = "替换为您申请的开放平台App Secret";
SdkClient sdkClient = new SdkClient(serverUrl, accessKey, accessSecret);
// 添加合同文档
DocumentAddByFileRequest request = new DocumentAddByFileRequest(contractId,
                new StreamFile(new FileInputStream("E:/test/NoSign.pdf")), "pdf", "文件一");
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#示例

//初始化sdkClient
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 path = "C:\\Users\\Richard Cheung\\Documents\\契约锁\\测试\\人事合同.pdf";
Stream file = new FileStream(path, FileMode.Open);
// 组装根据文件添加文档请求
DocumentAddByFileRequest request = new DocumentAddByFileRequest(contractId, "添加文件", file, "pdf");
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();
$documentAddByFileRequest = new DocumentAddByFileRequest();
$documentAddByFileRequest->setContractId('2590758386643734529');
$documentAddByFileRequest->setBizId("1111111");
$file_path = "C:/Users/QYS/Desktop/Test/444.pdf";
$file_path = iconv("UTF-8", "GBK", realpath($file_path));
$file = new \CURLFile($file_path);
$documentAddByFileRequest->setFile($file);
$documentAddByFileRequest->setFileSuffix('pdf');
$documentAddByFileRequest->setTitle('V2添加文档');
$result = $sdkClient->service($documentAddByFileRequest);
print_r($result);
return $result;
Python示例

#初始化SdkClient
url = "https://openapi.qiyuesuo.cn"
accessToken = '替换为您申请的开放平台App Token'
accessSecret = '替换为您申请的开放平台App Secret'
sdkClient = SdkClient(url, accessToken, accessSecret)
documentbyfile_request = DocumentAddByFileRequest()
file = open("C:\\Users\\Richard Cheung\\Documents\\契约锁\\测试\\测试合同.pdf", "rb")
documentbyfile_request.set_file(file)
documentbyfile_request.set_contractId(draft_contractid)
# 将fileSuffix替换为将上传文件正确的文件类型
documentbyfile_request.set_fileSuffix('pdf')
documentbyfile_request.set_title('本地文件上传文档')
# 请求服务器
documentbyfile_response = sdkClient.request(documentbyfile_request)
# 解析返回数据
documentbyfile_mapper = json.loads(documentbyfile_response)
if documentbyfile_mapper['code'] != 0:
    raise Exception('根据本地文件添加合同文档失败,失败原因:', documentbyfile_mapper['message'])
documentbyfile_result = documentbyfile_mapper['result']
file_documentId = documentbyfile_result['documentId']
print('根据本地文件添加合同文档成功,文档ID:', file_documentId)
Go示例

sdkClient := http.NewSdkClient("https://openapi.qiyuesuo.cn", "替换为您申请的开放平台App Token", "替换为您申请的开放平台App Secret")
req := request.DocumentAddByFileRequest{}
req.ContractId = "3121362688614077231"
req.Title = "goFile1"
req.FileSuffix = "pdf"
sort := 1
req.DocumentSort = &sort
file, _ := os.Open("/Users/sgf/Downloads/文件模板三.pdf")
req.File = &http.FileItem{file, ""}
response, err := sdkClient.Service(req)
if err != nil {
    fmt.Println("request failed,", err.Error())
    return
}
fmt.Println(response)

返回参数

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

Response(返回数据):

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

响应码

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

响应码 描述
1101 INVALID CONTRACT STATUS,合同状态无效;
只能为“草稿”状态合同添加文档。
1403 INVALID FILE,无效的合同文件;
合同文件转换失败,可能是由于文件损坏或者文件类型错误。