QuickBooks Integration — API Guide | Cloud Maven

Overview

This document describes the authentication flow and REST API endpoints used by the Cloud Maven QuickBooks Connector to integrate a Salesforce org with Intuit QuickBooks Online.

1. Authentication

The connector uses OAuth 2.0 Authorization Code Flow via a Cloud Maven middleware site. No tokens are ever held or persisted by the middleware — it acts purely as a redirect relay.

1.1 Authentication Flow (Step-by-Step)

Client Salesforce Org  →  Cloud Maven Middleware  →  QuickBooks (Intuit)

Step	Actor	Action
1	User	Opens the Connect to QuickBooks button in the Salesforce app, which loads `QBAuthVFPage`
2	`QBAuthController`	Builds the authorization URL pointing to the Cloud Maven middleware site and redirects the browser
3	Middleware (`QB_AuthVFPage` on Cloud Maven Business Org)	Constructs the Intuit OAuth URL and redirects the user to the QuickBooks login page
4	User	Logs in to QuickBooks and grants access
5	Intuit	Redirects back to the Cloud Maven middleware with `code` (auth code) and `realmId` (Company ID)
6	Middleware	Relays `authCode`, `realmId`, and `isRedirected=true` back to the client's `QBAuthVFPage`
7	`QBAuthController`	Exchanges the auth code for `access_token` + `refresh_token` via the Intuit token endpoint
8	`QBAuthController`	Calls the Company Info endpoint to retrieve company details
9	Salesforce	Stores tokens and company info in `Quickbooks_Credentials__c` and `Quickbooks_Company__c` records; fires `QB_Auth__e` platform event to notify the UI

1.2 Authorization URL Construction

The initial redirect URL built by QBAuthController follows this pattern:

https://cloudmaveninc.my.salesforce-sites.com/sms/QB_AuthVFPage
  ?stateURL={State_URL from Quickbooks_Credentials__c}
  &clientId={Client_ID or Sandbox_Client_ID}

Middleware Base URL: https://cloudmaveninc.my.salesforce-sites.com
Middleware Path: /sms
Page: QB_AuthVFPage

The clientId sent depends on the configured API instance:

Production → Client_ID__c

Sandbox → Sandbox_Client_ID__c

1.3 Token Exchange (Authorization Code → Access Token)

After the middleware relays the auth code back to the client org, QBAuthController calls WS_Quickbooks.getAccessToken(), which makes the following POST request:

Property	Value
Method	`POST`
URL	`https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer`
Authorization Header	`Basic Base64(clientId:clientSecret)`
Content-Type	`application/x-www-form-urlencoded`
Accept	`application/json`

Request Body:

grant_type=authorization_code
&code={authCode}
&redirect_uri=https://cloudmaveninc.my.salesforce-sites.com/sms/QB_AuthVFPage

Success Response (HTTP 200):

{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "bearer",
  "expires_in": 3600,
  "x_refresh_token_expires_in": 8726400
}

Both tokens are stored on the company's Quickbooks_Credentials__c record. The Refresh_Token_Last_Modified_Date__c is stamped with the current datetime.

1.4 Token Refresh

When the access token expires, WS_Quickbooks.refreshAccessToken() is called automatically. It uses the same token endpoint with a different grant type:

Property	Value
Method	`POST`
URL	`https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer`
Authorization Header	`Basic Base64(clientId:clientSecret)`
Content-Type	`application/x-www-form-urlencoded`

Request Body:

grant_type=refresh_token
&refresh_token={storedRefreshToken}

1.5 Callback / Redirect Handling

Once the browser is redirected back to the client's QBAuthVFPage with parameters, the controller validates inputs and handles both success and error cases:

Parameter	Description
`isRedirected`	`true` when returning from middleware
`authCode`	OAuth 2.0 authorization code (alphanumeric + dashes, max 256 chars)
`realmId`	QuickBooks Company ID (alphanumeric + dashes, max 256 chars)
`error`	Set by Intuit if the user denied access or an error occurred

On success, the VF page displays a confirmation message and auto-closes after 2.5 seconds. On failure, an error is displayed and a QB_Auth__e platform event is fired with Is_Success__c = false.

2. Base URLs

Environment	Base URL
Production	`https://quickbooks.api.intuit.com`
Sandbox	`https://sandbox-quickbooks.api.intuit.com`
OAuth Token Endpoint	`https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer`
Middleware (Cloud Maven)	`https://cloudmaveninc.my.salesforce-sites.com/sms`

The active instance (Production vs Sandbox) is controlled by the ApiInstance setting in Quickbooks_Common_Settings__c. Default: Production.

All QuickBooks API calls use Minor Version 75 (minorversion=75).

