.NET

The QuickBooks Online .NET SDK makes it easier to integrate your .NET 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:

Install the QuickBooks Online .NET 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:

Visual Studio 2017 or later

.NET Framework 4.6.1

IIS or IIS Express 8.0

A basic knowledge of ASP.NET MVC Framework

Install the SDK using NuGet

Note

Note

You can skip this step if you are running the Hello, World! sample app.
To install the IppDotNetSdkForQuickBooksApiV3 package, use the NuGet console in Visual Studio:
1
Install-Package IppDotNetSdkForQuickBooksApiV3
To verify installation of the .NET SDK, go to the Visual Studio Solution Explorer and note the Intuit.Ipp entries under References—for example, Intuit.Ipp.DataService.

Create an app on the Intuit Developer portal

Note

Note

Skip to the next section if you have already created an app in the developer portal.

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

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

x

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

x

Select Get Started.

x

Enter a name for your app and select Next.

x

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.

You will use your sandbox company in the following steps to become familiar with the authorization flow.

Connect to QuickBooks Online

To get access to 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 will click on the Connect to QuickBooks button. The steps in this section go over how to build this button.
Development and Production keys can be found in the sidebar on the left. Select Keys and credentials.

x

Locate your client ID and client secret.

x

During the authorization flow, your app is redirected to an Intuit 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, the redirect URI is http://localhost:27353/callback. Set the Redirect URI in Settings to this URL.

x

Configure the client ID, client secret, app environment (development or production) along with the redirect URI in the <appSettings> section of your Web.config file as shown here. To view a complete web.config file, go here.
1
2
3
4
5
6
<appSettings>
    <add key="clientid" value="Enter value here" />
    <add key="clientsecret" value="Enter value here" />
    <add key="redirectUrl" value="http://localhost:27353/callback" />
    <add key="appEnvironment" value="sandbox" />
</appSettings>
Instantiate the OAuth2Client object with clientId, clientsecret, redirectUrl and environment. Using this object, generate the authorization URL to get the OAuth2 authorization code by specifying required scopes. The following example shows how to generate the authorization URL. To see a complete code example, go here.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
//Instantiate OAuth2Client object with clientId, clientsecret, redirectUrl and environment
public static OAuth2Client auth2Client = new OAuth2Client(clientid, clientsecret, redirectUrl, environment);

//Generate authorize url to get the OAuth2 code
public ActionResult InitiateAuth(string submitButton)
{

    List<OidcScopes> scopes = new List<OidcScopes>();
    scopes.Add(OidcScopes.Accounting);
    string authorizeUrl = auth2Client.GetAuthorizationURL(scopes);
    return Redirect(authorizeUrl);
}
The authorizeUrl shows Intuit’s consent window meant for the QuickBooks Online user to connect to the app.
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) on the redirect URI.
1
2
3
4
5
public ActionResult Index()
{
    string code = Request.QueryString["code"] ?? "none";
    string realmId = Request.QueryString["realmId"] ?? "none";
}
Use the GetBearerTokenAsync method of the OAuth2Client class to get OAuth2 tokens and expiry details as shown below. For the complete code example, go here.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
private async Task GetAuthTokensAsync(string code, string realmId)
{

    var tokenResponse = await AppController.auth2Client.GetBearerTokenAsync(code);

    var access_token = tokenResponse.AccessToken;
    var access_token_expires_at = tokenResponse.AccessTokenExpiresIn;

    var refresh_token = tokenResponse.RefreshToken;
    var refresh_token_expires_at = tokenResponse.RefreshTokenExpiresIn;
}
Make a QuickBooks Online API request
Once the tokens are received, they can be used to make QuickBooks Online API calls. First, create a ServiceContext object. A ServiceContext object is created with an access token along with the realmId and works as a context for the API request. This ServiceContext object is then used in QueryService to query for CompanyInfo data. QueryService can be used to execute any QuickBooks Online API supported query as a string in the parameter as shown below. Go here for a complete example.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
public ActionResult ApiCallService()
{
    var principal = User as ClaimsPrincipal;
    OAuth2RequestValidator oauthValidator = new OAuth2RequestValidator(principal.FindFirst("access_token").Value);

    ServiceContext serviceContext = new ServiceContext(realmId, IntuitServicesType.QBO, oauthValidator);
    serviceContext.IppConfiguration.MinorVersion.Qbo = "23";
    serviceContext.IppConfiguration.BaseUrl.Qbo = "https://sandbox-quickbooks.api.intuit.com/"; //This is sandbox Url. Change to Prod Url if you are using production

    QueryService<CompanyInfo> querySvc = new QueryService<CompanyInfo>(serviceContext);
    CompanyInfo companyInfo = querySvc.ExecuteIdsQuery("SELECT * FROM CompanyInfo").FirstOrDefault();

    string output = JsonConvert.SerializeObject(companyInfo, new JsonSerializerSettings
    {
        NullValueHandling = NullValueHandling.Ignore
    });
    return View("ApiCallService", (object)output);
}

Important

Congratulations

You are now set to develop your app with QuickBooks Online.