Java

The QuickBooks Online Java SDK makes it easier to integrate your Java web app with the QuickBooks Online API. This guide assumes that you have an existing web app that you want to integrate.

Tutorial objective

This tutorial demonstrates how to:

• Configure the QuickBooks Online Java SDK and required software
• Create an app on the Intuit Developer portal
• Connect to QuickBooks Online
• Make a request to the QuickBooks Online API

Prerequisites

To follow this tutorial, you need:

• Java Developer Kit (JDK) 7.0, or above, installed on your system.
• Your web app must use either Maven or Gradle package managers.
• Basic understanding of model-view-controller (MVC) architecture and the Spring Framework.

Configure the QuickBooks Java SDK

Maven

Gradle

Install Jars Manually

For a Maven project, add the following dependencies to the pom.xml file. Make sure to use the latest version of the SDK found here.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22

<!-- data jar --> <dependency> <groupId> com.intuit.quickbooks-online </groupId> <artifactId> ipp-v3-java-data </artifactId> <version> 6.0.7 </version> </dependency> <!-- devkit jar with dependencies--> <dependency> <groupId>com.intuit.quickbooks-online</groupId> <artifactId>ipp-v3-java-devkit</artifactId> <classifier>jar-with-dependencies</classifier> <version> 6.0.7 </version> </dependency> <!-- oauth jar with dependencies--> <dependency> <groupId>com.intuit.quickbooks-online</groupId> <artifactId>oauth2-platform-api</artifactId> <classifier>jar-with-dependencies</classifier> <version> 6.0.7 </version> </dependency>

For a Gradle project, add the following dependencies to the build.gradle file. For a Maven project, add the following dependencies to the pom.xml file. Make sure to use the latest version of the SDK found here.

1 2 3

compile("com.intuit.quickbooks-online:ipp-v3-java-data:6.0.7") compile (group: 'com.intuit.quickbooks-online', name: 'ipp-v3-java-devkit', version: '6.0.7', classifier: 'jar-with-dependencies') compile (group: 'com.intuit.quickbooks-online', name: 'oauth2-platform-api', version: '6.0.7', classifier: 'jar-with-dependencies')

While we recommend using a package manager to track the dependencies in your application, it is possible to download and use the Java SDK manually by downloading a pre-built jar file. Click the download button next to the latest version of the artifact to download.

• ipp-v3-java-data.jar
• ipp-v3-java-devkit.jar
• oauth2-platform-api.jar

Create an app on the Intuit Developer portal

To connect your application to a QuickBooks Online company, you need to create an app on the developer portal.

1. Sign into the developer portal. Select My Hub > App dashboard from the upper-right corner of the toolbar.

x

2. In your apps dashboard, select the app card with a +.

x

3. Select Get Started.

x

4. Enter a name for your app and select Next.

x

5. Select a scope, either Accounting or Payments, and select Done.

x

Note

Note

Creating a developer account also creates a QuickBooks Online test company (also referred to as a sandbox company). You can create up to 10 sandbox companies.

Connect to QuickBooks Online

To access the data of a QuickBooks Online company, a user must authorize your app through an authorization flow. At the end of the authorization flow an access token is generated, which is used to make QuickBooks Online API requests. To initiate the authorization flow, users of your app click on the Connect to QuickBooks button. The steps in this section go over how to build this button.

1. Development and Production keys can be found in the sidebar on the left. Select Keys and credentials.

x

2. Locate your client ID and client secret.

x

3. During the authorization flow, your app is redirected to Intuit’s OAuth server to get the authorization code after validating the user’s username and password. This authorization code is sent to the redirect URI. For this tutorial, redirect users to http://localhost:8080/oauth2redirect. Set the Redirect URI in Settings to this URL.

x

4. Configure the client ID, client secret, and redirect URI in your application’s property file.

1 2 3 4 5 6 7 8

#OAuth2 App Configuration OAuth2AppClientId=add your clientId OAuth2AppClientSecret=add your clientSecret OAuth2AppRedirectUri=http://localhost:8080/oauth2redirect #QBO API endpoint IntuitAccountingAPIHost=https://sandbox-quickbooks.api.intuit.com

5. To initiate the authorization flow, prepare the authorization URL by specifying the required parameters for the request, such as accounting scope, redirect URI, and state (a unique identifier or any other information that might be useful to your application). A code snippet is shown below. For the complete code, go here.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

public View connectToQuickBooks() { //initialize the config OAuth2Config oauth2Config = new OAuth2Config.OAuth2ConfigBuilder(clientId,clientSecret) .callDiscoveryAPI(Environment.SANDBOX) .buildConfig(); //generate csrf token String csrf = oauth2Config.generateCSRFToken(); //prepare scopes List<Scope> scopes = new ArrayList<Scope>(); scopes.add(Scope.Accounting); //prepare authorization url to intiate the oauth handshake return new RedirectView(oauth2Config.prepareUrl(scopes, redirectUri, csrf), true, true, false); }

The code above:

• Initializes the OAuth2Config object by providing the clientId and clientSecret and by specifying the environment (development or production) to make the API calls.
• Retrieves the discovery document. This is a resource that has information about the API-level properties such as an API description, resource schemas, authentication scopes, and method used to populate the URLs needed for the OAuth workflow.
• Gathers essential parameters needed for the request such as scope, redirect URI, and CSRF token (a unique identifier to your app) and prepares the authorization URL to initiate the OAuth workflow.

The above method uses the Spring Framework for controller mapping but can be modified to match any MVC framework used in your application.

6. The user goes through the authorization flow on this authorize endpoint:

x

After the user clicks the Connect button, the request is sent to an Intuit server.

• When successful, Intuit responds with an authorization code and QuickBooks Online Company ID (also called Realm ID) to the redirect URI you specified earlier, for example, http://localhost:8080/oauth2redirect.
• The temporary authorization code returned by Intuit’s OAuth service is exchanged to obtain the access_token and refresh_token using the Token endpoint.

The access_token is used in an API request and the refresh_token is used to get a fresh, short-lived access_token after it expires. Below is a code snippet. You can view complete code here.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

public String callBackFromOAuth() { //initialize the config OAuth2Config oauth2Config = new OAuth2Config.OAuth2ConfigBuilder(clientId,clientSecret) .callDiscoveryAPI(Environment.SANDBOX) .buildConfig(); //prepare OAuth2Platform client OAuth2PlatformClient client = new OAuth2PlatformClient(oauth2Config); //retrieve access token by calling the token endpoint BearerTokenResponse bearerTokenResponse = client.retrieveBearerTokens(authCode, redirectUri); return "connected"; }

Make a QuickBooks Online API request

Once the access_token is obtained, it can be used to make QuickBooks Online API calls. The example below shows how to make a call to the CompanyInfo endpoint. The example performing the following:

• Initializes DataService object by passing the realmId and accessToken.
• Calls the executeQuery method of the service class to get company information.
• Serializes the resulting companyInfo Java object into JSON.

The example data query can be modified to execute any QuickBooks Online API-supported query as a string in the sql parameter. You can view complete code here.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

public String callQBOCompanyInfo() { //get DataService DataService service = helper.getDataService(realmId, accessToken); // get all companyinfo String sql = "select * from companyinfo"; QueryResult queryResult = service.executeQuery(sql); CompanyInfo companyInfo = (CompanyInfo) queryResult.getEntities().get(0); // process response ObjectMapper mapper = new ObjectMapper(); return mapper.writeValueAsString(companyInfo); }