获取个人认证&授权页面链接

重要提示：自2024年9月12日起，认证授权涉及权限范围（authorizedScopes）部分功能需要购买e签宝高级版或生态伙伴版本方可支持！

接口描述

用于获取个人的认证授权页面链接，通过此链接个人用户可进行个人实名认证、资源授权等操作。

点击这里了解更多关于“用户授权与实名认证”场景介绍。

调用本API接口前，开发者可通过【查询个人认证信息】根据手机号（邮箱）或证件号来查询个人用户是否已实名，已实名用户无需重复实名；
开发者可接收实名认证通过的回调通知，来获取个人实名认证通过的结果，并保管个人用户的psnId；
开发者可接收授权完成通知的回调通知，来获取本次授权的有效期限等相关信息；
本次流程中认证授权操作的更多详情参考API接口：【查询认证授权流程详情】。

接口地址&请求方法

接口地址：https://{host}/v3/psn-auth-url

请求方法：POST

请求头格式

具体请求头参数，请查看公共请求格式。

请求参数

展开全部参数参数名称			参数类型	必选	参数位置	参数说明
psnAuthConfig（点击“+”展开详情）			object	是	body	个人实名认证配置项（如果不传个人的账号信息，则需要个人用户自主在页面填写手机号/邮箱进行验证码回填注册）
	psnAccount		string	否	body	个人用户账号标识（手机号或邮箱）【注】若未知用户的psnId，请传此字段
	psnId		string	否	body	个人账号ID 【注】若已知用户的psnId，可以传此字段
	psnInfo		object	否	body	个人身份附加信息
		psnName	string	否	body	姓名
psnIDCardNum		string	否	body	证件号码
psnIDCardType		string	否	body	证件类型，可选值如下： CRED_PSN_CH_IDCARD - 中国大陆居民身份证 CRED_PSN_CH_HONGKONG - 香港来往大陆通行证（回乡证） CRED_PSN_CH_MACAO - 澳门来往大陆通行证（回乡证） CRED_PSN_CH_TWCARD - 台湾来往大陆通行证（台胞证） CRED_PSN_PASSPORT - 护照【注】CRED_PSN_CH_IDCARD 类型同时兼容港澳台居住证（81、82、83开头18位证件号）、外国人永久居住证（9开头18位证件号）
psnMobile		string	否	body	个人手机号（运营商实名登记手机号或银行卡预留手机号，仅用于认证）
bankCardNum		string	否	body	个人银行卡号
psnIdentityVerify		boolean	否	body	是否校验：psnAccount（个人用户账号标识）或 psnId（个人账号ID）绑定的e签宝个人信息与传入的psnInfo（个人身份信息）中的信息一致 true - 校验 false - 不校验（默认值）【注】若传true，则校验信息是否一致。若信息一致或用户未在e签宝注册认证过则正常发起，若信息不一致则报错：“传入的%s和该用户在e签宝的个人信息不一致” ，其中%s可能为多个字段，包含：姓名、证件号、实名手机号、银行卡号
psnAuthPageConfig		object	否	body	个人实名认证页面配置项
	psnDefaultAuthMode	string	否	body	设置页面中默认选择的实名认证方式，可选值如下： PSN_FACE - 人脸识别认证（默认值） PSN_MOBILE3 - 手机运营商三要素认证 PSN_BANKCARD4 - 银行卡四要素认证【注】使用iframe内嵌集成不支持对接刷脸方式
	psnAvailableAuthModes	list	否	body	设置页面中可选择的个人认证方式范围，若不传此参数，则可选择全部认证方式。 PSN_FACE - 人脸识别认证 PSN_MOBILE3 - 手机运营商三要素认证 PSN_BANKCARD4 - 银行卡四要素认证【注】使用iframe内嵌集成不支持对接刷脸方式
	advancedVersion	list	否	body	通过银行卡认证或运营商认证方式时，是否使用详情版（如指定则核验失败可返回具体不匹配信息），传空默认为普通版。 PSN_MOBILE3 - 手机运营商三要素认证 PSN_BANKCARD4 - 银行卡四要素认证【注】详情版：针对个人认证失败可以返回具体的不匹配信息，需要单独购买，具体购买方式请咨询e签宝商务人员；普通版：只返回信息比对核验失败，不会返回具体的不匹配信息。
	psnEditableFields	list	否	body	设置页面中可编辑的个人信息字段，不传此参数，页面默认不允许编辑个人信息。 name - 姓名 IDCardNum - 证件号码（如果账号已实名，传了该字段，页面也是不可编辑更改的，因为证件号是唯一标识） mobile - 个人手机号（仅针对实名认证手机号） bankCardNum - 个人银行卡号
