Skip to content

README.md

Latest commit

 

History

History
199 lines (157 loc) · 12.5 KB

README.md

File metadata and controls

199 lines (157 loc) · 12.5 KB
Raw

DocSpring Java SDK

The official Java client for the DocSpring API. DocSpring fills PDF templates with your data, generates PDFs from HTML templates, combines PDFs and collects e-signatures.

Documentation · API reference · Maven Central · Changelog

The code in this repository is generated from DocSpring's OpenAPI spec (About this SDK). Issues and pull requests are welcome.

Version 4.0.0. Requires Java 8 or later.

Install and configure

Maven: add to your pom.xml dependencies:

<dependency>
  <groupId>com.docspring</groupId>
  <artifactId>DocSpring</artifactId>
  <version>4.0.0</version>
</dependency>

Gradle: add to your build.gradle:

implementation 'com.docspring:DocSpring:4.0.0'

Configure authentication via environment variables:

export DOCSPRING_TOKEN_ID="API_TOKEN_ID"
export DOCSPRING_TOKEN_SECRET="API_TOKEN_SECRET"

You can also configure the region or host. The host takes priority over the region:

export DOCSPRING_REGION="US" # US or EU (defaults to US)
export DOCSPRING_HOST="docspring.yourcompany.com" # For on-premise deployments

Initialize the client with no arguments:

com.docspring.Client api = new com.docspring.Client();

Or provide credentials directly:

com.docspring.Client api = new com.docspring.Client("API_TOKEN_ID", "API_TOKEN_SECRET");

Pass a host or region too. A null host or region falls back to its environment variable, and a host (including DOCSPRING_HOST) is used before a region:

com.docspring.Client api = new com.docspring.Client("API_TOKEN_ID", "API_TOKEN_SECRET", null, "EU");

Generate a PDF

Fill a template with data (use your template's ID in place of tpl_1234567890abcdef01):

String templateId = "tpl_1234567890abcdef01";
com.docspring.CreateSubmissionRequest body =
    new com.docspring.CreateSubmissionRequest()
        .data(
            new java.util.HashMap<String, Object>() {
              {
                put("first_name", "John");
                put("last_name", "Smith");
                put("phone_number", "+11234567890");
              }
            })
        .metadata(
            new java.util.HashMap<String, Object>() {
              {
                put("user_id", 42);
              }
            })
        .test(true);

try {
  com.docspring.Submission result = api.createSubmission(templateId, body, null, null);
  System.out.println(result);
} catch (com.docspring.ApiException ex) {
  System.out.println(ex);
} catch (Exception ex) {
  System.out.println(ex);
}

By default the call waits for the PDF, for up to 95 seconds, and the submission in the response has a link to download it (files.pdf.download_url). Set wait to false to get a pending submission straight away. Sync vs. async processing covers the time limit, status checks and webhooks.

Methods

docs/Client.md has each method's parameters and return type, and docs/ has the models. The API reference has Java code for every method.

Method Description
copyTemplate Copy a template
createCombinedPdf Combine PDFs
createCustomFileFromUpload Create a custom file from an upload
createFolder Create a folder
createSignatureRequestEvent Record a signature request event
createSignatureRequestToken Create a signature request token
createSubmission Generate a PDF
createSubmissionBatch Generate PDFs in a batch
createTemplate Create a template
createWebhook Create a webhook
deleteCustomFile Delete a custom file
deleteFolder Delete a folder
deleteTemplate Delete a template
deleteWebhook Delete a webhook
expireCombinedPdf Expire a combined PDF
expireSubmission Expire a submission
generateSubmissionPreview Generate a preview PDF
getCombinedPdf Get a combined PDF
getCustomFile Get a custom file
getFolder Get a folder
getPresignUrl Get a presigned URL to upload a file
getSignatureRequest Get a signature request
getSubmission Get a submission
getSubmissionBatch Get a batch
getTemplate Get a template
getTemplateModelCode Generate typed code for a template's submission data
getTemplateSchema Get the JSON Schema of a template's submission data
getWebhook Get a webhook
listCombinedPdfs List combined PDFs
listCustomFiles List custom files
listFolders List folders
listSubmissions List submissions
listTemplates List templates
listTemplateSubmissions List a template's submissions
listWebhooks List webhooks
moveFolder Move a folder
moveTemplate Move a template to a folder
publishTemplateVersion Publish a template version
renameFolder Rename a folder
restoreTemplateVersion Restore a template version
testAuthentication Test authentication
updateSignatureRequest Update a signature request
updateTemplate Update a template
updateTemplateDocument Replace a template's PDF
updateWebhook Update a webhook
uploadTemplate Create a PDF template from an uploaded PDF
uploadTemplateDocument Replace a template's PDF with an uploaded PDF

Errors

Methods throw com.docspring.ApiException for an error response, with the HTTP status in getCode() and the body in getResponseBody().

The client checks each request against the API's request schemas before sending it. A request the API would reject throws a com.docspring.ValidationException (an IllegalArgumentException), whose getDetails() are ErrorDetails with a code, a message and a pointer into the body (or a parameter). Turn the check off with apiClient.setValidateRequests(false). The details are the ones the API's 422 response would have, so you get them without a round trip.

API changes

DocSpring adds fields and enum values to API v2 without releasing a new API version. Changes that would break existing code, such as removing or renaming a field, go in a new API version (API changes). So this SDK keeps working with responses that are newer than it is:

  • The model keeps a response field added to the API after this release in its additional properties (getAdditionalProperties()). The objects defined inside a model, such as a template's document, leave it out.
  • Enum values in responses are strings, so a value added to the API after this release comes back as it is: handle values you don't recognize.

Upgrade the SDK to read new fields and enum values. The changelog lists what each release adds.

About this SDK

This SDK is generated from DocSpring's OpenAPI spec with DocSpring's fork of OpenAPI Generator 7.26.0. The fork changes the Java generator:

  • Enum types are final classes rather than Java enums, so an enum value added to the API after this release comes back as the API sent it (getValue()), with isKnown() false. The constants are the values this release knows, and values() lists them.

On top of the generated code, we add:

  • A client constructor that reads your credentials, region and host from the environment.

Each release regenerates every file, so a change made only here would be lost in the next one. Issues and pull requests are welcome all the same: open an issue or a pull request, or email support@docspring.com, and we'll make the fix in the generator so that every release keeps it. AGENTS.md is a guide for AI coding agents that integrate this SDK.

License

MIT. See LICENSE.