☕Java SDK

Official Java client library for the Docs-Dispatcher API. Generate documents (DOCX, XLSX, PPTX, PDF, HTML, images) from templates, send emails, SMS, postal mail, or compose multiple services together.

API Version: 3.7.2
SDK Version: 0.0.1
Source: GitLab Repository

Requirements

Java: 1.8 or later
Build Tools: Maven 3.8.3+ or Gradle 7.2+

Installation

Maven

Add this dependency to your project's pom.xml:

<dependency>
  <groupId>io.docs-dispatcher</groupId>
  <artifactId>docsdispatcher-java-client</artifactId>
  <version>0.0.1</version>
</dependency>

Gradle

Add this dependency to your build.gradle:

repositories {
    mavenCentral()
}

dependencies {
    implementation 'io.docs-dispatcher:docsdispatcher-java-client:0.0.1'
}

Building from Source

Clone the repository and install locally:

git clone https://gitlab.com/docs-dispatcher-io/docs-dispatcher-clients/docsdispatcher-java-client.git
cd docsdispatcher-java-client
mvn clean install

Quick Start

Authentication Setup

All API calls (except health checks) require a Bearer token for authentication. Obtain your API token from the Docs-Dispatcher dashboard.

import io.docs_dispatcher.client.ApiClient;
import io.docs_dispatcher.client.Configuration;

// Configure the default API client with authentication
ApiClient apiClient = Configuration.getDefaultApiClient();
apiClient.setBasePath("https://api.docs-dispatcher.io");
apiClient.setBearerToken("your-api-token-here");

Get Your API Token: Log in to the Docs-Dispatcher dashboard and navigate to Settings → API Tokens to generate a new token.

Check API Status

Verify the API is healthy and accessible:

import io.docs_dispatcher.client.ApiClient;
import io.docs_dispatcher.client.ApiException;
import io.docs_dispatcher.client.Configuration;
import io.docs_dispatcher.client.api.ApiStatusApi;

public class HealthCheckExample {
    public static void main(String[] args) {
        ApiClient apiClient = Configuration.getDefaultApiClient();
        apiClient.setBasePath("https://api.docs-dispatcher.io");

        ApiStatusApi statusApi = new ApiStatusApi(apiClient);
        try {
            Object result = statusApi.applicationLiveness();
            System.out.println("API is healthy: " + result);
        } catch (ApiException e) {
            System.err.println("API health check failed");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Response: " + e.getResponseBody());
        }
    }
}

Service Examples

Generate a Document

Generate a PDF, DOCX, or other document from a template:

import io.docs_dispatcher.client.ApiClient;
import io.docs_dispatcher.client.ApiException;
import io.docs_dispatcher.client.Configuration;
import io.docs_dispatcher.client.api.EndUserApiApi;
import io.docs_dispatcher.client.model.CompositeRequest;
import io.docs_dispatcher.client.model.FileContentRequest;
import io.docs_dispatcher.client.model.Service;

import java.io.File;
import java.util.HashMap;
import java.util.Map;

public class GenerateDocumentExample {
    public static void main(String[] args) {
        // Configure API client with authentication
        ApiClient apiClient = Configuration.getDefaultApiClient();
        apiClient.setBasePath("https://api.docs-dispatcher.io");
        apiClient.setBearerToken("your-api-token-here");

        EndUserApiApi endUserApi = new EndUserApiApi(apiClient);

        try {
            // Build the request with template data
            Map<String, Object> data = new HashMap<>();
            data.put("customerName", "John Doe");
            data.put("invoiceNumber", "INV-2024-001");
            data.put("amount", 150.00);

            FileContentRequest fileContent = new FileContentRequest();
            fileContent.setTemplateName("invoice-template");
            fileContent.setData(data);

            CompositeRequest request = new CompositeRequest();
            request.setFileContent(fileContent);

            // Generate the document (returns file bytes)
            File result = endUserApi.dispatchersDispatch(Service.FILE, request);
            System.out.println("Document generated: " + result.getAbsolutePath());
        } catch (ApiException e) {
            System.err.println("Document generation failed");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Response: " + e.getResponseBody());
        }
    }
}

