资源中心芝麻认证初始化
您可以点击纯净版进行查看

开始接入

欢迎你成为芝麻信用的商户,在开始接口调用之前请先确保完成以下事项:

  1. 完成 商户入驻 流程,并已经完成本 产品签约
  2. 你需要获取一个 应用 ID,并完成必要的开发 环境配置
  3. 芝麻开放平台通过 HTTPS 通信进行接口调用,包含系统调用和页面转跳两类接口,相关概念参照 接口调用;参数的加密解密和加签验签参考 介绍文档
  4. 业务流水凭证(transaction_id)是商户与芝麻信用系统产生业务交互的唯一凭证,生成规则参考 业务流水凭证
  5. 部分芝麻信用产品需要商户进行数据反馈,参考文档 数据反馈 部分;
  6. 入参中包含 open_id 的产品需要进行 用户授权
  7. 芝麻开放平台提供了 Java 1.5、Java 1.4 、PHP 和 .NET 的服务端 SDK 供商家快速接入服务使用,SDK 能够在 开发工具包下载页 获取。

接口信息

API 名称 zhima.customer.certification.initialize
API 中文名称 芝麻认证初始化
API 描述信息 芝麻认证初始化

请求参数

系统参数:

参数名

类型

是否必须

是否芝麻分配

示例值

备注

app_id

String

1000033

商户技术开发自助创建的应用标识

charset

String

UTF-8

加密加签时使用的charset

method

String

zhima.customer.certification.initialize

要调用的接口名

version

String

1.0

接口版本,目前只支持1.0

platform

String

zmop

来源平台,默认为zmop

params

String

加密后信息

RSA加密后的业务参数

sign

String

加密后信息

对params参数加密前的签名,算法为SHA1WithRSA


业务参数:

注:入参中的产品码(product_code)直接使用当前表格中的示例值即可

名称 类型 是否必须 描述 示例值
transaction_id String 商户请求的唯一标志,32位长度的字母数字下划线组合。该标识作为对账的关键信息,商户要保证其唯一性.建议:前面几位字符是商户自定义的简称,中间可以使用一段日期,结尾可以使用一个序列 ZGYD201610252323000001234
product_code String 芝麻认证产品码,示例值为真实的产品码 w1010100000000002978
biz_code String 认证场景码,支持的场景码有: FACE:多因子活体人脸认证, SMART_FACE:多因子快捷活体人脸认证, FACE_SDK:SDK活体人脸认证 签约的协议决定了可以使用的场景 FACE
identity_param String 值为一个json串,无入参时值为"{}",有入参时必须指定身份类型identity_type,不同的身份类型对应的身份信息不同 当前支持: 身份信息为证件信息,identity_type值为CERT_INFO: 证件类型为身份证cert_type值为IDENTITY_CARD,必要信息cert_name和cert_no; 身份信息为短信手机号,适用于短信认证,identity_type值为SMS_MOBILE_NO: 证件类型可以为空,当证件类型为身份证cert_type值为IDENTITY_CARD,必要信息cert_name和cert_no,mobile_no可以为空,以上信息没有传入的时候会上用户录入; 身份信息为支付宝UID,identity_type值为USER_ID: 必要信息user_id 示例:{"identity_type": "USER_ID", "user_id": "2088172637486509"} {"identity_type": "CERT_INFO", "cert_type": "IDENTITY_CARD", "cert_name": "收委", "cert_no":"260104197909275964"}
merchant_config String 认证商户自定义配置,支持一些商户可选的功能 need_user_authorization: 值为true或者false 当值为true时,在认证用户引导页会展示用户授权协议,在认证通过后会进行授权,但是授权是否成功不影响认证结果 {"need_user_authorization":"false"}
ext_biz_param String 扩展业务参数,暂时没有用到,接口预留 {}

响应参数

名称 类型 是否列表 描述
biz_no String 本次认证的唯一标识,商户需要记录,biz_no有效期为23小时

请求示例

JDK 1.4 JDK 1.5 PHP .NET Python


import com.antgroup.zmxy.openplatform.api.DefaultZhimaClient;
import com.antgroup.zmxy.openplatform.api.FileItem;
import com.antgroup.zmxy.openplatform.api.ZhimaApiException;
import com.antgroup.zmxy.openplatform.api.request.ZhimaCustomerCertificationInitializeRequest;
import com.antgroup.zmxy.openplatform.api.response.ZhimaCustomerCertificationInitializeResponse;

public class TestZhimaCustomerCertificationInitialize {
    //芝麻开放平台地址
    private String gatewayUrl     = "https://zmopenapi.zmxy.com.cn/openapi.do";
    //商户应用 Id
    private String appId          = "***";
    //商户 RSA 私钥
    private String privateKey     = "***";
    //芝麻 RSA 公钥
    private String zhimaPublicKey = "***";

