Quickbooks

This plugin allows for API integration with Quickbooks, and could be used as a driver for invoicing module. Driver name: quickbooks

Installation

To install this module:

composer require qore/quickbooks

php artisan vendor:publish --tag=qore.quickbooks.config
php artisan vendor:publish --tag=qore.quickbooks.frontend

Note: the publishable config file is mainly for invoicing integration, if you do not need this, you can ignore it.

Usage

Getting started

After you enable this plugin in the interface, you will be required to fill in Client ID, Client Secret and Redirect URL. Quickbook authentication will be done via oAuth2, so the steps below are required to set it up.

info

The information below assumes you have created an account and set up an app at Intuit.

Client ID & Client Secret

You can find the Client ID and Client Secret on the dashboard of one of your apps under Development Settings -> Keys & Credentials.

Redirect URL

This plugin exposes a few routes to make this step as easy as possible. Your redirect URL should be:

// For development:
http://localhost:8000/api/quickbooks/auth/development-redirect

// For production:
https://{production-domain}/api/quickbooks/auth/redirect

You should add your redirect URL both in Quickbooks, and in the plugin interface.

info

The reason why we have a different redirect URI for development is because Quickbooks does not allow 127.0.0.1. Our session exists on 127.0.0.1, so for it to work properly, development-redirect will do an internal redirect to 127.0.0.1.

If everything is set up correctly, you can save the settings.

Then after saving go to the plugin interface -> Sandbox -> and click on Enable API. It should redirect you a few times, and once you click on Sandbox again, it should show that you are connected.

info

After this installation, the refresh token will be updated automatically every time an API request is done when it is older than 20 minutes, so you do not have to do this manually.

API requests

You can start doing requests to Quickbooks by getting the DataService:

$dataService = (new QuickbooksClient())
    ->getDataService();

For example, to retrieve your company details:

$dataService = (new QuickbooksClient())
    ->getDataService();

$companyInfo = $dataService->getCompanyInfo();

Querying Quickbooks resources

Quickbooks supports a Mysql-like syntax to query its resources:

$dataService = (new QuickbooksClient())
    ->getDataService();

$customers = $dataService->Query('SELECT * FROM Customer');
$invoices = $dataService->Query('SELECT * FROM Invoice STARTPOSITION 1 MAXRESULTS 5');

More info can be found here.

Finding details for a Quickbook resource

You can find a specific resource by ID:

$dataService = (new QuickbooksClient())
    ->getDataService();

$invoice = $dataService->FindById('Invoice', 1)

Creating a Quickbooks resource

You can create a new resource like this:

use QuickBooksOnline\API\Data\IPPCustomer;
use QuickBooksOnline\API\Facades\Customer;

$dataService = (new QuickbooksClient())
    ->getDataService();

$object = Customer::create([
   'DisplayName' => 'Koen',
]);

$customer = $dataService->Add($object);

Updating a Quickbooks resource

You can update an existing resource like this:

use QuickBooksOnline\API\Data\IPPCustomer;
use QuickBooksOnline\API\Facades\Customer;

$dataService = (new QuickbooksClient())
    ->getDataService();
    
$existingCustomer = $dataService->FindById('Customer', 1);

$object = Customer::create([
   'DisplayName' => 'Koen',
   'FamilyName' => 'Baas'
]);

$dataService->Update(Customer::update($object, [
    'sparse' => true,
    'Id' => $existingCustomer->Id,
    'SyncToken' => $existingCustomer->SyncToken
]));

As you can see, we also provide sparse and SyncToken. A sparse update means that only the given data will be updated. So every field that is omitted, will not be touched. The SyncToken makes sure we're not editing the customer inside Quickbooks at the same time.

Invoice integration

This plugin publishes a quickbooks.php config file. You can override any class if needed.

• A booker is a class that will book an invoice (or credit memo) to quickbooks. This will create or update a customer as well.
• Hydrators are classes that provide the data necessary for updating/creating.
• Synchronisers are classes meant to be syncing data like invoice payments.

return [
    /**
     * Bookers that send data to quickbooks
     */
    'bookers' => [
        'invoice' => \Qore\Quickbooks\Accounting\InvoiceBooker::class
    ],

    /**
     * When Quickbooks models are being created/updated,
     * use the following hydrators
     */
    'hydrators' => [
        'invoice' => \Qore\Quickbooks\Hydrators\AccountingInvoiceHydrator::class,
        'credit_invoice' => \Qore\Quickbooks\Hydrators\AccountingCreditInvoiceHydrator::class,
        'customer' => \Qore\Quickbooks\Hydrators\AccountingCustomerHydrator::class
    ],

    /**
     * Synchronisation between Quickbooks and local Invoices
     */
    'synchronisers' => [
        'payments' => \Qore\Quickbooks\Accounting\PaymentsSyncer::class
    ]
];

Invoice payments synchronisation

This plugin exposes a command SyncQuickbooksPaymentsCommand::class to create local payments for invoices. By default, it only checks for invoices which are not concepts or paid. This command will call the payments synchroniser from the quickbooks.php config file.

php artisan quickbooks:sync_payments

Webhooks

There is by default no route that accepts webhook calls.

If you would like to use Quickbooks webhook functionality, make sure you add a route which is available through the api namespace/middleware. Webhooks will not work if you for example put routes inside web.php.

A note about Credit Invoices

Invoices can not have a negative amount inside Quickbooks. In order to book a credit invoice, you will need to create a CreditMemo.

CreditMemos can also not receive payments, unlike Invoices.

Upgrade Guide

To upgrade this module:

composer update qore/quickbooks

If you need to upgrade config:

php artisan vendor:publish --tag=qore.quickbooks.config --force