Supported Formats:

PDF
DOCX (Microsoft Word)
XLSX (Microsoft Excel)
PPTX (Microsoft PowerPoint)
HTML
PNG/JPG/SVG images

See Template Management for template creation.

Send an Email

Send an email with generated attachments:

import io.docs_dispatcher.client.model.CompositeRequest;
import io.docs_dispatcher.client.model.EmailContentRequest;
import io.docs_dispatcher.client.model.Service;

import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

public class SendEmailExample {
    public static void main(String[] args) {
        ApiClient apiClient = Configuration.getDefaultApiClient();
        apiClient.setBasePath("https://api.docs-dispatcher.io");
        apiClient.setBearerToken("your-api-token-here");

        EndUserApiApi endUserApi = new EndUserApiApi(apiClient);

        try {
            Map<String, Object> data = new HashMap<>();
            data.put("username", "John Doe");
            data.put("activationLink", "https://example.com/activate");

            EmailContentRequest emailContent = new EmailContentRequest();
            emailContent.setFrom("[email protected]");
            emailContent.setTo(Arrays.asList("[email protected]"));
            emailContent.setSubject("Welcome to Our Service");
            emailContent.setTemplateName("welcome-email");
            emailContent.setData(data);

            CompositeRequest request = new CompositeRequest();
            request.setEmailContent(emailContent);

            Object result = endUserApi.dispatchersDispatch(Service.EMAIL, request);
            System.out.println("Email sent successfully");
        } catch (ApiException e) {
            System.err.println("Email sending failed");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Response: " + e.getResponseBody());
        }
    }
}

Send an SMS

Send SMS messages via configured providers:

import io.docs_dispatcher.client.model.CompositeRequest;
import io.docs_dispatcher.client.model.SmsContentRequest;
import io.docs_dispatcher.client.model.Service;

public class SendSmsExample {
    public static void main(String[] args) {
        ApiClient apiClient = Configuration.getDefaultApiClient();
        apiClient.setBasePath("https://api.docs-dispatcher.io");
        apiClient.setBearerToken("your-api-token-here");

        EndUserApiApi endUserApi = new EndUserApiApi(apiClient);

        try {
            SmsContentRequest smsContent = new SmsContentRequest();
            smsContent.setTo("+1234567890");
            smsContent.setSmsContent("Your verification code is: 123456");
            smsContent.setProvider("SMS_FACTOR");

            CompositeRequest request = new CompositeRequest();
            request.setSmsContent(smsContent);

            Object result = endUserApi.dispatchersDispatch(Service.SMS, request);
            System.out.println("SMS sent successfully");
        } catch (ApiException e) {
            System.err.println("SMS sending failed");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Response: " + e.getResponseBody());
        }
    }
}

Supported Providers:

SMS Factor
Twilio
AWS SNS
Others (see SMS Providers)

Create an Invoice

Generate invoices, quotes, or credit notes:

import io.docs_dispatcher.client.model.CompositeRequest;
import io.docs_dispatcher.client.model.InvoicingContentRequest;
import io.docs_dispatcher.client.model.InvoiceCustomer;
import io.docs_dispatcher.client.model.InvoiceItem;
import io.docs_dispatcher.client.model.Service;

import java.util.Arrays;

