search

mcohen01 / node-quickbooks

nodejs client for Intuit's Quickbooks API
332 stars 235 forks source link

readme

node-quickbooks

nodejs client for Intuit's QuickBooks API

Installation

npm install node-quickbooks

Documentation


var QuickBooks = require('node-quickbooks')

var qbo = new QuickBooks(consumerKey,
                         consumerSecret,
                         oauthToken,
                         false, // no token secret for oAuth 2.0
                         realmId,
                         false, // use the sandbox?
                         true, // enable debugging?
                         null, // set minorversion, or null for the latest version
                         '2.0', //oAuth version
                         refreshToken);

qbo.createAttachable({Note: 'My File'}, function(err, attachable) {
  if (err) console.log(err)
  else console.log(attachable.Id)
})

qbo.getBillPayment('42', function(err, billPayment) {
  console.log(billPayment)
})

qbo.updateCustomer({
  Id: '42',
  SyncToken: '1',
  sparse: true,
  PrimaryEmailAddr: {Address: 'customer@example.com'}
}, function(err, customer) {
  if (err) console.log(err)
  else console.log(customer)
})

qbo.deleteAttachable('42', function(err, attachable) {
  if (err) console.log(err)
  else console.log(attachable)
}))

qbo.findAccounts({
  AccountType: 'Expense',
  desc: 'MetaData.LastUpdatedTime',
  limit: 5,
  offset: 5
  }, function(err, accounts) {
  accounts.QueryResponse.Account.forEach(function(account) {
    console.log(account.Name)
  })
})

qbo.reportBalanceSheet({department: '1,4,7'}, function(err, balanceSheet) {
  console.log(balanceSheet)
})

qbo.upload(
  'contractor.jpg',
  'image/jpeg',
  fs.createReadStream('contractor.jpg'),
  'Invoice',
  40,
  function(err, data) {
    console.log(err)
    console.log(data)
  })

Query

Filters

All query functions take an optional first argument object which will be converted to a where clause by means of the keys and values of the object used as column names and parameter values of the where clause. For example, in order to issue a query with a simple where clause such as, select * from attachable where Note = 'My sample note field', the following code would be needed:

qbo.findAttachables({
  Note: 'My sample note field'
}, function(e, attachables) {
  console.log(attachables)
})

Alternatively, the object can be an array of objects, each specifying a field, value and operator (optional) keys. This allows you to build a more complex query using operators such as =, IN, <, >, <=, >=, or LIKE.

qbo.findTimeActivities([
  {field: 'TxnDate', value: '2014-12-01', operator: '>'},
  {field: 'TxnDate', value: '2014-12-03', operator: '<'},
  {field: 'limit', value: 5}
], function (e, timeActivities) {
  console.log(timeActivities)
})
Sorting

Basic ordering is achieved via the optional first argument object as well. Include asc or desc keys in the object whose values are the columns you wish to sort on. For example:

qbo.findAttachables({
  desc: 'MetaData.LastUpdatedTime'
}, function(e, attachables) {
  console.log(attachables)
})
Pagination

Pagination is achieved via the optional first argument object as well. Include limit and/or offset keys in the object whose values are the number of rows you wish to limit the result set to or from respectively. For example:

qbo.findAttachables({
  limit: 10,
  offset: 10
}, function(e, attachables) {
  console.log(attachables)
})

The default (and max) limit is 1000 records returned in a single request. Adding a boolean fetchAll parameter will return all available records, transparently issuing as many requests as necessary to fetch them. So in the first example below, if your Quickbooks business contains 5,000 customers, 5 http requests will be issued behind the scenes and finally your callback will be invoked with an array of those 5,000 customers passed to it.

qbo.findCustomers({
  fetchAll: true
}, function(e, customers) {
  console.log(customers)
})

qbo.findCustomers([
  {field: 'fetchAll', value: true},
  {field: 'FamilyName', value: 'S%', operator: 'LIKE'}
], function(e, customers) {
  console.log(customers)
})
Counts

Row counts rather than full result sets can be obtained by passing the count key in the optional first argument object with a boolean true value. For example:

qbo.findAttachables({
  count: true
}, function(e, attachables) {
  console.log(attachables)
})

