支付宝芝麻信用商家接入教程

JAVA herman 1905浏览 0评论

总结一下,常用的第三方开放API,一般都有一下几个要素:应用ID,应用公钥,应用私钥,请求公共URL,请求接口方法名。
对于芝麻信用的话,这些都是必须的,那么芝麻对于API接口的定义,官方的解释如下:

目前芝麻信用开放平台支持两种类型的接口,一种是系统调用类接口,主要是商户后端直接通过HTTP的方式进行接口调用,并同步返回结果给商户。另外一种是页面跳转类接口,这种接口的用法是商户在浏览器中输入芝麻信用开放平台的URL并组织好对应的参数,以HTTP GET的方式进行调用,用户页面授权接口(zhima.auth.info.authorize)就是属于页面跳转类接口,用户在页面上完成相应的操作后,浏览器最后跳转到商户提供的callback URL,并带上业务的返回结果在callback页面的URL中,从而商户可以在后台从callback URL的请求中把业务返回结果拿到。

每个通过芝麻信用开放平台输出的芝麻信用产品,都会对应于一个注册在开放平台中的接口(API),这些接口中会定义业务参数的列表,系统参数列表,返回值字段列表,以及错误码列表。每个接口会有一个对应的接口文档,里面会对系统参数、业务参数、返回值和错误码都有详细的描述。

首先我们要明白芝麻信用是怎么跟我们进行交互的,那既然牵扯到接口的交互,那么肯定我们想到,需要一个地址去进行交互,那么这个地址又是什么呢?这个地址就是:https://zmopenapi.zmxy.com.cn/openapi.do ,  我们可以把它看成是一个入口,所有和芝麻进行交互的一个入口,在入口的地方有很多的警卫员,我们需要出示工牌(凭证)才能进入办公(执行方法),如果我们的凭证(比如APPID,私钥)等错误的话,那么我们就不被拥有准入权限。下面一张表格更加详细的介绍了芝麻的一些准入凭证等。

 

参数名

类型

是否必须

是否芝麻分配

示例值

备注

app_id

String

1000033

商户应用ID

charset

String

UTF-8

加密加签时使用的charset

method

String

zhima.auth.info.authorize

要调用的接口名

version

String

1.0

接口版本,目前只支持1.0

platform

String

zmop

来源平台,默认为zmop

params

String

abc

RSA加密后的业务参数

sign

String

bcd

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

 

对于上面的表格,介绍一下几个详细点:

  1. APPID即应用ID,这个是芝麻给我们的应用单独分配的APPID,它其实是和Sign结合起来使用的,这说得有点迷糊,因为从上图来说,Sign是客户端生成的,所以我们首先需要了解一下Sign(签名)的生成机制,其实也就是说,一个APPID,一次请求,会有一个独一无二的签名对应起来,签名就好像我开始说的准入凭证,其实更形象的比喻就是一把钥匙。
  2. method后面会提到更多,其实当你进入“办公场所”以后,你会发现其实不止一个部门,如果你想和某一个部门的人交流或者进入某个部门(当然现实中不存在或者很少有这种情况),你就需要一个method(方法),当然更确切的比喻就是,如果你的面前有很多的保险柜,不同部门的保险柜需要你输入不同的密码,而在输入密码以前你会选择是要对哪个保险柜进行操作,这个时候“方法”就是一个不可替代的前置条件了。
  3. params,简单理解,就是你的Action对应的 get请求的参数。

其实主要是介绍了Sign的形成的方法,他们经历了如下过程,下面是官方的解释,简单点概括,就是客户端加密,然后传到服务端,然后服务端解密,给出正确的数据,然后再加密返回给客户端,客户端再进行解密后拿到正确的数据,具体的过程可以参考文档。

商户端发起请求到芝麻信用时

  商户使用芝麻信用的RSA公钥对业务参数进行RSA加密,使用商户自己的RSA私钥对业务参数进行签名;
  芝麻信用使用芝麻信用的RSA私钥进行业务参数的解密,使用商户的RSA公钥进行验签。

