2017 © Pedro Peláez
 

library exact-php-client

A PHP Client for the Exact API

image

picqer/exact-php-client

A PHP Client for the Exact API

  • Thursday, May 24, 2018
  • by stephangroen
  • Repository
  • 17 Watchers
  • 61 Stars
  • 104,624 Installations
  • PHP
  • 2 Dependents
  • 0 Suggesters
  • 100 Forks
  • 15 Open issues
  • 52 Versions
  • 15 % Grown

The README.md

Exact PHP Client

Run phpunit, (*1)

PHP client library for the Exact Online API. This client lets you integrate with Exact Online, for example by: - creating and sending invoices, - add journal entries, - or upload received invoices., (*2)

This client uses the same naming and conventions as the Exact API itself, so best way to find out how this client works is by looking at the Exact Online documentation and API reference., (*3)

This library is created and maintained by Picqer. We are looking for PHP developers to join our team!, (*4)

Composer install

Installing this Exact client for PHP can be done through Composer., (*5)

composer require picqer/exact-php-client

Usage

  1. Set up app at Exact App Center to retrieve credentials
  2. Authorize the integration from your app
  3. Parse callback and finish connection set up
  4. Use the library to do stuff

Steps 1 - 3 are only required once on set up., (*6)

Set up app at Exact App Center to retrieve credentials

Set up an App at the Exact App Center to retrieve your Client ID and Client Secret. You will also need to set the correct Callback URL for the oAuth dance to work., (*7)

Authorize the integration from your app

The code below is an example authorize() function., (*8)

$connection = new \Picqer\Financials\Exact\Connection();
$connection->setRedirectUrl('CALLBACK_URL'); // Same as entered online in the App Center
$connection->setExactClientId('CLIENT_ID');
$connection->setExactClientSecret('CLIENT_SECRET');
$connection->redirectForAuthorization();

This will redirect the user to Exact to login and authorize your integration with their account., (*9)

Parse callback and finish connection set up

Exact will redirect back to the callback url you provided. The callback will receive a code param. This is the authorization code for oAuth. Store this code., (*10)

Make a new connection to Exact so the library can exchange codes and fetch the accesstoken and refreshtoken. The accesstoken is a temporary token which allows for communication between your app and Exact. The refreshtoken is a token which is used to get a new accesstoken which also refreshes the refreshtoken. The library will settle all of this for you. The code below could be an general connect() function, which returns the api connection., (*11)

$connection = new \Picqer\Financials\Exact\Connection();
$connection->setRedirectUrl('CALLBACK_URL');
$connection->setExactClientId('CLIENT_ID');
$connection->setExactClientSecret('CLIENT_SECRET');

if (getValue('authorizationcode')) {
    // Retrieves authorizationcode from database
    $connection->setAuthorizationCode(getValue('authorizationcode'));
}

if (getValue('accesstoken')) {
    // Retrieves accesstoken from database
    $connection->setAccessToken(unserialize(getValue('accesstoken')));
}

if (getValue('refreshtoken')) {
    // Retrieves refreshtoken from database
    $connection->setRefreshToken(getValue('refreshtoken'));
}

if (getValue('expires_in')) {
    // Retrieves expires timestamp from database
    $connection->setTokenExpires(getValue('expires_in'));
}

// Make the client connect and exchange tokens
try {
    $connection->connect();
} catch (\Exception $e)
{
    throw new Exception('Could not connect to Exact: ' . $e->getMessage());
}

// Save the new tokens for next connections
setValue('accesstoken', serialize($connection->getAccessToken()));
setValue('refreshtoken', $connection->getRefreshToken());

// Optionally, save the expiry-timestamp. This prevents exchanging valid tokens (ie. saves you some requests)
setValue('expires_in', $connection->getTokenExpires());

// Optionally, set the lock and unlock callbacks to prevent multiple request for acquiring a new refresh token with the same refresh token.
$connection->setAcquireAccessTokenLockCallback('CALLBACK_FUNCTION');
$connection->setAcquireAccessTokenUnlockCallback('CALLBACK_FUNCTION');

About divisions (administrations)

By default the library will use the default administration of the user. This means that when the user switches administrations in Exact Online. The library will also start working with this administration., (*12)

Rate limits

Exact uses a minutely and daily rate limit. There are a maximum number of calls per day you can do per company, and to prevent bursting they have also implemented a limit per minute. This PR stores this information in the Connection and adds methods to read the rate limits so you can handle these as appropriate for your app. Exact documentation on rate limits is found here: https://support.exactonline.com/community/s/knowledge-base#All-All-DNO-Simulation-gen-apilimits, (*13)

If you hit a rate limit, an ApiException will be thrown with code 429. At that point you can determine whether you've hit the minutely or the daily limit. If you've hit the minutely limit, try again after 60 seconds. If you've hit the daily limit, try again after the daily reset., (*14)