3. API Endpoints

All endpoints below are relative to the applicable Base URL. Path parameters use {0}, {1}, {2} notation as stored in the Quickbooks_Credentials__c custom setting.

Operation	Method	Endpoint Pattern	Path Parameters
Get Company Info	GET	`/v3/company/{0}/companyinfo/{0}`	`{0}` = `companyId` (realmId)
Query (SOQL-style)	GET	`/v3/company/{0}/query`	`{0}` = `companyId`
Create Account	POST	`/v3/company/{0}/account?minorversion={1}`	`{0}` = `companyId`, `{1}` = `minorVersion`
Create Customer	POST	`/v3/company/{0}/customer?minorversion={1}`	`{0}` = `companyId`, `{1}` = `minorVersion`
Create Vendor	POST	`/v3/company/{0}/vendor?minorversion={1}`	`{0}` = `companyId`, `{1}` = `minorVersion`
Create Invoice	POST	`/v3/company/{0}/invoice?minorversion={1}`	`{0}` = `companyId`, `{1}` = `minorVersion`
Create Sales Receipt	POST	`/v3/company/{0}/salesreceipt?minorversion={1}`	`{0}` = `companyId`, `{1}` = `minorVersion`
Get Invoice PDF	GET	`/v3/company/{0}/invoice/{1}/pdf?minorversion={2}`	`{0}` = `companyId`, `{1}` = `invoiceId`, `{2}` = `minorVersion`
Get Sales Receipt PDF	GET	`/v3/company/{0}/salesreceipt/{1}/pdf?minorversion={2}`	`{0}` = `companyId`, `{1}` = `salesReceiptId`, `{2}` = `minorVersion`
Create Product (Item)	POST	`/v3/company/{0}/item?minorversion={1}`	`{0}` = `companyId`, `{1}` = `minorVersion`
Update Product (Item)	POST	`/v3/company/{0}/item?include=donotupdateaccountontxns&minorversion={1}`	`{0}` = `companyId`, `{1}` = `minorVersion`
Create Journal Entry	POST	`/v3/company/{0}/journalentry?minorversion={1}`	`{0}` = `companyId`, `{1}` = `minorVersion`
Create Payment	POST	`/v3/company/{0}/payment?minorversion={1}`	`{0}` = `companyId`, `{1}` = `minorVersion`
Create Payment Method	POST	`/v3/company/{0}/paymentmethod?minorversion={1}`	`{0}` = `companyId`, `{1}` = `minorVersion`
Get Payment Receipt PDF	GET	`/v3/company/{0}/payment/{1}/pdf?minorversion={2}`	`{0}` = `companyId`, `{1}` = `paymentId`, `{2}` = `minorVersion`
Batch Operations	POST	`/v3/company/{0}/batch?minorversion={1}`	`{0}` = `companyId`, `{1}` = `minorVersion`
Preferences	GET	`/v3/company/{0}/preferences?minorversion={1}`	`{0}` = `companyId`, `{1}` = `minorVersion`

4. Request Headers (All API Calls)

Header	Value
`Authorization`	`Bearer {access_token}`
`Accept`	`application/json`
`Content-Type`	`application/json` (for POST)

5. Common Settings Reference

These values are seeded on package install via PostInstallScript into the Quickbooks_Common_Settings__c custom setting and can be changed post-install.

Setting Name	Default Value	Description
`ApiInstance`	`Production`	Toggles between `Production` and `Sandbox`
`BusinessOrg_Site`	`https://cloudmaveninc.my.salesforce-sites.com`	Cloud Maven middleware base URL
`BusinessOrg_Path`	`sms`	Path segment appended to middleware URL
`DefaultCompanyId`	(set post-auth)	QuickBooks realmId of the default company
`BatchSize`	`50`	Max records per batch sync operation
`GenerateInvoicePDF`	`true`	Auto-generate PDF on invoice creation
`GenerateSalesReceiptPDF`	`true`	Auto-generate PDF on sales receipt creation
`AutomateSendPaymentReceipt`	`false`	Auto-send payment receipts
`CMSupportEmailAddress`	`support@cloudmaveninc.com`	Support contact for error notifications

6. Security Notes

All authCode and realmId values received via callback are sanitized: HTML-escaped, Java-escaped, single-quote-escaped, and XML-escaped before use.
Only alphanumeric characters, dashes (-), and underscores (_) are accepted for authCode and realmId. Any other characters result in an immediate auth failure.
Client credentials (clientId, clientSecret) are stored in the encrypted Quickbooks_Credentials__c protected custom setting and are never logged or exposed in the UI.
The middleware never stores tokens — it relays only the authorization code and realmId back to the client org.