README

A Laravel package providing a fluent API client for the Affilbox affiliate marketing platform. Supports PHP 8.3+ and Laravel 11/12.

Installation

composer require jakuborava/affilbox-client

Publish the config file:

php artisan vendor:publish --tag="affilbox-client-config"

Add your credentials to .env:

AFFILBOX_INSTANCE_NUMBER=your-instance-number
AFFILBOX_API_KEY=your-api-key

Usage

You can use the Facade or inject the client via dependency injection:

use JakubOrava\AffilboxClient\Facades\AffilboxClient;

// Facade
$dashboard = AffilboxClient::dashboard()->get();

// Dependency injection
use JakubOrava\AffilboxClient\AffilboxClient;

public function __construct(private AffilboxClient $client) {}

$dashboard = $this->client->dashboard()->get();

You can also pass credentials directly:

$client = new AffilboxClient('instance-number', 'api-key');

Test Connection

$client->test()->ping();             // Returns "pong"
$client->test()->checkCredentials(); // Returns "ok"

Dashboard

$dashboard = $client->dashboard()->get(); // DashboardDTO

$dashboard->clicks;
$dashboard->conversions;
$dashboard->commission;
$dashboard->pending;
$dashboard->payment;
$dashboard->total;

Instance

$instance = $client->instance()->get(); // InstanceDTO

$instance->domain;
$instance->currency;
$instance->locked;
$instance->terminated;
$instance->expire; // Carbon|false

Campaigns

$campaigns = $client->campaigns()->list(); // Collection<int, CampaignDTO>

foreach ($campaigns as $campaign) {
    $campaign->id;
    $campaign->name;
    $campaign->active;
    $campaign->commission;
}

Conversions

List conversions:

use JakubOrava\AffilboxClient\Requests\ConversionsListRequest;
use JakubOrava\AffilboxClient\Enums\ConversionState;
use Carbon\Carbon;

// All conversions
$conversions = $client->conversions()->list();

// Filtered
$request = (new ConversionsListRequest)
    ->state(ConversionState::Authorized)
    ->dateFrom(Carbon::parse('2024-01-01'))
    ->dateTo(Carbon::parse('2024-12-31'))
    ->campaignId(42)
    ->coupon('SUMMER');

$conversions = $client->conversions()->list($request); // Collection<int, ConversionDTO>

Add a conversion:

use JakubOrava\AffilboxClient\Requests\AddConversionRequest;

$request = new AddConversionRequest(
    campaignId: 42,
    userId: 'partner@example.com',
    createDate: Carbon::now(),
    value: 200.00,
);

// Optional fluent methods
$request->sales(150.00)
    ->transactionId('TXN-123')
    ->channel('web')
    ->coupon('SUMMER');

$client->conversions()->add($request);

Change a conversion:

use JakubOrava\AffilboxClient\Requests\ChangeConversionRequest;

$request = (new ChangeConversionRequest(
    conversionId: 23,
    state: ConversionState::Authorized,
))
    ->value(123.46)
    ->sales(100.00)
    ->currency('CZK')
    ->comment('Approved');

$client->conversions()->change($request);

Partners

List partners:

use JakubOrava\AffilboxClient\Requests\PartnersListRequest;

// All partners
$partners = $client->partners()->list();

// Filtered
$request = (new PartnersListRequest)
    ->registerFrom(Carbon::parse('2024-01-01'))
    ->registerTo(Carbon::parse('2024-12-31'))
    ->lastLoginFrom(Carbon::parse('2024-06-01'));

$partners = $client->partners()->list($request); // Collection<int, PartnerDTO>

foreach ($partners as $partner) {
    $partner->person->name;
    $partner->person->email;
    $partner->company->name;
    $partner->address->city;
}

Add a partner:

use JakubOrava\AffilboxClient\Requests\AddPartnerRequest;

$request = (new AddPartnerRequest('partner@example.com'))
    ->name('Jan')
    ->surname('Novák')
    ->phone('+420608100100')
    ->street('Národní 12')
    ->city('Praha')
    ->postCode('10000')
    ->country('CZ')
    ->company('Firma s.r.o.')
    ->ic('12345678')
    ->dic('CZ12345678');

$response = $client->partners()->add($request); // AddPartnerResponseDTO

$response->instance;
$response->url;
$response->apiKey;
$response->login;
$response->password;

Invoices

List invoices:

$invoices = $client->invoices()->list(); // Collection<int, InvoiceDTO>

foreach ($invoices as $invoice) {
    $invoice->id;
    $invoice->vs;
    $invoice->paid;
    $invoice->issueDate;  // Carbon
    $invoice->dueDate;    // Carbon
    $invoice->supplier;   // SupplierDTO
    $invoice->customer;   // CustomerDTO

    foreach ($invoice->items as $item) {
        $item->item;
        $item->amount;
        $item->currency;
    }
}

Request billing:

$status = $client->invoices()->billingRequest();

Upload an invoice:

use JakubOrava\AffilboxClient\Requests\UploadInvoiceRequest;

$request = new UploadInvoiceRequest(
    invoiceId: 24,
    issuedOn: Carbon::parse('2024-10-09'),
    due: Carbon::parse('2024-10-19'),
    vs: 202410045,
    file: base64_encode(file_get_contents('invoice.pdf')),
);

$invoice = $client->invoices()->upload($request); // InvoiceDTO

DTOs

All DTOs use readonly properties. Dates are Carbon instances.

Enums

ConversionState

Error Handling

All exceptions extend AffilboxClientException, so you can catch them individually or as a group:

use JakubOrava\AffilboxClient\Exceptions\AffilboxClientException;
use JakubOrava\AffilboxClient\Exceptions\AuthenticationException;
use JakubOrava\AffilboxClient\Exceptions\ValidationException;
use JakubOrava\AffilboxClient\Exceptions\ApiErrorException;
use JakubOrava\AffilboxClient\Exceptions\UnexpectedResponseException;

try {
    $client->conversions()->list();
} catch (AuthenticationException $e) {
    // 401 - Invalid credentials
} catch (ValidationException $e) {
    // 422 - Validation error
} catch (ApiErrorException $e) {
    // Server error or API error status
} catch (UnexpectedResponseException $e) {
    // Non-array / malformed response
} catch (AffilboxClientException $e) {
    // Catch-all for any client exception
}

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

• Jakub Orava
• All Contributors

License

The MIT License (MIT). Please see License File for more information.