Example App

The example directory contains a barebones Express application that demonstrates the OAuth workflow.

Setup

First navigate to the example directory and install the required dependencies from NPM

npm install

You will need to create an Intuit Developer account at https://developer.intuit.com and add your app's OAuth Consumer Key and Secret to app.js. Pay attention to which APIs (Payments, QuickBooks) you select during the application creation process, you will have to update example/views/intuit.ejs if you did not select both.

Running

Start the app

node app.js

Browse to http://localhost:3000/start and you will see a page containing only the Intuit Developer Javascript-rendered button. Clicking on this kicks off the OAuth exchange.

The Intuit Developer Javascript code calls back into the node application, which needs to invoke the OAuth Request Token URL at https://oauth.intuit.com/oauth/v1/get_request_token via a server-side http POST method. Note how the response from the http POST is parsed and the browser is redirected to the App Center URL at https://appcenter.intuit.com/Connect/Begin?oauth_token= with the oauth_token passed as a URL parameter. Note also how the oauth_token_secret needs to somehow be maintained across http requests, as it needs to be passed in the second server-side http POST to the Access Token URL at https://oauth.intuit.com/oauth/v1/get_access_token. This final step is invoked once the user has authenticated on Intuit's site and authorized the application, and then the user is redirected back to the node application at the callback URL specified as a parameter in the Request Token remote call, in the example app's case, http://localhost:3000/callback.

Configuration

The Intuit Developer Javascript code contained in intuit.ejs is configured with the grantUrl option set to "http://localhost:3000/requestToken". You will want to change this to an appropriate URL for your application, but you will need to write similar functionality to that contained in the '/requestToken' route configured in app.js, also taking care to configure your consumerKey and consumerSecret on lines 27-28 in app.js.

Running the tests

First you'll need to fill in the missing values in config.js. The consumerKey and consumerSecret you can get from the Intuit Developer portal, the token, tokenSecret, and realmId are easiest to obtain by running the example app, completing the OAuth workflow, and copying the values that are logged to the console. Once you've filled in the missing credentials in config.js you can simply run:

npm test

Public Api

QuickBooks(consumerKey, consumerSecret, oauth_token, oauth_token_secret, realmId, debug, minorVer, oAuthVer, refresh_token)

Arguments

Create

Read

Update

Delete

Query

Reports

SalesReceipt and Invoice PDFs

Purchase Order Email

Miscellaneous

createAccount(object, callback)

Creates the Account in QuickBooks

Arguments

createAttachable(object, callback)

Creates the Attachable in QuickBooks

Arguments

createBill(object, callback)

Creates the Bill in QuickBooks

Arguments

createBillPayment(object, callback)

Creates the BillPayment in QuickBooks

Arguments

createClass(object, callback)

Creates the Class in QuickBooks

Arguments

createCreditMemo(object, callback)

Creates the CreditMemo in QuickBooks

Arguments

createCustomer(object, callback)

Creates the Customer in QuickBooks

Arguments

createDepartment(object, callback)

Creates the Department in QuickBooks

Arguments

createDeposit(object, callback)

Creates the Deposit in QuickBooks

Arguments

createEmployee(object, callback)

Creates the Employee in QuickBooks

Arguments

createEstimate(object, callback)

Creates the Estimate in QuickBooks

Arguments

createInvoice(object, callback)

Creates the Invoice in QuickBooks

Arguments

createItem(object, callback)

Creates the Item in QuickBooks

Arguments

createJournalCode(object, callback)

Creates the JournalCode in QuickBooks

Arguments

createJournalEntry(object, callback)

Creates the JournalEntry in QuickBooks

Arguments

createPayment(object, callback)

Creates the Payment in QuickBooks

Arguments

createPaymentMethod(object, callback)

Creates the PaymentMethod in QuickBooks

Arguments

createPurchase(object, callback)

Creates the Purchase in QuickBooks

Arguments

createPurchaseOrder(object, callback)

Creates the PurchaseOrder in QuickBooks

Arguments

createRefundReceipt(object, callback)

Creates the RefundReceipt in QuickBooks

Arguments

createSalesReceipt(object, callback)

