Synchronous calls

The following topics describe how to call synchronous methods on the following types of APIs in theQuickBooks Online .NET SDK:

The .NET SDK can call the QuickBooks Online API with either synchronous or asynchronous methods. These methods enable apps to access QuickBooks Online resources such as Accounts, Customers, and Invoices.

The following steps describe how to call the APIs synchronously:

1. Reference the SDK Assemblies

Make sure the following assemblies have been referenced:

• Intuit.Ipp.Core
• Intuit.Ipp.Data
• Intuit.Ipp.DataService
• Intuit.Ipp.Diagnostics
• Intuit.Ipp.EntitlementService
• Intuit.Ipp.Exception
• Intuit.Ipp.GlobalTaxService
• Intuit.Ipp.OAuth2PlatformClient
• Intuit.Ipp.QueryFilter
• Intuit.Ipp.ReportService
• Intuit.Ipp.Retry
• Intuit.Ipp.Security
• Intuit.Ipp.Utility
• Intuit.Ipp.WebHooksService
• Newtonsoft.Json

Include the following using statements:

1
2
3
4

using Intuit.Ipp.Core;
using Intuit.Ipp.DataService;
using Intuit.Ipp.Data;
using Intuit.Ipp.Security;

2. Set up Configuration

The SDK allows you to define a custom configuration for features such as Retry and Logging in the application settings (Appsettings.json) file. If you have already defined custom settings or do not need to configure custom settings for your app, go to step 3.

a. Configure the request and response message formats. Configure the serialization and compression format of requests and responses. For more information, see Making calls with the RESTAPI. Include the following script to set the serialization format of requests and responses to Json/XML and their compression format to GZip:

3. Build the ServiceContext object

ServiceContext is a parameter for all calls to QuickBooks Online Data Services, Platform Services, and Reporting Services. When you call a Data Service resource to access QuickBooks Online data, the SDK first retrieves the available custom configuration settings to build the ServiceContext object. In the absence of custom settings, it uses the default values available within the SDK.

a. Create the OAuth2RequestValidator object. A valid OAuth2RequestValidator object ensures that the end-user has authorized your app to access QuickBooks Online data. For details on how to create an OAuth2RequestValidator object, see Authorization.

1

OAuth2RequestValidator reqValidator = new OAuth2RequestValidator(accessToken);

2. Create an instance of the ServiceContext class. The following code creates a ServiceContext object:

1

ServiceContext serviceContext = new ServiceContext(realmId, IntuitServicesType.QBO, oauthValidator);

4. Create the DataService object

Create an instance of DataService by passing the ServiceContext created in Step 3 as the argument:

1

DataService service = new DataService(context);

5. Create the Data Object

Data objects (entities) represent QuickBooks company data, such as invoices and customers. The following code shows how to create a Customer object:

1
2
3
4
5
6

Customer customer = new Customer();
//Mandatory Fields
customer.GivenName = "Mary";
customer.Title = "Ms.";
customer.MiddleName = "Jayne";
customer.FamilyName = "Cooper";

6. Call the Service

To perform a CRUD operation on QuickBooks Online data, call the appropriate method on the service. The following code snippets show how to perform CRUD operations by calling C# methods on the service:

1

Customer resultCustomer = service.Add(customer) as Customer;

This operation updates all writable properties of an existing entity. If a writable property is omitted in the request, that property’s value is set to NULL:

1

Customer resultCustomer = service.Update(customer) as Customer;

1

Customer resultCustomer = service.FindById(customer) as Customer;

To paginate through all of the objects of a specific type in a given company, call the FindAll() method. Increment the startPosition parameter with each successive call. The maxResult parameter is the number of objects to fetch in each call. For example, the following code snippet gets the first ten accounts:

1
2
3

int startPosition = 1;
int maxResult = 10;
List<Customer> customers = service.FindAll(customer, startPosition, maxResult).ToList<Customer>();

1

Invoice resultInvoice =  service.Delete(invoice);

Name list entities, such as Customer and Vendor, cannot be deleted using the Delete() method. To delete a name list entity, set the Active flag to false, and use Update() to update the entity.

1

service.Void(customer);

Batch process is used to execute multiple operations (add, delete, update, and so forth) on multiple data objects (entities) in a single request. For more information, see Batch. To synchronously execute multiple operations, perform the steps described in the following example:

1. Build the ServiceContext object

ServiceContext is a parameter for all calls to QuickBooks Online Data Services, Platform Services, and Reporting Services. When you call a Data Service API to access QuickBooks Online data, the SDK first retrieves the available custom configuration settings to build the ServiceContext object.

1. Create the OAuth2RequestValidator object. A valid OAuth2RequestValidator object ensures that the end-user has authorized your app to access QuickBooks Online data. The following code creates an OAuth2RequestValidator object:

1

OAuth2RequestValidator reqValidator = new OAuth2RequestValidator(accessToken);

2. Create an instance of the ServiceContext class. The following code creates a ServiceContext object:

1

ServiceContext serviceContext = new ServiceContext(realmId, IntuitServicesType.QBO, oauthValidator);

2. Create the Data Service

Create an instance of DataService by passing the ServiceContext as the argument:

1

DataService service = new DataService (context);

3. Create the Batch object

The following code snippet shows how to create a batch object. Individual operation elements will be added to the batch object in a later step:

1

Batch batch = service.CreateNewBatch();

4. Create the data object

Data objects (entities) represent QuickBooks company data, such as invoices and customers. The following code shows how to create the Customer and Invoice objects:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

Customer customer = new Customer();
//Mandatory fields
customer.GivenName = "Mary";
customer.Title = "Ms.";
customer.MiddleName = "Jayne";
customer.FamilyName = "Cooper";

Customer delcustomer = new Customer();
//Mandatory fields
customer.GivenName = "Dana";
customer.Title = "Ms.";
customer.MiddleName = "Jayne";
customer.FamilyName = "Cooper";

Invoice invoice = new Invoice();
//Mandatory fields
invoice.DocNumber = Guid.NewGuid().ToString("N").Substring(0, 10);
invoice.TxnDate = DateTime.Today.Date;
invoice.TxnDateSpecified = true;
invoice.CustomerRef = new ReferenceType() { type = objectNameEnumType.Customer, name = "Mary", Value = customers[0].Id,
typeSpecified = true };
invoice.ARAccountRef = new ReferenceType() { type = objectNameEnumType.Account, name = "Account Receivable",
Value = "QB:37", typeSpecified = true };
invoice.TxnTaxDetail = new TxnTaxDetail() { TotalTax = 0, CustomerTaxCodeRef = new ReferenceType()
{ Value = taxCodes[0].Id, type = objectNameEnumType.Customer, typeSpecified = true, name = taxCodes[0].Name } };
Line invLine = new Line();

invLine.Amount = 10000;
invLine.DetailType = LineDetailTypeEnum.DescriptionOnly;
invLine.AmountSpecified = true;
invLine.Description = "Desc Invoice";
invoice.Line = new Line[] { invLine };

5. Add request to the batch

Each operation element in the batch is called a batch item and is represented by a unique batch ID. The ID is referenced in the IntuitBatchResponse objects that are returned by the call to the service. The following code snippets show how to add the operation element to the batch object created in step 3:

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

//This code adds the Create request to the batch
batch.Add(customer, "bID1", OperationEnum.create);
batch.Add(invoice, "bID2", OperationEnum.create);

//This code adds the Update request to the batch
batch.Add(customer, "bID3", OperationEnum.update);

//This code adds the Delete request to the batch
batch.Add(delcustomer, "bID4", OperationEnum.delete);

//This code adds the Query request to the batch
batch.Add("select * from Customer", "bID5");

6. Execute the batch

Call the service using the Execute() method to obtain an IntuitBatchResponse object. Batch items are executed sequentially in the order specified in the request. In the following code sample, the first two occurrences of IntuitBatchResponse are for the create operation followed by update, delete, and query operations. The IntuitBatchResponse can return three different ResponseType objects:

• Entity: For operations such as create and update that return single entity responses.
• Entities: For operations such as FindAll() and queries that return multiple entity responses.
• Exceptions: For operations that return exceptions due to one or more batch items in error.

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

batch.Execute();

IntuitBatchResponse addCustomerResponse = batch["bID1"];
if (addCustomerResponse.ResponseType == ResponseType.Entity)
{
   Customer addedcustomer = addCustomerResponse.Entity as Customer;
}
IntuitBatchResponse addInvoiceResponse = batch["bID2"];
if (addInvoiceResponse.ResponseType == ResponseType.Entity)
{
   Invoice addedinvoice = addInvoiceResponse.Entity as Invoice;
}
IntuitBatchResponse updateCustomerResponse = batch["bID3"];
if (updateCustomerResponse.ResponseType == ResponseType.Entity)
{
   Customer updatedcustomer = updateCustomerResponse.Entity as Customer;
}
IntuitBatchResponse deleteCustomerResponse = batch["bID4"];
if (deleteCustomerResponse.ResponseType == ResponseType.Entity)
{
   Customer deletedcustomer = deleteCustomerResponse.Entity as Customer;
}
IntuitBatchResponse queryCustomerResponse = batch["bID5"];
if (queryCustomerResponse.ResponseType == ResponseType.Query)
{
   List<Customer> customers = queryCustomerResponse.Entities.ToList().ConvertAll(item => item as Customer);
}

Each IntuitBatchItemResponse object is assigned to a batch request object identified by the unique batch ID that was assigned by the app to the batch item. If a fault occurs for a specific batch item, the IntuitBatchResponse returns an exception as the ResponseType.