public class CreateInvoiceExample {
    public static void main(String[] args) {
        ApiClient apiClient = Configuration.getDefaultApiClient();
        apiClient.setBasePath("https://api.docs-dispatcher.io");
        apiClient.setBearerToken("your-api-token-here");

        EndUserApiApi endUserApi = new EndUserApiApi(apiClient);

        try {
            // Create customer
            InvoiceCustomer customer = new InvoiceCustomer();
            customer.setCustomerType("COMPANY");
            customer.setName("Acme Corporation");
            customer.setEmail("[email protected]");
            customer.setVatNumber("US123456789");

            // Create invoice items
            InvoiceItem item1 = new InvoiceItem();
            item1.setLabel("Consulting Services");
            item1.setUnitPrice(150.00);
            item1.setQuantity(10.0);
            item1.setTaxPercent(20.0);

            InvoiceItem item2 = new InvoiceItem();
            item2.setLabel("Support Plan");
            item2.setUnitPrice(500.00);
            item2.setQuantity(1.0);
            item2.setTaxPercent(20.0);

            // Create invoicing request
            InvoicingContentRequest invoicingContent = new InvoicingContentRequest();
            invoicingContent.setCustomer(customer);
            invoicingContent.setItems(Arrays.asList(item1, item2));
            invoicingContent.setDocumentType("INVOICE");
            invoicingContent.setIssueDate("2025-01-15");
            invoicingContent.setProvider("ipaidthat");
            invoicingContent.setSendByEmail(true);

            CompositeRequest request = new CompositeRequest();
            request.setInvoicingContent(invoicingContent);

            Object result = endUserApi.dispatchersDispatch(Service.INVOICING, request);
            System.out.println("Invoice created successfully");
        } catch (ApiException e) {
            System.err.println("Invoice creation failed");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Response: " + e.getResponseBody());
        }
    }
}

Invoice Providers:

ipaidthat: French invoicing platform
qonto: European business banking
stripe: Payment processing with invoicing

See Invoice Providers for configuration details.

E-Signature Workflow

Request electronic signatures:

import io.docs_dispatcher.client.model.CompositeRequest;
import io.docs_dispatcher.client.model.ESignContentRequest;
import io.docs_dispatcher.client.model.Signer;
import io.docs_dispatcher.client.model.Service;

import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

public class ESignExample {
    public static void main(String[] args) {
        ApiClient apiClient = Configuration.getDefaultApiClient();
        apiClient.setBasePath("https://api.docs-dispatcher.io");
        apiClient.setBearerToken("your-api-token-here");

        EndUserApiApi endUserApi = new EndUserApiApi(apiClient);

        try {
            // Create signer
            Signer signer = new Signer();
            signer.setFirstname("John");
            signer.setLastname("Doe");
            signer.setEmail("[email protected]");
            signer.setPhoneNumber("+1234567890");

            // Create e-sign request
            Map<String, Object> data = new HashMap<>();
            data.put("agreementDate", "2025-01-15");

            ESignContentRequest esignContent = new ESignContentRequest();
            esignContent.setDocumentName("Service Agreement");
            esignContent.setSignatureType("ADVANCED"); // SIMPLE, ADVANCED, or QUALIFIED
            esignContent.setSigners(Arrays.asList(signer));
            esignContent.setTemplateName("agreement-template");
            esignContent.setData(data);

            CompositeRequest request = new CompositeRequest();
            request.setEsignContent(esignContent);

            Object result = endUserApi.dispatchersDispatch(Service.ESIGN, request);
            System.out.println("E-signature request sent");
        } catch (ApiException e) {
            System.err.println("E-signature request failed");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Response: " + e.getResponseBody());
        }
    }
}

Signature Types:

SIMPLE: Basic electronic signature
ADVANCED: Identity-verified signature
QUALIFIED: Legally binding qualified signature (eIDAS compliant)

See E-Signature Providers for provider configuration.

Advanced Features

List Available Configurations

Get all available configurations for your account:

import io.docs_dispatcher.client.ApiClient;
import io.docs_dispatcher.client.ApiException;
import io.docs_dispatcher.client.Configuration;
import io.docs_dispatcher.client.api.ConfigurationsHelpersApi;
import io.docs_dispatcher.client.model.ConfigurationElement;

import java.util.List;

