WhiteBooks Java SDK

Maven-Central-published SDK for Java 11+ applications. Wraps every WhiteBooks API (GST, e-Invoice, e-Way Bill, KSA ZATCA) behind a typed client. Handles OAuth 2.0 token refresh, retries, and webhook signature verification automatically.

Installation

<!-- pom.xml -->
<dependency>
  <groupId>com.whitebooks</groupId>
  <artifactId>sdk</artifactId>
  <version>3.2.0</version>
</dependency>

Or Gradle:

implementation 'com.whitebooks:sdk:3.2.0'

Quickstart

import com.whitebooks.WhiteBooks;

var wb = WhiteBooks.builder()
    .clientId(System.getenv("WB_CLIENT_ID"))
    .clientSecret(System.getenv("WB_CLIENT_SECRET"))
    .env(WhiteBooks.Env.SANDBOX)   // or PRODUCTION
    .build();

// Same builder, four APIs:
var gstr2b   = wb.gst().gstr2b().fetch("29AAAAA0000A1Z5", "04", "2026");
var irn      = wb.einvoice().generateIrn(IrnRequest.of(...));
var ewb      = wb.eway().generate(EwbRequest.of(...));
var clear    = wb.ksaEinvoice().clearance(KsaRequest.of(...));

Features

• Automatic OAuth 2.0 token refresh (1-hour validity managed transparently)
• Built-in exponential-backoff retry (1s / 2s / 4s) on NIC/IRP transients
• Webhook signature verification (WhiteBooks.Webhooks.verify(payload, signature))
• Typed request/response models for every endpoint in the OpenAPI spec
• Spring Boot starter (com.whitebooks:sdk-spring-boot-starter)
• Reactive variant (com.whitebooks:sdk-reactor) for Project Reactor users

Versioning

SDK follows the API's semver. Major version bumps signal breaking changes; we ship migration guides in /changelog. The 3.x line targets API v3 (current production).

Related

Part of the WhiteBooks developer documentation cluster. See /llms.txt for the full machine-readable site index. Last updated 27 May 2026.