gigerit/bexio-api-client

A Laravel package for the Bexio API

v4.5.0 2026-04-01 14:32 UTC

Requires

• php: ^8.2
• illuminate/support: ^10.0|^11.0|^12.0|^13.0
• saloonphp/saloon: ^4
• spatie/laravel-data: ^4

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0|^10.0|^11.0
• pestphp/pest: ^v3
• pestphp/pest-plugin-faker: ^v3
• pestphp/pest-plugin-laravel: ^v3
• phpstan/phpstan: ^2.1
• symfony/var-dumper: ^7

MIT

• Manuel Giger

• api
• client
• laravel
• bexio

README

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

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();
}

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
• 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

CONTACTS

Resource	Implemented
Contacts	✅
Contact Relations	✅
Contact Groups	✅
Contact Sectors	✅
Additional Addresses	✅
Salutations	✅
Titles	✅

SALES ORDER MANAGEMENT

Resource	Implemented
Quotes	✅
Orders	✅
Deliveries	✅
Invoices	✅
Document Settings	✅
Comments	✅
Default positions	✅
Item positions	✅
Text positions	✅
Subtotal positions	✅
Discount positions	✅
Pagebreak positions	✅
Sub positions	✅
Document templates	✅

PURCHASE

Resource	Implemented
Bills	✅
Expenses	✅
Purchase Orders	✅
Outgoing Payment	✅

ACCOUNTING

Resource	Implemented
Accounts	✅
Account Groups	✅
Calendar Years	✅
Business Years	✅
Currencies	✅
Manual Entries	✅
Reports	✅
Taxes	✅
Vat Periods	✅

BANKING

Resource	Implemented
Bank Accounts	✅
IBAN Payments	✅
QR Payments	✅
Payments	✅

ITEMS & PRODUCTS

Resource	Implemented
Items	✅
Stock locations	✅
Stock Areas	✅

PROJECTS & TIME TRACKING

Resource	Implemented
Projects	✅
Timesheets	✅
Business Activities	✅
Communication Types	✅

FILES

Resource	Implemented
Files	✅

OTHER

Resource	Implemented
Company Profile	✅
Countries	✅
Languages	✅
Notes	✅
Payment Types	✅
Permissions	✅
Tasks	✅
Units	✅
User Management	✅

Testing

composer test

License

MIT License - see the LICENSE file for details.