public class ListConfigurationsExample {
    public static void main(String[] args) {
        ApiClient apiClient = Configuration.getDefaultApiClient();
        apiClient.setBasePath("https://api.docs-dispatcher.io");
        apiClient.setBearerToken("your-api-token-here");

        ConfigurationsHelpersApi configApi = new ConfigurationsHelpersApi(apiClient);

        try {
            List<ConfigurationElement> configurations = configApi.configurationsList();
            for (ConfigurationElement config : configurations) {
                System.out.println("Configuration: " + config);
            }
        } catch (ApiException e) {
            System.err.println("Failed to list configurations");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Response: " + e.getResponseBody());
        }
    }
}

Validate a Request

Validate a request before dispatching to catch errors early:

import io.docs_dispatcher.client.ApiClient;
import io.docs_dispatcher.client.ApiException;
import io.docs_dispatcher.client.Configuration;
import io.docs_dispatcher.client.api.EndUserApiApi;
import io.docs_dispatcher.client.model.CompositeRequest;
import io.docs_dispatcher.client.model.Service;

public class ValidateRequestExample {
    public static void main(String[] args) {
        ApiClient apiClient = Configuration.getDefaultApiClient();
        apiClient.setBasePath("https://api.docs-dispatcher.io");
        apiClient.setBearerToken("your-api-token-here");

        EndUserApiApi endUserApi = new EndUserApiApi(apiClient);

        try {
            CompositeRequest request = new CompositeRequest();
            // ... configure your request ...

            Object validationResult = endUserApi.dispatchersValidateRequest(Service.FILE, request);
            System.out.println("Request is valid: " + validationResult);
        } catch (ApiException e) {
            System.err.println("Validation failed");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Response: " + e.getResponseBody());
        }
    }
}

Service Composition

Compose multiple services in a single API call:

import io.docs_dispatcher.client.api.EndUserApiApi;
import io.docs_dispatcher.client.model.CompositeRequest;
import io.docs_dispatcher.client.model.Service;

public class ServiceCompositionExample {
    public static void main(String[] args) {
        ApiClient apiClient = Configuration.getDefaultApiClient();
        apiClient.setBasePath("https://api.docs-dispatcher.io");
        apiClient.setBearerToken("your-api-token-here");

        EndUserApiApi endUserApi = new EndUserApiApi(apiClient);

        try {
            // Configure request with file and email content
            CompositeRequest request = new CompositeRequest();
            // ... set fileContent and emailContent ...

            // Generate document AND send via email in one call
            Object result = endUserApi.dispatchersDispatchWithOneComposable(
                Service.FILE,
                Service.EMAIL,
                request
            );

            System.out.println("Document generated and emailed successfully");
        } catch (ApiException e) {
            System.err.println("Service composition failed");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Response: " + e.getResponseBody());
        }
    }
}

Composition Patterns:

Generate + Email: dispatchersDispatchWithOneComposable(FILE, EMAIL, request)
Generate + Email + Upload: dispatchersDispatchWithTwoComposable(FILE, EMAIL, UPLOAD, request)

API Reference

Available Services

The Service enum defines the available dispatcher services:

Service

Description

FILE

Generate documents from templates

EMAIL

Send emails with generated attachments

SMS

Send SMS messages

POSTAL

Send postal mail

UPLOAD

Upload files to storage

ESIGN

Electronic signature requests

INVOICING

Generate invoices

API Classes

Class

Description

ApiStatusApi

Health check endpoints

EndUserApiApi

Main API for document generation and service dispatch

ConfigurationsHelpersApi

Configuration management and validation

RequestValidationApi

Request validation utilities

ExternalServicesWebhooksApi

Webhook handling for external services

Endpoints

All URIs are relative to https://api.docs-dispatcher.io

Class

Method

HTTP Request

Description

ApiStatusApi

applicationLiveness

GET /healthz

Get API liveness status

ConfigurationsHelpersApi

configurationsList

GET /api/configurations

List all supported configurations

ConfigurationsHelpersApi

configurationsGetConfiguration

GET /api/configurations/{configTypeName}/config

Get configuration for a config type

ConfigurationsHelpersApi

configurationsListProviders

GET /api/configurations/{configTypeName}/providers

List providers for a config type

ConfigurationsHelpersApi

configurationsValidateConfiguration

POST /api/configurations/{configTypeName}/validate

Validate a configuration

EndUserApiApi

dispatchersDispatch

POST /api/{dispatcherService}

Dispatch a service request

EndUserApiApi

dispatchersDispatchWithOneComposable

POST /api/{dispatcherService}/{composableService1}

Compose two services

EndUserApiApi

dispatchersDispatchWithTwoComposable

POST /api/{dispatcherService}/{composableService1}/{composableService2}

Compose three services

EndUserApiApi

dispatchersValidateRequest

POST /api/{dispatcherService}/validate

Validate a service request

Error Handling

The SDK throws ApiException for all API errors. The exception provides:

getCode() - HTTP status code
getResponseBody() - Error response body
getResponseHeaders() - Response headers

Common Error Codes

Code

Description

400

Bad request - invalid data or missing parameters

401

Unauthorized - invalid or missing API token

403

Forbidden - insufficient permissions

404

Not found - template or configuration not found

415

Unsupported media type

417

Missing required parameters

500

Internal server error

501

Service not implemented

Error Handling Example

try {
    Object result = endUserApi.dispatchersDispatch(Service.FILE, request);
} catch (ApiException e) {
    switch (e.getCode()) {
        case 400:
            System.err.println("Validation error: " + e.getResponseBody());
            break;
        case 401:
            System.err.println("Authentication failed: Invalid token");
            break;
        case 403:
            System.err.println("Access denied: Insufficient permissions");
            break;
        case 404:
            System.err.println("Template not found");
            break;
        default:
            System.err.println("Unexpected error: " + e.getMessage());
            System.err.println("Response: " + e.getResponseBody());
    }
}

See Troubleshooting for common errors and solutions.

Thread Safety

Thread Safety: It is recommended to create a separate ApiClient instance per thread in multithreaded environments to avoid potential issues with shared state.

// Thread-safe pattern
public class DocumentService {
    private final String apiToken;
    private final String basePath;

    public DocumentService(String apiToken) {
        this.apiToken = apiToken;
        this.basePath = "https://api.docs-dispatcher.io";
    }

    public File generateDocument(Map<String, Object> data) throws ApiException {
        // Create new instance per request
        ApiClient apiClient = new ApiClient();
        apiClient.setBasePath(basePath);
        apiClient.setBearerToken(apiToken);

        EndUserApiApi endUserApi = new EndUserApiApi(apiClient);
        // ... proceed with request
    }
}

Dependencies

This SDK uses the following libraries:

OkHttp 4.12.0: HTTP client
Gson 2.10.1: JSON serialization
Gson Fire 1.9.0: Gson extensions

All dependencies are automatically managed by Maven or Gradle.

Configuration

Custom Base Path

Override the default API endpoint:

ApiClient apiClient = Configuration.getDefaultApiClient();
apiClient.setBasePath("https://custom-api.example.com");

Custom HTTP Client

Configure the underlying OkHttp client:

import okhttp3.OkHttpClient;
import java.util.concurrent.TimeUnit;

OkHttpClient httpClient = new OkHttpClient.Builder()
    .connectTimeout(30, TimeUnit.SECONDS)
    .readTimeout(60, TimeUnit.SECONDS)
    .writeTimeout(60, TimeUnit.SECONDS)
    .build();

ApiClient apiClient = new ApiClient(httpClient);
apiClient.setBasePath("https://api.docs-dispatcher.io");
apiClient.setBearerToken("your-api-token-here");

Logging and Debugging

Enable debug logging:

ApiClient apiClient = Configuration.getDefaultApiClient();
apiClient.setDebugging(true);

Framework Integration

