接入ZOLOZ网关

2023-09-08 01:09

ZOLOZ API独立于编程语言并由网关服务对外开放。在接入ZOLOZ API之前，您需要确保可以与ZOLOZ网关服务进行通信。本文介绍使用Java库接入ZOLOZ API的方法。

前提条件

网关服务基于网关协议而实现，请确保您已了解ZOLOZ网关协议。
您已获取与网关服务通信时使用的API凭证，请参见获取API凭证。

接入方法

要实现与网关服务通信，一是可以集成已有的网关协议库，二是自行实现网关协议。

ZOLOZ为您提供以下库：

Java库：当您的编程语言是Java时使用此库，请参见添加Java库。

Authentication test API说明

本文使用Authentication test API进行演示。Authentication test API是一个特殊的API，与任何特定的ZOLOZ产品无关，用于身份验证测试。Authentication test API支持所有有效的JSON对象，并返回相同的JSON对象，类似echo命令。

和其他API 一样，Authentication test API也建立在网关服务之上，当您成功地调用Authentication test API后，集成其他API将非常简单。

操作步骤

下面介绍使用Java库接入ZOLOZ API的配置步骤。

添加Java库

ZOLOZ Java库发布在Maven中央存储库中。以下介绍如何使用公共Java库与网关服务交互并调用ZOLOZ API。

引入API SDK。
在项目的POM文件中添加以下依赖项，将库引入项目中。如需获取最新版本的依赖项，请单击这里。

copy
<dependency>
   <groupId>com.zoloz.api.sdk</groupId>
   <artifactId>zoloz-api-sdk</artifactId>
   <version>1.0.2</version>
</dependency>

导入OpenApiClient类。

copy
import com.zoloz.api.sdk.client.OpenApiClient;

实例化并配置OpenApiClient类。

copy
//Set proper values to following vairables
String clientId = "<Client ID>";
String zolozPublicKey = "<ZOLOZ's public key content encoded in base64>";
String merchantPrivateKey = "<The merchant's private key content encoded in base64>";

//Instantiate an OpenApiClient object with signature validation and encryption both enabled by default
OpenApiClient client = new OpenApiClient(); 
client.setHostUrl("<ZOLOZ gateway URL>");
client.setClientId(clientId);
client.setMerchantPrivateKey(merchantPrivateKey);
client.setOpenApiPublicKey(zolozPublicKey);
//NOTE: uncomment the following line if you want to skip signature validation for response
//client.setSigned(false);      
//NOTE: uncomment the following line if you want to disable encryption
//client.setEncrypted(false);  

您需要将代码中的以下字段替换成您的真实信息。如需获取clientId、zolozPublicKey、merchantPrivateKey，请参见获取API凭证。

clientId：客户ID。
zolozPublicKey：ZOLOZ交易公钥，采用Base64编码格式。
merchantPrivateKey：商户交易私钥，采用Base64编码格式。
setHostUrl：ZOLOZ网关URL，如需获取ZOLOZ网关URL，请参见选择站点和环境。

调用ZOLOZ API。

copy
//Set the name of authentication test API 
String apiName = "v1.aml.analyze";

//Set the request, a simple JSON object
String request = "{\"bizCode\":\"TEST\",\"extendData\":{\"certName\":\"test\",\"gender\":\"male\",\"nationality\":\"u\"},\"tenantID\":\"TEST\",\"tntInstID\":\"GLOBAL\"}";

//Call the API, the response is expected to be a JSON string of the same JSON object
String response = client.callOpenApi(apiName, request);

接收来自API的响应。