You can use the following methods on the Connection, which will return the limits after your first API call (based on the headers from Exact)., (*15)

$connection->getDailyLimit(); // Retrieve your daily limit
$connection->getDailyLimitRemaining(); // Retrieve the remaining amount of API calls for this day
$connection->getDailyLimitReset(); // Retrieve the timestamp for when the limit will reset
$connection->getMinutelyLimit(); // Retrieve your limit per minute
$connection->getMinutelyLimitRemaining(); // Retrieve the amount of API calls remaining for this minute
$connection->getMinutelyLimitReset(); // Retrieve the timestamp for when the minutely limit will reset

Do note when you have no more minutely calls available, Exact only sends the Minutely Limit headers. So in that case, the Daily Limit headers will remain 0 until the minutely reset rolls over., (*16)

There is basic support to sleep upon hitting the minutely rate limits. If you enable "Wait on minutely rate limit hit", the client will sleep until the limit is reset. Daily limits are not considered., (*17)

$connection->setWaitOnMinutelyRateLimitHit(true);

Use the library to do stuff (examples)

// Optionally set administration, otherwise use the current administration of the user
$connection->setDivision(123456);

// Create a new account
$account = new \Picqer\Financials\Exact\Account($connection);
$account->AddressLine1 = 'Customers address line';
$account->AddressLine2 = 'Customer address line 2';
$account->City = 'Customer city';
$account->Code = 'Customer code';
$account->Country = 'Customer country';
$account->IsSales = 'true';
$account->Name = 'Customer name';
$account->Postcode = 'Customer postcode';
$account->Status = 'C';
$account->save();

// Add a product in Exact
$item = new \Picqer\Financials\Exact\Item($connection);
$item->Code = 'product code';
$item->CostPriceStandard = 2.50;
$item->Description = 'product description';
$item->IsSalesItem = true;
$item->SalesVatCode = 'VH';
$item->save();

// Retrieve an item by id
$item = new \Picqer\Financials\Exact\Item($connection);
$id = '097A82A9-6EF7-4EDC-8036-3F7559D9EF82';
$item->find($id);

// List items
$item = new \Picqer\Financials\Exact\Item($connection);
$item->get();

// List items with filter (using a filter always returns a collection) and loop through the result
$item = new \Picqer\Financials\Exact\Item($connection);
$items = $item->filter("Code eq '$item->Code'"); // Uses filters as described in Exact API docs (odata filters)
foreach($items as $itemObject){
    $attrs = (array) $itemObject->attributes(); // Turns the endpoint properties into an array
    $picture = $itemObject->download();         // Fetches an image string instead of the url
    // Do something with $attrs and or $picture, e.g. imagecreatefromstring($picture) 
}

// Create new invoice with invoice lines
$invoiceLines[] = [
    'Item'      => $item->ID,
    'Quantity'  => 1,
    'UnitPrice' => $item->CostPriceStandard
];

$salesInvoice = new \Picqer\Financials\Exact\SalesInvoice($connection);
$salesInvoice->InvoiceTo = $account->ID;
$salesInvoice->OrderedBy = $account->ID;
$salesInvoice->YourRef = 'Invoice reference';
$salesInvoice->SalesInvoiceLines = $invoiceLines;
$salesInvoice->save();

// Print and email the invoice
$printedInvoice = new \Picqer\Financials\Exact\PrintedSalesInvoice($connection);
$printedInvoice->InvoiceID = $salesInvoice->InvoiceID;
$printedInvoice->SendEmailToCustomer = true;
$printedInvoice->SenderEmailAddress = "from@example.com";
$printedInvoice->DocumentLayout = "401f3020-35cd-49a2-843a-d904df0c09ff";
$printedInvoice->ExtraText = "Some additional text";
$printedInvoice->save();

Use generators to prevent memory overflow

This package allows you to interact with the Exact API using PHP generators. This may be useful when you're retrieving large sets of data that are too big to load into memory all at once., (*18)

$item = new \Picqer\Financials\Exact\Item($connection);
$item->getAsGenerator();
$item->filterAsGenerator('IsWebshopItem eq 1');

Connect to other Exact country than NL

Choose the right base URL according to Exact developers guide, (*19)

$connection = new \Picqer\Financials\Exact\Connection();
$connection->setRedirectUrl('CALLBACK_URL');
$connection->setExactClientId('CLIENT_ID');
$connection->setExactClientSecret('CLIENT_SECRET');
$connection->setBaseUrl('https://start.exactonline.de');

Check src/Picqer/Financials/Exact for all available entities., (*20)

Webhooks

Managaging webhook subscriptions is possible through the WebhookSubscription entitiy., (*21)

For authenticating incoming webhook calls you can use the Authenticatable trait. Supply the authenticate method with the full JSON request and your Webhook secret supplied by Exact, it will return true or false., (*22)

Troubleshooting

