添加签署方

描述

合同在“签署中”或“已完成”状态下,并且业务分类支持“发起后允许继续发送签署”,可以调用该接口添加签署方。在业务分类配置的“基础信息设置->签署方”下设置“发起后允许继续发送签署”。

请求地址

/v2/signatory/add

请求方法

POST

请求格式

application/json;charset=UTF-8

请求参数

参数 类型 必须 长度 描述 示例

contractId

Long

CY

合同ID

bizId

String

CY

业务ID;
一个合同对应一个bizId,不能重复

tenantName

String

CY

发起方名称;如果合同发起方不是对接方,且通过bizId确定合同时,传入此参数

signatory 点“+”展开

Signatory

Y

签署方信息

locateAllStamperKeywords

Boolean

N

是否必须找出全部签署位置传入的关键字,默认为true;传入false时,对于传入的关键字定位的签署位置,只需定位到任意一个签署位置的关键字即可

请求示例

                
POST /v2/signatory/modify 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":2698131828788437206,
    "signatory":{
        "tenantType":"COMPANY",
        "tenantName":"来看看调用的一大堆接口-1",
        "receiver":{
            "contact":"15164046497",
            "contactType":"MOBILE"
        }
    }
}

            

返回参数

参数 类型 长度 描述

responseCode

String

响应码

message

String

200

响应消息

result

Signatory

签署方信息

响应码

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

响应码 描述
11011304 业务分类配置无权限,例如:业务分类配置发起后不能添加签署方,则发起后添加时报此错误
14990002 权限不匹配
21990001 内部错误:如果未找到对应的开放平台错误码,统一以此错误码返回;
11990005 无效的参数:参数格式错误,必传参数未传,参数超出取值范围,参数类型不正确;
11041701 未找到该员工

添加签署方

描述

合同在“签署中”或“已完成”状态下,并且业务分类支持“发起后允许继续发送签署”,可以调用该接口添加签署方。在业务分类配置的“基础信息设置->签署方”下设置“发起后允许继续发送签署”。

请求地址

/v2/signatory/add

请求方法

POST

请求格式

application/json;charset=UTF-8

请求参数

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

参数 类型 是否必传 长度 描述 示例
contractId Long CY 合同ID
bizId String CY 业务ID;
一个合同对应一个bizId,不能重复
tenantName String CY 发起方名称;如果合同发起方不是对接方,且通过bizId确定合同时,传入此参数
signatory Signatory Y 签署方信息
locateAllStamperKeywords Boolean N 是否必须找出全部签署位置传入的关键字,默认为true;传入false时,对于传入的关键字定位的签署位置,只需定位到任意一个签署位置的关键字即可

Signatory(签署方):

参数 类型 是否必传 长度 描述 示例
class String 签署方ID(接口返回值)
tenantType String Y 签署方类型:COMPANY(公司),
PERSONAL(个人)
status String 签署方状态(接口返回值):DRAFT(草稿)
RECALLED(已撤回),SIGNING(签署中),REJECTED(已退回),SIGNED(已完成),EXPIRED(已截止签署),FILLING(拟定中),WAITING(待签署),INVALIDING(作废中),INVALIDED(已作废)
tenantName String Y 签署方名称
receiver User Y 接收人
serialNo Integer 签署顺序(接口返回值)
actions List<Action> N 签署动作(签署流程)
attachments List<Attchment> N 附件要求;用于指定用户签署时上传的附件
userAuthInfo UserAuthInfo N 指定签署方认证信息
stampers List<Stamper> N 签署位置;用于指定个人签署方的签署位置,公司签署方的签署位置请在Action中指定
category Category N 业务分类;只能指定公司类型接收方(内部企业)的业务分类,可以配合设置业务分类的查看人,来控制接收方中查看人权限
defaultCategoryAccepted Boolean N 仅公司类型接收方(内部企业)生效,当业务分类不传时,是否取接收方默认业务分类【传参方式】TRUE:满足发起方配置的签署要求基础上,同需满足接收方默认业务分类配置的签署要求进行签署 FLASE:接收方按发起方配置的签署要求进行签署

User(个人用户):

参数 类型 是否必传 长度 描述 示例
name String N 名称,作为抄送接收方参数时,该参数必传
contact String Y 联系方式
contactType String Y 联系类型:MOBILE(手机号),EMAIL(邮箱),EMPLOYEEID(员工ID),NUMBER(员工编号)

Action(签署动作/签署流程):

