QuickBooks

The QuickBooks example solution showcases how to connect a Teneo solution with the QuickBooks REST API. The example flows in the solution demonstrate how user can be authenticated as well as how to retrieve, filter, create, update & delete invoices on QuickBooks.

QuickBooks long

Solution contents

QuickBooks integration

The solution contains a QuickBooks backend integration containing methods for authentication, retrieval of invoices, filtering invoices, create, update and delete invoices. Since the source code of the integration is embedded in the solution, it can be easily extended or used as a starting point for new methods.

Example flows

For each core method in the QuickBooks integration, the solution contains a corresponding example flow:

User asks to retrieve invoices by customer name
User asks to create a invoice
User asks to update a invoice
User asks to delete a invoice
User asks to filter invoices

Authentication flow

QuickBooks provides a support for OAuth authentication method that allow a Teneo bot to interact with QuickBooks on the user's behalf. This example solution contains flow to demonstrate OAuth2.0 based authentication approach.

Getting started

Prerequisites

These instructions assume you have a QuickBooks admin account. Alternatively, you can signup for a free user account on QuickBooks Online Simple Start plan. These instructions assume you have downloaded and imported the QuickBooks solution. See instructions below.

QuickBooks Base URL references

It has two different types of base URLs as below,

Production Base URL: https://quickbooks.api.intuit.com
Sandbox Base URL: https://sandbox-quickbooks.api.intuit.com
For OAuth2.0, the base URL is: https://oauth.platform.intuit.com

Manage sandbox environments

In order to perform various test operations in QuickBooks portal, it has come up with an exclusive US sandbox environments for developers with preloaded company datasets.

Access the Manage Sandboxes page.
When you click on + Add a sandbox company button, you will be presented with a choice of selecting from the two plan options.
Choose QuickBooks SKUs – QuickBooks Online Plus.
Click on the 'Company Name' of the sandbox you want to launch.
Click on Sales menu from left menu panel and click on Invoices.

QuickBooks API authentication steps (OAuth2.0)

QuickBooks API's use the industry-standard OAuth 2.0 protocol for authentication and authorization.This protocol delegates user authentication to the service that hosts the user account and authorizes third-party applications to access the user account. Each API request must include an OAuthToken to retrieve any resource from your QuickBooks portal.

Create an app

Creating an app generates your development keys. Use the app for yourself, your clients, or make it available to all QuickBooks users by listing it on the QuickBooks app store.
Sign into the developers portal. From the menu at the top-right select Dashboard.
In the Dashboard create a new app by clicking the + Create an App button, under 'Apps' tab.
Select 'QuickBooks Online and Payments'.
Give your app a 'Name' and select Accounting from the 'Select Scopes' drop down. Select the team that you want to create your App in. Then click 'Create App'. !!! Note: you need permission from the team admin to create apps for a team.
Development and Production keys can be found in the sidebar on the left. Under Development select 'Keys and OAuth'.
Locate your Client ID and Client Secret.

You need your 'Client ID' and 'Client Secret' in the next step to generate an OAuth2.0 access token.

Get an OAuth 2.0 access token

Your app needs an OAuth 2.0 Access Token to access QuickBooks Online data. The OAuth 2.0 playground is the easiest way to get your access token. If you’d like to learn about OAuth 2.0 in detail, see Authentication.

Below are set of OAuth scopes should be considered, while performing the step 'Get authorization code' in OAuth 2.0 playground

Accounting
Open ID
Profile
Email
Phone
Address

Getting Company Id

You can now find the company Id for your QuickBooks sandbox instance as given below,

Go to the developers portal.
Under Manage sandbox companies section, your sandbox company instance will be displayed in a table format.
In the table section, Column COMPANY NAME has Company ID with actual value.
Copy the 'Company ID' displayed on screen and store it securely.

Add credentials to your solution

The solution contains a global variables QuickBooks_sClientId, QuickBooks_sCompanyId, QuickBooks_sClientSecret and QuickBooks_sOauthRefreshToken in which various keys we have collected should be stored. We’re interested in our instance based Oauth keys. People may try to use their QuickBooks OAuth keys accordingly. The values of the global variables should be a type of String like this:

