README

The PHP client for the billit.io API, with first-class Laravel support. Create MyData (A.A.D.E.) compatible invoices, manage contacts, products, payments, purchases, tags and One Click Payment links, and look up Greek companies by VAT id.

Requirements

• PHP 8.2 or newer
• Guzzle 7.9 or newer
• Laravel 12 or 13 (optional, for the service provider and facade)

Upgrading from 2.x? See UPGRADE.md.

Install

composer require drakakisgeo/billit

Getting a token

Register for a Sandbox account, go to Settings > API and generate a token. Build and test against the sandbox first. Production tokens are read only until you contact Billit for full access. Sandbox data is wiped every month.

Usage

Plain PHP

use Drakakisgeo\Billit\Billit;

$billit = new Billit('your-token', sandbox: true);

$billit->welcome(); // { "msg": "Hello from the Billit API" }

The default HTTP client uses a 10 second request timeout and a 5 second connect timeout. To change them, or to add your own Guzzle middleware, pass a client:

$billit = new Billit('your-token', sandbox: true, client: Billit::httpClient(sandbox: true, timeout: 30));

Laravel

The service provider and the Billit facade are auto-discovered. Add the credentials to config/services.php:

'billit' => [
    'token' => env('BILLIT_API_TOKEN'),
    'sandbox' => env('BILLIT_API_IS_SANDBOX', false),
    'version' => 'v1',
    'timeout' => 10,          // seconds, optional
    'connect_timeout' => 5,   // seconds, optional
],

Then inject it, resolve it, or use the facade:

use Drakakisgeo\Billit\Billit;

public function __construct(private Billit $billit) {}

$billit = app(Billit::class);

\Billit::myAccount();

Responses

Every method returns the decoded JSON as a stdClass. Single resources live under data, and lists add links and meta for pagination. Successful DELETE calls return an empty object.

Errors

API and network failures throw an exception that extends Drakakisgeo\Billit\Exceptions\BillitException:

Every exception has getStatusCode() and getResponseBody().

use Drakakisgeo\Billit\Exceptions\BillitException;
use Drakakisgeo\Billit\Exceptions\ValidationException;

try {
    $invoice = $billit->invoiceCreate($payload);
} catch (ValidationException $e) {
    $e->errors(); // ['customerId' => ['The customer id field is required.']]
} catch (BillitException $e) {
    report($e);
}

Endpoints

List methods send $params as query string filters. All lists accept per_page (default 25, max 250) and page. See the API reference for each resource's fields and filters.

Examples

The account

The account response contains the biller, payment method and VAT ids you need when creating invoices. It rarely changes, so it is safe to cache.

$account = $billit->myAccount();

Contacts

$billit->contacts(['q' => 'Awesome', 'unpaid' => 1, 'per_page' => 100]);

$billit->contactCreate([
    'isCompany' => true,
    'company' => 'Awesome S.A.',
    'customerType' => 1, // 1 customer, 2 supplier, 3 both
    'country' => 'GR',
    'inCharge' => 'Kalampakopoulos George',
    'lang' => 'el',
    'vatId' => 'EL075101010',
]);

$billit->contactUpdate(1010, ['inCharge' => 'Papadopoulos Maria']);
$billit->contactShow(1010);
$billit->contactDelete(1010);

Create an invoice (MyData enabled)

$billit->invoiceCreate([
    'customerId' => 694,
    'sendMail' => false,
    'excludeMydata' => false,
    'invoiceDate' => '2026-04-15',
    'invoiceTypeId' => 349,
    'isPaid' => true,
    'mydataInvoiceType' => '2.1',
    'taxes' => [
        ['taxId' => 514],
        ['taxId' => 524, 'taxVatShow' => 1],
    ],
    'products' => [
        [
            'productId' => null,
            'details' => 'Consulting',
            'measurementUnit' => 1,
            'vatId' => 376,
            'price' => 123.32,
            'quantity' => 1,
            'incomeClassificationCat' => 'category1_3',
            'incomeClassificationType' => 'E3_561_001',
        ],
    ],
    'tags' => ['billit', 'test-tag'],
    'mydataPayment' => [
        'paidAmount' => 0.32,
        'paymentMethod' => 3,
        'epiPistosi' => 10,
    ],
]);

One Click Payment link

You need an online payment method set up in the Billit app first. Use that provider's sandbox account while testing.

$ocp = $billit->ocpCreate([
    'title' => 'Annual subscription',
    'cost' => 124.00,
    'netValue' => 100.00,
    'vatId' => 376,
    'invoiceTypeId' => 349,
    'paymentMethodId' => 12,
    'lang' => 'el',
    'expirationAt' => '2026-12-31',
]);

Look up a company by VAT id

Enable GSIS in your Billit settings first.

$company = $billit->gsis('094014201');

Testing

composer test
composer analyse

Security

Please report vulnerabilities as described in SECURITY.md, not in public issues.

Contributing

Please see CONTRIBUTING for details.

Credits

• Drakakis George
• All Contributors

License

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