ZOLOZZOLOZDOCS

      Server-mode Product Integration

      #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>1.0-SNAPSHOT</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

      #Build Examples

      Prequisites

      • JDK 1.8
      • Maven >3.2.5


      The examples are also included in the API SDK project, to build the project, simply execute following command from the root directory of the API SDK project:

      copy
      mvn package


      #Launch FaceCompare Example

      Prequisite

      • JDK 1.8


      Execute following command to launch the example:

      copy
      java -jar src/examples/facecompare/target/zoloz-facecompare-example-1.0-SNAPSHOT.jar \
        -c <client_id> \
        -p <zoloz_public_key_content> \
        -k <merchant_private_key_path> \
        -a <face1_image_path> \
        -b <face1_image_path>


      #Launch IdRecognize Example

      Prequisite

      • JDK 1.8


      Execute following command to launch the example:

      copy
      java -jar src/examples/idrecognize/target/zoloz-idrecognize-example-1.0-SNAPSHOT.jar \
        -c <client_id> \
        -p <zoloz_public_key_content> \
        -k <merchant_private_key_path> \
        -f <passport_image_path>


      #References

      Corresponding API specifications: