Java SDK

Official Java SDK for thelawin.dev.

Requires Java 17+

Installation

Beta-Phase

Während der Beta sind die SDKs über GitHub/JitPack verfügbar. Maven Central-Veröffentlichung folgt mit dem stabilen Release.

Via JitPack

<!-- pom.xml -->
<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependency>
    <groupId>com.github.steviee.thelawin-clients</groupId>
    <artifactId>java</artifactId>
    <version>main-SNAPSHOT</version>
</dependency>

Lokaler Build

git clone https://github.com/steviee/thelawin-clients.git
cd thelawin-clients/java
mvn install

<dependency>
    <groupId>dev.thelawin</groupId>
    <artifactId>sdk</artifactId>
    <version>1.0.0</version>
</dependency>

Quick Start

import dev.thelawin.ThelawinClient;
import dev.thelawin.InvoiceResult;

var client = new ThelawinClient("env_sandbox_xxx");

var result = client.invoice()
    .number("2026-001")
    .date("2026-01-15")
    .seller(s -> s.name("Acme GmbH").vatId("DE123456789").city("Berlin").country("DE"))
    .buyer(b -> b.name("Customer AG").city("München").country("DE"))
    .addItem(i -> i.description("Consulting Services").quantity(8).unit("HUR").unitPrice(150).vatRate(19))
    .template("minimal")
    .generate();

if (result.isSuccess()) {
    result.savePdf(Path.of("./invoice.pdf"));
    System.out.println("Generated: " + result.getFilename());
} else {
    result.getErrors().forEach(e ->
        System.err.println(e.getPath() + ": " + e.getMessage()));
}

Async Support

import java.util.concurrent.CompletableFuture;

CompletableFuture<InvoiceResult> future = client.invoice()
    .number("2026-001")
    .seller(s -> s.name("Acme GmbH").vatId("DE123456789").city("Berlin").country("DE"))
    .buyer(b -> b.name("Customer AG").city("München").country("DE"))
    .addItem(i -> i.description("Consulting").quantity(8).unit("HUR").unitPrice(150).vatRate(19))
    .generateAsync();

future.thenAccept(result -> {
    if (result.isSuccess()) {
        result.savePdf(Path.of("./invoice.pdf"));
    }
});

Client Options

var client = new ThelawinClient(
    "env_sandbox_xxx",
    "https://api.thelawin.dev",  // optional
    Duration.ofSeconds(30)       // optional
);

Builder API

Invoice Details

client.invoice()
    .number("2026-001")           // Required
    .date("2026-01-15")           // Required
    .dueDate("2026-02-15")        // Optional
    .currency("EUR")              // Default: "EUR"

Parties (Lambda Style)

.seller(s -> s
    .name("Acme GmbH")           // Required
    .vatId("DE123456789")        // Required
    .street("Hauptstraße 1")
    .city("Berlin")              // Required
    .postalCode("10115")
    .country("DE"))              // Required
.buyer(b -> b
    .name("Customer AG")         // Required
    .city("München")             // Required
    .country("DE"))              // Required

Line Items

.addItem(i -> i
    .description("Consulting")   // Required
    .quantity(8)                 // Required
    .unit("HUR")                 // Required
    .unitPrice(150.0)            // Required
    .vatRate(19.0))              // Required

Customization

.template("minimal")            // "minimal", "classic", "compact"
.locale("de")                   // "en", "de", "fr", "es", "it"
.accentColor("#8b5cf6")
.footerText("Thank you!")

Logo

// From file (auto Base64)
.logoFile(Path.of("./logo.png"))
.logoFile(Path.of("./logo.png"), 30)  // with width in mm

// From Base64
.logoBase64("iVBORw0KGgo...", 30)

Result Handling

var result = builder.generate();

if (result.isSuccess()) {
    System.out.println(result.getFilename());      // "invoice-2026-001.pdf"
    System.out.println(result.getValidation());    // ValidationResult{status=valid, ...}

    // Save to file
    result.savePdf(Path.of("./invoice.pdf"));

    // Get bytes
    byte[] bytes = result.toBytes();

    // Get data URL
    String dataUrl = result.toDataUrl();
} else {
    for (var error : result.getErrors()) {
        System.err.println(error.getPath() + ": " + error.getMessage());
    }
}

Pattern Matching (Java 21+)

switch (result) {
    case InvoiceSuccess success -> {
        success.savePdf(Path.of("./invoice.pdf"));
        System.out.println("Generated: " + success.getFilename());
    }
    case InvoiceFailure failure -> {
        failure.getErrors().forEach(e ->
            System.err.println(e.getPath() + ": " + e.getMessage()));
    }
}

Error Handling

import dev.thelawin.ThelawinApiException;
import dev.thelawin.ThelawinNetworkException;
import dev.thelawin.ThelawinQuotaExceededException;

try {
    var result = client.invoice().generate();
} catch (ThelawinQuotaExceededException e) {
    System.out.println("Quota exceeded, upgrade your plan");
} catch (ThelawinNetworkException e) {
    System.out.println("Network error: " + e.getMessage());
} catch (ThelawinApiException e) {
    System.out.println("API error " + e.getStatusCode() + ": " + e.getMessage());
}

Source Code

github.com/steviee/thelawin-clients/tree/main/java