Java

com.useyona:einvoice-java is the official SDK for Java 17 and later. Jackson is its only runtime dependency. Responses are records with the API’s field names, and request records have builders.

Install

Gradle:

implementation("com.useyona:einvoice-java:0.1.0")

Maven:

<dependency>
  <groupId>com.useyona</groupId>
  <artifactId>einvoice-java</artifactId>
  <version>0.1.0</version>
</dependency>

The current version is on Maven Central .

Quick start

import com.useyona.einvoice.EInvoice;
import com.useyona.einvoice.types.*;
import java.util.List;
 
try (EInvoice client = new EInvoice(System.getenv("YONA_API_KEY"))) {
 
    // 1. A buyer
    BuyerViewDto buyer = client.buyers.create(CreateBuyerDto.builder()
            .name("Acme Nigeria Ltd")
            .taxId("12345678-0001")
            .email("accounts@acme.ng")
            .partyType(CreateBuyerDto.PartyType.COMPANY)
            .address(BuyerAddressDto.builder()
                    .line1("1 Marina").city("Lagos").country("NG").build())
            .build());
 
    // 2. A saved item
    ItemViewDto item = client.items.create(CreateItemDto.builder()
            .name("Laptop")
            .itemType(CreateItemDto.ItemType.GOODS)
            .hsnCode("8471.30")
            .productCategory("Machinery")
            .unitCode("EA")
            .unitPriceMinor("45000000")
            .currency("NGN")
            .taxCategory("STANDARD_VAT")
            .build());
 
    // 3. A draft invoice
    InvoiceViewDto invoice = client.invoices.create(CreateInvoiceDto.builder()
            .invoiceKind("B2B")
            .invoiceDate("2026-10-05")
            .currency("NGN")
            .buyerId(buyer.id())
            .lineItems(List.of(InvoiceLineItemDto.builder()
                    .itemId(item.id()).quantity(Amount.of(2)).build()))
            .build());
 
    // 4. Finalise it and report it to the tax authority
    client.invoices.finalise(invoice.id());
    client.submissions.submit(invoice.id());
    SubmissionStatusDto status = client.submissions.getStatus(invoice.id());
}

Submitting is asynchronous: poll submissions.getStatus or listen for the invoice.accepted webhook. The states are explained in Invoice lifecycle.

The client is AutoCloseable; close() releases the HTTP client the SDK created.

Sandbox and live

An sk_test_ key works in the sandbox and an sk_live_ key in live, on the same host; client.mode() tells you which. To make a deployment refuse a key of the wrong kind:

EInvoice client = EInvoice.builder(key).assertMode(Mode.LIVE).build();

Responses and pagination

Methods return the API’s answer as a record (invoice.invoiceNumber()). List methods return a page:

ListBuyersQuery query = ListBuyersQuery.builder().limit(50.0).build();
Page<BuyerViewDto> page = client.buyers.list(query);

page.data() holds the buyers and page.pagination() carries total, page, pageSize, totalPages, hasNext and hasPrevious.

Paginate.paginate walks every page for you as a lazy stream:

Paginate.paginate(p -> client.buyers.list(
                ListBuyersQuery.builder().page((double) p).limit(100.0).build()))
        .forEach(buyer -> System.out.println(buyer.name()));

Received invoices and issued history return Paginated<D> with the items under data().items(). PDF downloads return BinaryResponse with data(), contentType() and fileName(). Quantities and prices the API accepts as a string or a number are Amount (Amount.of("25000.00"), Amount.of(2), asBigDecimal()). Two answers come in one of two shapes (IssueCreditNoteData, IssueDebitNoteData); decode them with their as…(Json.mapper()) methods.

Errors

A refused request throws an unchecked exception chosen by status:

All extend EInvoiceApiException, which carries status(), errorCode(), errors() (per field), requestId() and retryAfter():

try {
    client.invoices.create(params);
} catch (EInvoiceValidationException err) {
    for (ApiErrorDetail e : err.errors()) {
        System.out.println(e.field() + ": " + e.message());
    }
} catch (EInvoiceApiException err) {
    System.out.println(err.errorCode() + " " + err.requestId());
}

Branch on errorCode(), not on the message, and quote requestId() when you write to support. Problems before the API answers are EInvoiceTimeoutException, EInvoiceConnectionException and EInvoiceConfigException; all SDK exceptions extend EInvoiceException. The codes are listed on each page of the API Reference.

Retries and idempotency

Reads, and writes that carry an Idempotency-Key, are retried automatically on network errors, timeouts, 408, 429 and 5xx, with backoff and respecting Retry-After. Other writes are never retried.

Where the API accepts an Idempotency-Key (creating an invoice, submitting, sending, downloading and so on) the SDK generates one per call, so a retry is never applied or charged twice. Pass your own to make a retry safe across restarts:

client.invoices.create(params, RequestOptions.idempotencyKey("order-" + orderId));

Tune the defaults with .timeout(...) and .retry(...) on the builder, or per call with RequestOptions.builder() (timeout, header, maxRetries).

Webhooks

In your HTTP handler, with the raw body bytes and the request headers:

import com.useyona.einvoice.Webhooks;
import com.useyona.einvoice.WebhookEvent;
 
String secret = System.getenv("YONA_WEBHOOK_SECRET");
WebhookEvent event = Webhooks.verifyWebhook(rawBody, headers, secret);
if (event.type().equals(WebhookEventType.INVOICE_ACCEPTED)) {
    // …
}

verifyWebhook checks the Yona-Signature header over the raw body, accepts either signature while a rotated secret overlaps, and returns the event; a failed check throws EInvoiceWebhookException. Always pass the raw bytes, and deduplicate on event.id(). Webhooks.signWebhookPayload signs a payload the way Yona does, so you can test your handler locally.

Endpoints are created and their secrets rotated in the Yona app; the SDK can list and test endpoints and read and redeliver deliveries and events. See Webhooks for the events.

Configuration

EInvoice.builder(key) accepts:

What it covers

Every module mirrors a tag of the API Reference, and the method names are the reference’s operation names in the casing of the language (issueCreditNote, getStatus). Every method takes an overload with a trailing RequestOptions; request and query records are named after the operation (CreateInvoiceDto, ListInvoicesQuery) and built with .builder(). Each method needs the capability shown on the key; the full_integration preset has them all.

Account management (users, roles, API keys, purchases, webhook endpoint settings) is done in the Yona app, not through the API key.

Next steps

• Invoice lifecycle: the states a submission climbs through, and what each one means
• Webhooks: the events, and how deliveries are retried
• Going live: the checklist before you deploy a live key
• API Reference: every field, status code and error code