'Picqer\Financials\Exact\ApiException' with message 'Error 400: Please add a $select or a $top=1 statement to the query string.', (*23)

In specific instances, sadly not documented in the API documentation of Exact this is a requirement. Probably to prevent overflooding requests. What you have to do when encountering this error is adding a select or top. The select is used to provide a list of fields you want to extract, the $top=1 limits the results to one item., (*24)

Examples:, (*25)

Return only the EntryID and FinancialYear., (*26)

$test = new \Picqer\Financials\Exact\GeneralJournalEntry($connection);
var_dump($test->filter('', '', 'EntryID, FinancialYear'));

The $top=1 is added like this:, (*27)

$test = new \Picqer\Financials\Exact\GeneralJournalEntry($connection);
var_dump($test->filter('', '', '', ['$top'=> 1]));

Authentication error

'Fatal error: Uncaught Exception: Could not connect to Exact: Client error:POST https://start.exactonline.nl/api/oauth2/token resulted in a 400 Bad Request response: Bad Request in /var/www/html/oauth_call_connect.php:61 Stack trace: #0 {main} thrown in /var/www/html/oauth_call_connect.php on line 61`', (*28)

This error occurs because the code you get in your redirect URL is only valid for one call. When you call the authentication-process again with a "used" code. You get this error. Make sure you use the provided code by Exact Online only once to get your access token., (*29)

Code example

See for example: example/example.php, (*30)

Guzzle versions

Guzzle 6 and 7 is supported starting from v3. For Guzzle 3 use v1., (*31)

TODO

  • Current entities do not contain all available properties. Feel free to submit a PR with added or extended entities if you require them. Use the userscript.js in greasemonkey or tampermonkey to generate entities consistently and completely.

The Versions

24/05 2018

dev-master

9999999-dev http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

The Development Requires

api php exact

24/05 2018

v3.14.0

3.14.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

The Development Requires

api php exact

17/05 2018

v3.13.0

3.13.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

The Development Requires

api php exact

21/02 2018

v3.12.1

3.12.1.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

The Development Requires

api php exact

12/02 2018

v3.12.0

3.12.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

The Development Requires

api php exact

18/01 2018

v3.11.0

3.11.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

The Development Requires

api php exact

11/01 2018

v3.10.0

3.10.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

The Development Requires

api php exact

08/11 2017

v3.9.0

3.9.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

The Development Requires

api php exact

06/10 2017

v3.8.0

3.8.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

The Development Requires

api php exact

22/09 2017

v3.7.2

3.7.2.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

16/08 2017

v3.7.1

3.7.1.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

10/08 2017

v3.7.0

3.7.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

12/06 2017

v3.6.0

3.6.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

06/06 2017

v3.5.0

3.5.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

22/05 2017

v3.4.0

3.4.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

06/05 2017

v3.3.0

3.3.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

31/03 2017

v3.2.0

3.2.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

30/12 2016

v3.1.0

3.1.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

24/10 2016

v3.0.0

3.0.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

25/07 2016

v2.15.0

2.15.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

20/07 2016

v2.14.0

2.14.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

07/06 2016

v2.13.0

2.13.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

23/05 2016

v2.12.1

2.12.1.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

11/05 2016

v2.12.0

2.12.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

14/03 2016

v2.11.0

2.11.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

04/03 2016

v2.10.0

2.10.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

15/02 2016

v2.9.1

2.9.1.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

08/02 2016

v2.9.0

2.9.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

04/02 2016

v2.8.0

2.8.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

02/02 2016

v2.7.0

2.7.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

25/01 2016

v2.6.1

2.6.1.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

19/01 2016

v2.6.0

2.6.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

18/01 2016

v2.5.0

2.5.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

31/12 2015

v2.4.0

2.4.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

25/12 2015

v2.3.0

2.3.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

14/12 2015

v2.2.0

2.2.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

09/11 2015

v2.1.3

2.1.3.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

09/11 2015

1.x-dev

1.9999999.9999999.9999999-dev http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

09/11 2015

v1.0.9

1.0.9.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

09/11 2015

v2.1.2

2.1.2.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

03/11 2015

v2.1.1

2.1.1.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

02/11 2015

v2.1.0

2.1.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

27/10 2015

v2.0.0

2.0.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

27/10 2015

v1.0.8

1.0.8.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

03/10 2015

v1.0.7

1.0.7.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

12/08 2015

v1.0.6

1.0.6.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

22/07 2015

v1.0.5

1.0.5.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

16/06 2015

v1.0.4

1.0.4.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

24/04 2015

v1.0.3

1.0.3.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

24/04 2015

v1.0.2

1.0.2.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

04/03 2015

v1.0.1

1.0.1.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact

04/11 2014

v1.0.0

1.0.0.0 http://github.com/picqer/exact-php-client

A PHP Client for the Exact API

  Sources   Download

MIT

The Requires

 

api php exact