Spring Boot

// src/main/java/com/example/config/DocsDispatcherConfig.java
@Configuration
public class DocsDispatcherConfig {

    @Value("${docsdispatcher.api.token}")
    private String apiToken;

    @Bean
    public ApiClient docsDispatcherApiClient() {
        ApiClient apiClient = Configuration.getDefaultApiClient();
        apiClient.setBasePath("https://api.docs-dispatcher.io");
        apiClient.setBearerToken(apiToken);
        return apiClient;
    }

    @Bean
    public EndUserApiApi endUserApiApi(ApiClient apiClient) {
        return new EndUserApiApi(apiClient);
    }
}

// src/main/resources/application.properties
docsdispatcher.api.token=${DOCSDISPATCHER_TOKEN}

Jakarta EE

// src/main/java/com/example/service/DocumentService.java
@ApplicationScoped
public class DocumentService {

    @Inject
    @ConfigProperty(name = "docsdispatcher.api.token")
    private String apiToken;

    private EndUserApiApi endUserApi;

    @PostConstruct
    public void init() {
        ApiClient apiClient = Configuration.getDefaultApiClient();
        apiClient.setBasePath("https://api.docs-dispatcher.io");
        apiClient.setBearerToken(apiToken);
        this.endUserApi = new EndUserApiApi(apiClient);
    }

    public File generateDocument(Map<String, Object> data) throws ApiException {
        // Use endUserApi...
    }
}

Documentation

API Documentation: https://docs-dispatcher.io/docs
API Specification: https://api.docs-dispatcher.io/docs/swagger.json
Swagger UI: https://api.docs-dispatcher.io/docs/swagger

Repository

GitLab: https://gitlab.com/docs-dispatcher-io/docs-dispatcher-clients/docsdispatcher-java-client
Issues: GitLab Issues

Next Steps

Learn from Examples

Recipes & Use Cases

Configure Providers

Service Providers

Troubleshoot Issues

SDK Troubleshooting

Manage Templates

Template Management

Support

Email: [email protected]
Issues: GitLab Issues
Documentation: https://docs-dispatcher.io/docs

License

This project is licensed under the Unlicense - see the LICENSE file for details.

PreviousPHP SDK NextSDK Troubleshooting

Last updated 5 days ago

hashtagRequirements

hashtagInstallation

hashtagMaven

hashtagGradle

hashtagBuilding from Source

hashtagQuick Start

hashtagAuthentication Setup

hashtagCheck API Status

hashtagService Examples

hashtagGenerate a Document

hashtagSend an Email

hashtagSend an SMS

hashtagCreate an Invoice

hashtagE-Signature Workflow

hashtagAdvanced Features

hashtagList Available Configurations

hashtagValidate a Request

hashtagService Composition

hashtagAPI Reference

hashtagAvailable Services

hashtagAPI Classes

hashtagEndpoints

hashtagError Handling

hashtagCommon Error Codes

hashtagError Handling Example

hashtagThread Safety

hashtagDependencies

hashtagConfiguration

hashtagCustom Base Path

hashtagCustom HTTP Client

hashtagLogging and Debugging

hashtagFramework Integration

hashtagSpring Boot

hashtagJakarta EE

hashtagDocumentation

hashtagRepository

hashtagNext Steps

hashtagSupport

hashtagLicense

Requirements

Installation

Maven

Gradle

Building from Source

Quick Start

Authentication Setup

Check API Status

Service Examples

Generate a Document

Send an Email

Send an SMS

Create an Invoice

E-Signature Workflow

Advanced Features

List Available Configurations

Validate a Request

Service Composition

API Reference

Available Services

API Classes

Endpoints

Error Handling

Common Error Codes

Error Handling Example

Thread Safety

Dependencies

Configuration

Custom Base Path

Custom HTTP Client

Logging and Debugging

Framework Integration

Spring Boot

Jakarta EE

Documentation

Repository

Next Steps

Support

License