kingscode / exact-php-client
A PHP Client for the Exact API
Requires
- php: >=5.5.0
- guzzlehttp/guzzle: ~6.0
Requires (Dev)
- phpunit/phpunit: ~4.0
- dev-master
- v3.8.04
- v3.8.03
- v3.8.02
- v3.8.01
- v3.8.0
- v3.7.2
- v3.7.1
- v3.7.0
- v3.6.0
- v3.5.0
- v3.4.0
- v3.3.0
- v3.2.0
- v3.1.0
- v3.0.0
- v2.15.0
- v2.14.0
- v2.13.0
- v2.12.1
- v2.12.0
- v2.11.0
- v2.10.0
- v2.9.1
- v2.9.0
- v2.8.0
- v2.7.0
- v2.6.1
- v2.6.0
- v2.5.0
- v2.4.0
- v2.3.0
- v2.2.0
- v2.1.3
- v2.1.2
- v2.1.1
- v2.1.0
- v2.0.0
- v1.x-dev
- v1.0.9
- v1.0.8
- v1.0.7
- v1.0.6
- v1.0.5
- v1.0.4
- v1.0.3
- v1.0.2
- v1.0.1
- v1.0.0
This package is auto-updated.
Last update: 2020-04-09 08:02:13 UTC
README
PHP client library to use the Exact Online API.
Note: For Guzzle 6 use v2, for Guzzle 3 use v1.
Composer install
Installing this Exact client for PHP can be done through Composer.
composer require picqer/exact-php-client
Usage
- Set up app at Exact App Center to retrieve credentials
- Authorize the integration from your app
- Parse callback and finish connection set up
- Use the library to do stuff
Steps 1 - 3 are only required once on set up.
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.
Authorize the integration from your app
The code below is an example authorize()
function.
$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.
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.
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.
$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());
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.
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 Account($connection); $account->AddressLine1 = $customer['address']; $account->AddressLine2 = $customer['address2']; $account->City = $customer['city']; $account->Code = $customer['customerid']; $account->Country = $customer['country']; $account->IsSales = 'true'; $account->Name = $customer['name']; $account->Postcode = $customer['zipcode']; $account->Status = 'C'; $account->save(); // Add a product in Exact $item = new Item($connection); $item->Code = $productcode; $item->CostPriceStandard = $costprice; $item->Description = $name; $item->IsSalesItem = true; $item->SalesVatCode = 'VH'; $item->save(); // Retrieve an item $item = new Item($connection); $item->find(ID); // List items $item = new Item($connection); $item->get(); // List items with filter (using a filter always returns a collection) $item = new Item($connection); $items = $item->filter("Code eq '$productcode'"); // Uses filters as described in Exact API docs (odata filters) // Create new invoice with invoice lines $items[] = [ 'Item' => $itemId, 'Quantity' => $orderproduct['amount'], 'UnitPrice' => $orderproduct['price'] ]; $salesInvoice = new SalesInvoice($this->connection()); $salesInvoice->InvoiceTo = $customer_code; $salesInvoice->OrderedBy = $customer_code; $salesInvoice->YourRef = $orderId; $salesInvoice->SalesInvoiceLines = $items;
Connect to other Exact country than NL
Choose the right base URL according to Exact developers guide
<?php $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.
Webhooks
Managaging webhook subscriptions is possible through the WebhookSubscription entitiy.
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.
Troubleshooting
'Picqer\Financials\Exact\ApiException' with message 'Error 400: Please add a $select or a $top=1 statement to the query string.'
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.
Examples:
Return only the EntryID and FinancialYear.
$test = new GeneralJournalEntry($connection); var_dump($test->filter('', '', 'EntryID, FinancialYear'));
The $top=1 is added like this:
$test = new 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`'
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.
Code example
See for example: example/example.php
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.