PHPackages                             vrok/billomat-client - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Payment Processing](/categories/payments)
4. /
5. vrok/billomat-client

ActiveLibrary[Payment Processing](/categories/payments)

vrok/billomat-client
====================

PHP library for interacting with the Billomat REST API

v3.2.0(2y ago)1758↓100%3MITPHPPHP ^7.4|^8

Since Feb 28Pushed 2y ago1 watchersCompare

[ Source](https://github.com/j-schumann/billomat-client)[ Packagist](https://packagist.org/packages/vrok/billomat-client)[ Docs](https://github.com/vrok/billomat-client)[ RSS](/packages/vrok-billomat-client/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (4)Dependencies (2)Versions (15)Used By (0)

A PHP Billomat API Client
=========================

[](#a-php-billomat-api-client)

[![Latest Stable Version](https://camo.githubusercontent.com/f6fbf77ed71099228785488b5de2495cf8499f88112691184be4ab93de26b87f/68747470733a2f2f706f7365722e707567782e6f72672f76726f6b2f62696c6c6f6d61742d636c69656e742f762f737461626c652e706e67)](https://packagist.org/packages/vrok/billomat-client) [![License](https://camo.githubusercontent.com/6b5cd340c4fc753e1d3ee5bcd48e125af7911562dd306e4cc48a41ba9bd54a9e/68747470733a2f2f706f7365722e707567782e6f72672f76726f6b2f62696c6c6f6d61742d636c69656e742f6c6963656e73652e706e67)](https://packagist.org/packages/vrok/billomat-client)

Introduction
------------

[](#introduction)

This is a Billomat PHP client for interacting with the REST Billomat API.

Extent of this client
---------------------

[](#extent-of-this-client)

All methods on the following assets are supported:

- [Clients](http://www.billomat.com/en/api/clients)
    - [Properties](http://www.billomat.com/en/api/clients/properties)
- [Articles](http://www.billomat.com/en/api/articles)
    - [Properties](http://www.billomat.com/en/api/articles/properties)
- [Invoices](http://www.billomat.com/en/api/invoices)
    - [Items](http://www.billomat.com/en/api/invoices/items)
    - [Payments](http://www.billomat.com/en/api/invoices/payments)
    - [Tags](http://www.billomat.com/en/api/invoices/tags)
- [Credit Notes](http://www.billomat.com/en/api/credit-notes)
    - [Items](http://www.billomat.com/en/api/credit-notes/items)
    - [Payments](http://www.billomat.com/en/api/credit-notes/payments)
- [Templates](http://www.billomat.com/en/api/templates)
- Settings
    - [Article Properties](http://www.billomat.com/en/api/settings/article-properties)
    - [Client Properties](http://www.billomat.com/en/api/settings/client-properties)
    - [User Properties](http://www.billomat.com/en/api/settings/user-properties)
    - [Taxes](http://www.billomat.com/en/api/settings/taxes)
    - [Tax free countries](http://www.billomat.com/en/api/settings/tax-free-countries)
    - [Dunning Levels](http://www.billomat.com/en/api/settings/reminder-texts)
    - [Email Templates](http://www.billomat.com/en/api/settings/email-vorlagen)

Dependencies
------------

[](#dependencies)

- [Guzzle library](http://guzzlephp.org): >= 7.4
- PHP >= 7.4 or >= 8, ext-curl

Installation via composer
-------------------------

[](#installation-via-composer)

```
composer require vrok/billomat-client
```

How to use this
---------------

[](#how-to-use-this)

Instantiate the client:

```
use Phobetor\Billomat\Client\BillomatClient;

$billomat = new BillomatClient('my-id', 'my-api-key');
```

If you have a registered app for billomat’s API (which is highly recommended due to higher rate limits) instantiate the client like this:

```
use Phobetor\Billomat\Client\BillomatClient;

$billomat = new BillomatClient('my-id', 'my-api-key', 'my-api-app-id', 'my-api-app-secret');
```

The client will find the correct endpoint automatically based on your id.

All methods are accessible from that client object:

```
// Get the client with id 133713371337
$client = $billomat->getClient(array(
    'id' => 133713371337
));

// Create a new client
$client = $billomat->createClient(array(
    'client' => array(
        'number' => 424242424242,
        'name' => 'client-name'
    )
));
```

### Calling methods

[](#calling-methods)

All method names are based on the Billomat API URLs and follow the [CRUD](http://de.wikipedia.org/wiki/CRUD) naming schema whenever possible.

All parameter names are exactly mapped. Therefore, you can refer to the [official API documentation](http://www.billomat.com/en/api). Deep links to specific documentation sections are given in the [extend of this client](#extend-of-this-client) list above and the [complete method reference](#complete-method-reference) list below.

Here is the user update method as an example for the [client](http://www.billomat.com/en/api/clients) asset:

```
// Update a client
$client = $billomat->updateClient(array(
    'id' => 133713371337,
    'client' => array(
        'number' => 424242424242,
        'name' => 'client-name'
    )
));
```

### Return values

[](#return-values)

All `delete*` methods return nothing.

The methods `get*Pdf` (when called with `'format' => 'pdf'`) and `getTemplatePreview` return a guzzle response. You can easily extract the file content:

```
// Fetch an invoice pdf file
$response = $billomat->getInvoicePdf(array(
    'id' => 133713371337,
    'format' => 'pdf'
));
$content = (string)$response->getBody();
```

All the other methods return `array` values.

### Exception handling

[](#exception-handling)

This client creates exceptions from Billomat errors based on the HTTP status code and filled with the error message provided by the Billomat API. All exceptions are `GuzzleHttp\Command\Exception\CommandException` and contain a `Phobetor\Billomat\Exception\ExceptionInterface` as `$e->getPrevious()`, so you can catch this to handle everything. You can find all exceptions in the `Phobetor\Billomat\Exception` folder.

Usage example:

```
try {
    $client = $billomat->updateClient(array(
        'id' => 133713371337,
        'client' => array(
            'number' => 424242424242,
            'name' => 'client-name'
        )
    ));
}
catch (GuzzleHttp\Command\Exception\CommandException $e) {
    switch (get_class($e->getPrevious())) {
        case \Phobetor\Billomat\Exception\NotFoundException::class:
            // There seems to be no such client.
            break;
        case \Phobetor\Billomat\Exception\BadRequestException::class:
            // Some of the given data must have been bad. $e->getMessage() could help.
            breaK;
        case \Phobetor\Billomat\Exception\TooManyRequestsException::class:
            // The rate limit was reached. $e->getRateLimitReset() returns the UTC timestamp of the next rate limit reset.
            // @see http://www.billomat.com/en/api/basics/rate-limiting for details about the rate limit.
            breaK;
        default:
            // Something else failed. Maybe there is no connection to the API servers.
            break;
    }
}
```

### Automatic rate limit handling

[](#automatic-rate-limit-handling)

If this client is used in asynchronous processes or CLI commands you can activate automatic waiting for rate limit reset. In that mode all method calls that would otherwise throw a `\Phobetor\Billomat\Exception\TooManyRequestsException` will wait for the rate limit reset and retry automatically. You **should not** use this in synchronous request (e. g. a website request) because all method calls in that mode can last very long and most likely longer than your server’s request timeout. There are two ways to do this.

At construction:

```
use Phobetor\Billomat\Client\BillomatClient;

// setting the fifth parameter to true enables waiting for rate limit
$billomat = new BillomatClient('my-id', 'my-api-key', 'my-api-app-id', 'my-api-app-secret', true);
```

After construction:

```
$billomat->setDoWaitForRateLimitReset(true);
```

### Complete method reference

[](#complete-method-reference)

CLIENT RELATED METHODS [doc](http://www.billomat.com/en/api/clients):

- array getClients(array $args = \[\])
- array getClient(array $args = \[\])
- array getClientMyself(array $args = \[\])
- array createClient(array $args = \[\])
- array updateClient(array $args = \[\])
- void deleteClient(array $args = \[\])

CLIENT PROPERTY VALUE RELATED METHODS [doc](http://www.billomat.com/en/api/clients/properties):

- array getClientPropertyValues(array $args = \[\])
- array getClientPropertyValue(array $args = \[\])
- array setClientPropertyValue(array $args = \[\])

ARTICLE RELATED METHODS [doc](http://www.billomat.com/en/api/articles):

- array getArticles(array $args = \[\])
- array getArticle(array $args = \[\])
- array createArticle(array $args = \[\])
- array updateArticle(array $args = \[\])
- void deleteArticle(array $args = \[\])

ARTICLE PROPERTY VALUE RELATED METHODS [doc](http://www.billomat.com/en/api/articles/properties):

- array getArticlePropertyValues(array $args = \[\])
- array getArticlePropertyValue(array $args = \[\])
- array setArticlePropertyValue(array $args = \[\])

INVOICE RELATED METHODS [doc](http://www.billomat.com/en/api/invoices):

- array getInvoices(array $args = \[\])
- array getInvoice(array $args = \[\])
- array createInvoice(array $args = \[\])
- array updateInvoice(array $args = \[\])
- array completeInvoice(array $args = \[\])
- \\Guzzle\\Http\\Message\\Response getInvoicePdf(array $args = \[\])
- array signInvoice(array $args = \[\])
- array sendInvoiceEmail(array $args = \[\])
- array cancelInvoice(array $args = \[\])
- array undoCancelInvoice(array $args = \[\])
- void deleteInvoice(array $args = \[\])

INVOICE ITEM RELATED METHODS [doc](http://www.billomat.com/en/api/invoices/items):

- array getInvoiceItems(array $args = \[\])
- array getInvoiceItem(array $args = \[\])
- array createInvoiceItem(array $args = \[\])
- array updateInvoiceItem(array $args = \[\])
- void deleteInvoiceItem(array $args = \[\])

INVOICE PAYMENT RELATED METHODS [doc](http://www.billomat.com/en/api/invoices/payments):

- array getInvoicePayments(array $args = \[\])
- array getInvoicePayment(array $args = \[\])
- array createInvoicePayment(array $args = \[\])
- array deleteInvoicePayment(array $args = \[\])

INVOICE TAG RELATED METHODS [doc](http://www.billomat.com/en/api/invoices/tags):

- array getInvoiceTagCloud(array $args = \[\])
- array getInvoiceTags(array $args = \[\])
- array getInvoiceTag(array $args = \[\])
- array createInvoiceTag(array $args = \[\])
- array deleteInvoiceTag(array $args = \[\])

CREDIT NOTE RELATED METHODS [doc](http://www.billomat.com/en/api/credit-notes):

- array getCreditNotes(array $args = \[\])
- array getCreditNote(array $args = \[\])
- array createCreditNote(array $args = \[\])
- array updateCreditNote(array $args = \[\])
- array completeCreditNote(array $args = \[\])
- \\Guzzle\\Http\\Message\\Response getCreditNotePdf(array $args = \[\])
- array signCreditNote(array $args = \[\])
- array sendCreditNoteEmail(array $args = \[\])
- void deleteCreditNote(array $args = \[\])

CREDIT NOTE ITEM RELATED METHODS [doc](http://www.billomat.com/en/api/credit-notes/items):

- array getCreditNoteItems(array $args = \[\])
- array getCreditNoteItem(array $args = \[\])
- array createCreditNoteItem(array $args = \[\])
- array updateCreditNoteItem(array $args = \[\])
- void deleteCreditNoteItem(array $args = \[\])

CREDIT NOTE PAYMENT RELATED METHODS [doc](http://www.billomat.com/en/api/invoices/credit-notes):

- array getCreditNotePayments(array $args = \[\])
- array getCreditNotePayment(array $args = \[\])
- array createCreditNotePayment(array $args = \[\])
- array deleteCreditNotePayment(array $args = \[\])

TEMPLATE RELATED METHODS [doc](http://www.billomat.com/en/api/templates):

- array getTemplates(array $args = \[\])
- array getTemplate(array $args = \[\])
- \\Guzzle\\Http\\Message\\Response getTemplatePreview(array $args = \[\])
- array createTemplate(array $args = \[\])
- array updateTemplate(array $args = \[\])
- void deleteTemplate(array $args = \[\])

ARTICLE PROPERTY RELATED METHODS [doc](http://www.billomat.com/en/api/settings/article-properties):

- array getArticleProperties(array $args = \[\])
- array getArticleProperty(array $args = \[\])
- array createArticleProperty(array $args = \[\])
- array updateArticleProperty(array $args = \[\])
- void deleteArticleProperty(array $args = \[\])

CLIENT PROPERTY RELATED METHODS [doc](http://www.billomat.com/en/api/settings/client-properties):

- array getClientProperties(array $args = \[\])
- array getClientProperty(array $args = \[\])
- array createClientProperty(array $args = \[\])
- array updateClientProperty(array $args = \[\])
- void deleteClientProperty(array $args = \[\])

USER PROPERTY RELATED METHODS [doc](http://www.billomat.com/en/api/settings/user-properties):

- array getUserProperties(array $args = \[\])
- array getUserProperty(array $args = \[\])
- array createUserProperty(array $args = \[\])
- array updateUserProperty(array $args = \[\])
- void deleteUserProperty(array $args = \[\])

TAX RELATED METHODS [doc](http://www.billomat.com/en/api/settings/taxes):

- array getTaxes(array $args = \[\])
- array getTax(array $args = \[\])
- array createTax(array $args = \[\])
- array updateTax(array $args = \[\])
- void deleteTax(array $args = \[\])

COUNTRY TAX RELATED METHODS [doc](http://www.billomat.com/en/api/settings/tax-free-countries):

- array getCountryTaxes(array $args = \[\])
- array getCountryTax(array $args = \[\])
- array createCountryTax(array $args = \[\])
- array updateCountryTax(array $args = \[\])
- void deleteCountryTax(array $args = \[\])

REMINDER TEXT RELATED METHODS [doc](http://www.billomat.com/en/api/settings/reminder-texts):

- array getReminderTexts(array $args = \[\])
- array getReminderText(array $args = \[\])
- array createReminderText(array $args = \[\])
- array updateReminderText(array $args = \[\])
- void deleteReminderText(array $args = \[\])

EMAIL TEMPLATE RELATED METHODS [doc](http://www.billomat.com/en/api/settings/email-templates/):

- array getEmailTemplates(array $args = \[\])
- array getEmailTemplate(array $args = \[\])
- array createEmailTemplate(array $args = \[\])
- array updateEmailTemplate(array $args = \[\])
- void deleteEmailTemplate(array $args = \[\])

FREE TEXT RELATED METHODS [doc](http://www.billomat.com/en/api/settings/free-texts/):

- array getFreeTexts(array $args = \[\])
- array getFreeText(array $args = \[\])
- array createFreeText(array $args = \[\])
- array updateFreeText(array $args = \[\])
- void deleteFreeText(array $args = \[\])

USER PROPERTY VALUE RELATED METHODS [doc](http://www.billomat.com/en/api/users/properties):

- array getUserPropertyValues(array $args = \[\])
- array getUserPropertyValue(array $args = \[\])
- array setUserPropertyValue(array $args = \[\])

SUPPLIER RELATED METHODS [doc](https://www.billomat.com/en/api/suppliers/):

- array getSupplier(array $args = \[\])
- array getSuppliers(array $args = \[\])

INCOMING INVOICES [doc](https://www.billomat.com/en/api/incomings/):

- array getIncomings(array $args = \[\])
- array getIncomingPdf(array $args = \[\])

INCOMING INVOICE TAGS [doc](http://www.billomat.com/en/api/incomings/tags):

- array createIncomingTag(array $args = \[\])

INCOMING PAYMENTS [doc](https://www.billomat.com/en/api/incomings/payments/):

- array createIncomingPayment(array $args = \[\])

INCOMING DOCUMENTS [doc](http://www.billomat.com/en/api/incomings/inbox):

- array createIncomingInboxDocument(array $args = \[\])

### API glitches handled by this client internally

[](#api-glitches-handled-by-this-client-internally)

The Billomat API provides two data formats, xml and json. The json format is used here. Due to an xml to json conversion in the Billomat API lists have a data inconsistency in the json responses.

If there is ony one element in a list the API returns something like this:

```
array(
    'clients' => array(
        'client' => array(
            'id' => 133713371337,
            /* […] */
        ),
    ),
)
```

If there are more elements in a list the API returns something like this:

```
array(
    'clients' => array(
        'client' => array(
            array(
                'id' => 133713371337,
                /* […] */
            ),
            array(
                'id' => 133713371338,
                /* […] */
            ),
            /* […] */
        ),
    ),
)
```

The type of `$result['clients']['client']` changes from an associative array to a numeric array of associative arrays.

This issue is addressed by this client internally. You can be sure that lists are numeric arrays (like in the lower example) no matter how many elements are returned.

Advanced usage
--------------

[](#advanced-usage)

This client is built on top of Guzzle, so you can take advantage of all its features. Please refer to the [Guzzle documentation](http://docs.guzzlephp.org/en/latest/) to learn more …

###  Health Score

35

—

LowBetter than 79% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity20

Limited adoption so far

Community15

Small or concentrated contributor base

Maturity71

Established project with proven stability

 Bus Factor2

2 contributors hold 50%+ of commits

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~303 days

Recently: every ~861 days

Total

13

Last Release

816d ago

Major Versions

1.5.0 → 2.0.02014-09-07

2.0.0 → v3.0.02021-03-06

PHP version history (3 changes)1.0.0PHP >=5.3.3

v3.0.0PHP ^7.4

v3.1.0PHP ^7.4|^8

### Community

Maintainers

![](https://www.gravatar.com/avatar/ed9373b6806c33f512ca3b63214dd2a2b2621bcbddffcdb99acc66ae7f0324aa?d=identicon)[j-schumann](/maintainers/j-schumann)

---

Top Contributors

[![Phobetor](https://avatars.githubusercontent.com/u/712973?v=4)](https://github.com/Phobetor "Phobetor (20 commits)")[![j-schumann](https://avatars.githubusercontent.com/u/114239?v=4)](https://github.com/j-schumann "j-schumann (16 commits)")[![leasing-erhan](https://avatars.githubusercontent.com/u/98851898?v=4)](https://github.com/leasing-erhan "leasing-erhan (5 commits)")[![vbezaras-leasingmarkt](https://avatars.githubusercontent.com/u/109661563?v=4)](https://github.com/vbezaras-leasingmarkt "vbezaras-leasingmarkt (3 commits)")[![Csardelacal](https://avatars.githubusercontent.com/u/1152823?v=4)](https://github.com/Csardelacal "Csardelacal (1 commits)")[![netzkollektiv](https://avatars.githubusercontent.com/u/618218?v=4)](https://github.com/netzkollektiv "netzkollektiv (1 commits)")

---

Tags

billinginvoicebillomat

### Embed Badge

![Health badge](/badges/vrok-billomat-client/health.svg)

```
[![Health](https://phpackages.com/badges/vrok-billomat-client/health.svg)](https://phpackages.com/packages/vrok-billomat-client)
```

###  Alternatives

[lemonsqueezy/laravel

A package to easily integrate your Laravel application with Lemon Squeezy.

58596.1k](/packages/lemonsqueezy-laravel)[superfaktura/apiclient

Api client for SuperFaktura | online invoicing tool

19133.3k](/packages/superfaktura-apiclient)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)