Creates the SalesReceipt in QuickBooks

Arguments

createTaxAgency(object, callback)

Creates the TaxAgency in QuickBooks

Arguments

createTaxService(object, callback)

Creates the TaxService in QuickBooks

Arguments

createTerm(object, callback)

Creates the Term in QuickBooks

Arguments

createTimeActivity(object, callback)

Creates the TimeActivity in QuickBooks

Arguments

createTransfer(object, callback)

Creates the Transfer in QuickBooks

Arguments

createVendor(object, callback)

Creates the Vendor in QuickBooks

Arguments

createVendorCredit(object, callback)

Creates the VendorCredit in QuickBooks

Arguments

getAccount(id, callback)

Retrieves the Account from QuickBooks

Arguments

getAttachable(id, callback)

Retrieves the Attachable from QuickBooks

Arguments

getBill(id, callback)

Retrieves the Bill from QuickBooks

Arguments

getBillPayment(id, callback)

Retrieves the BillPayment from QuickBooks

Arguments

getClass(id, callback)

Retrieves the Class from QuickBooks

Arguments

getCompanyInfo(id, callback)

Retrieves the CompanyInfo from QuickBooks

Arguments

getCreditMemo(id, callback)

Retrieves the CreditMemo from QuickBooks

Arguments

getCustomer(id, callback)

Retrieves the Customer from QuickBooks

Arguments

getDepartment(id, callback)

Retrieves the Department from QuickBooks

Arguments

getDeposit(id, callback)

Retrieves the Deposit from QuickBooks

Arguments

getEmployee(id, callback)

Retrieves the Employee from QuickBooks

Arguments

getEstimate(id, callback)

Retrieves the Estimate from QuickBooks

Arguments

getExchangeRate(options, callback)

Retrieves an ExchangeRate from QuickBooks

Arguments

getInvoice(id, callback)

Retrieves the Invoice from QuickBooks

Arguments

getItem(id, callback)

Retrieves the Item from QuickBooks

Arguments

getJournalCode(id, callback)

Retrieves the JournalCode from QuickBooks

Arguments

getJournalEntry(id, callback)

Retrieves the JournalEntry from QuickBooks

Arguments

getPayment(id, callback)

Retrieves the Payment from QuickBooks

Arguments

getPaymentMethod(id, callback)

Retrieves the PaymentMethod from QuickBooks

Arguments

getPreferences(callback)

Retrieves the Preferences from QuickBooks

Arguments

getPurchase(id, callback)

Retrieves the Purchase from QuickBooks

Arguments

getPurchaseOrder(id, callback)

Retrieves the PurchaseOrder from QuickBooks

Arguments

getRefundReceipt(id, callback)

Retrieves the RefundReceipt from QuickBooks

Arguments

getReports(id, callback)

Retrieves the Reports from QuickBooks

Arguments

getSalesReceipt(id, callback)

Retrieves the SalesReceipt from QuickBooks

Arguments

getTaxAgency(id, callback)

Retrieves the TaxAgency from QuickBooks

Arguments

getTaxCode(id, callback)

Retrieves the TaxCode from QuickBooks

Arguments

getTaxRate(id, callback)

Retrieves the TaxRate from QuickBooks

Arguments

getTerm(id, callback)

Retrieves the Term from QuickBooks

Arguments

getTimeActivity(id, callback)

Retrieves the TimeActivity from QuickBooks

Arguments

getTransfer(id, callback)

Retrieves the Transfer from QuickBooks

Arguments

getVendor(id, callback)

Retrieves the Vendor from QuickBooks

Arguments

getVendorCredit(id, callback)

Retrieves the VendorCredit from QuickBooks

Arguments

updateAccount(object, callback)

Updates QuickBooks version of Account

Arguments

updateAttachable(object, callback)

Updates QuickBooks version of Attachable

Arguments

updateBill(object, callback)

Updates QuickBooks version of Bill

Arguments

updateBillPayment(object, callback)

Updates QuickBooks version of BillPayment

Arguments

updateClass(object, callback)

Updates QuickBooks version of Class

Arguments

updateCompanyInfo(object, callback)