copy
{
    /**details for the hit**/
    "hitResults":[
      {
        "reason":"{
            "date":"2021/04/01",
            /**screening engine type**/
            "engineType":"WISE_NEXT_SANCTION",
            /** if is Financially Exposed Person */
            "fep":-1,
            /**ID for hit watchlist**/
            "hitId":"FAWC51068",
            /**命中类型，可以不使用该字段，使用下面的tag字段**/
            "hitType":1,
            /**screening matching score**/
            "matchRate":100,
            /**watchlist provider**/
            "origin":"DOWJONES",
            /**引擎扫描分组**/
            "originCategory":"US",
            /**传入参数**/
            "paramMatch":"carrie lam",
            /** 是否是政治敏感人物 */
            "pep":1,
            
            /**匹配名单详情**/
            "record":{
                /**地址信息**/
                "addressList":[
                    {
                        "addressCity":"",
                        "addressCountry":"hk",
                        "addressLine":"The Peak",
                        "addressState":""
                    }
                ],
                /**出生地**/
                "birthPlace":[
                    {
                        "name":"Hong Kong"
                    }
                ],
                /**名单类别**/
                "category":"POLITICAL INDIVIDUAL",
                /**国籍信息**/
                "countryDetails":[
                    {
                        "countryType":"Resident of",
                        "countryValueList":[
                            {
                                "code":"hk"
                            }
                        ]
                    },
                    {
                        "countryType":"Citizenship",
                        "countryValueList":[
                            {
                                "code":"hk"
                            }
                        ]
                    }
                ],
                "date":"2021/04/01",
                /**出生日期**/
                "dateDetails":[
                    {
                        "dateType":"Date of Birth",
                        "dateValueList":[
                            {
                                "day":"13",
                                "month":"May",
                                "year":"1957"
                            }
                        ]
                    }
                ],
                /**是否已过时**/
                "deceased":"No",
                "gender":"Female",
                /**名单分组**/
                "groups":[
                    "TEST"
                ],
                /**名单ID**/
                "id":"WC51068",
                /**名单证件信息**/
                "idNumberTypes":[
                    {
                        "idType":"Passport No.",
                        "idValueList":[
                            {
                                "idNotes":"HONG KONG",
                                "value":"test"
                            }
                        ]
                    }
                ],
                "keywords":[
                    "OFAC-HK-EO13936",
                    "OFAC"
                ],
                /**别名**/
                "nameDetails":[
                    {
                        "nameType":"Primary Name",
                        "nameValueList":[
                            {
                                "firstName":"test",
                                "surname":"test",
                                "titleHonorific":""
                            }
                        ]
                    },
                    {
                        "nameType":"Also Known As",
                        "nameValueList":[
                            {
                                "firstName":"Yuet Ngor",
                                "surname":"CHENG"
                            }
                        ]
                    },
                    {
                        "nameType":"Native Character Name",
                        "nameValueList":[
                            {
                                "language":"zh-CN",
                                "originalScriptNameList":[
                                    "\xE6\x9E\x97\xE9\x83\x91\xE6\x9C\x88\xE5\xA8\xA5"
                                ]
                            }
                        ]
                    }
                ],
                "origin":"WORLDCHECK",
                "originId":"51068",
                /**职位**/
                "position":"Chief Executive of the Hong Kong Special Administrative Region",
                /**子类别**/
                "subCategory":"PEP N",
                "type":"Person"
            },
            "recordBirthDays":[
                "19570513"
            ],
            "recordBirthPlace":"Hong Kong",
            /**名单证件号**/
            "recordIdentifyNo":"TEST",
            /**匹配记录**/
            "recordMatch":"LAM",
            "recordNations":[
                "hk"
            ],
            "recordResCountries":[
                "hk"
            ],
            /**引擎tag信息**/
            "tag":"GROUP1.PERSON_NAME",
            /**名单类型 Individual：个人,Company：公司，Vessel:, Other：其他 **/
            "type":"Individual"
            }",
            /**引擎扫描参数**/
          "scanArgs":"[{\"groupName\":\"GROUP1\",\"requestArgMap\":{\"PERSON_NAME\":\"Li Yi\"},\"watchlistGroups\":[\"ALL_SANCTION_WATCHLIST\"]}]",
          "scanTarget":"NOT_USED",
          /**引擎扫描结论**/
          "scanResult":"review"
      }
    ],
    "requestID":"2112121234141151",
    "amlDecision":"ACCEPT",
    "amlResultCode":"AML_CLEAN"
}