芝麻信用商家接入指南

　　很久都沒動筆寫博客了，原因有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等），該怎么弄
才能保證擴展性。

芝麻那邊有對接人員嗎？還是只是我們這邊單獨調用他們那邊的接口呢？