芝麻信用商家接入指南

　本文转自 http://www.cnblogs.com/kmsfan/p/6244000.html

一般来说不管是芝麻信用还用其他的一些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个参数，具体参考文档：

序号参数名称用途示例1open_id芝麻用户在商户端的身份标识，商户维度唯一且终生保持不变；
芝麻用户在商户端完成授权后生成。2688087194177100528844720952product_code产品码，标记商户接入的具体产品；
直接使用每个接口入参中示例值即可。w10101001000000000013transaction_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的返回字段，官方的解释是对账用的，因为每一次请求芝麻信用，其实都是收费的，所以到后期进行结算的时候，需要这些凭证，所以大家还是小心为好，最后附上一张我自己画的流程图吧。

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