composer require finbaze/finbaze-php

PHP 8.1 or newer, any PSR-18 HTTP client (Guzzle is the default). The typed operation classes are generated with Sailor from the same GraphQL operations as the Node SDK; the resources and names match, in camelCase.

use FinBaze\FinBaze;

$finbaze = new FinBaze('fb_sk_test_…');  // fb_*_test_ keys use the sandbox API

$company = $finbaze->platform->companies->create(['externalId' => 'acme-1', 'registrationCountry' => 'NL', 'registrationNumber' => '00000001']);
$user = $finbaze->platform->users->upsert(['externalUserId' => 'user-42', 'firstName' => 'Sam']);
$finbaze->platform->users->setAccess(companyId: $company->company->id, role: 'admin', userId: $user->id);

$session = $finbaze->platform->embedSessions->create(
    company: $company->company->id,
    user: ['id' => $user->id],
    components: ['vatReturn' => ['enabled' => true]],
);
return ['clientSecret' => $session->clientSecret];

Options (second argument): apiBase, version, maxRetries (default 2), timeout (seconds), scopes, appInfo, httpClient (any PSR-18 client), requestFactory, streamFactory, and accessToken or clientId + clientSecret + profileId instead of a secret key.

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 the key as the last argument of a write 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#

$event = $finbaze->webhooks->constructPlatformEvent(file_get_contents('php://input'), $_SERVER['HTTP_X_FINBAZE_SIGNATURE'] ?? null, $secret);

Pass the body exactly as received. $secret may be an array ([$new, $old]) while you rotate. The check is constant-time (hash_equals) and rejects timestamps more than 300 seconds off; failures throw FinBaze\Errors\SignatureVerificationError. See events and webhooks.

Errors#

FinBaze\Errors\FinBazeError is the base class; each error carries errorCode, 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, $page->autoPaging() is a generator over all of them.

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

use FinBaze\Generated\Operations\SdkPlatformCompany;

$result = $finbaze->execute(fn () => SdkPlatformCompany::execute(externalId: 'acme-1'));
$result->data->platformCompany->legalName;

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