Updates QuickBooks version of CompanyInfo

Arguments

updateCreditMemo(object, callback)

Updates QuickBooks version of CreditMemo

Arguments

updateCustomer(object, callback)

Updates QuickBooks version of Customer

Arguments

updateDepartment(object, callback)

Updates QuickBooks version of Department

Arguments

updateDeposit(object, callback)

Updates QuickBooks version of Deposit

Arguments

updateEmployee(object, callback)

Updates QuickBooks version of Employee

Arguments

updateEstimate(object, callback)

Updates QuickBooks version of Estimate

Arguments

updateInvoice(object, callback)

Updates QuickBooks version of Invoice

Arguments

updateItem(object, callback)

Updates QuickBooks version of Item

Arguments

updateJournalCode(object, callback)

Updates QuickBooks version of JournalCode

Arguments

updateJournalEntry(object, callback)

Updates QuickBooks version of JournalEntry

Arguments

updatePayment(object, callback)

Updates QuickBooks version of Payment

Arguments

updatePaymentMethod(object, callback)

Updates QuickBooks version of PaymentMethod

Arguments

updatePreferences(object, callback)

Updates QuickBooks version of Preferences

Arguments

updatePurchase(object, callback)

Updates QuickBooks version of Purchase

Arguments

updatePurchaseOrder(object, callback)

Updates QuickBooks version of PurchaseOrder

Arguments

updateRefundReceipt(object, callback)

Updates QuickBooks version of RefundReceipt

Arguments

updateSalesReceipt(object, callback)

Updates QuickBooks version of SalesReceipt

Arguments

updateTaxAgency(object, callback)

Updates QuickBooks version of TaxAgency

Arguments

updateTaxCode(object, callback)

Updates QuickBooks version of TaxCode

Arguments

updateTaxRate(object, callback)

Updates QuickBooks version of TaxRate

Arguments

updateTerm(object, callback)

Updates QuickBooks version of Term

Arguments

updateTimeActivity(object, callback)

Updates QuickBooks version of TimeActivity

Arguments

updateTransfer(object, callback)

Updates QuickBooks version of Transfer

Arguments

updateVendor(object, callback)

Updates QuickBooks version of Vendor

Arguments

updateVendorCredit(object, callback)

Updates QuickBooks version of VendorCredit

Arguments

updateExchangeRate(object, callback)

Updates QuickBooks version of ExchangeRate

Arguments

deleteAttachable(idOrEntity, callback)

Deletes the Attachable from QuickBooks

Arguments

deleteBill(idOrEntity, callback)

Deletes the Bill from QuickBooks

Arguments

deleteBillPayment(idOrEntity, callback)

Deletes the BillPayment from QuickBooks

Arguments

deleteCreditMemo(idOrEntity, callback)

Deletes the CreditMemo from QuickBooks

Arguments

deleteDeposit(idOrEntity, callback)

Deletes the Deposit from QuickBooks

Arguments

deleteEstimate(idOrEntity, callback)

Deletes the Estimate from QuickBooks

Arguments

deleteInvoice(idOrEntity, callback)

Deletes the Invoice from QuickBooks

Arguments

deleteJournalCode(idOrEntity, callback)

Deletes the JournalCode from QuickBooks

Arguments

deleteJournalEntry(idOrEntity, callback)

Deletes the JournalEntry from QuickBooks

Arguments

deletePayment(idOrEntity, callback)

Deletes the Payment from QuickBooks

Arguments

deletePurchase(idOrEntity, callback)

Deletes the Purchase from QuickBooks

Arguments

deletePurchaseOrder(idOrEntity, callback)

Deletes the PurchaseOrder from QuickBooks

Arguments

deleteRefundReceipt(idOrEntity, callback)

Deletes the RefundReceipt from QuickBooks

Arguments

deleteSalesReceipt(idOrEntity, callback)

Deletes the SalesReceipt from QuickBooks

Arguments

deleteTimeActivity(idOrEntity, callback)

Deletes the TimeActivity from QuickBooks

Arguments

deleteTransfer(idOrEntity, callback)

Deletes the Transfer from QuickBooks

Arguments

deleteVendorCredit(idOrEntity, callback)

