电子签名SDK
    点击展开收起
    电子签名SDK 2.0 产品介绍
    开发前准备
    接口列表（新对接需先找e签宝审批）
    SDK&DEMO下载
    常见QA
    附录

    独立意愿对接文档

    更新时间：2025-04-15 15:16:28

    功能概述

    独立意愿认证方式，是由e签宝提供的网页版认证方式，开发者可通过接口任意选择其中一种或多种意愿认证方式提供给签署用户选择使用。同时，开发者也可以平台用户PDF签署（意愿bizId批量签署）接口，来实现多样化意愿认证方式进行签署。

    对接流程

    h5流程图

    1、用户业务页面通过后台接口获取意愿认证页面

    2、通过页面按钮点击跳到意愿页面

    3、用户进行刷脸操作

    4、完成意愿认证跳回用户业务页面

    PC流程图

    1、用户业务页面通过后台接口获取意愿认证页面

    2、通过页面按钮点弹出意愿页面窗口

    3、用户通过手机进行刷脸操作

    4、完成意愿认证跳回意愿页面

    5、用户页面后台通过查询意愿状态轮询意愿认证状态，如果意愿成功，关闭意愿窗口页面

    请求域名

    环境

    域名

    沙箱环境

    https://smlopenapi.esign.cn

    正式环境

    https://openapi.esign.cn

    接口列表

    接口名称

    API接口

    请求方式

    描述

    获取鉴权Token

     /v1/oauth2/access_token

    GET

    查看文档

    获取意愿地址

    /v1/sign/willingness/createSignAuth

    POST

    查看文档

    查询意愿状态

    /v1/sign/willingness/queryWillAuthResult

    POST

    查看文档

    API接口详解

    获取鉴权Token

    接口描述

    通过appid和secrect请求api 授权码，用来请求业务api。token有效时长为120分钟。如果有多台机器建议使用分布式存储，新旧token会共存5分钟。

    接口地址

    /v1/oauth2/access_token

    请求参数

    参数名称

    类型

    必选

    参数说明

    appId

    string

    是

    应用id，需在e签宝开放平台创建

    secret

    string

    是

    应用密钥，不可泄露

    grantType

    string

    是

    授权类型，固定值: client_credentials

    响应参数

    展开全部参数参数名称

    类型

    必选

    参数说明

    code

    int

    是

    业务码，0表示成功

    message

    string

    否

    信息

    data

    object

    否

    业务信息


    token

    string

    否

    授权码

    注意：120分钟失效，请在expiresIn参数的有效截止时间失效前重新获取token

    expiresIn

    string

    否

    授权码有效期截止时间（毫秒）

    refreshToken

    string

    否

    授权刷新请求码

    注意：此字段为预留项，暂不启用

    请求示例

    GET 【请求域名】/v1/oauth2/access_token?appId=xx&secret=xx&grantType=client_credentials

    响应示例

    {
    "code":0,
    "message":"成功",
    "data":{
        "expiresIn":"1569211376807",
        "token":"eyJ0eXAiOiJKxxxx"
    }
}

    获取意愿地址

    接口描述

    意愿地址可以在H5和pc端同时使用

    接口地址

    /v1/sign/willingness/createSignAuth

    请求头

    提供两种安全接入方式，对应参数如何获取，参考文档【请点击】。

    方式一：请求签名鉴权

    参数名称

    类型

    必选

    参数说明

    X-Tsign-Open-App-Id

    string

    是

    项目ID

    X-Tsign-Dns-App-Id

    String

    否

    项目ID。在微信小程序中对接，该参数必传；其他场景无需添加该参数

    Content-Type

    string

    是

    application/json;charset=UTF-8

    X-Tsign-Open-Ca-Timestamp

    string

    是

    API 调用者传递时间戳，值为当前时间的毫秒数，也就是从1970年1月1日起至今的时间转换为毫秒，时间戳有效时间为15分钟，为了防重放攻击

    Accept

    string

    是

    建议统一填写 */*

    X-Tsign-Open-Ca-Signature

    string

    是

    签名字符串

    Content-MD5

    string

    否

    当请求 Body 非 Form 表单时，可以计算 Body 的 MD5 值传递给云网关进行 Body MD5 校验。建议当请求 Body 非 Form 表单时，加上此请求头。

    X-Tsign-Open-Auth-Mode

    string

    是

    选择请求方式进行鉴权，固定值，Signature

    方式二：OAuth2.0鉴权

    当安全接入选择OAuth2.0鉴权方式，请点击查阅详情。

    请求参数

    展开全部参数参数名称

    类型

    必选

    参数说明

    示例值

    name

    String

    是

    用户个人姓名

    idNumber

    String

    是

    用户个人证件号

    certType

    String

    否

    用户个人证件类型，默认中国大陆身份证

    INDIVIDUAL_CH_IDCARD - 中国大陆身份证（默认值）

    INDIVIDUAL_CH_TWCARD - 台湾来往大陆通行证（台胞证）

    INDIVIDUAL_CH_HONGKONG_MACAO - 港澳来往大陆通行证（回乡证）

    INDIVIDUAL_PASSPORT - 护照

    INDIVIDUAL_CH_RESIDENCE_PERMIT_HK_MO_TW - 港澳台居民居住证（18位810开头）

    INDIVIDUAL_CH_GREEN_CARD - 外国人永久居留身份证（18位9开头）

    mobile

    String

    否

    用户手机号

    appScheme

    String

    否

    App打开协议，用于重定向跳转到app端

    from

    String

    否

    app，如app对接独立意愿，需要传入此参数

    app

    noticeDeveloperUrl

    String

    否

    开发者回调通知地址

    redirectUrl

    String

    是

    意愿完成跳转地址

    isPCRedirect

    Boolean

    否

    是否需要pc端重定向跳转，默认false。

    true-PC端意愿认证成功，支持重定向跳转

    false-PC端意愿认证成功，不会进行跳转

    willTypes

    List

    否

    页面指定意愿认证方式，可指定类型如下：

    CODE_SMS 短信验证码

    FACE_ZHIMA_XY 支付宝刷脸

    FACE_FACE_LIVENESS_RECOGNITION 快捷刷脸

    FACE_WE_CHAT_FACE 微信小程序刷脸

    以下两种方式需联系交付顾问开通后方可使用：
    FACE_TECENT_CLOUD_H5 腾讯云刷脸

    PSN_AUDIO_VIDEO_ESIGN 智能视频认证

    willDefaultType

    String

    否

    页面展示默认的意愿认证方式，方式类型如下：

    CODE_SMS 短信验证码

    FACE_ZHIMA_XY 支付宝刷脸

    FACE_FACE_LIVENESS_RECOGNITION 快捷刷脸

    FACE_WE_CHAT_FACE 微信小程序刷脸

    以下两种方式需联系交付顾问开通后方可使用：

    FACE_TECENT_CLOUD_H5 腾讯云刷脸

    PSN_AUDIO_VIDEO_ESIGN 智能视频认证

    config

    object

    否

    配置信息

    faceVideoTemplate

    String

    否

    智能视频认证模板ID（可以指定录制视频页面的朗读文案）

    注意：需要使用智能视频认证功能，想要自定义模板的情况需要联系e签宝交付顾问配置，配置后会提供模板ID给您。

    audioVideoActiveField

    object

    否

    智能视频认证文案中的动态朗读内容，动态内容 Key:Value值（支持自定义key和Value），格式如下：

    "audioVideoActiveField": {"appName": "开发者平台名","userName": "认证人姓名","bizScene":"签署的文件名"}

    注意：与 faceVideoTemplate（智能视频认证模板ID）配套使用，请联系e签宝交付顾问进行配置。

    响应参数

    展开全部参数参数名称

    类型

    必选

    参数说明

    code

    int

    是

    业务码，0表示成功

    message

    string

    否

    信息

    data

    object

    否

    业务信息




    bizId

    string

    否

    意愿任务业务ID,从获取到开始，30分钟内有效

    shortUrl

    string

    否

    意愿地址短连接

    url

    string

    否

    意愿地址长连接

    请求示例

    POST https://smlopenapi.esign.cn/v1/sign/willingness/createSignAuth
    {
"appScheme":"",
"idNumber":"342***4915",
"mobile":"17***526",
"name":"宗炼",
"noticeDeveloperUrl":"http://callback/url",
"redirectUrl":"https://www.baidu.com",
"willTypes":["CODE_SMS","FACE_ZHIMA_XY","FACE_TECENT_CLOUD_H5","FACE_FACE_LIVENESS_RECOGNITION"],
"willDefaultType":"FACE_ZHIMA_XY"
}

    响应示例

    {
    "code": 0,
    "message": "成功",
    "data": {
        "url": "https://smlwill.esign.cn/identity/login?willAuthParam=Xxxxxxx3%2FME7BcG2jcShFNomFDPI9IXAFsVfYtvFTFKdsoYJP8xSx3%2F%2F%2BoMjkY0iEGddl65Y91wbn2wqOCvDaZatCtwUnLM6%2B3c6SDkx6SsbPUF%2F5RXD9MN6D%2Bus%2Bf8PjYCkwbi6dc7QYFvxvNUPWX4c7hExxI2W7ny29%2BnJjZC4pNymWn%2Fz1NRMnItZfJw4kdydDPtjWUDH5Ql2BqrtgklWFGy2UthIq1vtDpCi%2BdKDy%2BOautnjBwzjB5Yr3g9Od44ZrQ0PWJFgrbPq6T3t7BshAPBCNnmWgjeEu%2FWjfUJN3%2BxmHL7p19E0upCsZBksY0s690dGJKgv0u%2FGfV8ivmiA1iuvAoxv78xiuvAGQFTg76e%2FeCSUd9szLLR5tbZ2wElGW8huMsuZ6WnZzVpZnXHPOvKqEuJCX8Akb2UOfvB3x45uX6j%2Bg8%2BSClFSZuLebGe9hiFrEpxWEatqBRpy5BfA9EO5mwSduduvs%2FM%2F0SJpT%2BRibi%2BdJOcHhyUrK6vpxeE0VPl1onEqvDJZ7ziKxT2O5B%2BmwxWv4JNTXDzkrnOcX0bhxjV03W4Dq2zNJJZigzLqnyj7wTF%2BNQmXhMzGUArHTs1pC3FQLRZra7zdoRIzTvCkmLk0eSKfTUy0bjzZSA5aGM1iWcEffpUXUr64P%2F40%2Boci%2By3s7E%3D",
        "shortUrl": "https://smlt.tsign.cn/OwWxxxQW",
        "bizId": "e5f65df6a6684xxxxxxc226259f"
    }
}

    查询意愿状态

    接口描述

    查询实时查询意愿状态，有实效性，从获取url开始，30分钟后失效。

    接口地址

    /v1/sign/willingness/queryWillAuthResult

    请求头

    提供两种安全接入方式，对应参数如何获取，参考文档【请点击】。

    方式一：请求签名鉴权

    参数名称

    类型

    必选

    参数说明

    X-Tsign-Open-App-Id

    string

    是

    项目ID

    Content-Type

    string

    是

    application/json;charset=UTF-8

    X-Tsign-Open-Ca-Timestamp

    string

    是

    API 调用者传递时间戳，值为当前时间的毫秒数，也就是从1970年1月1日起至今的时间转换为毫秒，时间戳有效时间为15分钟，为了防重放攻击

    Accept

    string

    是

    建议统一填写 */*

    X-Tsign-Open-Ca-Signature

    string

    是

    签名字符串

    Content-MD5

    string

    否

    当请求 Body 非 Form 表单时，可以计算 Body 的 MD5 值传递给云网关进行 Body MD5 校验。建议当请求 Body 非 Form 表单时，加上此请求头。

    X-Tsign-Open-Auth-Mode

    string

    是

    选择请求方式进行鉴权，固定值，Signature

    方式二：OAuth2.0鉴权

    当安全接入选择OAuth2.0鉴权方式，请点击查阅详情。

    请求参数

    参数名称

    类型

    必选

    参数说明

    bizId

    String

    是

    意愿任务业务ID

    响应参数

    展开全部参数参数名称

    类型

    必选

    参数说明

    code

    int

    是

    业务码，0表示成功

    message

    string

    否

    信息

    data

    object

    否

    业务信息

    status

    string

    否

    意愿状态

    0 - 进行中

    1 - 成功

    2 - 失败

    facePhotoUrl

    string

    否

    刷脸认证时刷脸照片（base64编码的照片图片数据）

    补充说明：

    • 此字段默认不返回任何信息，需联系e签宝沟通业务场景通过后才可开通
    • 只有认证方式选择腾讯云刷脸、快捷刷脸、微信小程序刷脸或者智能视频认证，才可以返回照片
    • 地址有效期默认1个小时，过期后可以重新调用接口获取新的地址

    faceVideoUrl

    string

    否

    刷脸认证时刷脸视频（base64编码的mp4视频数据）

    补充说明：

    • 此字段默认不返回任何信息，需联系e签宝沟通业务场景通过后才可开通
    • 只有认证方式选择腾讯云刷脸、快捷刷脸和智能视频认证时，才可以返回视频
    • 地址有效期默认1个小时，过期后可以重新调用接口获取新的地址

    similarity

    string

    否

    刷脸照片相似度得分（目前腾讯云刷脸才有）

    livingScore

    string

    否

    刷脸活体检测得分（目前腾讯云刷脸才有）

    willAuthType

    string

    否

    意愿方式

    CODE_SMS 短信验证码

    FACE_ZHIMA_XY 支付宝刷脸

    FACE_TECENT_CLOUD_H5 腾讯云刷脸

    FACE_FACE_LIVENESS_RECOGNITION 快捷刷脸

    FACE_WE_CHAT_FACE 微信小程序刷脸

    PSN_AUDIO_VIDEO_ESIGN 智能视频认证

    FACE_AUDIO_VIDEO_DUAL 支付宝智能视频认证（历史逻辑）

    VIDEO_WE_CHAT_VIDEO_DUAL 微信智能视频认证（历史逻辑）

    willAuthId

    string

    否

    意愿认证子任务ID

    endTime

    int64

    否

    认证完成时间

    请求示例

    POST https://smlopenapi.esign.cn/v1/sign/willingness/queryWillAuthResult
{
"bizId":"1331b7aa70xxxxac153453b42af68a"
}

    响应示例

    {
  "code": 0,
  "message": "成功",
  "data": {
    "status": 1,
    "facePhotoUrl": "https://esignoss.esign.cn/111156xxxx/7ebd6c86-2c6f-4abe-85dc-1dacac727d0e/47fb32e704fd431a9a2d2ed15bc1e48f?Expires=1578572126&OSSAccessKeyId=LTAIdvHfiVrzDKbE&Signature=W9/Vj1fwGdzqKnjLmGNC62Sc8d0%3D",
    "similarity": "96.0",
    "livingScore": "98",
    "willAuthType": "FACE_TECENT_CLOUD_H5",
    "willAuthId":"xxx",
    "endTime": 1656418640000
  }
}

    意愿状态变化通知

    参数名称

    类型

    必选

    参数说明

    action

    String

    是

    标记该通知的业务类型，该通知固定为：WILL_FINISH

    accountId

    String

    是

    意愿认证用户ID（与电子签名不通用，可忽略此字段）

    willAuthId

    String

    是

    意愿子任务ID

    willAuthType

    String

    是

    意愿方式

    CODE_SMS 短信验证码

    FACE_ZHIMA_XY 支付宝刷脸

    FACE_TECENT_CLOUD_H5 腾讯云刷脸

    FACE_FACE_LIVENESS_RECOGNITION 快捷刷脸

    FACE_WE_CHAT_FACE 微信小程序刷脸

    PSN_AUDIO_VIDEO_ESIGN 智能视频认证

    FACE_AUDIO_VIDEO_DUAL 支付宝智能视频认证（历史逻辑）

    VIDEO_WE_CHAT_VIDEO_DUAL 微信智能视频认证（历史逻辑）

    success

    Bool

    是

    是否成功

    bizId

    int

    是

    意愿任务业务ID

    timestamp

    Int

    是

    发送消息时间（毫秒时间）

    响应示例

    {
  "action":"WILL_FINISH",
  "accountId":"111111*****222222222244444",
  "bizId":"c67f4469304d4bc4932ca19b6444444",
  "success":true,
  "timestamp":1578881662374,
  "willAuthId":"4d77a59f0aef464994d0ccf2555555",
  "willAuthType":"FACE_ZHIMA_XY"
}
    开放平台e签宝官网

    Copyright ©2004-2022 Esign.cn版权所有 增值电信业务经营许可证：浙B2-20180376 浙公网安备33010602006438号

    我要纠错