参数 类型 是否必传 长度 描述 示例
class String 签署节点ID(接口返回值)
type String Y 类型:COMPANY(企业签章),OPERATOR(经办人签字)
LP(法定代表人签字),AUDIT(审批),PERSONAL(审批并签字)
status String 动作状态(接口返回值):INIT(初始化)
START(已启动),FINISH(已完成),STOP(意外终止)
name String N 名称
serialNo Integer N 执行顺序,从0开始
stampers List<Stamper> N 签署位置;用于指定公司签署方的签署位置
corpSealIds List<Long> N 9 印章ID集合
【作用】
用于指定签署时可选印章列表,仅对发起方和内部企业接收方生效
【传参方式】
可传一个或多个,最多不可超过9个
【特殊说明】
1、当指定了多个印章时,该签署节点将不可进行批量签署,且调用静默签署接口时需要在接口重新指定印章;
2、对于内部企业接收方,仅当内部接收方没有收件流程设置,且defaultCategoryAccepted为false或者在接口指定了非默认的业务分类时生效
[2963869214318056324, 2963995940230582347]
corpOperators List<User> N 操作人
【作用】
1、可指定印章签章人或审批人
2、支持指定发起方和接收方签章人
【特殊说明】
1、对于内部企业接收方,仅当内部接收方没有收件流程设置,且defaultCategoryAccepted为false或者在接口指定了非默认的业务分类时生效
2、对于外部企业接收方,仅当操作人同为经办人时才生效,且不可用于审批或审批签字节点
详见User

Stamper(签署位置):

参数 类型 是否必传 长度 描述 示例
type String Y 签署类型:
COMPANY(公章),PERSONAL(个人签名),
LP(法人章),TIMESTAMP(时间戳),
ACROSS_PAGE(骑缝章), ACROSS_PAGE_ODD(奇数页骑缝章),ACROSS_PAGE_EVEN(偶数页骑缝章),ACROSS_PAGE_SCOPE(指定页面范围骑缝章)
COMPANY
acrossType String N 骑缝章位置指定方式
【作用】
指定骑缝章位置时,可以通过此参数控制位置的指定方式
【传参】
取值范围:SINGLE_DOCUMENT(每份文档单独指定骑缝章位置),ALL_DOCUMENT(多份文档合并指定骑缝章位置);不传值默认为:SINGLE_DOCUMENT(每份文档单独指定骑缝章位置)。
SINGLE_DOCUMENT
sealPageConfig String N 骑缝章自定义页面加盖
【传参】
1、可传入页码或页码范围,多组页码或页码范围之间用英文逗号(,)分隔,例如:2,4 ~ 7,8 ~ 11。
2、当rectType(签署位置类型)为ACROSS_PAGE_SCOPE(指定页面范围骑缝章)时,此参数必填。
1,2~3
documentId String Y 合同文档ID
documentIds String N 签署文档class集合
【作用】
用于指定签署位置所在的签署文档
2964011533600084814,2964011533611111111
keyword String N 关键字
keywordIndex Integer N 关键字索引:1代表第1个关键字,0代码所有关键字
,-1代表倒数第1个关键字;默认为1
page Integer N 坐标页码,0代表所有,-1代表最后一页
offsetX Decimal N 横坐标/关键字偏移量
offsetY Decimal N 纵坐标/关键字偏移量
wclassth Integer N 签署位置宽度
【作用】
设置签署位置的宽度,防止用户在文件上添加的签名过大或过小
【传参方式】
1、取值范围10-120;
2、支持个人签名、时间戳位置,不支持签章位置;
3、仅传宽度时,高度按比例适配,两者均传参以宽度为准;
40
height Integer N 签署位置高度
【作用】
设置签署位置的高度,防止用户在文件添加的签名过大或过小
【传参方式】
1、取值范围4-48;
2、支持个人签名、时间戳位置,不支持签章位置;
3、仅传宽度时。高度按比例适配。两者均传参以宽度为准;
10
rotationDegrees Double N 签署位置旋转角度
【作用】
指定签署位置的旋转角度,当文件为横向或扫描件存在角度偏移时,可以指定签署位置的旋转角度
【传参方式】
1、取值范围0-360;
2.支持个人签名、时间戳、签章位置;
3、旋转中心为签署图片中心,方向为顺时针;
10

Attchment(附件要求):

参数 类型 是否必传 长度 描述 示例
class String 附件ID(接口返回值)
title String Y 名称
required Boolean N 是否必须;默认为false
needSign Boolean N 是否需要签署;默认为false

UserAuthInfo(签署方认证信息):

