implementation("com.finbaze:finbaze-java:0.1.0")

JVM 17 or newer. OkHttp does the HTTP; the models and operations are generated with Apollo Kotlin from the same GraphQL operations as the Node SDK. Kotlin gets suspend functions and Flow; every call also has an …Async twin returning a CompletableFuture for Java, and executeBlocking for scripts.

val finbaze = FinBaze(secretKey = "fb_sk_test_…")  // fb_*_test_ keys use the sandbox API

val company = finbaze.platform.companies.create(externalId = "acme-1", registrationCountry = Country.NL, registrationNumber = "00000001")
val companyId = company.company.sdkPlatformCompanyFields.id
val user = finbaze.platform.users.upsert(externalUserId = "user-42", firstName = "Sam")
finbaze.platform.users.setAccess(companyId = companyId, role = PermissionSet.admin, userId = user.id)

val session = finbaze.platform.embedSessions.create(
    company = companyId,
    user = EmbedUser.id(user.id),
    components = EmbedComponents.builder().vatReturn().build(),
)
return mapOf("clientSecret" to session.clientSecret)

FinBaze finbaze = FinBaze.builder().secretKey("fb_sk_test_…").maxRetries(2).build();

var company = finbaze.getPlatform().getCompanies().createAsync("acme-1", Country.NL, "00000001").get();

The long forms take the generated input classes (CreatePlatformCompanyInput, UpsertPlatformUserInput, …) when you need fields the short forms leave out. Close the client (close()) when your application stops.

What the client does for you#

• Exchanges the key for an access token, caches it and refreshes it 60 seconds before it expires; a token the API rejects is dropped and exchanged again.
• Sends FinBaze-Version, and an Idempotency-Key on every mutation that can be retried, the same on every attempt. Pass idempotencyKey to choose it.
• Retries network errors, HTTP 429 and 500/502/503/504 (not GraphQL errors) with jittered backoff; a Retry-After header is a floor.

Webhooks#

val event = Webhooks.constructPlatformEvent(rawBody, request.header("X-FinBaze-Signature"), secret)

Pass the body exactly as received. Webhooks is a static helper for Java; pass a List<String> of secrets while you rotate. The check is constant-time and rejects timestamps more than 300 seconds off; failures throw SignatureVerificationError. See events and webhooks.

Errors#

FinBazeError is the base class (unchecked); each error carries code, status, param, docUrl and requestId. The subclasses are AuthenticationError, RateLimitError (retryAfterSeconds), FeatureDisabledError, OperationNotAllowedError, NotFoundError, ValidationError, ApiError, NetworkError and ServiceUnavailableError, mapped from extensions.code exactly as in the Python SDK and every other server SDK. See errors.

Resources and every operation#

platform.companies, users, userTokens, embedSessions, features (and features.limits), usage, dataSources, bulk (NDJSON uploads), messages (acknowledge) and stepUp. Lists return a Page: page.data is one page; autoPaging() is a Flow, autoPagingToList() a list and autoPagingIterable() a blocking Iterable for Java.

Any other operation is a generated class in com.finbaze.generated; run it with the client's credentials, retries and key:

val data = finbaze.execute(SdkPlatformCompanyQuery(profileId = null, externalId = "acme-1"))
data.platformCompany?.sdkPlatformCompanyFields?.legalName

The same calls in all five languages are on server SDK snippets.