电子签章(在线签合同)

企业与自然人在线签署电子合同:自然人在托管页完成实名认证 + 手写签名, 企业预先授权后自动盖章(静默签),签署完成文件带 CA 数字证书与国家授时中心时间戳。鉴权与全站一致:X-App-Key + X-Timestamp + X-Sign 三个请求头; 上游令牌由平台代管,你不用关心。参数与上游原字段一致、原样透传;返回统一为data.ok(业务成败)+ 平铺业务字段 + reason(失败原文)+ raw(原始返回)。计费点只有一个:⑦创建签署任务,创建成功计一次,失败不计。

流程总览:哪些只做一次,哪些每单都做

企业开户(每个企业一次):
  ① company/register 创建企业账号 → unionId
  ② auth/url 获取实名认证页 → 法人打开完成人脸实名
  ③ company/silent-auth 静默签授权 → 管理员短信确认(有效期 365 天)
  ④ seal/generate 生成企业印章 → sealId

自然人开户(每人一次):
  ⑤ person/register 创建个人账号 → unionId

每笔签署(常规流程):
  ⑥ file/upload 上传合同 → fileCode
  ⑦ task/create 创建签署任务(★计费) → taskNo
  ⑧ task/link 拿签署链接 → 发给自然人:实名 + 手写签名 → 企业自动盖章
  ⑨ task/detail 查详情/取签署完成文件(任务完成也有回调推送)

① 创建企业账号

POST  https://openapi.kailingteck.com/api/v1/esign/company/register

参数	必填	说明
`uid`	必填	你系统内该企业的唯一标识(8-20字符)
`mobile`	必填	经办人手机号
`orgName`	必填	企业名称
`legalName`	必填	法人姓名
`legalNo`	必填	法人身份证号
`creditNo`	建议	统一社会信用代码

返回 unionId——该企业在签章体系的唯一标识,后续所有接口都用它。

② 获取实名认证页

POST  https://openapi.kailingteck.com/api/v1/esign/auth/url

参数	必填	说明
`unionId`	必填	主体唯一标识(企业或个人)
`notifyUrl`	必填	认证结果回调地址(直接回调到你系统)
`companyAuthType`	选填	企业实名方式:1 企业四要素+法人个人认证(推荐,最快)/2 三要素+对公打款/3 四要素+授权书
`authTypes`	选填	个人实名方式:1 三要素 / 2 银行卡四要素 / 3 人脸,逗号分隔
`redirectUrl`	选填	认证完成后的跳转地址

返回 pcUrl / h5Url,交给企业法人/本人打开完成认证。 ★企业必须先实名,否则生成印章报「50001 该账号未认证」。⚠ 链接含多段参数,转发必须整行完整,丢参会报「认证id不能为空」。

③ 静默签授权(自动盖章授权)

POST  https://openapi.kailingteck.com/api/v1/esign/company/silent-auth

参数	必填	说明
`signerUnionId`	必填	企业 unionId
`notifyUrl`	选填	授权结果回调地址

返回授权页链接,企业管理员打开后短信验证码确认。授权有效期 365 天,到期重新授权。 ★授权和实名是两个独立流程:授权页不含实名,实名另走②。

④ 生成企业印章

POST  https://openapi.kailingteck.com/api/v1/esign/seal/generate

参数	必填	说明
`unionId`	必填	企业 unionId(须已实名)
`name`	必填	印章名称,如「合同专用章」
`color / font / shape`	选填	颜色 0红/1蓝/2黑;字体 0仿宋/1楷体/2黑体;形状 0圆/1椭圆

返回 sealId——创建签署任务时企业静默签必传的 signerSealId。

⑤ 创建个人账号

POST  https://openapi.kailingteck.com/api/v1/esign/person/register

参数	必填	说明
`uid`	必填	你系统内该用户唯一标识(8-20字符)
`mobile`	必填	用户手机号
`signAuthTypes`	选填	签署页实名方式:1 三要素/2 银行卡四要素/3 人脸。★传 "2" 可实现全程免人脸
`name / identNo / bankCardNo`	选填	预填姓名/身份证/银行卡,省用户输入

返回 unionId 与 registerCode(3 注册成功 / 1 已存在且实名一致 / 2 已存在但实名不一致,需业务侧处理)。

⑥ 上传合同文件

POST  https://openapi.kailingteck.com/api/v1/esign/file/upload

参数	必填	说明
`file`	必填	文件 URL 或 base64(不带头信息),小于 10M
`fileName`	必填	文件名
`fileSuffix`	必填	pdf / doc / docx
`fileType`	必填	固定传 1(合同)
`unionId`	必填	发起方(企业)unionId