Variable Name	Example value	Description
QuickBooks_sClientId	'ABKojXXXXXXXXXXXXXXXe73ZZmkoEXXXXXXXXXXXvraXA'	Client id for Oauth2.0.
QuickBooks_sClientSecret	'VdcXXXXXXXXXXXXXxCLSXXXXXXXXXxSR'	Client secret for Oauth2.0.
QuickBooks_sOauthRefreshToken	'ABXXXXXXX856WAXXXXXXqIWVHUsyXXXXXXXXXXXXTE1ed'	Oauth2.0 refresh token.
QuickBooks_sCompanyId	'4620XXXXXXXX1456XXX'	Company id of a QuickBooks user.

To update the global variables, proceed as follows:

In a text editor, update each of above global variables by pasting in the values you have collected in the steps above.
In you QuickBooks solution, click the 'Solution' tab and select 'Globals' in the purple navigation bar.
Select the 'Variables' tab at the top, select the variables called QuickBooks_sClientId, QuickBooks_sClientSecret, QuickBooks_sOauthRefreshToken and QuickBooks_sCompanyId.
In the panel on the right, click 'Edit'. You can now update the value of the variable by pasting the updated string values.
When done, click 'Save All' in the top left corner.

Test in Try Out

Your solution is now ready. You can test this in Try Out by asking I want to login followed up with I want to retrieve invoices by customers. The Teneo bot would then start asking you to input for follow up questions and then answer should provide the invoices, which are raised for a customer on QuickBooks portal.

Example conversations

User: I want to retrieve invoices by customers
Bot: Please enter a customer full name.
User: test user
Bot: Below is a list of invoices for test user. 1004, 1005, 1007

User: Can I filter invoices
Bot: Please choose one of the following filters. Overdue transactions, Last 10 days transactions or Last 30 days transactions
User: Overdue transactions
Bot: Below is a list of invoices for a chosen filter. 1005, 1007

User: I want to create a invoice
Bot: Please enter a customer full name.
User: test user
Bot: Please choose one of the following line items. Services, Design or Installation
User: Services
Bot: Please enter a due amount. Note: Amount format should be 100.0, if a due amount is 100. The format ignores commas.
User: 101.11
Bot: New invoice 1015 has been created successfully!

User: Can I update my invoice
Bot: Please enter an invoice number.
User: 1015
Bot: Please choose one of the following fields. Customer name or Message on Invoice
User: Customer name
Bot: Please enter a customer full name.
User: test user 123
Bot: Customer name has been updated on a invoice 1015 successfully!

User: I want to delete a invoice
Bot: Please enter an invoice number.
User: 1015
Bot: Invoice 1015 has been deleted successfully!

For simplicity, the bot answers in this solution are text only. Depending on the channel, interactive cards can be added, for example to add buttons or allow the user to select items from a list.

More on authentication

QuickBooks offers OAuth authentication that developers can use to allow their users to authenticate with QuickBooks.

All the use case flows in QuickBooks solution uses OAuth2.0 protocol based access token to authenticate the requests to QuickBooks API. Every 60 minutes once, access token will get expired for security reasons by QuickBooks OAuth server. QuickBooks solution flows are having the capability to refresh the access tokens automatically upon expiry and hence API requests are deemed as valid and gets passed.

This authentication uses stored credentials from a global variable QuickBooks_sClientId, QuickBooks_sClientSecret, QuickBooks_sOauthRefreshToken, QuickBooks_sCompanyId to prepare an authentication with QuickBooks. QuickBooks_sOauthAccessToken authorization header value checks an access against QuickBooks instance URL stored on QuickBooks_sApiEndPointUrl and return a successful authentication.

The value will be auto assigned at run time in the global variable QuickBooks_sOauthAccessToken and this global variable can be used for subsequent requests that require authentication across flows in the QuickBooks solution. The global variable is used by the QuickBooks integration for the various REST requests.

This authentication flow can be used in production grade as it uses OAuth2.0 protocol in Teneo in a more secured way by using any industrial standard techniques.

The authentication mechanism for the OAuth2.0 authentication roughly looks like this:

QuickBooks - authorization flow diagram

For more details on QuickBooks and OAuth2.0 based authentication, see: Digging Deeper into OAuth2.0 in QuickBooks

Download

Download the solution here.
Import the solution into Teneo. For more details see: How to import solutions.