Description
The quickbooks-ruby-base
gem complements the quickbooks-ruby
library by providing a base class to handle routine tasks like creating a model, service, and displaying information.
See the screencast for more details.
Installation
Add this line to your application's Gemfile:
gem 'quickbooks-ruby-base'
And then execute:
$ bundle
Or install it yourself as:
$ gem install quickbooks-ruby-base
Usage
- The first argument is required and is a persistent object holding Intuit OAuth information (see Configuration section).
- The second argument is optional but if passed must be a valid
quickbooks-ruby
service type such as Invoice, Customer, Item, PaymentMethod, etc. When passing in a symbol, snake case must be used e.g.:payment_method
. If a string you must use the explicit name, e.g. 'PaymentMethod'
def initialize(account, type = nil)
@account = account
create_service_for(type) if type
end
qr_model(*args)
Generate a quickbooks-ruby
model. First argument must be valid quickbooks-ruby
model.
>> base = Quickbooks::Base.new(account)
>> customer = base.qr_model(:customer)
# Accepts more than 1 argument e.g.
>> base = Quickbooks::Base.new(account)
>> qb_invoice = base.qr_model :invoice
>> qb_invoice.bill_email = base.qr_model(:email_address, invoice.customer.email)
service()
Returns quickbooks-ruby
service.
>> base = Quickbooks::Base.new(account, :customer)
>> base.service
=> #<Quickbooks::Service::Customer:0x007faf7fe3f130 @base_uri="https://qb.sbfinance.intuit.com/v3/company", .etc
>> customer = base.qr_model(:customer)
>> customer.display_name = 'Minimul X'
# Do a create
>> base.service.create(customer)
# Or an update
>> base.service.update(customer)
# Execute a query
>> base.service.query('SELECT * FROM INVOICES')
show(options = {})
Returns an array of the QuickBooks' IDs and a "smart" description. Smart, meaning that different services have different identifiers. For a customer, employee, and vendor the DESC
is display_name
. For invoice, it is doc_number
. For item, tax_code, and payment_method it is the name
.
base = Quickbooks::Base.new(account, :invoice)
# Returns an array of payment_methods from QBO account
base = Quickbooks::Base.new(account, :payment_method)
>> base.show
# Returns an array of payment_methods from QBO account
>> base.show
=> ["QBID: 5 DESC: American Express", "QBID: 1 DESC: Cash", "QBID: 2 DESC: Check", "QBID: 6 DESC: Diners Club", "QBID: 7 DESC: Discover", "QBID: 4 DESC: MasterCard", "QBID: 3 DESC: Visa"]
# With options
>> base.show page:1, per_page: 3
=> ["QBID: 5 DESC: American Express", "QBID: 1 DESC: Cash", "QBID: 2 DESC: Check"]
# Show another entity
>> base.show(entity: :vendor)
=> ["QBID: 5 DESC: Hampton's Car Parts", "QBID: 6 DESC: Good Eats", "QBID: 7 DESC: The Flower Shoppe"]
find_by_id()
Convenience method to fetch an entity by its reference id
base = Quickbooks::Base.new(account, :customer)
>> base.find_by_id(1)
# Second argument to find Employee with id = 55
>> base.find_by_id(55, :employee)
find_by_display_name()
Convenience method to search for a name entity by DisplayName. Note: Leverages proper escaping via the Quickbooks::Util::QueryBuilder module.
base = Quickbooks::Base.new(account, :customer)
>> base.find_by_display_name('Chuck Russell')
# Generates a query based on the following SQL
# "SELECT Id, DisplayName FROM Customer WHERE DisplayName = 'Chuck Russell'"
with options
base = Quickbooks::Base.new(account)
>> base.find_by_display_name("Jonnie O'Meara", entity: :vendor, select: '*')
# Generates a query based on the following SQL
# "SELECT * FROM Vendor WHERE DisplayName = 'Jonnie O\\'Meara'"
Configuration
As the first argument, the Quickbooks::Base
class expects a persistent object that holds OAuth connection information.
For example, if an account's OAuth2 information is stored like this:
account.qb_token
account.qb_refresh_token
account.qb_company_id
Your Quickbooks::Base
configuration would look like this.
QB_KEY = ENV['MINIMULCASTS_CONSUMER_KEY']
QB_SECRET = ENV['MINIMULCASTS_CONSUMER_SECRET']
$qb_oauth_consumer = OAuth::Consumer.new(QB_KEY, QB_SECRET, {
:site => "https://oauth.intuit.com",
:request_token_path => "/oauth/v1/get_request_token",
:authorize_url => "https://appcenter.intuit.com/Connect/Begin",
:access_token_path => "/oauth/v1/get_access_token"
})
Quickbooks::Base.configure do |c|
c.persistent_token = 'qb_token'
c.persistent_refresh_token = 'qb_refresh_token'
c.persistent_company_id = 'qb_company_id'
end
Configuration defaults
p Quickbooks::Base.persistent_token
# "settings.qb_token"
p Quickbooks::Base.persistent_secret
# "settings.qb_secret"
p Quickbooks::Base.persistent_company_id
# "settings.qb_company_id"
By default quickbooks-base-ruby
uses the $qb_oauth_consumer
global var but can be overridden e.g.:
$intuit_oauth_consumer = OAuth::Consumer.new(QB_KEY, QB_SECRET, {
:site => "https://oauth.intuit.com",
:request_token_path => "/oauth/v1/get_request_token",
:authorize_url => "https://appcenter.intuit.com/Connect/Begin",
:access_token_path => "/oauth/v1/get_access_token"
})
Quickbooks::Base.configure do |c|
c.oauth_consumer = $intuit_oauth_consumer
end
Contributing
- Fork it ( http://github.com//quickbooks-ruby-base/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Create a spec to test your feature.
- Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request