返回 fileCode,同一文件可复用于多个签署任务。★合同模板建议用微软 Office 转 PDF(WPS 文档做关键词替换不支持);关键词占位用 <英文关键字>,避开 q、y、p、g、j、Q 字母。

⑦ 创建签署任务(★计费点)

POST  https://openapi.kailingteck.com/api/v1/esign/task/create

参数	必填	说明
`unionId`	必填	发起方(企业)unionId
`fileCode`	必填	⑥返回的文件编号
`notifyUrl`	必填	签署结果回调地址(每一方签完都推一次)
`sortType`	必填	1 有序(按 sortNo 依次签)/ 2 无序
`taskTitle`	必填	任务标题(≤50字)
`signers`	必填	签署方数组,字段见下
`authType`	选填	签署意愿:1 短信验证码(默认)/ 2 人脸
`signDateEnable`	选填	传 1=印章下自动加盖签署日期(合同里就别再排日期栏,避免重复)
`keywordReplacements`	选填	合同关键词替换填充(模板动态填值)

signers 每个签署方:signerUnionId(必)、userType(必,1 个人/2 企业)、signType(0 手动签默认/1 静默签自动盖章)、stampType(1 坐标/2 关键字)、areas 或 keywords(盖章位置)、signerSealId(企业静默签必传=④的 sealId)、sortNo(有序签顺序)。

{
  "unionId": "企业unionId", "fileCode": "⑥的fileCode",
  "notifyUrl": "https://你的回调地址", "sortType": "1",
  "taskTitle": "服务协议签署", "authType": "2", "signDateEnable": "1",
  "signers": [
    { "signerUnionId": "个人unionId", "userType": "1", "signType": "0",
      "stampType": "2", "keywords": [{ "keyword": "乙方签字" }], "sortNo": 1 },
    { "signerUnionId": "企业unionId", "userType": "2", "signType": "1",
      "signerSealId": "④的sealId",
      "stampType": "2", "keywords": [{ "keyword": "甲方盖章" }], "sortNo": 2 }
  ]
}

返回 taskNo。创建成功即计费一次;失败(如上游余额不足)不计。

⑧ 获取签署链接

POST  https://openapi.kailingteck.com/api/v1/esign/task/link

传 taskNo + 签署方 unionId,返回该签署方的signH5Url / signPCUrl,发给本人打开:实名核验 → 手写签名 → 提交(轮到企业时自动盖章)。 signStatus:1 可签署 / 2 已签署 / 3 拒签 / 9 顺序签未轮到。

⑨ 任务详情 / 取签署完成文件

POST  https://openapi.kailingteck.com/api/v1/esign/task/detail

传 taskNo + 发起方 unionId。taskStatus:-30 已过期 / -20 已撤销 / -10 已拒签 / 10 待签署 / 20 已完成。完成后 contracts[].contractUrl 是签署完成文件,⚠ 临时地址,须立即下载归档到你自己的存储。

异步回调(上游 → 你的 notifyUrl)

POST + JSON 直推到你传入的 notifyUrl。notifyType:1 认证注册 / 2 合同签署或拒签 / 3 实名信息授权 / 4 静默签授权 / 5 扫码签。签署回调带 taskNo、taskStatus、signers(拒签时另有 refusedReason)。

★处理成功必须响应字符串 success(否则最多重发 5 次);须按 notifyNo 做幂等去重。

常见报错怎么处理

上游码	含义	怎么办
10010	余额不足	上游签署次数用完,联系平台充值(SaaS 与标准API次数池是分开的)
50001 / 30002	账号/签署主体未认证	先走②完成实名认证,再生成印章/发起签署
11003	未找到关键词	检查合同内关键词与参数是否一字不差;WPS 编写的文档不支持关键词替换
10009	服务暂未开通	该接口权限未开,联系平台
99999	其他异常	稍后重试,仍失败带 raw 里的 requestId 联系平台

实测避坑清单

实名与静默签授权是两个独立页面:授权页只做短信确认,不含实名;都要走。
个人配 signAuthTypes="2"(银行卡四要素)+ 任务 authType="1"(短信意愿)可全程免人脸;要强人脸就都传人脸。
signDateEnable=1 时印章自动带日期,合同模板里删掉自排的日期栏,避免出现两个日期。
认证/授权/签署链接都含多段 URL 参数,转发必须整行完整,微信里断行丢参数是最常见的坑。
签署完成文件是临时地址,回调收到完成通知后立即下载归档。
签署时如遇「获取CA协议失败」属上游平台侧问题(CA 体系升级期),联系平台协调处理。