This guide will assist you in integrating DocuSeal document e-signing capabilities into your Java application. With DocuSeal, you can create document templates from your PDF files, send them to the signers, and receive signed copies. Templates can be created either using our web UI or through the API. For instance, you can design a document template with various field types using HTML and CSS or PDF upload. More information on this can be found in our guides.
Before you begin making requests to our API, you need to obtain an authorization token so that we can identify you and your API requests.
To do this, you should register on our website if you haven't already and obtain an authorization token via Developer Console. The authorization token will look something like this:
ET6sBznGN42bTMEaNMkzAa
DocuSeal allows you to sign a document by one or multiple signatories. Each signing request is referred to as a "submission", and each signatory is called a "submitter". Let's take a look at an example of sending a signing request to one signatory.
You can send signing requests using an HTTP POST request to the address:
https://api.docuseal.com/submissions
In the request body, you should specify the following:
Each submitter should contain:
Here's an example of how to create a submission using the Unirest library and core Java libraries:
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
import com.google.gson.Gson;
import java.util.HashMap;
import java.util.Map;
Map<String, Object> bodyMap = new HashMap<>();
bodyMap.put("template_id", 1000001);
bodyMap.put("send_email", true);
Map<String, String> submitter = new HashMap<>();
submitter.put("role", "First Party");
submitter.put("email", "john.doe@example.com");
bodyMap.put("submitters", new Map[]{submitter});
String jsonBody = new Gson().toJson(bodyMap);
HttpResponse<String> response = Unirest.post("https://api.docuseal.com/submissions")
.header("X-Auth-Token", "API_KEY") // Replace with your API key
.header("content-type", "application/json")
.body(jsonBody)
.asString();
System.out.println(response.getBody());
DocuSeal API has many other parameters that you can use for sending signing requests. In this guide, we will only cover the most basic example so you can understand how it works. For more detailed information, you can refer to our documentation.
In the previous example, we used the API to send a signing request, but sometimes you may not have the opportunity to use the API or the DocuSeal web UI. Also, you may not always know the email of the signer, but you do know that they have visited your website. In such cases, you can use an embedded Signing form. This allows you to embed a Signing form on your website so that the signer can sign the document directly on your website. To embed the Signing form, you need to create a document template in our web UI or using our API and use the unique template ID.
Let's integrate a signing form into our web page using React for this example (DocuSeal also provides libraries for Vue.js and plain JavaScript). To do this, install the @docuseal/react library. You can do this using yarn:
yarn add @docuseal/react
Or using npm:
npm install @docuseal/react
import React from "react"
import { DocusealForm } from '@docuseal/react'
export function App() {
return (
<div className="app">
<DocusealForm
src="https://docuseal.com/d/LEVGR9rhZYf86M" // Unique template URL
onComplete={(data) => console.log(data)}
/>
</div>
);
}
After adding this code to your page, you will see such a signing form on your website. However, you can customize its appearance and behavior using many parameters. You can read more about this in our documentation.
After the signer has signed the document, DocuSeal can send you the sign results using a webhook. You can use these results to process the sign in your application. For example, you can save the signed document in your application. To do this, you need to specify the address of your server, to which we will send the sign results. You can do this in the webhooks settings.
DocuSeal can send you 3 types of webhooks:
Let's consider an example when the signer has completed filling out the Signing form, and a webhook has been sent to your server. To do this, you need to create a webhook handler on your server that will process the sign results.
In this example, we use the Spring Web library to handle the webhook payload and save the signed PDFs to the local file system.
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.client.RestTemplate;
import org.springframework.core.io.Resource;
import org.springframework.core.io.ByteArrayResource;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.nio.file.Path;
import java.util.Map;
@RestController
public class WebhookController {
@PostMapping("/webhook")
public void handleWebhook(@RequestBody Map<String, Object> payload) {
String eventType = (String) payload.get("event_type");
if ("form.completed".equals(eventType)) {
var data = (Map<String, Object>) payload.get("data");
var documents = (List<Map<String, String>>) data.get("documents");
if (documents != null) {
for (var document : documents) {
String url = document.get("url");
String name = document.get("name").replaceAll("[^a-zA-Z0-9_\\-\\.]", "_") + ".pdf";
Path savePath = Paths.get("saved_files", name);
try {
RestTemplate restTemplate = new RestTemplate();
Resource resource = restTemplate.getForObject(url, ByteArrayResource.class);
if (resource != null) {
Files.createDirectories(savePath.getParent());
Files.write(savePath, resource.getByteArray());
System.out.println("Document saved to: " + savePath);
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
}
}
}
In this guide, we have only covered the most basic example of using DocuSeal in a Java application. DocuSeal has many other capabilities that you can use to enhance your application. For example, you can embed not only the Signing form on your website but also the Form builder. You can also use the API to fully automate the process of generating custom documents using HTML and then sending them for signer without using the DocuSeal web UI. Additionally, you can host DocuSeal on your own server to gain the full ownership and control over your data.