A PHP Billomat API Client

Introduction

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

Extend of this client

All methods on the following assets are supported:

Clients
- Properties
Articles
- Properties
Invoices
- Items
Credit Notes
- Items
Templates
~~Settings~~

Dependencies

Guzzle library: >= 3.5

Integration with frameworks

If you want to use this client with Symfony 2, there is a ready-to-use bundle:

billomat-bundle: a Symfony 2 bundle

Installation via composer

php composer.phar require phobetor/billomat:~1.0

How to use this

Instantiate the client:

use Phobetor\Billomat\Client\BillomatClient;

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

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

All method names are based on the Billomat API URLs and follow the CRUD naming schema whenever possible.

All parameter names are exactly mapped. Therefore, you can refer to the official API documentation. Deep links are given in the asset list above and the method list below.

Here is the user update method as an example for the client asset:

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

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

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 implement the Phobetor\Billomat\Exception\ExceptionInterface interface, 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 (\Phobetor\Billomat\Exception\NotFoundException $e) {
    // There seems to be no such client.
}
catch (\Phobetor\Billomat\Exception\BadRequestException $e) {
    // Some of the given data must have been bad. $e->getMessage() could help.
}
catch (\Phobetor\Billomat\ExceptionInterface $e) {
    // Something else failed. Maybe there is no connection to the API servers.
}

Complete reference

CLIENT RELATED METHODS doc:

array getClients(array $args = array())
array getClient(array $args = array())
array getClientMyself(array $args = array())
array createClient(array $args = array())
array updateClient(array $args = array())
void deleteClient(array $args = array())

CLIENT PROPERTY VALUE RELATED METHODS doc:

array getClientPropertyValues(array $args = array())
array getClientPropertyValue(array $args = array())
array setClientPropertyValue(array $args = array())

ARTICLE RELATED METHODS doc:

array getArticles(array $args = array())
array getArticle(array $args = array())
array createArticle(array $args = array())
array updateArticle(array $args = array())
void deleteArticle(array $args = array())

ARTICLE PROPERTY VALUE RELATED METHODS doc:

array getArticlePropertyValues(array $args = array())
array getArticlePropertyValue(array $args = array())
array setArticlePropertyValue(array $args = array())

INVOICE RELATED METHODS doc:

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

INVOICE ITEM RELATED METHODS doc:

array getInvoiceItems(array $args = array())
array getInvoiceItem(array $args = array())
array createInvoiceItem(array $args = array())
array updateInvoiceItem(array $args = array())
void deleteInvoiceItem(array $args = array())

CREDIT NOTE RELATED METHODS doc:

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

CREDIT NOTE ITEM RELATED METHODS doc:

array getCreditNoteItems(array $args = array())
array getCreditNoteItem(array $args = array())
array createCreditNoteItem(array $args = array())
array updateCreditNoteItem(array $args = array())
void deleteCreditNoteItem(array $args = array())

TEMPLATE RELATED METHODS doc:

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

ARTICLE PROPERTY RELATED METHODS doc:

array getArticleProperties(array $args = array())
array getArticleProperty(array $args = array())
array createArticleProperty(array $args = array())
array updateArticleProperty(array $args = array())
void deleteArticleProperty(array $args = array())

CLIENT PROPERTY RELATED METHODS doc:

array getClientProperties(array $args = array())
array getClientProperty(array $args = array())
array createClientProperty(array $args = array())
array updateClientProperty(array $args = array())
void deleteClientProperty(array $args = array())

USER PROPERTY RELATED METHODS doc:

array getUserProperties(array $args = array())
array getUserProperty(array $args = array())
array createUserProperty(array $args = array())
array updateUserProperty(array $args = array())
void deleteUserProperty(array $args = array())

TAX RELATED METHODS doc:

array getTaxes(array $args = array())
array getTax(array $args = array())
array createTax(array $args = array())
array updateTax(array $args = array())
void deleteTax(array $args = array())

COUNTRY TAX RELATED METHODS doc:

array getCountryTaxes(array $args = array())
array getCountryTax(array $args = array())
array createCountryTax(array $args = array())
array updateCountryTax(array $args = array())
void deleteCountryTax(array $args = array())

REMINDER TEXT RELATED METHODS doc:

array getReminderTexts(array $args = array())
array getReminderText(array $args = array())
array createReminderText(array $args = array())
array updateReminderText(array $args = array())
void deleteReminderText(array $args = array())

EMAIL TEMPLATE RELATED METHODS doc:

array getEmailTemplates(array $args = array())
array getEmailTemplate(array $args = array())
array createEmailTemplate(array $args = array())
array updateEmailTemplate(array $args = array())
void deleteEmailTemplate(array $args = array())

USER PROPERTY VALUE RELATED METHODS doc:

array getUserPropertyValues(array $args = array())
array getUserPropertyValue(array $args = array())
array setUserPropertyValue(array $args = array())

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

This client is built on top of Guzzle, so you can take advantage of all its features. Please refer to the Guzzle documentation to learn more …

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

A PHP Billomat API Client

Introduction

Extend of this client

Dependencies

Integration with frameworks

Installation via composer

How to use this

Calling methods

Return values

Exception handling

Complete reference

API glitches handled by this client internally

Advanced usage

Files

README.md

Latest commit

History

README.md

File metadata and controls

A PHP Billomat API Client

Introduction

Extend of this client

Dependencies

Integration with frameworks

Installation via composer

How to use this

Calling methods

Return values

Exception handling

Complete reference

API glitches handled by this client internally

Advanced usage