Deletes the VendorCredit from QuickBooks

Arguments

findAccounts(criteria, callback)

Finds all Accounts in QuickBooks, optionally matching the specified criteria

Arguments

findAttachables(criteria, callback)

Finds all Attachables in QuickBooks, optionally matching the specified criteria

Arguments

findBills(criteria, callback)

Finds all Bills in QuickBooks, optionally matching the specified criteria

Arguments

findBillPayments(criteria, callback)

Finds all BillPayments in QuickBooks, optionally matching the specified criteria

Arguments

findBudgets(criteria, callback)

Finds all Budgets in QuickBooks, optionally matching the specified criteria

Arguments

findClasses(criteria, callback)

Finds all Classs in QuickBooks, optionally matching the specified criteria

Arguments

findCompanyInfos(criteria, callback)

Finds all CompanyInfos in QuickBooks, optionally matching the specified criteria

Arguments

findCreditMemos(criteria, callback)

Finds all CreditMemos in QuickBooks, optionally matching the specified criteria

Arguments

findCustomers(criteria, callback)

Finds all Customers in QuickBooks, optionally matching the specified criteria

Arguments

findDepartments(criteria, callback)

Finds all Departments in QuickBooks, optionally matching the specified criteria

Arguments

findDeposits(criteria, callback)

Finds all Deposits in QuickBooks, optionally matching the specified criteria

Arguments

findEmployees(criteria, callback)

Finds all Employees in QuickBooks, optionally matching the specified criteria

Arguments

findEstimates(criteria, callback)

Finds all Estimates in QuickBooks, optionally matching the specified criteria

Arguments

findInvoices(criteria, callback)

Finds all Invoices in QuickBooks, optionally matching the specified criteria

Arguments

findItems(criteria, callback)

Finds all Items in QuickBooks, optionally matching the specified criteria

Arguments

findJournalCodes(criteria, callback)

Finds all JournalCodes in QuickBooks, optionally matching the specified criteria

Arguments

findJournalEntries(criteria, callback)

Finds all JournalEntrys in QuickBooks, optionally matching the specified criteria

Arguments

findPayments(criteria, callback)

Finds all Payments in QuickBooks, optionally matching the specified criteria

Arguments

findPaymentMethods(criteria, callback)

Finds all PaymentMethods in QuickBooks, optionally matching the specified criteria

Arguments

findPreferenceses(criteria, callback)

Finds all Preferencess in QuickBooks, optionally matching the specified criteria

Arguments

findPurchases(criteria, callback)

Finds all Purchases in QuickBooks, optionally matching the specified criteria

Arguments

findPurchaseOrders(criteria, callback)

Finds all PurchaseOrders in QuickBooks, optionally matching the specified criteria

Arguments

findRefundReceipts(criteria, callback)

Finds all RefundReceipts in QuickBooks, optionally matching the specified criteria

Arguments

findSalesReceipts(criteria, callback)

Finds all SalesReceipts in QuickBooks, optionally matching the specified criteria

Arguments

findTaxAgencies(criteria, callback)

Finds all TaxAgencys in QuickBooks, optionally matching the specified criteria

Arguments

findTaxCodes(criteria, callback)

Finds all TaxCodes in QuickBooks, optionally matching the specified criteria

Arguments

findTaxRates(criteria, callback)

Finds all TaxRates in QuickBooks, optionally matching the specified criteria

Arguments

findTerms(criteria, callback)

Finds all Terms in QuickBooks, optionally matching the specified criteria

Arguments

findTimeActivities(criteria, callback)

Finds all TimeActivitys in QuickBooks, optionally matching the specified criteria

Arguments

findVendors(criteria, callback)

Finds all Vendors in QuickBooks, optionally matching the specified criteria

Arguments

findVendorCredits(criteria, callback)

Finds all VendorCredits in QuickBooks, optionally matching the specified criteria

Arguments

findExchangeRates(criteria, callback)

Finds all ExchangeRates in QuickBooks, optionally matching the specified criteria

Arguments

reportBalanceSheet(options, callback)

Retrieves the BalanceSheet Report from QuickBooks

Arguments

reportProfitAndLoss(options, callback)