    public void  testZhimaCustomerCertificationInitialize() {
        ZhimaCustomerCertificationInitializeRequest req = new ZhimaCustomerCertificationInitializeRequest();
        req.setChannel("apppc");
        req.setPlatform("zmop");
        req.setTransactionId("ZGYD201610252323000001234");// 必要参数 
        req.setProductCode("w1010100000000002978");// 必要参数 
        req.setBizCode("FACE");// 必要参数 
        req.setIdentityParam("{\"identity_type\": \"CERT_INFO\", \"cert_type\": \"IDENTITY_CARD\", \"cert_name\": \"收委\", \"cert_no\":\"260104197909275964\"}");// 必要参数 
        req.setMerchantConfig("{\"need_user_authorization\":\"false\"}");// 
        req.setExtBizParam("{}");// 必要参数 
        DefaultZhimaClient client = new DefaultZhimaClient(gatewayUrl, appId, privateKey, zhimaPublicKey);
        try {
            ZhimaCustomerCertificationInitializeResponse response =(ZhimaCustomerCertificationInitializeResponse)client.execute(req);
            System.out.println(response.isSuccess());
            System.out.println(response.getErrorCode());
            System.out.println(response.getErrorMessage());
        } catch (ZhimaApiException e) {
            e.printStackTrace();
        }
    }

    public static void main(String[] args) {
        TestZhimaCustomerCertificationInitialize result = new  TestZhimaCustomerCertificationInitialize();
        result.testZhimaCustomerCertificationInitialize();
    }
}

响应示例

正确示例 1


{
  "bizNo": "ZM201703313000000191900768449771",
  "body": "{\"success\":true,\"biz_no\":\"ZM201703313000000191900768449771\"}",
  "params": {
    "params": "Gejqzwt7S+sxsa12F73kGtLasGl/D7Inu4QB842ujACpV4POjxEzgFC9zof+3dbngO8GZJqUrNcUX9Y/yAxo9fDBtJk//uR9rhvnJ2PXOZhJM8qfJqNbzFn3mPyVCHQORdKOtdmkMjDuRIu5sda0qpLMRW8ANII2r6xzAbmX1clpBuQ0+KCw6+dmRAmF2jaFFJzRnkwD6uj8WoI2YZB2OR/lBcCVcAbuoUVNkr45mP9Q7wW/68/0r5fOPIZdKzBy61oJsRfMXboro3BFKUyhgC0wS2he3Hkz7aNjP0baWCVD5TIOvThLiTphHV7/Sx9NddmTBKMuwHy0g7JOjPvpbnLmi6w/Ol1SNBHZJww+m1+YjePxSAnU5KH5GENZwF+nPoLRXUkA/zQK8/3DEwg4zNJKfmx2huKFInzhFFSwXcnn1KmpcxxJlvUOF20K9iun5eE1rX6ZBrR1lbotSacGLcBNPxiLWGO/Pd1qWFoCOmT/JX3LxLf9k/R876xtFzWL"
  },
  "success": true
}

异常示例

错误示例 1 错误示例 2 错误示例 3


{
  "errorMessage": "未知错误",
  "errorCode": "ZMOP.unknow_error",
  "body": "{\"error_message\":\"未知错误\",\"error_code\":\"ZMOP.unknow_error\",\"success\":false}",
  "params": {
    "params": "IYmgKHcuBFHXhr8io7Ono7itDy9oIBteK3tXisk7jA7ma+wayhYb9crjcecSNETXgmCqTR8s0sYgyfER6Y2vqYkRu9tDkWLgC5dSUHnfR39Nf9Z+NiAxuZqE3xVJUAp1Yt7Fs5m8YiQOXPxENrAd5DUmhVLme8CSgUxLgOi5CRuM6JxjHPzZ3JDTBZKek/h8oY9sxJNqXYUxvYourxqd2N07MzAZ90wujikWiQbT76mja9K1ESL3B7Xm3zouD1XDrXVOVgqnQw+KOKw9IbFW3Kut1Z9I6H/dAVQ8BNl2lMHQS6zfYKsv/E7xacQ412scKCxJuz7DPbevX5PEC+G430XBO08UHtMebacRNv/zwVTEDj8yNUYr2nA1d0Z5e+XmzLCoAE+o+2GsowS+ooaNungaViDdvFlBnOmi+3TWpuJY84ye9yS7VKhie1lDnptC/2BDZDmw6cFIO+LBzXeaGEFX4q33IvYV3/MObtkWpU6SP4am4rL/G6Bbd/Q15nND"
  },
  "success": false
}

错误码说明

