gigerit/bexio-api-client

Bexio API Laravel Package

A Laravel package for the Bexio API, built with saloonphp/saloon as API connector and spatie/laravel-data for DTOs.

Requirements

• PHP 8.2+
• Laravel 10.x, 11.x, 12.x, or 13.x

Installation

composer require gigerit/bexio-api-client

The package will automatically register its service provider.

Publish Configuration

php artisan vendor:publish --tag=bexio-config

This will create a config/bexio.php configuration file.

Environment Variables

Add your Bexio API credentials to your .env file:

# For Personal Access Token (simplest method)
BEXIO_ACCESS_TOKEN=your-access-token

# For OAuth2 (user-based authentication)
BEXIO_CLIENT_ID=your-client-id
BEXIO_CLIENT_SECRET=your-client-secret
BEXIO_REDIRECT_URI=https://your-app.com/bexio/callback

# Optional: persisted OAuth tokens
BEXIO_OAUTH_ACCESS_TOKEN=your-oauth-access-token
BEXIO_OAUTH_REFRESH_TOKEN=your-oauth-refresh-token

Quick Start

Using Dependency Injection

use Bexio\BexioClient;
use Bexio\Resources\Contacts\Contacts\Contact;

class ContactController extends Controller
{
    public function index(BexioClient $client)
    {
        $contacts = Contact::useClient($client)->all();

        return view('contacts.index', compact('contacts'));
    }

    public function show(BexioClient $client, int $id)
    {
        $contact = Contact::useClient($client)->find($id);

        return view('contacts.show', compact('contact'));
    }
}

Using the Facade

use Bexio\Facades\Bexio;
use Bexio\Resources\Contacts\Contacts\Contact;

// Get all contacts
$contacts = Contact::useClient(Bexio::getFacadeRoot())->all();

// Or resolve the client directly
$client = app('bexio');
$contacts = Contact::useClient($client)->all();

Resource Guides

Detailed resource usage is documented in segmented guides under docs/resources/ so this README stays high-level.

• Resource guides index
• Contacts guides
• Contacts resource
• Orders resource
• Quotes resource

OAuth2 Authentication

For user-based authentication where users authenticate with their own Bexio account:

1. Generate Authorization URL

use Bexio\BexioAuth;
use Illuminate\Support\Str;

class BexioAuthController extends Controller
{
    public function redirect()
    {
        $auth = new BexioAuth(
            config('bexio.oauth.client_id'),
            config('bexio.oauth.client_secret'),
            config('bexio.oauth.redirect_uri')
        );

        $state = Str::random(40);

        session()->put('bexio_state', $state);

        $url = $auth->getAuthorizationUrl(
            scopes: config('bexio.scopes'),
            state: $state
        );

        return redirect($url);
    }
}

2. Handle Callback

use Bexio\BexioAuth;

public function callback(Request $request)
{
    $code = $request->get('code');
    $state = $request->get('state');

    if ($state !== session('bexio_state')) {
        abort(403, 'Invalid state');
    }

    $auth = new BexioAuth(
        config('bexio.oauth.client_id'),
        config('bexio.oauth.client_secret'),
        config('bexio.oauth.redirect_uri')
    );

    $authenticator = $auth->getAccessToken($code, $state, session('bexio_state'));

    // Store the tokens (serialize the $authenticator or store individual values)
    auth()->user()->update([
        'bexio_access_token' => $authenticator->getAccessToken(),
        'bexio_refresh_token' => $authenticator->getRefreshToken(),
        'bexio_expires_at' => $authenticator->getExpiresAt(),
    ]);

    return redirect()->route('dashboard');
}

3. Use with Per-User Authentication

use Bexio\BexioAuth;
use DateTimeImmutable;
use Bexio\Resources\Contacts\Contacts\Contact;
use Bexio\BexioClient;
use Saloon\Http\Auth\AccessTokenAuthenticator;

public function getContacts()
{
    $user = auth()->user();

    $authService = new BexioAuth(
        config('bexio.oauth.client_id'),
        config('bexio.oauth.client_secret'),
        config('bexio.oauth.redirect_uri')
    );

    $auth = new AccessTokenAuthenticator(
        $user->bexio_access_token,
        $user->bexio_refresh_token,
        new DateTimeImmutable($user->bexio_expires_at)
    );

    if ($auth->hasExpired()) {
        $auth = $authService->refreshAccessToken($auth);

        $user->update([
            'bexio_access_token' => $auth->getAccessToken(),
            'bexio_refresh_token' => $auth->getRefreshToken(),
            'bexio_expires_at' => $auth->getExpiresAt(),
        ]);
    }

    $client = new BexioClient($auth->getAccessToken());

    return Contact::useClient($client)->all();
}

4. Disconnect OAuth

Revoke the stored refresh token before clearing the locally persisted OAuth values. revokeToken() throws when Bexio rejects the request, so the local values are cleared only after a successful revocation:

use Bexio\BexioAuth;

public function disconnect()
{
    $user = auth()->user();

    $auth = new BexioAuth(
        config('bexio.oauth.client_id'),
        config('bexio.oauth.client_secret'),
    );

    $auth->revokeToken($user->bexio_refresh_token, 'refresh_token');

    $user->update([
        'bexio_access_token' => null,
        'bexio_refresh_token' => null,
        'bexio_expires_at' => null,
    ]);
}

Revoking only an OAuth access token invalidates that token but does not disconnect the renewable refresh-token session. For a full disconnect, revoke the refresh token as shown above. The optional token_type_hint (access_token or refresh_token) helps the authorization server locate the token but is advisory. This method is for tokens issued through the OAuth flow; it does not revoke Bexio personal access tokens.

Documentation

For detailed documentation and advanced usage examples, see:

Resource Guides

• Resource Guides Index - Entry point for segmented per-resource documentation
• Contacts Guides - Contacts, Contact Relations, Contact Groups, Contact Sectors, Additional Addresses, Salutations, and Titles
• Orders Guide - Order CRUD, search endpoint usage, and status helpers
• Endpoint Status Overview - Current implementation status by Bexio endpoint
• Legacy Contacts Redirect - Compatibility landing page pointing to the segmented contacts guides

Additional Resources

• Tests - Unit tests with practical examples

Data Transfer Objects

DTOs provide type hinting and autocompletion in the IDE, for a better development experience.

Available Resources

Endpoint coverage is derived from docs/bexio-api-docs.md. Implemented means a matching request method and endpoint exists in src/Resources/**/Requests.

CONTACTS

See contact title/address payloads.

SALES ORDER MANAGEMENT

See manual quote addresses and position metadata and writes.

PURCHASE

See current purchase OAuth scope requirements, response metadata, and bill-scoped outgoing payments.

ACCOUNTING

See manual entry metadata and attachments.

BANKING

See v4 payment creation and updates.

ITEMS & PRODUCTS

PROJECTS & TIME TRACKING

See timesheet tracking payloads.

FILES

PAYROLL

See employee and absence contracts.

OTHER

Testing

composer test

For a known trial test account, set BEXIO_TEST_ACCOUNT_PLAN=trial in .env. This explicitly skips live payroll, legacy IBAN/QR writes, and purchase-order writes unavailable on that account; their request/DTO contract tests still run. Leave the setting empty for full accounts so authorization failures surface. Data-dependent skips and trial exclusions do not constitute successful live verification. CI defaults to the shared trial account; set the repository variable BEXIO_TEST_ACCOUNT_PLAN to full when using an account with the required access.

License

MIT, as declared in composer.json.