Java

Tutorial objective
The QuickBooks Online Java SDK makes it easy 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 with QuickBooks Online.

Prerequisites:

  • 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.

Create an app on the Intuit Developer portal
To connect your application to a QuickBooks company, you need to create an app on the developer portal.
  1. Sign into the developer portal. From the menu at the top-right select Dashboard.

View Screenshot

../../../../_images/create-app-1-v1.png
  1. In the My Apps Dashboard create a new app by clicking the + Create an App button.

View Screenshot

../../../../_images/create-app-2-v1.png
  1. Select QuickBooks Online and Payments.

View Screenshot

../../../../_images/create-app-3-v1.png
  1. Enter a name for your app, select a scope (choose from Accounting or Payments), select the countries you want to accept connections from, and click on Create App.

View Screenshot

../../../../_images/create-app-4-v1.png
Connect to QuickBooks Online
To get access to the data of a QuickBooks 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.
  1. Development and Production keys can be found in the sidebar on the left. Under Development select Keys and OAuth.

View Screenshot

../../../../_images/create-app-5-v1.png
  1. Locate your Client ID and Client Secret.

View Screenshot

../../../../_images/create-app-6-v1.png
  1. 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 the Keys & OAuth tab with this URL.

View Screenshot

../../../../_images/create-app-7-v1.png
  1. 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
  1. To initiate the authorization flow, prepare the authorization URL by specifying the required parameters for the request such as accounting scope, redirect URI, state (a unique identifier or any other information that might be useful to your application). A code snippet is shown here, refer here for full code.

 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 (sandbox 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.

  1. The user goes through the authorization flow on this authorize endpoint which looks like:

View Screenshot

../../../../_images/language_screenshot5.jpg

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

  • When successful, Intuit responds with an authorization code and QuickBooks 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; 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 method below illustrates how to make a call to the CompanyInfo endpoint, by 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 data query can be modified to execute any QuickBooks Online API supported query as a String in the sql parameter in the snippet below. 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);

}