芝麻信用商家接入指南

　　很久都没动笔写博客了，原因有2，第一是自己太懒了，第二是因为确实没什么好写的，因为一直接触新技术的机会比较少，这次正好又逢2017年开始，所以写下博客，记录下自己的一些点点滴滴，以后有用的时候可以翻过来看看。

　　这一部分在这篇文档 中有详细的介绍，因为公司其实是有其他人把这一步做好的，这一步主要是业务洽谈，公司的业务部门会去申请一系列的准入凭证，一般来说不管是芝麻信用还用其他的一些API接口，大到比如QQ互联，小到公司内部对外暴露的一些小的接口，都会包含如下几个要素：

1. 应用公钥
2. 应用私钥
3. 请求公共URL
4. 请求接口方法名

　　有兴趣的可以自己去百度一下，这里就不做详细的介绍了，其实对于芝麻信用的话，上面4条也是必须的，那么芝麻对于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请求的参数。
4. 关于公钥私钥的介绍，请移步这篇文章。

　　不太理解的地方：数据反馈文档。

　　关于param加密验签，这里有相对应的文档。不过我觉得还是介绍一下比较好，其实主要是介绍了Sign的形成的方法，他们经历了如下过程，下面是官方的解释，简单点概括，就是客户端加密，然后传到服务端，然后服务端解密，给出正确的数据，然后再加密返回给客户端，客户端再进行解密后拿到正确的数据，具体的过程可以参考文档。　

1）商户端发起请求到芝麻信用时：
  商户使用芝麻信用的RSA公钥对业务参数进行RSA加密，使用商户自己的RSA私钥对业务参数进行签名；
  芝麻信用使用芝麻信用的RSA私钥进行业务参数的解密，使用商户的RSA公钥进行验签。

2）芝麻信用返回调用结果给商户时：
  芝麻信用使用商户的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可以根据自己的语言选择合适的，请看这里。

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();
    }
}

　　 页面授权接口是页面跳转类接口，如果成功的话，会返回相对应的URL，不过我有一个疑问，这个跳转的URL是哪里指定的呢，个人觉得应该是芝麻里面设置的,如下图所示。

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

身份标识类型

1:按照OPENId进行授权

2:按照身份证+姓名进行授权

 最后需要注意biz_no这个字段，每一个获取数据的接口都会有一个BIZ_NO的返回字段，官方的解释是对账用的，因为每一次请求芝麻信用，其实都是收费的，所以到后期进行结算的时候，需要这些凭证，所以大家还是小心为好，最后附上一张我自己画的流程图吧。

我会记录对于接口的一些进展：

Update 1:

已知的问题(未解决)：
如果用户关闭了对芝麻信用的商户授权，因为商户(Server)并不知道用户是否关闭了芝麻信
用的授权，是否每一次都要去调用授权查询接口(芝麻端)。使用身份证号姓名或者OPENID计
费的费用是否不同(待确认)？

对于输入的参数，有可能出现不同的接口错误码，那么对于这些不同的接口错误码，该怎样
做不同的处理，还是统一跳出逻辑？

页面跳转类接口，sign的作用是什么？
什么时候会触发不同的芝麻接口，用户主动触发？还是服务端触发？
我需要提供几个接口出来？

计费怎么算？

芝麻那边有测试环境吗，具体调用次数有限制吗。
哪些步骤需要和其他人联调

回调页面是回调到哪里，回调页面具体有什么用，如果以后有新的渠道接入进来（比如SDK,H5，PC等），该怎么弄
才能保证扩展性。

芝麻那边有对接人员吗？还是只是我们这边单独调用他们那边的接口呢？