Configuration

This page provides a introduction on how to configure necessary settings for QuickBooks V3 SDK before making actual API call.

On QuickBooks V3 SDK, all API requests are made through DataService Object. It is equivalent to “Client” in other library.

Creating DataService

Depends on your authorization protocol, OAuth 1.0 or OAuth 2.0, you will need to pass corresponding OAuth values to your DataService Object. For OAuth 2, if you already know your access token and refresh token, you can use:

use QuickBooksOnline\API\DataService\DataService;


// Prep Data Services
$dataService = DataService::Configure(array(
      'auth_mode' => 'oauth2',
      'ClientID' => "Client ID from the app's keys tab",
      'ClientSecret' => "Client Secret from the app's keys tab",
      'RedirectURI' => "The redirect URI provided on the Redirect URIs part under keys tab",
      'scope' => "com.intuit.quickbooks.accounting or com.intuit.quickbooks.payment",
      'baseUrl' => "Development/Production"
));

to initialize your DataService object. For passing OAuth 1 value, or how to generate OAuth 2 tokens from beginning, refer to the OAuth 1.0a page, or Generate OAuth 2.0 Tokens page.

The DataService configure method accepts an associative array of options:

auth_mode

(String, required for all cases) OAuth protocol used by your app. It is either ‘oauth2’ or ‘oauth1’, case insensitive.

ClientID

(String, required for OAuth 2) Used when the ‘auth_mode’ is equal to ‘oauth2’. The client ID found from your app’s keys tab.

ClientSecret

(String, required for OAuth 2) Used when the ‘auth_mode’ is equal to ‘oauth2’. The client Secret found from your app’s keys tab.

accessTokenKey

(String) Used when the ‘auth_mode’ is equal to ‘oauth2’. The access token value received from QuickBooks Online by exchanging authorization code. Required if DataService is making API calls directly.

refreshTokenKey

(String) Used when the ‘auth_mode’ is equal to ‘oauth2’. The refresh token value received from QuickBooks Online by exchanging authorization code. Required if requesting for a new access token.

consumerKey

(String, required for OAuth 1) Used when the ‘auth_mode’ is equal to ‘oauth1’. The consumer key found from your app’s keys tab.

consumerSecret

(String, required for OAuth 1) Used when the ‘auth_mode’ is equal to ‘oauth1’. The consumer secret found from your app’s keys tab.

accessTokenKey

(String) Used when the ‘auth_mode’ is equal to ‘oauth1’. The oauth_token value returned from QuickBooks Online during the last step of OAuth 1.

accessTokenSecret

(String) Used when the ‘auth_mode’ is equal to ‘oauth1’. The oauth_token_secret value returned from QuickBooks Online during the last step of OAuth 1.

QBORealmID

(String) The Company ID that the API request is called against to, it is returned during OAuth 1&2 protocol with authorization code. Required when making API call with your OAuth 1&2 tokens.

baseUrl

(String) Identify the base URL the request is making. It is either “Development” or “Production”. You can also use the full url “https://sandbox-quickbooks.api.intuit.com” for sandbox, or “https://quickbooks.api.intuit.com” for production. Required when QBORealmID is used.

RedirectURI

(String) Used when the ‘auth_mode’ is equal to ‘oauth2’. The redirect URI provided on the Redirect URIs part under keys tab. Required for OAuth 2 when generating OAuth 2 token

scope

(String) Used when the ‘auth_mode’ is equal to ‘oauth2’. It is either “com.intuit.quickbooks.accounting” or “com.intuit.quickbooks.payment” , required for OAuth 2 when RedirectURI is used.

Note

For directly using OAuth 1&2 values, you can also put your values from file, and configure the dataService directly from file:

$dataService = DataService::Configure(“/Your/Path/To/sdk.config”);

However, this is only suggested for OAuth 1.0 tokens, since it is relatively long-lived tokens. For OAuth 2.0, this is not recommended. See the sdk.config file located in /src folder as a template for configuring DataService.

Setting DataService

DataService provides a list of methods to help you use QuickBooks Online API.

Minor version

You can use setMinorVersion() to specify which minor version you want to use against QuickBooks Online API. If developer didn’t specify a minor version, the default minor version, 8 , would be used.

$dataService->setMinorVersion("9");

Logging

Logging is default to be turned ON QuickBooks V3 PHP SDK. You can use disableLog() to disable logging.

$dataService->disableLog();

If logging is enabled, QuickBooks will record all requests and responses to the default directory tmp/IdsLogs. To change the default log location, use setLogLocation() method:

$dataService->setLogLocation("/Your/Path/ForLog");

The logging function will only work if the specified directory exists, and is accessible. The requests/responses may contain sensitive company data, please be aware of the directory you used to store logs.

Errors and Timeouts

For whatever reason, the HTTP(s) requests to QuickBooks Online API may not always succeed. For QuickBooks V3 PHP SDK, any response with status code that is not 200 level will be considered as a failed request.

If a request failed, the DataService will record the error on its lastError object, and developer should always use $dataService->getLastError() to check what the error is before acting on the results of the method call.

$error = $dataService->getLastError();
if($error){
   ...
}

If no error occurred, the $dataService->getLastError() will return false.

Note

On version <4.0.1, the $dataService->getLastError() will return NULL on success instead of false.

Developers also can configure the API client to throw exceptions when request failed. However, if you do this, you will need to catch and handle the exception in code yourself.

To throw exceptions when a request failed, you will use throwExceptionOnError(true)

$dataService->throwExceptionOnError(true);

The default behavior for QuickBooks V3 PHP SDK is NOT thrown exception on error. If developers want this behavior, they need to turn it on.

ServiceContext

ServiceContext contains all the information associated with the DataService, like OAuth values, Log location, etc. It is often necessary to return the ServiceContext for various purpose. To get the ServiceContext associated with DataService object, you will use:

$dataService->getServiceContext()