接入ZOLOZ网关

2025-10-17 02:55

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，与特定产品无关，用于身份验证测试。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 = "v3.aml.nss.screen";

//Set the request, a simple JSON object
String request = "{\"bizCode\":\"ONBOARDING_PERSON_DEFAULT\",\"person\":{\"personName\":\"peter\"},\"customerId\":\"test_customer\",\"subjectType\":\"PERSON\"}";

//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
{
    "decision": "REVIEW", 
    "bizCode": "ONBOARDING_PERSON_DEFAULT", 
    "hitResults": [
        {
            "scanArgs": "[{\"disableSearch\":false,\"groupName\":\"GROUP1\",\"requestArgMap\":{\"BIRTHDAY\":\"19660510\",\"CITIZENSHIP\":\"\",\"PERSON_NAME\":\"John Doe\",\"ID\":\"\",\"GENDER\":\"\"},\"watchlistGroups\":[\"DEMO_PERSON_SANCTION\"]}]", 
            "scanResult": "review", 
            "hitReason": {
                "engineType": "SANCTION", 
                "hitType": "name_match", 
                "paramMatch": "John Doe", 
                "recordMatch": "John Doe", 
                "matchRate": 100, 
                "matchStrategy": "s_person_name_common_src_full_name_similar"
            }, 
            "hitRecord": {
                "id": "example_12345", 
                "origin": "DOWJONES", 
                "type": "Person", 
                "activeStatus": "Active", 
                "nameDetails": [
                    {
                        "nameType": "Primary Name", 
                        "nameValueList": [
                            {
                                "firstName": "John", 
                                "surname": "Doe"
                            }
                        ]
                    }
                ], 
                "descriptions": [
                    {
                        "description1": "3", 
                        "description2": "1"
                    }
                ], 
                "dateDetails": [
                    {
                        "dateType": "Date of Birth", 
                        "dateValueList": [
                            {
                                "day": "10", 
                                "month": "May", 
                                "year": "1966"
                            }
                        ]
                    }
                ], 
                "sanctionsReferences": [
                    {
                        "toDay": "10", 
                        "toMonth": "Sep", 
                        "toYear": "2019", 
                        "value": "Sanctioned for financial crimes"
                    }
                ], 
                "countryDetails": [
                    {
                        "countryType": "Citizenship", 
                        "countryValueList": [
                            {
                                "code": "example_country_code"
                            }
                        ]
                    }
                ]
            }
        }
    ], 
    "totalHits": 1, 
    "rcrrRiskLevel": "", 
    "eventId": "6728d09e2113b33b6cc7e47a361c****", 
    "result": {
        "resultCode": "SUCCESS", 
        "resultMsg": "success", 
        "resultStatus": "S"
    }
}