Repository navigation
Examples
Technical documentation can be found in the code and the generated docs in the docs folder. If you have any questions or find a bug, please contact me on twitter (@sjorsvdp), email (sjors@youngguns.nl) or create a new issue.
Setting up
First, we need a connection with your Moneybird accout. You’re advised to create a new user for the API connection. Moneybird also supports oAuth (see below).
An autoloader is included if you need it:
<?php
spl_autoload_register('Moneybird\ApiConnector::autoload');
?>
To connect with Moneybird, we need to create the ApiConnector object:
<?php
// Create a Transport
$transport = new Moneybird\HttpClient();
$transport->setAuth(
$config['username'], // put your username here
$config['password'] // put your password here
);
$connector = new Moneybird\ApiConnector(
$config['clientname'], // put your client name here (<...>.moneybird.nl)
$transport,
new Moneybird\XmlMapper() // create a mapper
);
?>The basics – errors
If something goes wrong, an exception is thrown. When a NotValidException is thrown, detailed messages (if any) can be found by calling $connector→getErrors(). This returns an Error_Array(). The messages are in the exception message too.
<?php
$errors = $connector->getErrors();
foreach ($errors as $error) {
echo $error->attribute . ': ' . $error->message . '<br />';
}
?>The basics – services
To get, save or delete contacts, recurring templates, invoices, etc, you need to get their service first:
<?php
$contactService = $connector->getService('Contact');
$invoiceService = $connector->getService('Invoice');
?>The basics – getAll()
To get all contacts, simply call getAll() on the service:
<?php
$contacts = $contactService->getAll();
foreach ($contacts as $contact) {
echo $contact->name . '<br />';
}
?>Some services allow a filter for getAll().
<?php
// Get all invoices
$invoices = $invoiceService->getAll();
// Get all invoices draft invoices
// A list of available filters is defined in ApiConnector::$filters
$invoices = $invoiceService->getAll('draft);
// Get all invoices that match your saved advanced filter with id 12345
// Warning: if the filter is not found, all invoices will be returned!
$invoices = $invoiceService->getAll(12345);
// Get all late invoices of a contact
$invoices = $contact->getInvoices($invoiceService, 'late');
?>The basics – getById()
To get a contact by it’s id, use getById():
<?php
$contact = $contactService->getById(12345);
?>The basics – save()
To create a new contact pass an array to the constructor. The keys should match the property name you want to set. You don’t need to set all the fields, just the mandatory ones and the ones you want to set. Which fields are mandatory can be found on the Moneybird website and is stored in Contact::$_requiredAttr.
<?php
$contact = new Moneybird\Contact(array(
'companyName' => 'My Test company',
'attention' => 'Attention',
'contactName' => 'Contact name',
'address1' => 'Address line 1',
'address2' => 'Address line 2',
'zipcode' => '1111 AA',
'city' => 'City name',
'country' => 'Country name',
'bankAccount' => 'Bank account',
'chamberOfCommerce' => '1234567',
'email' => 'email@fake.fake',
'phone' => '073-1234567',
'sendMethod' => 'email',
'taxNumber' => 'NL12345678B01',
));
$contact->save($contactService);
// $contact is updated, so this will work
echo $contact->id; // Shows the contact id
?>The save method can be used for updating too.
<?php
$contact = $contactService->getById(123456);
$contact->setData(array( // Use setData() to change data
'firstname' => 'James'
));
$contact->save($contactService);
?>The basics – delete()
To delete a contact, call delete:
<?php
$contact = $contactService->getById(123456);
$contact->delete($contactService);
?>Syncing
Contacts and invoices have a revision number. If you store this revision number and the id of the contact in your local database, you’re ready to sync.
<?php
// Get the revision numbers of all contacts
$syncList = $contactService->getSyncList();
$updateIds = array();
foreach ($syncList as $sync) {
// Compare $sync with your local storage
// $sync->id contains the id of the contact or invoice
// $sync->revision contains the revision of the contact at Moneybird
if ($sync->revision > $localRevision) {
$updateIds[] = $sync->id;
}
}
// Get the contacts that need updating (max 100; break up requests if you need more)
$contacts = $contactService->getByIds($updateIds);
foreach ($contacts as $contact) {
// Update your local contact
}
?>Create and send your first invoice
To create an invoice, create the invoice details (lines) first. You can pass the $contact to the constructor of Invoice, or you can specify contactId in the data array.
<?php
define('TAXRATEID_HIGH', 12345);
$details = new Moneybird\Invoice_Detail_Array();
$details->append(new Moneybird\Invoice_Detail(array(
'amount' => 5,
'description' => 'My invoice line',
'price' => 20,
'taxRateId' => TAXRATEID_HIGH,
)));
$details->append(new Moneybird\Invoice_Detail(array(
'amount' => 1,
'description' => 'My second invoice line',
'price' => 12,
'taxRateId' => TAXRATEID_HIGH,
)));
$invoice = new Moneybird\Invoice(array(
'poNumber' => 'PO Number',
'details' => $details,
//'contactId' => 12345,
'lastname' => 'Custom lastname',
), $contact);
$invoice->save($invoiceService);
?><?php
$invoice->send($invoiceService, 'email', 'fake@fake.fake');
?>Register payments
<?php
$payment = new Moneybird\Invoice_Payment(array(
'paymentDate' => new DateTime(),
'paymentMethod' => 'bank_transfer',
'price' => 123.14,
'sendEmail' => false,
));
$invoice->registerPayment(
$invoiceService,
$payment
);
?>Get PDF documents
If you want to store the invoice PDF you can download it with getPdf()
<?php
file_put_contents('invoice.pdf', $invoice->getPdf());
?>Receiving push messages
If you ask nicely Moneybird can notify you when invoices change state. This is done by a post request to your website or application. To get the invoice from the request, use:
<?php
$invoice = $invoiceService->getByPushMessage();
?>oAuth
To use the library to connect through oAuth you need a token and token secret. See the oAuth website for information about oAuth. How oAuth works in Zend Framework (with good explanation) can be found here.
Using oAuth is just a matter of using another Transport.
<?php
$transport = new Moneybird\HttpClient_Oauth();
$consumer = new Moneybird\Lib\OAuthConsumer(
$config['oauth']['consumerKey'],
$config['oauth']['consumerSecret'],
NULL
);
$token = new Moneybird\Lib\OAuthConsumer(
$config['oauth']['token'],
$config['oauth']['tokenSecret']
);
$transport->setConsumerAndToken($consumer, $token);
$connector = new Moneybird\ApiConnector(
$config['clientname'], // put your client name here (<...>.moneybird.nl)
$transport,
new Moneybird\XmlMapper() // create a mapper
);
?>Requests limit
Moneybird limits the number of requests (350/h). You can find out how many requests you have left using Moneybird\ApiConnector::requestsLeft().
<?php
echo 'Requests left: ' . $connector->requestsLeft();
?>