.NET

The QuickBooks Online .NET SDK makes it easier for .NET developers to create apps for the QuickBooks Online APIs. This page describes how to create your integration, including features you will most likely want in your app.
Tutorial Objective
The QuickBooks Online .NET SDK makes it easy 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 with QuickBooks Online.
Prerequisites
  1. You need the following installed on your machine:
  • Visual Studio 2017 or later
  • .NET Framework 4.6.1
  • IIS or IIS Express 8.0
  1. You should have basic knowledge of ASP.NET MVC Framework.
Install the SDK using NuGet

Note

Note

This step can be skipped 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 company, you need to create an app on the Intuit developer portal.
  1. Sign into the developer portal. From the menu at the top-right select My Apps.

View Screenshot

qbo/docs/develop/sdks-and-samples-collections/create-app-1-v1.png
  1. In the My Apps Dashboard create a new app by clicking the + Create an App button.

View Screenshot

qbo/docs/develop/sdks-and-samples-collections/create-app-2-v1.png
  1. Select QuickBooks Online and Payments.

View Screenshot

qbo/docs/develop/sdks-and-samples-collections/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

qbo/docs/develop/sdks-and-samples-collections/create-app-4-v1.png

Note

Note

Creating a developer account also creates a QuickBooks test company (also referred to as a sandbox company). You can create up to 5 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 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 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

qbo/docs/develop/sdks-and-samples-collections/create-app-5-v1.png
  1. Locate your Client ID and Client Secret.

View Screenshot

qbo/docs/develop/sdks-and-samples-collections/create-app-6-v1.png
  1. 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 the Keys & OAuth tab with this URL.

View Screenshot

qbo/docs/develop/sdks-and-samples-collections/create-app-7-v1.png
  1. Configure the client ID, client secret, app environment (sandbox 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>
  1. Instantiate 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);
}
  1. The authorizeUrl shows Intuit’s consent window meant for the QBO user to connect to the app.

View Screenshot

qbo/docs/develop/sdks-and-samples-collections/net_authorize.png

After they click the Connect 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) on the redirect URI.

1
2
3
4
5
public ActionResult Index()
{
  string code = Request.QueryString["code"] ?? "none";
  string realmId = Request.QueryString["realmId"] ?? "none";
}
  1. Use GetBearerTokenAsync method of 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
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";

    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);
}