参数 类型 是否必传 长度 描述 示例
classCardNo String N 指定认证身份证号码
bankNo String N 指定认证银行卡号,仅银行卡认证时生效
bankMobile String N 指定认证银行卡预留手机号,仅银行卡认证时生效

Category(业务分类):

参数 类型 是否必传 长度 描述 示例
class String N 业务分类ID
name String N 业务分类名称;
如果class为空时,使用name来确定业务分类,
需要保证name对应的业务分类唯一

请求示例

Http示例

POST /v2/signatory/modify 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":2698131828788437206,
    "signatory":{
        "tenantType":"COMPANY",
        "tenantName":"来看看调用的一大堆接口-1",
        "receiver":{
            "contact":"15164046497",
            "contactType":"MOBILE"
        }
    }
}
Java示例

# 初始化SdkClient
url = "https://openapi.qiyuesuo.cn"
accessToken = '替换为您申请的开放平台App Token'
accessSecret = '替换为您申请的开放平台App Secret'
sdkClient = SdkClient(url, accessToken, accessSecret)
SignatoryAddRequest signatoryAddRequest=new SignatoryAddRequest();
signatoryAddRequest.setContractId(2698150064800145919L);
Signatory signatory = new Signatory();
signatory.setTenantName("12344321");
signatory.setTenantType("COMPANY");
signatory.setReceiver(new User("15164046497", "MOBILE"));
signatoryAddRequest.setSignatory(signatory);
String response = sdkClient.service(signatoryAddRequest);
SdkResponse responseObj = JSONUtils.toQysResponse(response, Signatory.class);
if(responseObj.getResponseCode().equals("00000000"))) {
    Signatory result = responseObj.getResult();
    logger.info("添加签署方成功,签署方ID:{}", result.getId());
} else {
    logger.info("请求失败,错误码:{},错误信息:{}", responseObj.getCode(), responseObj.getMessage());
}
PHP示例

// 初始化$sdkClient
class Util {
    const     url = "https://openapi.qiyuesuo.cn";
    const     accessKey = "替换为您申请的开放平台App Token";
    const     accessSecret = "替换为您申请的开放平台App Secret";
}
$sdkClient = Util::getSDk();
$request = new SignatoryAddRequest();
$request->setContractId(2698150064800145919);
$signatory = new Signatory();
$signatory->setTenantName("12344321");
$signatory->setTenantType("COMPANY");
$receiver = new User();
$receiver->setName("孙*雪");
$receiver->setContact("188****7942");
$receiver->setContactType("MOBILE");
$signatory->setReceiver($receiver);
$request->setSignatory($signatory);
$result = $sdkClient->service($request);
print_r($result);
Python示例

signatoryAddRequest = SignatoryAddRequest()
signatoryAddRequest.set_contractId(2695602165676553072)
person_signatory = Signatory()
person_signatory.set_tenantType("PERSONAL")
person_signatory.set_tenantName("胡*坤")
person_signatory.set_receiver(User("胡*坤", "151****6497", "MOBILE"))
signatoryAddRequest.set_signatory(person_signatory)
signatoryAddResponse = sdkClient.request(signatoryAddRequest)
print('创建合同草稿:\n', str(signatoryAddResponse), '\n')
Go示例

sdkClient := http.NewSdkClient("https://openapi.qiyuesuo.cn", "替换为您申请的开放平台App Token", "替换为您申请的开放平台App Secret")
req := request.SignatoryAddRequest{}
req.ContractId = "3119917770918068335"
signatory := model.Signatory{}
signatory.TenantName = "宋三"
signatory.TenantType = "PERSONAL"
receiver := model.User{}
receiver.Name = "宋三"
receiver.Contact = "10036350002"
receiver.ContactType = "MOBILE"
signatory.Receiver = &receiver
signatorySerialNo := 3
signatory.SerialNo = &signatorySerialNo
req.Signatory = &signatory
response, err := sdkClient.Service(req)
if err != nil {
    fmt.Println("request failed,", err.Error())
    return
}
fmt.Println(response)

返回参数

参数 类型 长度 描述
responseCode String 响应码
message String 200 响应消息
result Signatory 签署方信息

响应码

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

响应码 描述
11011304 业务分类配置无权限,例如:业务分类配置发起后不能添加签署方,则发起后添加时报此错误
14990002 权限不匹配
21990001 内部错误:如果未找到对应的开放平台错误码,统一以此错误码返回;
11990005 无效的参数:参数格式错误,必传参数未传,参数超出取值范围,参数类型不正确;
11041701 未找到该员工
常见
问题
在线
客服
电话
咨询