接口错误码
名称 错误描述 解决方案
ZMCSP.arrangement_error 合约异常 请确定的产品码正确,合约已经生效,并且包含此业务的权限
ZMCSP.certify_init_failed 认证初始化失败 请根据错误码描述检查错误原因
ZMCSP.illegal_argument 参数有误 根据错误码描述修改入参后再重试
ZMCSP.system_failure 系统繁忙 系统繁忙,请稍后再试
ZMCSP.transaction_error 交易订单异常 交易订单更新失败,请稍后重新发起
ZMCSP.unsupported_biz_code 不支持的认证场景 不支持的认证场景,请使用已签约的认证场景

系统错误码
名称 错误描述 解决方案
ZMOP.isv_cannot_invoke_method 平台服务商自营模式下不能调用该接口 平台服务商自营模式下不能调用该接口
ZMOP.not_isv_invoke_method 非平台类商户不能调用该接口 非平台类商户不能调用该接口
ZMOP.private_api_invoke_error 私有接口不能调用 芝麻开放平台不能调用私有接口
ZMOP.linked_merchant_relation_error 二级商户的关联关系错误 该二级商户不属于平台服务商
ZMOP.linked_merchant_zhima_freezed 二级商户被芝麻冻结 请联系芝麻客服,解冻该二级商户
ZMOP.linked_merchant_not_zhima_certificated 二级商户未通过芝麻认证 二级商户必须通过芝麻认证
ZMOP.linked_merchantid_not_certificated 二级商户未认证 二级商户必须通过认证
ZMOP.linked_merchant_is_null 二级商户不存在 请先确认二级商户是否存在
ZMOP.aop_platform_merchant_not_isv AOP渠道调用的平台服务商必须是非ISV模式 AOP渠道调用的平台服务商必须是非ISV模式
ZMOP.linked_merchantid_is_null 二级商户标识为空 平台服务商调用时,二级商户标识必须存在
ZMOP.linked_merchant_is_not_null 非平台类商户的二级商户必须为空 非平台类商户的二级商户必须为空
ZMOP.invalid_merchantid_param 无效的商户标识 请确认商户标识
ZMOP.app_invoke_excess_limit app接口调用受限 测试应用在使用中只能对特定配置的接口进行调用
ZMOP.missing_authtemplate_param 缺少授权模板参数 请确保已经创建了对应的授权模式
ZMOP.app_invoke_excess_limitation 应用调用服务次数超限 请降低应用调用的qps
ZMOP.invoke_isp_error 调用服务接口错误 芝麻内部服务出现错误,请稍后再试
ZMOP.invalid_openid_param 无效的open_id参数 请使用授权成功返回的open_id查询授权类信用产品.
ZMOP.cache_page_param_error 缓存签名参数错误 芝麻内部服务出现错误,请稍后再试
ZMOP.sign_system_param_error 用芝麻私钥加签返回结果错误 芝麻内部服务出现错误,请稍后再试
ZMOP.sign_page_param_error 用芝麻私钥加签页面参数错误 芝麻内部服务出现错误,请稍后再试
ZMOP.verify_sign_app_public_key_error 用商户公钥验签错误 请使用商户私钥加签
ZMOP.decode_private_key_error 用芝麻私钥解密错误 请使用芝麻公钥对数据加密
ZMOP.missing_interfaceconfig 缺少对应的接口配置信息 请确保接口名称和版本信息是否正确
ZMOP.missing_version_param 缺少version参数 请输入接口版本参数
ZMOP.missing_method_param 缺少method参数 请输入接口方法参数
ZMOP.invalid_charset_param 无效charset参数 请验证编码是否正确
ZMOP.missing_charset_param 缺少charset参数 请输入数据传输的编码
ZMOP.invalid_scene_param 无效的scene参数 请验证场景参数是否正确
ZMOP.missing_scene_param 缺少scene参数 请输入场景参数
ZMOP.missing_sign_param 缺少sign参数 请验证签名参数正确
ZMOP.missing_params_param 缺少params参数 请验证请求参数是否正确
ZMOP.invalid_channel_param 无效的channel参数 请验证请求方式是否正确
ZMOP.invalid_platform_param 无效的platform参数 请验证platform参数是否正确
ZMOP.invalid_app_status 应用生命周期状态错误 应用的状态必须是上线
ZMOP.invalid_appruntime_state 应用运行状态错误 应用的运行状态必须是正常
ZMOP.invalid_platform_appid_param 无效的渠道商app_id参数 请校验渠道商app_id是否正确
ZMOP.missing_platform_appid_param 缺少渠道商的app_id参数 请输入渠道商的app_id
ZMOP.unknow_error 未知错误 重试
ZMOP.invalid_appid_param 无效的app_id参数 传入正确的app_id
ZMOP.missing_appid_param 缺少app_id参数 传入app_id参数
  1. 开始接入
  2. 接口信息
  3. 请求参数
  4. 响应参数
  5. 请求示例
  6. 响应示例
  7. 异常示例
  8. 错误码说明
onlineServer