芝麻信用返回调用结果给商户时

  芝麻信用使用商户的RSA公钥对业务返回结果进行RSA加密,使用芝麻信用自己的RSA私钥对业务返回结果进行签名;
  商户使用商户自己的RSA私钥对业务返回结果进行解密,使用芝麻的RSA公钥对业务返回结果进行验签

这里需要注意3个参数:

序号 参数名称 用途 示例
1 open_id 芝麻用户在商户端的身份标识,商户维度唯一且终生保持不变;
芝麻用户在商户端完成授权后生成。
268808719417710052884472095
2 product_code 产品码,标记商户接入的具体产品;
直接使用每个接口入参中示例值即可。
w1010100100000000001
3 transaction_id 商户请求的唯一标志,长度64位以内字符串,仅限字母数字下划线组合。
该标识作为业务调用的唯一标识,商户要保证其业务唯一性,使用相同transaction_id的查询,芝麻在一段时间内(一般为1天)返回首次查询结果,超过有效期的查询即为无效并返回异常,有效期内的重复查询不重新计费。
20151127233347987676212309253,或直接采用UUID

尤其是transaction_id,为什么说Transation_id非常的重要呢,我们知道,芝麻不是慈善机构,你每调用它一次,肯定是要收取费用的,而这个Transaction_id其实是当天有效的,所以我们可以在缓存中保存这个id,如果一天内有多次调用,那么用这一个就够了,否则会造成多余的RMB浪费。
下面我会讲到2个接口,一个是获得授权(openid),另外一个是芝麻信用分的。或者授权(openid)的接口请看这里。关于详细的介绍文档里面都已经说得非常清楚了,我使用的是姓名+身份证的方式进行认证,方式是H5,具体的示例代码如下,参数请根据自己的情况自行调整,服务端SDK可以根据自己的语言选择合适的。

以下为相关java实现代码:

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.ZhimaAuthInfoAuthorizeRequest;
import com.antgroup.zmxy.openplatform.api.response.ZhimaAuthInfoAuthorizeResponse;
 
public class TestZhimaAuthInfoAuthorize {
    //芝麻开放平台地址
    private String gatewayUrl     = "https://zmopenapi.zmxy.com.cn/openapi.do";
    //商户应用 Id
    private String appId          = "***";
    //商户 RSA 私钥
    private String privateKey     = "***";
    //芝麻 RSA 公钥
    private String zhimaPublicKey = "***";
    public void  testZhimaAuthInfoAuthorize() {
        ZhimaAuthInfoAuthorizeRequest req = new ZhimaAuthInfoAuthorizeRequest();
        req.setChannel("apppc");
        req.setPlatform("zmop");
               req.setIdentityType("1");// 必要参数        
               req.setIdentityParam("{\"name\":\"张三\",\"certType\":\"IDENTITY_CARD\",\"certNo\":\"330100xxxxxxxxxxxx\"}");// 必要参数        
               req.setBizParams("{\"auth_code\":\"M_H5\",\"channelType\":\"app\",\"state\":\"商户自定义\"}");//        
                DefaultZhimaClient client = new DefaultZhimaClient(gatewayUrl, appId, privateKey,
            zhimaPublicKey);
        try {
            String url = client.generatePageRedirectInvokeUrl(request);  
            System.out.println(url);
        } catch (ZhimaApiException e) {
            e.printStackTrace();
        }
    }
    public static void main(String[] args) {
        TestZhimaAuthInfoAuthorize result = new  TestZhimaAuthInfoAuthorize();
        result.testZhimaAuthInfoAuthorize();
    }
}

注意:如果是授权接口的话,商户是有权关闭授权的,比如你的公司接入了芝麻,你的客户公司有一天关闭了芝麻的授权,那么你就获取不到了,就算有OPENID!如果商户关闭了授权,就算你拿到了OPENID,也会获取不成功,可以这么做:把OPENID存入数据库,如果第一次调用,就用下面第二种方式,如果第二次调用,就用第一种方式,因为它会返回是否授权成功,这样就不用每次对用身份证和姓名去查了,因为OPENID一旦生成,就是唯一且不变的。