authorizeConfig（点击“+”展开详情）			object	否	body	个人授权配置项授权过期需重新授权；不传此参数默认页面仅实名认证，不需要用户授权。
	authorizedScopes		list	否	body	设置页面中权限范围，参数值如下：
						授权当前应用AppId获取用户的账号基本信息： get_psn_identity_info - 授权允许获取个人用户的账号信息（姓名、手机号/邮箱、证件号等）（自2024年9月12日起，仅e签宝高级版或生态伙伴版本支持指定）
						授权当前应用AppId代用户发起合同签署： psn_initiate_sign - 授权允许代表个人用户发起合同签署以及查询合同签署详情（自2024年9月12日起，仅e签宝生态伙伴版本支持指定）
						授权当前应用AppId获取用户资源管理权限： manage_psn_resource - 授权允许获取个人用户的印章等资源的管理权限（自2024年9月12日起，仅e签宝高级版或生态伙伴版本支持指定）
						授权当前应用AppId存储用户的合同文件： psn_sign_file_storage - 授权允许个人合同文件存储到平台应用的本地服务器（用于平台专属云项目代客户发起合同签署场景）
redirectConfig（点击“+”展开详情）			object	否	body	认证完成重定向配置项
	redirectUrl		string	否	body	认证完成后跳转页面（除app和小程序端集成外，地址需符合 https /http 协议地址）【注】贵司的重定向域名需要在e签宝提前放行，否则会报错：“您即将访问的页面可能有安全风险”。（点击跳转重定向域名配置说明）
	redirectDelayTime		string	否	body	重定向跳转延迟时间，单位为秒。授权模式下（authorizedScopes有具体的参数值）：默认延迟时间为 3秒。传 0 - 不展示授权结果页（或结果页一闪而过），授权完成直接跳转重定向地址传其他数字 - 展示授权结果页，倒计时 x秒后，自动跳转重定向地址实名模式下（authorizedScopes不传或者没有具体的参数值）：默认延迟时间为 5秒。传 0 - 不展示实名结果页，认证完成直接跳转重定向地址传其他数字 - 展示实名结果页，倒计时5秒后，自动跳转重定向地址（只有5秒，没有其他秒数的控制）【注】当redirectUrl不传的情况下，该字段无需传入，认证完成结果页不跳转。
notifyUrl			string	否	body	接收回调通知的Web地址，通知开发者用户认证和授权的完成以及变更情况，点此了解更多认证授权回调通知。
clientType			string	否	body	指定客户端类型，默认值 ALL（注意参数值全部为英文大写） ALL - 自动适配移动端或PC端 H5 - 移动端适配 PC - PC端适配
appScheme			string	否	body	AppScheme，主要用于支付宝人脸认证重定向时跳回开发者自身App。示例值：esign://demo/realBack （点击了解 APP内嵌签署/认证H5对接说明）

响应参数

展开全部参数参数名称		参数类型	必选	参数说明
code		int32	是	业务码，0表示成功，非0表示异常。
message		string	否	业务信息请根据 code 来判断错误情况，不应该依赖message匹配，因为 message 可能会调整。
data（点击“+”展开详情）		object	否	业务数据
	authUrl	string	否	个人认证授权长链接（有效期30天）【注】支持自定义域名，微信小程序H5内嵌场景需要使用长链接
	authShortUrl	string	否	个人认证授权短链接（有效期30天）
	authFlowId	string	否	本次认证授权流程ID（请注意保管流程ID，可用于【查询认证授权流程详情】）

请求示例

{
  "psnAuthConfig": {
    "psnAccount": "183****0101",
    "psnInfo": {
      "psnName": "赵四",
      "psnIDCardNum": "130204********1001",
      "psnIDCardType": "CRED_PSN_CH_IDCARD"
    },
    "psnAuthPageConfig": {
      "psnDefaultAuthMode": "PSN_MOBILE3",
      "psnAvailableAuthModes": ["PSN_BANKCARD4","PSN_MOBILE3","PSN_FACE"]
    }
  },
  "authorizeConfig": {
    "authorizedScopes": ["get_psn_identity_info"]
  },
  "notifyUrl": "http://xx.xx.xx.172:8081/CSTNotify/asyn/notify",
  "clientType": "ALL",
  "redirectConfig": {
    "redirectUrl": "https://www.xxx.cn/"
  }
}

响应示例

{
    "code": 0,
    "message": "成功",
    "data": {
        "authFlowId": "OF-203***e080010",
        "authUrl": "https://openapi.esign.cn/auth/h5/index?authFlowId=OF-xxx&clientType=ALL&appId=xxx",
        "authShortUrl": "https://openapi.esign.cn/mFHR***hUV46"
    }
}

错误码
点击查看错误码