Release v3.2

.env.example

@@ -7,3 +7,9 @@ SIGNNOW_API_HOST=https://api.signnow.com
 SIGNNOW_API_BASIC_TOKEN=c2lnbk5vdyBBUEkgc2FtcGxlIEFwcCB2MS4wCg==
 [email protected]
 SIGNNOW_API_PASSWORD=coolest_pazzw0rd
+
+# Absolute or relative (starts with .) path to the directory
+# where the downloaded files will be stored (make sure you have write permissions to this directory)
+#
+# Default: ./src/main/resources/downloads
+SIGNNOW_DOWNLOADS_DIR=./src/main/resources/downloads

README.md

@@ -1,5 +1,5 @@
 # signNow API Java SDK
-## v3.1.0
+## v3.2.0
 
 [![Java Version](https://img.shields.io/badge/codebase-java--11-yellowgreen)](https://www.java.com/)
 
@@ -166,5 +166,19 @@ public class DocumentGetExample {
 }
 ```
 
+#### Proxy endpoints usage
+
+If you need to call an API endpoint that is not yet available in the SDK, you can still access it using the proxy mechanism.
+
+This allows you to send custom requests without waiting for an official SDK update.
+
+To do this, create a class that extends `CustomProxyRequest` and annotate it with `@ApiEndpoint`, setting: `namespace = "proxy"`.
+
+The `name` and `entity` values within the annotation can be arbitrary and do not affect functionality.
+
+Example of creating a request to proxy any unimplemented endpoint that returns JSON data: [ProxyJsonTest](./src/test/java/com/signnow/api/proxy/ProxyJsonTest.java).
+
+Example of creating a request to proxy any unimplemented endpoint that returns a file: [ProxyFileTest](./src/test/java/com/signnow/api/proxy/ProxyFileTest.java).
+
 ### Examples
 You can find more examples of API usage in the [examples](./examples) directory.

examples/DownloadDocumentExample.java

@@ -0,0 +1,29 @@
+import com.signnow.api.document.request.DocumentDownloadGetRequest;
+import com.signnow.api.document.response.DocumentDownloadGetResponse;
+import com.signnow.core.ApiClient;
+import com.signnow.core.exception.SignNowApiException;
+import com.signnow.core.factory.SdkFactory;
+
+public class DownloadDocumentExample {
+    public static void main(String[] args) {
+        // Set your actual input data here
+        // Note: following values are dummy, just for example
+        //----------------------------------------------------
+        // if it is not specified here, a new Bearer token will be created automatically
+        String bearerToken = "";
+        String documentId = "05fbed799231d85cf3471121ecd6a4221f9c5610";
+
+        try {
+            ApiClient client = SdkFactory.createApiClientWithBearerToken(bearerToken);
+            DocumentDownloadGetRequest request = new DocumentDownloadGetRequest();
+            request.withDocumentId(documentId)
+                    .withType("collapsed")
+                    .withHistory("no");
+            DocumentDownloadGetResponse response = (DocumentDownloadGetResponse) client.send(request).getResponse();
+            File downloadedFile = response.getFile();
+            System.out.println(downloadedFile.getAbsolutePath());
+        } catch (SignNowApiException e) {
+            System.out.println("ERROR: " + e.getMessage());
+        }
+    }
+}

examples/DownloadDocumentGroupExample.java

@@ -0,0 +1,37 @@
+import com.signnow.api.documentgroup.request.DownloadDocumentGroupPostRequest;
+import com.signnow.api.documentgroup.request.data.DocumentOrderCollection;
+import com.signnow.api.documentgroup.response.DownloadDocumentGroupPostResponse;
+import com.signnow.core.ApiClient;
+import com.signnow.core.exception.SignNowApiException;
+import com.signnow.core.factory.SdkFactory;
+
+public class DownloadDocumentGroupExample {
+    public static void main(String[] args) {
+        // Set your actual input data here
+        // Note: following values are dummy, just for example
+        //----------------------------------------------------
+        // if it is not specified here, a new Bearer token will be created automatically
+        String bearerToken = "";
+        String documentGroupId = "e1b4c8a2f930d7e6a5b1f4c3d8a09e2b7c5d1f0a";
+        String documentId1 = "05fbed799231d85cf3471121ecd6a4221f9c5610";
+        String documentId2 = "9a3b1e4f0c2d7a8e5f6b9c1d3e0a4b7c8f2d6a9e";
+
+        try {
+            ApiClient client = SdkFactory.createApiClientWithBearerToken(bearerToken);
+            DocumentOrderCollection documentOrder = new DocumentOrderCollection();
+            // this order prescribes how downloaded documents will be located in merged file
+            // the collection is allowed to be empty
+            documentOrder.add(documentId1);
+            documentOrder.add(documentId2);
+            DownloadDocumentGroupPostRequest request = new DownloadDocumentGroupPostRequest("zip",
+                    "no",
+                    documentOrder);
+            request.withDocumentGroupId(documentGroupId);
+            DownloadDocumentGroupPostResponse response = (DownloadDocumentGroupPostResponse) client.send(request).getResponse();
+            File downloadedFile = response.getFile();
+            System.out.println(downloadedFile.getAbsolutePath());
+        } catch (SignNowApiException e) {
+            System.out.println("ERROR: " + e.getMessage());
+        }
+    }
+}

examples/EmbeddedEditorDocumentExample.java

@@ -1,15 +1,15 @@
+import java.io.File;
+
 import com.signnow.api.document.request.DocumentPostRequest;
 import com.signnow.api.document.response.DocumentPostResponse;
 import com.signnow.api.embeddededitor.request.DocumentEmbeddedEditorLinkPostRequest;
 import com.signnow.api.embeddededitor.response.DocumentEmbeddedEditorLinkPostResponse;
 import com.signnow.core.ApiClient;
 import com.signnow.core.exception.SignNowApiException;
 import com.signnow.core.factory.SdkFactory;
-import java.io.File;
 
-public class DocumentUploadExample {
+public class EmbeddedEditorDocumentExample {
   public static void main(String[] args) {
-
     // Set your actual input data here
     // Note: following values are dummy, just for example
     // ----------------------------------------------------

examples/EmbeddedEditorDocumentGroupExample.java

@@ -1,3 +1,5 @@
+import java.io.File;
+
 import com.signnow.api.document.request.DocumentPostRequest;
 import com.signnow.api.document.response.DocumentPostResponse;
 import com.signnow.api.documentgroup.request.DocumentGroupPostRequest;
@@ -8,9 +10,8 @@
 import com.signnow.core.ApiClient;
 import com.signnow.core.exception.SignNowApiException;
 import com.signnow.core.factory.SdkFactory;
-import java.io.File;
 
-public class DocumentUploadExample {
+public class EmbeddedEditorDocumentGroupExample {
   public static void main(String[] args) {
 
     // Set your actual input data here

examples/EmbeddedSendingDocumentExample.java

@@ -0,0 +1,44 @@
+import java.io.File;
+
+import com.signnow.api.document.request.DocumentPostRequest;
+import com.signnow.api.document.response.DocumentPostResponse;
+import com.signnow.api.embeddedsending.request.DocumentEmbeddedSendingLinkPostRequest;
+import com.signnow.api.embeddedsending.response.DocumentEmbeddedSendingLinkPostResponse;
+import com.signnow.core.ApiClient;
+import com.signnow.core.exception.SignNowApiException;
+import com.signnow.core.factory.SdkFactory;
+
+public class EmbeddedSendingDocumentExample {
+  public static void main(String[] args) {
+
+    /**
+     * Important:
+     * - The following variables are dummy, for example purposes only. Please provide actual data.
+     * - If you do not specify a Bearer token, it will be generated automatically.
+     */
+    String bearerToken = "";
+    String pathToDocument = "/your/path/to/document.pdf";
+
+    try {
+      ApiClient client = SdkFactory.createApiClientWithBearerToken(bearerToken);
+
+      DocumentPostRequest request = new DocumentPostRequest(new File(pathToDocument));
+      DocumentPostResponse response = (DocumentPostResponse) client.send(request).getResponse();
+
+      /** Create an embedded sending link for the uploaded document. */
+      DocumentEmbeddedSendingLinkPostRequest embeddedSendingRequest =
+          new DocumentEmbeddedSendingLinkPostRequest(
+              "document", "https://example.com", 15, "blank");
+      embeddedSendingRequest.withDocumentId(response.getId());
+
+      DocumentEmbeddedSendingLinkPostResponse embeddedSendingResponse =
+          (DocumentEmbeddedSendingLinkPostResponse)
+              client.send(embeddedSendingRequest).getResponse();
+
+      System.out.println(
+          "Link for embedded sending: " + embeddedSendingResponse.getData().getUrl());
+    } catch (SignNowApiException e) {
+      System.out.println("ERROR: " + e.getMessage());
+    }
+  }
+}

examples/EmbeddedSendingDocumentGroupExample.java

@@ -0,0 +1,64 @@
+import java.io.File;
+
+import com.signnow.api.document.request.DocumentPostRequest;
+import com.signnow.api.document.response.DocumentPostResponse;
+import com.signnow.api.documentgroup.request.DocumentGroupPostRequest;
+import com.signnow.api.documentgroup.request.data.DocumentIdCollection;
+import com.signnow.api.documentgroup.response.DocumentGroupPostResponse;
+import com.signnow.api.embeddedsending.request.DocumentGroupEmbeddedSendingLinkPostRequest;
+import com.signnow.api.embeddedsending.response.DocumentGroupEmbeddedSendingLinkPostResponse;
+import com.signnow.core.ApiClient;
+import com.signnow.core.exception.SignNowApiException;
+import com.signnow.core.factory.SdkFactory;
+
+public class EmbeddedSendingDocumentGroupExample {
+  public static void main(String[] args) {
+
+    /**
+     * Important:
+     * - The following variables are dummy, for example purposes only. Please provide actual data.
+     * - If you do not specify a Bearer token, it will be generated automatically.
+     */
+    String bearerToken = "";
+    String groupName = "Test Document Group";
+    String pathToDocument = "/your/path/to/file.pdf";
+
+    try {
+      ApiClient client = SdkFactory.createApiClientWithBearerToken(bearerToken);
+
+      /** Upload documents to create a document group, specify the paths to the files. */
+      DocumentPostRequest request = new DocumentPostRequest(new File(pathToDocument));
+      DocumentPostResponse response = (DocumentPostResponse) client.send(request).getResponse();
+      String documentId1 = response.getId();
+
+      DocumentPostRequest request2 = new DocumentPostRequest(new File(pathToDocument));
+      DocumentPostResponse response2 = (DocumentPostResponse) client.send(request2).getResponse();
+      String documentId2 = response2.getId();
+
+      /**
+       * Create a document group by specifying its name
+       * and the IDs of the documents it will consist of.
+       */
+      DocumentIdCollection documentIds = new DocumentIdCollection();
+      documentIds.add(documentId1);
+      documentIds.add(documentId2);
+      DocumentGroupPostRequest groupRequest = new DocumentGroupPostRequest(documentIds, groupName);
+      DocumentGroupPostResponse groupResponse =
+          (DocumentGroupPostResponse) client.send(groupRequest).getResponse();
+      String groupId = groupResponse.getId();
+
+      /** Create an embedded sending link for the created document group. */
+      DocumentGroupEmbeddedSendingLinkPostRequest embeddedSendingRequest =
+          new DocumentGroupEmbeddedSendingLinkPostRequest("https://example.com", 15, "blank");
+      embeddedSendingRequest.withDocumentGroupId(groupId);
+      DocumentGroupEmbeddedSendingLinkPostResponse embeddedSendingResponse =
+          (DocumentGroupEmbeddedSendingLinkPostResponse)
+              client.send(embeddedSendingRequest).getResponse();
+
+      System.out.println(
+          "Link for embedded sending: " + embeddedSendingResponse.getData().getUrl());
+    } catch (SignNowApiException e) {
+      System.out.println("ERROR: " + e.getMessage());
+    }
+  }
+}

src/main/java/com/signnow/api/document/request/DocumentDownloadGetRequest.java

@@ -17,8 +17,8 @@
 import org.jetbrains.annotations.NotNull;
 
 /**
- * This class represents a request to download a document.
- * It implements the RequestInterface with a String type parameter.
+ * This class represents a request to download a document. It implements the RequestInterface with a
+ * String type parameter.
  */
 @ApiEndpoint(
     name = "downloadDocument",
@@ -30,10 +30,31 @@
     type = "application/pdf")
 public final class DocumentDownloadGetRequest implements RequestInterface<String> {
 
+  /** A map to hold URI parameters for the request. */
+  private final HashMap<String, String> uriParams = new HashMap<>();
+
+  /** A map to hold query parameters for the request. */
+  private final HashMap<String, String> queryParams = new HashMap<>();
+
   /**
-   * A map to hold URI parameters for the request.
+   * Specifies file type to download: collapsed|zip|email
+   *
+   * @return this DocumentDownloadGetRequest instance
    */
-  private final HashMap<String, String> uriParams = new HashMap<>();
+  public DocumentDownloadGetRequest withType(String type) {
+    this.queryParams.put("type", type);
+    return this;
+  }
+
+  /**
+   * The value "yes" allows to include a table containing the document's history into a document.
+   *
+   * @return this DocumentDownloadGetRequest instance
+   */
+  public DocumentDownloadGetRequest withHistory(String withHistory) {
+    this.queryParams.put("with_history", withHistory);
+    return this;
+  }
 
   /**
    * Adds a document ID to the URI parameters.
@@ -58,6 +79,16 @@ public HashMap<String, String> uriParams() {
     return new HashMap<>(this.uriParams);
   }
 
+  /**
+   * Returns a map as the query parameters for this request.
+   *
+   * @return an empty map
+   */
+  @NotNull
+  public Map<String, String> queryParams() {
+    return new HashMap<>(this.queryParams);
+  }
+
   /**
    * Returns an empty map as the payload for this request.
    *
@@ -68,4 +99,4 @@ public HashMap<String, String> uriParams() {
   public Map<String, String> payload() {
     return new HashMap<>();
   }
-}
+}

src/main/java/com/signnow/api/document/response/DocumentDownloadGetResponse.java

@@ -10,12 +10,34 @@
 package com.signnow.api.document.response;
 
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import java.io.File;
 
 /**
  * This class represents the response received after a document download request.
- * It is annotated with JsonIgnoreProperties to ignore any unknown properties when deserializing JSON.
  */
-@JsonIgnoreProperties(ignoreUnknown = true)
 public class DocumentDownloadGetResponse {
-    // No public properties, constructors, or methods to comment on.
-}
+
+  /**
+   * The file downloaded as part of the response. This file is created from the response content and
+   * stored locally.
+   */
+  private final File file;
+
+  /**
+   * Creates a new DocumentDownloadGetResponse with the specified file.
+   *
+   * @param file The downloaded file
+   */
+  public DocumentDownloadGetResponse(File file) {
+    this.file = file;
+  }
+
+  /**
+   * Gets the downloaded file.
+   *
+   * @return The File object representing the downloaded file
+   */
+  public File getFile() {
+    return file;
+  }
+}