API接口文档
证书申请-个人证书
传入身份信息,进行证书的申请。
一、公共参数
-
请求地址:http://api.ca.demo.smartcert.cn/api,http://api.ca.demo.smartcert.cn/api
服务接口名称(即公共参数 method 的值): cert.application.personal
请求方式:POST
二、请求参数(请求方式为 post)
- 请求参数以表单形式提交,Content-Type 值为: application/x-www-form-urlencoded;charset=utf-8
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| request | PersonalIssueRequest | 是 | 个人高级证书签发请求 |
PersonalIssueRequest 说明:
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| personalSeniorCertificate | PersonalSeniorCertificate | 是 | 个人高级证书实体信息(仅 Java SDK 封装对象,API 提交时其字段与其它参数同层级平铺,见下方实体表说明) |
| pkCS10 | String | 是 | 用于制作证书的 pkCS10 |
| personVerifyMode | PersonVerifyMode | 否 | 个人认证方式 |
| businessDescribe | String | 否 | 业务描述,传入该参数后,证书申请确认页面将展示对应内容。 |
| noticeUrl | String | 否 | 服务器通知地址(点我查看详细使用),当证书申请成功或失败时,会通过此地址通知用户。 |
| auditNoticeUrl | String | 否 | 审核通知地址,不可携带请求参数(点我查看详细使用)。证件类型非身份证时,传递此参数用于发送证件信息审核结果。 |
| successUrl | String | 否 | h5书申请成功页面,不可携带请求参数(点我查看详细使用) |
| failUrl | String | 否 | h5证书申请失败跳转页面,不可携带请求参数(点我查看详细使用) |
| redirectUrl | String | 否 | 业务跳转地址,证书申请界面退出时重定向跳转地址 |
| businessExtensions | Map | 否 | 业务扩展属性,键值对均为String类型 |
参数层级说明:
personalSeniorCertificate仅为 Java SDK 中的封装对象,服务端并不接收名为personalSeniorCertificate的参数。通过 API 直接调用时,以下字段与 request 中其它参数同层级提交(表单平铺参数,如idType=ID&idNumber=xxx),请勿使用personalSeniorCertificate.idType=xxx的嵌套形式;通过 SDK 调用时,SDK 会自动将对象字段展平为同级参数,无需手动拼接。
PersonalSeniorCertificate (继承自 BaseCertificate) 说明:
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| idType | IdType | 是 | 证件类型 |
| idNumber | String | 是 | 证件号,需要与证件类型匹配 |
| phoneNumber | String | 否 | 联系号码,若需使用短信核验,则必填 |
| ownerName | String | 是 | 证书持有者姓名 |
BaseCertificate 说明:
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| organization | String | 否 | 证书 O 项,证书所属组织 |
| organizationUnit | String | 否 | 证书 OU 项,证书所属组织单元 |
| country | String | 否 | 证书 C 项,国家,默认 CN |
| province | String | 否 | 证书 S 项,证书所属省 |
| city | String | 否 | 证书 L 项,证书所属市 |
| districtCounty | String | 否 | 证书所属区县 |
| givenName | String | 否 | 名字,证书GIVENNAME项 |
| extraExtension | List<Extension> | 否 | 证书扩展项 |
Extension 说明:
| 名称 | 类型 | 描述 |
|---|---|---|
| oid | String | 扩展项oid值 |
| value | String | 扩展项值 |
| name | String | 扩展项名称 |
证件类型(IdType)说明:
| 名称 | 描述 |
|---|---|
| ID | 身份证 |
| PASSPORT | 护照 |
| MILITARY_ID | 军人身份证 |
| BUSINESS_REGISTRATION_CERT | 工商登记证 |
| TAX_REGISTRATION_CERT | 税务登记证 |
| SHAREHOLDER_CODE_CERT | 股东代码证 |
| SOCIAL_SECURITY_CARD | 社会保障卡 |
| ARMED_POLICE | 武装警察身份证件 |
| HK_MACAU_PASSPORT | 港澳居民往来内地通行证 |
| TAIWAN_PASSPORT | 台湾居民往来内地通行证 |
| HOUSEHOLD_REGISTER | 户口簿 |
| TEMPORARY_ID | 临时身份证 |
| POLICE_CERT | 警官证 |
| PERMANENT_RESIDENCE_PERMIT | 外国人永久居留证 |
| GOVERNMENT_APPROVAL | 政府批文 |
| UNIFIED_SOCIAL_CERT | 统一社会信用代码证 |
| PRIVATE_NON_ENTERPRISE_CERT | 民办非企业登记证书 |
| CORPORATE_CERT | 法人证书 |
| OTHER | 其他 |
个人认证方式(PersonVerifyMode)说明:
| 名称 | 描述 |
|---|---|
| FACE_VERIFY | 人脸核验 |
| SMS_VERIFY | 短信核验 |
请求示例(证书实体字段与其它参数同层级平铺提交):
http://api.ca.demo.smartcert.cn/api |
三、响应参数
| data 结果信息 | 类型 | 描述 |
|---|---|---|
| message | String | 业务描述 |
| incorrect | String | 业务返回码 |
| code | String | 业务码,后续获取结果使用 |
| h5Url | String | H5签发链接 |
| expireTime | Long | 过期时间 |
四、成功示例
JSON示例
{ |
五、失败示例
JSON示例
{ |
六、返回码说明(incorrect)
| 返回码 | 描述 |
|---|---|
| 0 | 证书申请请求成功 |
| 其它 | 参考异常代码表 |
证书申请-企业证书
传入企业信息,进行证书的申请和签发。
一、请求说明
-
请求地址:http://api.ca.demo.smartcert.cn/api,http://api.ca.demo.smartcert.cn/api
服务接口名称(即公共参数 method 的值): cert.application.enterprise
请求方式:POST
二、请求参数(请求方式为 post)
- 请求参数以表单形式提交,Content-Type 值为: application/x-www-form-urlencoded;charset=utf-8
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| request | EnterpriseIssueRequest | 是 | 企业证书签发请求 |
EnterpriseIssueRequest 说明:
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| enterpriseSeniorCertificate | EnterpriseSeniorCertificate | 是 | 企业高级证书实体信息(仅 Java SDK 封装对象,API 提交时其字段与其它参数同层级平铺,见下方实体表说明) |
| pkCS10 | String | 是 | 用于制作证书的 pkCS10 |
| personVerifyMode | PersonVerifyMode | 否 | 个人认证方式 |
| agentInfo | AgentInfo | 是 | 经办人信息 |
| legalInfo | LegalInfo | 是 | 法人信息 |
| duration | String | 否 | 证书有效期,格式为数字+字母,字母支持YMDHm,分别对应年月日时分,不传默认1Y。 |
| authCertFile | String | 否 | 授权证书文件,base64格式,传入后企业认证时将无需上传该文件,企业认证环节可重新修改上传 |
| businessLicenseFile | String | 否 | 营业执照文件,base64格式,传入后企业认证时将无需上传该文件,企业认证环节可重新修改上传 |
| businessDescribe | String | 否 | 业务描述,传入该参数后,证书申请确认页面将展示对应内容。 |
| noticeUrl | String | 否 | 服务器通知地址(点我查看详细使用),当证书申请成功或失败时,会通过此地址通知用户。 |
| successUrl | String | 否 | h5证书申请成功页面,不可携带请求参数(点我查看详细使用) |
| failUrl | String | 否 | h5证书申请失败跳转页面,不可携带请求参数(点我查看详细使用) |
| auditNoticeUrl | String | 否 | 审核通知地址,不可携带请求参数(点我查看详细使用) |
| redirectUrl | String | 否 | 业务跳转地址,证书申请界面退出时重定向跳转地址 |
| businessExtensions | Map | 否 | 业务扩展属性,键值对均为String类型 |
参数层级说明:
enterpriseSeniorCertificate仅为 Java SDK 中的封装对象,服务端并不接收名为enterpriseSeniorCertificate的参数。通过 API 直接调用时,以下字段与 request 中其它参数同层级提交(表单平铺参数,如enterprise=xxx&idType=xxx),请勿使用enterpriseSeniorCertificate.enterprise=xxx的嵌套形式;通过 SDK 调用时,SDK 会自动将对象字段展平为同级参数,无需手动拼接。
EnterpriseSeniorCertificate (继承自 BaseCertificate) 说明:
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| enterprise | String | 是 | 企业名称 |
| department | String | 否 | 部门名称 |
| idType | IdType | 是 | 证件类型 |
| idNumber | String | 是 | 证件号,需要与证件类型匹配 |
| phoneNumber | String | 否 | 联系号码 |
BaseCertificate 说明:
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| organization | String | 否 | 证书 O 项,证书所属组织 |
| organizationUnit | String | 否 | 证书 OU 项,证书所属组织单元 |
| country | String | 否 | 证书 C 项,国家,默认 CN |
| province | String | 否 | 证书 S 项,证书所属省 |
| city | String | 否 | 证书 L 项,证书所属市 |
| districtCounty | String | 否 | 证书所属区县 |
| givenName | String | 否 | 名字,证书GIVENNAME项 |
| extraExtension | List<Extension> | 否 | 证书扩展项 |
Extension 说明:
| 名称 | 类型 | 描述 |
|---|---|---|
| oid | String | 扩展项oid值 |
| value | String | 扩展项值 |
| name | String | 扩展项名称 |
证件类型(IdType)说明:
| 名称 | 描述 |
|---|---|
| ID | 身份证 |
| PASSPORT | 护照 |
| MILITARY_ID | 军人身份证 |
| BUSINESS_REGISTRATION_CERT | 工商登记证 |
| TAX_REGISTRATION_CERT | 税务登记证 |
| SHAREHOLDER_CODE_CERT | 股东代码证 |
| SOCIAL_SECURITY_CARD | 社会保障卡 |
| ARMED_POLICE | 武装警察身份证件 |
| HK_MACAU_PASSPORT | 港澳居民往来内地通行证 |
| TAIWAN_PASSPORT | 台湾居民往来内地通行证 |
| HOUSEHOLD_REGISTER | 户口簿 |
| TEMPORARY_ID | 临时身份证 |
| POLICE_CERT | 警官证 |
| PERMANENT_RESIDENCE_PERMIT | 外国人永久居留证 |
| GOVERNMENT_APPROVAL | 政府批文 |
| UNIFIED_SOCIAL_CERT | 统一社会信用代码证 |
| PRIVATE_NON_ENTERPRISE_CERT | 民办非企业登记证书 |
| CORPORATE_CERT | 法人证书 |
| OTHER | 其他 |
个人认证方式(PersonVerifyMode)说明:
| 名称 | 描述 |
|---|---|
| FACE_VERIFY | 人脸核验 |
| SMS_VERIFY | 短信核验 |
经办人信息(AgentInfo) 说明:
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| agentName | String | 是 | 经办人姓名 |
| agentId | String | 是 | 经办人证件号 |
| agentPhone | String | 否 | 经办人手机号码,若需使用短信核验,则必填 |
法人信息(LegalInfo) 说明:
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| legalName | String | 是 | 法人姓名 |
| legalIdCard | String | 否 | 法人身份证号 |
| legalPhone | String | 否 | 法人手机号码 |
| legalIdType | IdType | 否 | 法人证件类型,取值参考证件类型(IdType)说明 |
请求示例(证书实体字段与其它参数同层级平铺提交,agentInfo/legalInfo):
http://api.ca.demo.smartcert.cn/api |
三、响应参数
| data 结果信息 | 类型 | 描述 |
|---|---|---|
| message | String | 业务描述 |
| incorrect | String | 业务返回码 |
| code | String | 业务码,后续获取结果使用 |
| h5Url | String | H5签发链接 |
| expireTime | Long | 过期时间 |
四、成功示例
JSON示例
{ |
五、失败示例
JSON示例
{ |
六、返回码说明(incorrect)
| 返回码 | 描述 |
|---|---|
| 0 | 证书申请请求成功 |
| 其它 | 参考异常代码表 |
证书申请-证书重发
传入原证书申请码,对原证书申请进行重发,重新申请并签发证书。
一、请求说明
-
请求地址:http://api.ca.demo.smartcert.cn/api,http://api.ca.demo.smartcert.cn/api
服务接口名称(即公共参数 method 的值): cert.application.reissue
请求方式:POST
二、请求参数(请求方式为 post)
- 请求参数以表单形式提交,Content-Type 值为: application/x-www-form-urlencoded;charset=utf-8
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| request | CertApplicationReissueRequest | 是 | 证书申请重发请求 |
CertApplicationReissueRequest 说明:
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| code | String | 是 | 原证书申请码 |
| pkCS10 | String | 否 | 用于制作证书的 pkCS10 (建议使用) |
| extensions | Map | 否 | 扩展属性 |
| businessDescribe | String | 否 | 业务描述,传入该参数后,证书申请确认页面将展示对应内容。 |
| businessExtensions | Map | 否 | 业务扩展属性,键值对均为String类型 |
| noticeUrl | String | 否 | 服务器通知地址(点我查看详细使用),当证书申请成功或失败时,会通过此地址通知用户。 |
| successUrl | String | 否 | h5证书申请成功页面,不可携带请求参数(点我查看详细使用) |
| failUrl | String | 否 | h5证书申请失败跳转页面,不可携带请求参数(点我查看详细使用) |
| auditNoticeUrl | String | 否 | 审核通知地址,不可携带请求参数(点我查看详细使用) |
| redirectUrl | String | 否 | 业务跳转地址,证书申请界面退出时重定向跳转地址 |
请求示例:
http://api.ca.demo.smartcert.cn/api |
三、响应参数
| data 结果信息 | 类型 | 描述 |
|---|---|---|
| message | String | 业务描述 |
| incorrect | String | 业务返回码 |
| code | String | 业务码,后续获取结果使用 |
| h5Url | String | H5签发链接 |
| expireTime | Long | 过期时间 |
四、成功示例
JSON示例
{ |
五、失败示例
JSON示例
{ |
六、返回码说明(incorrect)
| 返回码 | 描述 |
|---|---|
| 0 | 证书申请请求成功 |
| 其它 | 参考异常代码表 |
证书申请-密钥恢复
传入原证书申请码,对原证书申请进行密钥恢复,重新申请并签发证书。
一、请求说明
-
请求地址:http://api.ca.demo.smartcert.cn/api,http://api.ca.demo.smartcert.cn/api
服务接口名称(即公共参数 method 的值): cert.application.recover
请求方式:POST
二、请求参数(请求方式为 post)
- 请求参数以表单形式提交,Content-Type 值为: application/x-www-form-urlencoded;charset=utf-8
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| request | CertApplicationRecoverRequest | 是 | 证书申请密钥恢复请求 |
CertApplicationRecoverRequest 说明:
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| code | String | 是 | 原证书申请码 |
| pkCS10 | String | 否 | 用于制作证书的 pkCS10 (建议使用) |
| extensions | Map | 否 | 扩展属性 |
| businessDescribe | String | 否 | 业务描述,传入该参数后,证书申请确认页面将展示对应内容。 |
| businessExtensions | Map | 否 | 业务扩展属性,键值对均为String类型 |
| noticeUrl | String | 否 | 服务器通知地址(点我查看详细使用),当证书申请成功或失败时,会通过此地址通知用户。 |
| successUrl | String | 否 | h5证书申请成功页面,不可携带请求参数(点我查看详细使用) |
| failUrl | String | 否 | h5证书申请失败跳转页面,不可携带请求参数(点我查看详细使用) |
| auditNoticeUrl | String | 否 | 审核通知地址,不可携带请求参数(点我查看详细使用) |
| redirectUrl | String | 否 | 业务跳转地址,证书申请界面退出时重定向跳转地址 |
请求示例:
http://api.ca.demo.smartcert.cn/api |
三、响应参数
| data 结果信息 | 类型 | 描述 |
|---|---|---|
| message | String | 业务描述 |
| incorrect | String | 业务返回码 |
| code | String | 业务码,后续获取结果使用 |
| h5Url | String | H5签发链接 |
| expireTime | Long | 过期时间 |
四、成功示例
JSON示例
{ |
五、失败示例
JSON示例
{ |
六、返回码说明(incorrect)
| 返回码 | 描述 |
|---|---|
| 0 | 证书申请请求成功 |
| 其它 | 参考异常代码表 |
证书申请-个人证书-无P10
传入身份信息,进行证书的申请。
一、公共参数
-
请求地址:http://api.ca.demo.smartcert.cn/api,http://api.ca.demo.smartcert.cn/api
服务接口名称(即公共参数 method 的值): cert.application.personal.without.p10
请求方式:POST
二、请求参数(请求方式为 post)
- 请求参数以表单形式提交,Content-Type 值为: application/x-www-form-urlencoded;charset=utf-8
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| request | PersonalIssueRequest | 是 | 个人高级证书签发请求 |
PersonalIssueRequest 说明:
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| personalSeniorCertificate | PersonalSeniorCertificate | 是 | 个人高级证书实体信息(仅 Java SDK 封装对象,API 提交时其字段与其它参数同层级平铺,见下方实体表说明) |
| personVerifyMode | PersonVerifyMode | 否 | 个人认证方式 |
| businessDescribe | String | 否 | 业务描述,传入该参数后,证书申请确认页面将展示对应内容。 |
| businessExtensions | Map | 否 | 业务扩展属性,键值对均为String类型 |
| noticeUrl | String | 否 | 服务器通知地址(点我查看详细使用),当证书申请成功或失败时,会通过此地址通知用户。 |
| auditNoticeUrl | String | 否 | 审核通知地址,不可携带请求参数(点我查看详细使用)。证件类型非身份证时,传递此参数用于发送证件信息审核结果。 |
| successUrl | String | 否 | h5书申请成功页面,不可携带请求参数(点我查看详细使用) |
| failUrl | String | 否 | h5证书申请失败跳转页面,不可携带请求参数(点我查看详细使用) |
| redirectUrl | String | 否 | 业务跳转地址,传入该参数后,证书申请界面左上角将显示「返回」按钮,点击按钮即可跳转至配置的目标地址 |
参数层级说明:
personalSeniorCertificate仅为 Java SDK 中的封装对象,服务端并不接收名为personalSeniorCertificate的参数。通过 API 直接调用时,以下字段与 request 中其它参数同层级提交(表单平铺参数,如idType=ID&idNumber=xxx),请勿使用personalSeniorCertificate.idType=xxx的嵌套形式;通过 SDK 调用时,SDK 会自动将对象字段展平为同级参数,无需手动拼接。
PersonalSeniorCertificate (继承自 BaseCertificate) 说明:
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| idType | IdType | 是 | 证件类型 |
| idNumber | String | 是 | 证件号,需要与证件类型匹配 |
| phoneNumber | String | 否 | 联系号码,若需使用短信核验,则必填 |
| ownerName | String | 是 | 证书持有者姓名 |
BaseCertificate 说明:
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| organization | String | 否 | 证书 O 项,证书所属组织 |
| organizationUnit | String | 否 | 证书 OU 项,证书所属组织单元 |
| country | String | 否 | 证书 C 项,国家,默认 CN |
| province | String | 否 | 证书 S 项,证书所属省 |
| city | String | 否 | 证书 L 项,证书所属市 |
| districtCounty | String | 否 | 证书所属区县 |
| givenName | String | 否 | 名字,证书GIVENNAME项 |
| extraExtension | List<Extension> | 否 | 证书扩展项 |
Extension 说明:
| 名称 | 类型 | 描述 |
|---|---|---|
| oid | String | 扩展项oid值 |
| value | String | 扩展项值 |
| name | String | 扩展项名称 |
证件类型(IdType)说明:
| 名称 | 描述 |
|---|---|
| ID | 身份证 |
| PASSPORT | 护照 |
| MILITARY_ID | 军人身份证 |
| BUSINESS_REGISTRATION_CERT | 工商登记证 |
| TAX_REGISTRATION_CERT | 税务登记证 |
| SHAREHOLDER_CODE_CERT | 股东代码证 |
| SOCIAL_SECURITY_CARD | 社会保障卡 |
| ARMED_POLICE | 武装警察身份证件 |
| HK_MACAU_PASSPORT | 港澳居民往来内地通行证 |
| TAIWAN_PASSPORT | 台湾居民往来内地通行证 |
| HOUSEHOLD_REGISTER | 户口簿 |
| TEMPORARY_ID | 临时身份证 |
| POLICE_CERT | 警官证 |
| PERMANENT_RESIDENCE_PERMIT | 外国人永久居留证 |
| GOVERNMENT_APPROVAL | 政府批文 |
| UNIFIED_SOCIAL_CERT | 统一社会信用代码证 |
| PRIVATE_NON_ENTERPRISE_CERT | 民办非企业登记证书 |
| CORPORATE_CERT | 法人证书 |
| OTHER | 其他 |
个人认证方式(PersonVerifyMode)说明:
| 名称 | 描述 |
|---|---|
| FACE_VERIFY | 人脸核验 |
| SMS_VERIFY | 短信核验 |
请求示例(证书实体字段与其它参数同层级平铺提交):
http://api.ca.demo.smartcert.cn/api |
三、响应参数
| data 结果信息 | 类型 | 描述 |
|---|---|---|
| message | String | 业务描述 |
| incorrect | String | 业务返回码 |
| code | String | 业务码,后续获取结果使用 |
| h5Url | String | H5签发链接 |
| expireTime | Long | 过期时间 |
四、成功示例
JSON示例
{ |
五、失败示例
JSON示例
{ |
六、返回码说明(incorrect)
| 返回码 | 描述 |
|---|---|
| 0 | 证书申请请求成功 |
| 其它 | 参考异常代码表 |
证书申请-企业证书-无P10
传入企业信息,进行证书的申请和签发。
一、请求说明
-
请求地址:http://api.ca.demo.smartcert.cn/api,http://api.ca.demo.smartcert.cn/api
服务接口名称(即公共参数 method 的值): cert.application.enterprise.without.p10
请求方式:POST
二、请求参数(请求方式为 post)
- 请求参数以表单形式提交,Content-Type 值为: application/x-www-form-urlencoded;charset=utf-8
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| request | EnterpriseIssueRequest | 是 | 企业证书签发请求 |
EnterpriseIssueRequest 说明:
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| enterpriseSeniorCertificate | EnterpriseSeniorCertificate | 是 | 企业高级证书实体信息(仅 Java SDK 封装对象,API 提交时其字段与其它参数同层级平铺,见下方实体表说明) |
| personVerifyMode | PersonVerifyMode | 否 | 个人认证方式 |
| agentInfo | AgentInfo | 是 | 经办人信息 |
| legalInfo | LegalInfo | 是 | 法人信息 |
| duration | String | 否 | 证书有效期,格式为数字+字母,字母支持YMDHm,分别对应年月日时分,不传默认1Y。 |
| authCertFile | String | 否 | 授权证书文件,base64格式,传入后企业认证时将无需上传该文件,企业认证环节可重新修改上传 |
| businessLicenseFile | String | 否 | 营业执照文件,base64格式,传入后企业认证时将无需上传该文件,企业认证环节可重新修改上传 |
| businessDescribe | String | 否 | 业务描述,传入该参数后,证书申请确认页面将展示对应内容。 |
| businessExtensions | Map | 否 | 业务扩展属性,键值对均为String类型 |
| noticeUrl | String | 否 | 服务器通知地址(点我查看详细使用),当证书申请成功或失败时,会通过此地址通知用户。 |
| successUrl | String | 否 | h5证书申请成功页面,不可携带请求参数(点我查看详细使用) |
| failUrl | String | 否 | h5证书申请失败跳转页面,不可携带请求参数(点我查看详细使用) |
| auditNoticeUrl | String | 否 | 审核通知地址,不可携带请求参数(点我查看详细使用) |
| redirectUrl | String | 否 | 业务跳转地址,,传入该参数后,证书申请界面左上角将显示「返回」按钮,点击按钮即可跳转至配置的目标地址 |
参数层级说明:
enterpriseSeniorCertificate仅为 Java SDK 中的封装对象,服务端并不接收名为enterpriseSeniorCertificate的参数。通过 API 直接调用时,以下字段与 request 中其它参数同层级提交(表单平铺参数,如enterprise=xxx&idType=xxx),请勿使用enterpriseSeniorCertificate.enterprise=xxx的嵌套形式;通过 SDK 调用时,SDK 会自动将对象字段展平为同级参数,无需手动拼接。
EnterpriseSeniorCertificate (继承自 BaseCertificate) 说明:
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| enterprise | String | 是 | 企业名称 |
| department | String | 否 | 部门名称 |
| idType | IdType | 是 | 证件类型 |
| idNumber | String | 是 | 证件号,需要与证件类型匹配 |
| phoneNumber | String | 否 | 联系号码 |
BaseCertificate 说明:
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| organization | String | 否 | 证书 O 项,证书所属组织 |
| organizationUnit | String | 否 | 证书 OU 项,证书所属组织单元 |
| country | String | 否 | 证书 C 项,国家,默认 CN |
| province | String | 否 | 证书 S 项,证书所属省 |
| city | String | 否 | 证书 L 项,证书所属市 |
| districtCounty | String | 否 | 证书所属区县 |
| givenName | String | 否 | 名字,证书GIVENNAME项 |
| extraExtension | List<Extension> | 否 | 证书扩展项 |
Extension 说明:
| 名称 | 类型 | 描述 |
|---|---|---|
| oid | String | 扩展项oid值 |
| value | String | 扩展项值 |
| name | String | 扩展项名称 |
证件类型(IdType)说明:
| 名称 | 描述 |
|---|---|
| ID | 身份证 |
| PASSPORT | 护照 |
| MILITARY_ID | 军人身份证 |
| BUSINESS_REGISTRATION_CERT | 工商登记证 |
| TAX_REGISTRATION_CERT | 税务登记证 |
| SHAREHOLDER_CODE_CERT | 股东代码证 |
| SOCIAL_SECURITY_CARD | 社会保障卡 |
| ARMED_POLICE | 武装警察身份证件 |
| HK_MACAU_PASSPORT | 港澳居民往来内地通行证 |
| TAIWAN_PASSPORT | 台湾居民往来内地通行证 |
| HOUSEHOLD_REGISTER | 户口簿 |
| TEMPORARY_ID | 临时身份证 |
| POLICE_CERT | 警官证 |
| PERMANENT_RESIDENCE_PERMIT | 外国人永久居留证 |
| GOVERNMENT_APPROVAL | 政府批文 |
| UNIFIED_SOCIAL_CERT | 统一社会信用代码证 |
| PRIVATE_NON_ENTERPRISE_CERT | 民办非企业登记证书 |
| CORPORATE_CERT | 法人证书 |
| OTHER | 其他 |
个人认证方式(PersonVerifyMode)说明:
| 名称 | 描述 |
|---|---|
| FACE_VERIFY | 人脸核验 |
| SMS_VERIFY | 短信核验 |
经办人信息(AgentInfo) 说明:
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| agentName | String | 是 | 经办人姓名 |
| agentId | String | 是 | 经办人证件号 |
| agentPhone | String | 否 | 经办人手机号码,若需使用短信核验,则必填 |
法人信息(LegalInfo) 说明:
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| legalName | String | 是 | 法人姓名 |
| legalIdCard | String | 否 | 法人证件号 |
| legalPhone | String | 否 | 法人手机号码 |
| legalIdType | IdType | 否 | 法人证件类型,取值参考证件类型(IdType)说明 |
请求示例(证书实体字段与其它参数同层级平铺提交,agentInfo/legalInfo 以点号嵌套):
http://api.ca.demo.smartcert.cn/api |
三、响应参数
| data 结果信息 | 类型 | 描述 |
|---|---|---|
| message | String | 业务描述 |
| incorrect | String | 业务返回码 |
| code | String | 业务码,后续获取结果使用 |
| h5Url | String | H5签发链接 |
| expireTime | Long | 过期时间 |
四、成功示例
JSON示例
{ |
五、失败示例
JSON示例
{ |
六、返回码说明(incorrect)
| 返回码 | 描述 |
|---|---|
| 0 | 证书申请请求成功 |
| 其它 | 参考异常代码表 |
证书申请 - 获取申请状态
传入证书申请业务码,获取申请状态。
一、公共参数
-
请求地址:http://api.ca.demo.smartcert.cn/api,http://api.ca.demo.smartcert.cn/api
服务接口名称(即公共参数 method 的值): cert.application.state
请求方式:POST
二、请求参数(请求方式为 post)
- 请求参数以表单形式提交,Content-Type 值为: application/x-www-form-urlencoded;charset=utf-8
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| code | String | 是 | 业务码 |
请求示例:
http://api.ca.demo.smartcert.cn/api |
三、响应参数
| data 结果信息 | 类型 | 描述 |
|---|---|---|
| message | String | 业务描述 |
| incorrect | String | 业务返回码 |
| code | String | 业务码 |
| h5Url | String | H5页面地址 |
| state | String | 证书申请状态 |
| livingVerifyState | String | 实人核验状态 |
| entVerifyState | String | 企业核验状态 |
| auditComment | String | 审核原因(审核意见),仅在材料审核驳回或活体核验审核拒绝时返回 |
证书申请状态(state)说明:
| 名称 | 描述 |
|---|---|
| CREATED | 已创建- 初始状态 |
| INFO_CONFIRMED | 证书信息已确认 |
| MATERIAL_REVIEWING | 材料审核中 |
| MATERIAL_APPROVED | 材料审核通过 |
| MATERIAL_REJECTED | 材料审核驳回 |
| ENT_BANK_PAY_RUNNING | 对公打款中 |
| ENT_BANK_PAY_APPROVED | 对公打款成功 |
| ENT_BANK_PAY_FAILED | 对公打款失败 |
| VERIFICATION_PROCESSING | 身份核验中 |
| VERIFICATION_APPROVED | 身份核验通过 |
| WILL_VERIFICATION_PROCESSING | 意愿认证中 |
| AGREEMENT_PENDING | 待签署协议 |
| AGREEMENT_SIGNED | 协议已签署 |
| OVER | 已完成 |
| ERROR | 异常 |
| EXPIRED | 已过期 |
当 state 为
ERROR时,message 返回具体异常原因;state 为EXPIRED时表示申请已超时过期。两种状态均不再返回 h5Url。
实人核验状态(livingVerifyState)说明:
| 名称 | 描述 |
|---|---|
| PENDING_VERIFY | 待核验 |
| VERIFY_FAILED | 核验失败 |
| PENDING_REVIEW | 待审核 |
| REJECTED | 审核拒绝 |
| APPROVED | 通过 |
企业核验状态(entVerifyState)说明:
| 名称 | 描述 |
|---|---|
| MATERIAL_REVIEWING | 材料审核中 |
| MATERIAL_APPROVED | 材料审核通过 |
| MATERIAL_REJECTED | 材料审核驳回 |
| ENT_BANK_PAY_RUNNING | 对公打款中 |
| ENT_BANK_PAY_APPROVED | 对公打款成功 |
| ENT_BANK_PAY_FAILED | 对公打款失败 |
四、成功示例
JSON示例
{ |
五、失败示例
JSON示例
{ |
六、返回码说明(incorrect)
| 返回码 | 描述 |
|---|---|
| 0 | 证书申请状态请求成功 |
| 1 | 证书申请记录状态异常 |
| 2 | 证书申请已取消 |
| 3 | 证书申请已过期 |
| 4 | 材料审核失败(审核意见见 message / auditComment) |
| 其它 | 参考异常代码表 |
证书申请 - 获取申请结果
传入证书申请业务码,获取申请结果。
一、公共参数
-
请求地址:http://api.ca.demo.smartcert.cn/api,http://api.ca.demo.smartcert.cn/api
服务接口名称(即公共参数 method 的值): cert.application.result
请求方式:POST
二、请求参数(请求方式为 post)
- 请求参数以表单形式提交,Content-Type 值为: application/x-www-form-urlencoded;charset=utf-8
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| code | String | 是 | 业务码 |
请求示例:
http://api.ca.demo.smartcert.cn/api |
三、响应参数
| data 结果信息 | 类型 | 描述 |
|---|---|---|
| message | String | 业务描述 |
| incorrect | String | 业务返回码 |
| certId | String | 证书 ID |
| signatureCert | String | 签名证书 |
| encryptionCert | String | 加密证书 |
| encryptionPrivateKey | String | 加密私钥 |
| personVerificationResult | String | 加密后的个人验证结果,需使用系统提供的指定appKey和appSecret调用指定方法解密,可参考SDK中提供的调用示例使用,(也可点我查看详细使用) |
四、成功示例
JSON示例
{ |
五、失败示例
JSON示例
{ |
六、返回码说明(incorrect)
| 返回码 | 描述 |
|---|---|
| 0 | 证书申请请求成功 |
| 其它 | 参考异常代码表 |
证书签发 - 根据code+P10 签发证书
传入证书申请业务码+P10,签发证书
一、公共参数
-
请求地址:http://api.ca.demo.smartcert.cn/api,http://api.ca.demo.smartcert.cn/api
服务接口名称(即公共参数 method 的值): cert.application.issue
请求方式:POST
二、请求参数(请求方式为 post)
- 请求参数以表单形式提交,Content-Type 值为: application/x-www-form-urlencoded;charset=utf-8
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| p10 | String | 是 | 用于制作证书的p10 |
| code | String | 是 | 业务码 |
请求示例:
http://api.ca.demo.smartcert.cn/api |
三、响应参数
| data 结果信息 | 类型 | 描述 |
|---|---|---|
| message | String | 业务描述 |
| incorrect | String | 业务返回码 |
| certId | String | 证书 ID |
| signatureCert | String | 签名证书 |
| encryptionCert | String | 加密证书 |
| encryptionPrivateKey | String | 加密私钥 |
| personVerificationResult | String | 加密后的个人验证结果,需使用系统提供的指定appKey和appSecret调用指定方法解密,可参考SDK中提供的调用示例使用,(也可点我查看详细使用) |
四、成功示例
JSON示例
{ |
五、失败示例
JSON示例
{ |
六、返回码说明(incorrect)
| 返回码 | 描述 |
|---|---|
| 0 | 证书申请请求成功 |
| 其它 | 参考异常代码表 |
证书注销
输入证书标识,注销证书。
一、公共参数
服务接口名称(即公共参数 method 的值): revoke
请求方式:POST 或 GET
二、请求参数
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| request | RevokeRequest | 是 | 证书注销请求 |
RevokeRequest 说明
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| certId | String | 是 | 证书唯一标识 |
| extensions | Map | 否 | 扩展属性 |
请求示例:
http或https://222.190.151.234:2016/api? |
三、响应参数
| 业务响应名称 | 类型 | 描述 |
|---|---|---|
| incorrect | String | 结果响应码 |
| message | String | 注销说明 |
| certId | String | 证书 ID |
| result | Boolean | 注销结果 |
| extensions | Map<String,String> | 扩展项 |
四、成功示例
JSON示例
{ |
五、失败示例
JSON示例
{ |
六、返回码说明(incorrect)
| 返回码 | 描述 |
|---|---|
| 0 | 证书注销成功 |
| 其它 | 参考异常代码表 |
证书延期
输入证书标识和需要延期的天数,对该证书进行延期。
一、公共参数
-
请求地址:http://api.ca.demo.smartcert.cn/api,http://api.ca.demo.smartcert.cn/api
服务接口名称(即公共参数 method 的值): postpone
请求方式:POST 或 GET
二、请求参数
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| request | PostponeRequest | 是 | 证书延期请求 |
PostponeRequest 说明:
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| certId | String | 是 | 证书唯一标识 |
| pkCS10 | String | 否 | 用于制作证书的 pkCS10 |
| duration | String | 否 | 证书延期时间,格式为数字+字母,字母支持YMDHm,分别对应年月日时分,不传默认1Y。 |
| userOldKey | Boolean | 否 | 是否使用原密钥对,默认为 True(此选项针对加密证书密钥对) |
| extensions | Map | 否 | 扩展属性 |
请求示例:
http或https://222.190.151.234:2016/api? |
三、响应参数
| data 结果信息 | 类型 | 描述 |
|---|---|---|
| signatureCert | String | 签名证书 |
| encryptionCert | String | 加密证书 |
| encryptionPrivateKey | String | 加密私钥 |
| certId | String | 证书 ID |
| message | String | 业务响应描述 |
| incorrect | String | 业务返回码 |
| extensions | Map<String,String> | 扩展项 |
四、成功示例
JSON示例
{ |
五、失败示例
JSON示例
{ |
六、返回码说明(incorrect)
| 返回码 | 描述 |
|---|---|
| 0 | 延期成功 |
| 其它 | 参考异常代码表 |
证书重发
传入证书标识和介质 P10,对相应证书做重发。
一、公共参数
-
请求地址:http://api.ca.demo.smartcert.cn/api,http://api.ca.demo.smartcert.cn/api
服务接口名称(即公共参数 method 的值): reissue
请求方式:POST
二、请求参数(请求方式为 post)
- 请求参数以表单形式提交,Content-Type 值为: application/x-www-form-urlencoded;charset=utf-8
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| request | ReissueRequest | 是 | 证书重发请求 |
ReissueRequest 说明
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| certId | String | 是 | 证书 id |
| pkCS10 | String | 否 | 用于制作证书的 pkCS10 (建议使用) |
| userOldKey | Boolean | 否 | 是否使用原密钥对,默认为 True(此选项针对加密证书密钥对) |
| extensions | Map | 否 | 扩展属性 |
请求示例:
http://api.ca.demo.smartcert.cn/api |
三、响应参数
| data 结果信息 | 类型 | 描述 |
|---|---|---|
| message | String | 描述 |
| incorrect | String | 返回码 |
| signatureCert | String | 签名证书 |
| encryptionCert | String | 加密证书 |
| encryptionPrivateKey | String | 加密私钥 |
| certId | String | 证书 ID |
| extensions | Map<String,String> | 扩展项 |
四、成功示例
JSON示例
{ |
五、失败示例
JSON示例
{ |
六、返回码说明(incorrect)
| 返回码 | 描述 |
|---|---|
| 0 | 证书重发成功 |
| 其它 | 参考异常代码表 |
证书密钥恢复
传入证书标识和介质 P10,对相应证书进行密钥恢复。
一、公共参数
-
请求地址:http://api.ca.demo.smartcert.cn/api,http://api.ca.demo.smartcert.cn/api
服务接口名称(即公共参数 method 的值): recover
请求方式:POST
二、请求参数(请求方式为 post)
- 请求参数以表单形式提交,Content-Type 值为: application/x-www-form-urlencoded;charset=utf-8
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| request | RecoverRequest | 是 | 证书密钥恢复请求 |
ReissueRequest 说明
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| certId | String | 是 | 证书 id |
| pkCS10 | String | 是 | 用于制作证书的 pkCS10 |
| extensions | Map | 否 | 扩展属性 |
请求示例:
http://api.ca.demo.smartcert.cn/api |
三、响应参数
| data 结果信息 | 类型 | 描述 |
|---|---|---|
| message | String | 描述 |
| incorrect | String | 返回码 |
| encryptionCert | String | 加密证书 |
| encryptionPrivateKey | String | 加密私钥 |
| signatureCert | String | 签名证书 |
| certId | String | 证书 ID |
| extensions | Map<String,String> | 扩展项 |
四、成功示例
JSON示例
{ |
五、失败示例
JSON示例
{ |
六、返回码说明(incorrect)
| 返回码 | 描述 |
|---|---|
| 0 | 证书密钥恢复成功 |
| 其它 | 参考异常代码表 |
根据id查询证书
传入证书id,精确查询证书。
一、公共参数
-
请求地址:http://api.ca.demo.smartcert.cn/api,http://api.ca.demo.smartcert.cn/api
服务接口名称(即公共参数 method 的值): query.by.id
请求方式:POST
二、请求参数(请求方式为 post)
- 请求参数以表单形式提交,Content-Type 值为: application/x-www-form-urlencoded;charset=utf-8
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| request | CertQueryByIdRequest | 是 | 根据证书id查询证书请求 |
CertQueryByIdRequest 说明:
| 名称 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| certId | String | 是 | 待查询证书的标识 |
请求示例:
http://api.ca.demo.smartcert.cn/api |
三、响应参数
| data 结果信息 | 类型 | 描述 |
|---|---|---|
| certJson | String | 证书对象json 格式 |
四、成功示例
JSON示例
{ |
五、失败示例
JSON示例
{ |
六、返回码说明(incorrect)
| 返回码 | 描述 |
|---|---|
| 0 | 证书查询成功 |
| 其它 | 参考异常代码表 |
回调通知接口示例
当申请证书结束后,平台服务器会向用户提供的noticeUrl参数地址向用户发送 HTTP 通知。
用户在接收到参数时,需要对参数进行验签,在确认无误的情况下,向实名认证系统返回”success”字符串。
参数说明
| 属性 | 类型 | 描述 |
|---|---|---|
| appKey | String | 身份标识 |
| timestamp | String | 时间戳 |
| nonce | String | 随机数 |
| version | String | API 版本号,目前版本是 1 |
| signMethod | String | 签名算法,默认HMAC-SHA256 |
| sign | String | 签名值 |
| code | String | 业务码 |
| state | String | 状态 |
| encryptionCert | String | 加密证书,state为 OVER时返回 |
| encryptionPrivateKey | String | 加密私钥,state为 OVER时返回 |
| signatureCert | String | 签名证书,state为 OVER时返回 |
| certId | String | 证书 ID,state为 OVER时返回 |
state参数说明
| state | 描述 |
|---|---|
| OVER | 已完成,可获取证书信息 |
| ERROR | 异常 |
回调通知接口示例
@PostMapping("/callback") |
url跳转说明
在配置successUrl、failUrl的情况下,流程结束或异常时会进行页面跳转,跳转时会以query的方式在url后拼接参数。
用户在接收到参数时,需要对参数进行验签。
参数示例
以 https://www.smartcert.cn/ 为跳转示例,生成如下url
https://www.smartcert.cn/?code=xxxxx&sign=3A9512A018B9709764CCB9CC1E0D0B7BF83C2A47E8DD3563D195B9F520AA1B17&appKey=xxxx&state=OVER&nonce=oaUDl2Gror&version=1&signMethod=HMAC-SHA256×tamp=1777346392048 |
拼接 参数说明(successUrl、failUrl)
| 属性 | 描述 |
|---|---|
| code | 业务码 |
| sign | 签名 |
| appKey | 应用标识 |
| state | 状态 |
| nonce | 随机字符串 |
| version | 版本 |
| signMethod | 签名方法 |
| timestamp | 时间戳 |
url验签
auditNoticeUrl 参数说明(审核通知地址)
| 属性 | 描述 |
|---|---|
| code | 业务码 |
| sign | 签名 |
| appKey | 应用标识 |
| state | 状态 |
| livingVerifyState | 活体核验状态 |
| entVerifyState | 企业核验状态 |
| auditComment | 审核意见 |
| nonce | 随机字符串 |
| version | 版本 |
| signMethod | 签名方法 |
| timestamp | 时间戳 |
livingVerifyState 活体核验状态 参数说明
| 属性 | 描述 |
|---|---|
| PENDING_VERIFY | 待核验 |
| PENDING_REVIEW | 待审核 |
| REJECTED | 审核拒绝 |
| APPROVED | 通过 |
| VERIFY_FAILED | 核验失败 |
entVerifyState 企业核验状态 参数说明
| 属性 | 描述 |
|---|---|
| MATERIAL_REVIEWING | 材料审核中 |
| MATERIAL_APPROVED | 材料审核通过 |
| MATERIAL_REJECTED | 材料审核驳回 |
| ENT_BANK_PAY_RUNNING | 对公打款中 |
| ENT_BANK_PAY_APPROVED | 对公打款成功 |
| ENT_BANK_PAY_FAILED | 对公打款失败 |
/** |
签名验签工具类
import org.apache.commons.lang3.StringUtils; |
SM4加解密方法示例
- 将 appKey 和 appSecret 拼接
- 对拼接后的结果做SM3摘要,取结果的前16字节作为密钥 (SM3结果长度是固定的32字节)
- 使用密钥进行SM4 CBC模式加解密,向量为16个字节0
- 将加密后的数据转为base64格式的字符
public static void main(String[] args) {
//您的appKey
String appKey = "123";
//您的appSecret
String appSecret = "234";
// 加密值
String value = "123";
// 拼接appKey和appSecret
String str = appKey + appSecret;
byte[] bytes = Sm3Utils.sm3Digest(str);
byte[] password = new byte[16];
System.arraycopy(bytes, 0, password, 0, 16);
// 加密数据
String encryptValue = Sm4Utils.encryptToString(value, password);
System.out.println("加密后数据 = " + encryptValue);
// 解密数据
String decrypt = Sm4Utils.decryptToString(encryptValue, password);
System.out.println("解密后数据 = " + decrypt);
}
调用示例
- 将 appSecret 和 appKey 拼接
appKey = “ODRp4fQmiQ1Vytrk”
appSecret = “ewEw3wsRtvgsPFonulBdpmmexZoACD09” - 对拼接后的结果做SM3摘要,取结果的前16字节作为密钥
密钥HEX结果为: c6d9460afd6597aef3a7d59cda11355c - 使用密钥进行 SM4-CBC 模式加解密 数据原文为123,使用密钥进行加密,将加密结果进行base64编码,获取结果
为:
InjV38FSUoeUA2kChAsLzg==