Retrieves the ProfitAndLoss Report from QuickBooks

Arguments

reportProfitAndLossDetail(options, callback)

Retrieves the ProfitAndLossDetail Report from QuickBooks

Arguments

reportTrialBalance(options, callback)

Retrieves the TrialBalance Report from QuickBooks

Arguments

reportCashFlow(options, callback)

Retrieves the CashFlow Report from QuickBooks

Arguments

reportInventoryValuationSummary(options, callback)

Retrieves the InventoryValuationSummary Report from QuickBooks

Arguments

reportCustomerSales(options, callback)

Retrieves the CustomerSales Report from QuickBooks

Arguments

reportItemSales(options, callback)

Retrieves the ItemSales Report from QuickBooks

Arguments

reportCustomerIncome(options, callback)

Retrieves the CustomerIncome Report from QuickBooks

Arguments

reportCustomerBalance(options, callback)

Retrieves the CustomerBalance Report from QuickBooks

Arguments

reportCustomerBalanceDetail(options, callback)

Retrieves the CustomerBalanceDetail Report from QuickBooks

Arguments

reportAgedReceivables(options, callback)

Retrieves the AgedReceivables Report from QuickBooks

Arguments

reportAgedReceivableDetail(options, callback)

Retrieves the AgedReceivableDetail Report from QuickBooks

Arguments

reportVendorBalance(options, callback)

Retrieves the VendorBalance Report from QuickBooks

Arguments

reportVendorBalanceDetail(options, callback)

Retrieves the VendorBalanceDetail Report from QuickBooks

Arguments

reportAgedPayables(options, callback)

Retrieves the AgedPayables Report from QuickBooks

Arguments

reportAgedPayableDetail(options, callback)

Retrieves the AgedPayableDetail Report from QuickBooks

Arguments

reportVendorExpenses(options, callback)

Retrieves the VendorExpenses Report from QuickBooks

Arguments

reportTransactionList(options, callback)

Retrieves the TransactionList Report from QuickBooks

Arguments

reportGeneralLedgerDetail(options, callback)

Retrieves the GeneralLedgerDetail Report from QuickBooks

Arguments

reportDepartmentSales(options, callback)

Retrieves the DepartmentSales Report from QuickBooks

Arguments

reportClassSales(options, callback)

Retrieves the ClassSales Report from QuickBooks

Arguments

getInvoicePdf(id, callback)

Retrieves the Invoice PDF from QuickBooks

Arguments

getCreditMemoPdf(id, callback)

Retrieves the Credit Memo PDF from QuickBooks

Arguments

getSalesReceiptPdf(id, callback)

Retrieves the SalesReceipt PDF from QuickBooks

Arguments

sendInvoicePdf(id, sendTo, callback)

Emails the Invoice PDF from QuickBooks to the address supplied in Invoice.BillEmail.EmailAddress or the specified 'sendTo' address

Arguments

sendCreditMemoPdf(id, sendTo, callback)

Emails the Credit Memo PDF from QuickBooks to the address supplied in CreditMemo.BillEmail.EmailAddress or the specified 'sendTo' address

Arguments

sendEstimatePdf(id, sendTo, callback)

Emails the Estimate PDF from QuickBooks to the address supplied in Estimate.BillEmail.EmailAddress or the specified 'sendTo' address

Arguments

sendSalesReceiptPdf(id, sendTo, callback)

Emails the SalesReceipt PDF from QuickBooks to the address supplied in SalesReceipt.BillEmail.EmailAddress or the specified 'sendTo' address

Arguments

sendPurchaseOrder(id, sendTo, callback)

Emails the Purchase Order from QuickBooks to the address supplied in PurchaseOrder.POEmail.Address or the specified 'sendTo' address

Arguments

batch(items, callback)

Batch operation to enable an application to perform multiple operations in a single request. The following batch items are supported:

Arguments

changeDataCapture(entities, since, callback)

The change data capture (CDC) operation returns a list of entities that have changed since a specified time.

Arguments

upload(filename, contentType, stream, entityType, entityId, callback)

Uploads a file as an Attachable in QBO, optionally linking it to the specified QBO Entity.

Arguments