Pure API-mode integration

2021-04-26 05:27

Overview

ZOLOZ SaaS API is language independent, which means you could integrate the API with any language. However, you need to fully understand ZOLOZ gateway protocol, properly create the request and handle the response; or else you could utilize an existing API SDK provided by ZOLOZ to integrate the API if your project is written in Java. In this chapter, we only demonstrate how to integrate with the Java API SDK.

Introduce API SDK

Introduce the library into your project by adding following dependency in the POM file of your project:

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

Consume API

Instantiate and Configure API SDK Client

copy
// initialize OpenApiClient
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>";

OpenApiClient client = new OpenApiClient();  // construct with signature and encryption by default
client.setHostUrl("https://sg-production-api.zoloz.com");
client.setClientId(clientId);
client.setMerchantPrivateKey(merchantPrivateKey);
client.setOpenApiPublicKey(zolozPublicKey);
//client.setSigned(false);     // signature (of response) validation can be turned off
//client.setEncrypted(false);  // encryption can be turned off

Consume FaceCompare Product

copy
// create api client
FaceCompareAPI faceCompareApi = new FaceCompareAPI(client);

// prepare api request
String face1ImgPath = "<file path of 1st face image>";
String face2ImgPath = "<file path of 2nd face image>";

FaceCompareRequest request = new FaceCompareRequest();
request.setBizId("biz-id-12345");  // for tracing purpose, it is recommended to use a global unique id
request.getFace1().setContent(getBase64ImageContent(face1ImgPath));
request.getFace2().setContent(getBase64ImageContent(face2ImgPath));

// call api
FaceCompareResponse response = faceCompareApi.compare(request);

if ("S".equals(response.getResult().getResultStatus())) {
    System.out.println(String.format(
            "Two faces are from %s, the similarity score is %2f",
            response.getSamePerson() ? "same person" : "different persons",
            response.getScore()
    ));
}
else {
    System.out.println(String.format(
            "[Error] %s: %s",
            response.getResult().getResultCode(),
            response.getResult().getResultMessage()
    ));
}

Consume IdRecognize Product

copy
// create api client
DocRecognitionAPI docRecognitionAPI = new DocRecognitionAPI(client);

// prepare api request
String imagePath = cmd.getOptionValue("f");

DocRecognitionRequest request=new DocRecognitionRequest();
request.setBizId("biz-id-12345");  // for tracing purpose, it is recommended to use a global unique id
request.setDocType("00000001003");
request.setFrontPageImage(getBase64ImageContent(imagePath));

// call api
DocRecognitionResponse response = docRecognitionAPI.recognition(request);
if ("S".equals(response.getResult().getResultStatus())) {
    if ("Y".equals(response.getRecognitionResult())) {
        System.out.println("ID detected.\n");

        if (response.getSpoofResult() != null && !response.getSpoofResult().isEmpty()) {
            System.out.println("Spoofing Detection:");
            response.getOcrResult().forEach((key, value) -> {
                System.out.println(String.format(" -%s: %s", key, value));
            });

        }

        System.out.println("OCR Result:");
        response.getOcrResult().forEach((key, value) -> {
            System.out.println(String.format(" -%s: %s", key, value));
        });
        System.out.println(String.format(
                "[Error] %s: %s",
                response.getResult().getResultCode(),
                response.getResult().getResultMessage()
        ));
    }
    else {
        System.out.println(String.format(
                "Cannot recognize image: %s",
                response.getRecognitionErrorCode()
        ));
    }
}
else {
    System.out.println(String.format(
            "[Error] %s: %s",
            response.getResult().getResultCode(),
            response.getResult().getResultMessage()
    ));
}

Usage Examples

Please check open-sourced examples in our Github repository:

References

Corresponding API specifications: