Ruby client for the QuickBooks Online API version 3.
- Built on top of the excellent Faraday gem.
- JSON only support.
- Please don't ask about XML support. Intuit has stated that JSON is the primary data format for the QuickBooks API (v3 and beyond). This gem will specialize in JSON only. The
quickbooks-ruby
gem has fantastic support for those who favor XML.
- Please don't ask about XML support. Intuit has stated that JSON is the primary data format for the QuickBooks API (v3 and beyond). This gem will specialize in JSON only. The
- Features specs built directly against a QuickBooks Online Sandbox via the VCR gem.
- Robust error handling.
- Why qbo_api is a better choice than the quickbooks-ruby gem.
- Part 1: Learn how to spin up the example app.
- Part 2: Running the specs to aid you in understanding a QuickBooks API transaction.
- Part 3: Contributing to the gem.
Add this line to your application's Gemfile:
gem 'qbo_api'
And then execute:
$ bundle
Or install it yourself as:
$ gem install qbo_api
q = account.qbo_account # or wherever you are storing the OAuth creds
qbo_api = QboApi.new(token: q.token,
token_secret: q.secret,
realm_id: q.companyid,
consumer_key: '*****',
consumer_secret: '********')
- cd ~/<local dir>
- git clone git@github.com:minimul/qbo_api.git && cd qbo_api
- bundle
- bin/console
- QboApi.production = true
- qboapi = QboApi.new(token: "qyprd2uvCOdRq8xzoSSiiiiii",
token_secret:"g8wcyQEtwxxxxxxm",
realm_id: "12314xxxxxx7",
consumer_key: "qyprdwzcxxxxxxbIWsIMIy9PYI",
consumer_secret: "CyDN4wpxxxxxxxPMv7hDhmh4")
- qboapi.get :customer, 1
- By default this client runs against a QBO sandbox. To run against the production QBO API URL do:
QboApi.production = true
- Logging:
QboApi.log = true
- To change logging target from
$stdout
e.g.
QboApi.logger = Rails.logger
invoice = {
"Line": [
{
"Amount": 100.00,
"DetailType": "SalesItemLineDetail",
"SalesItemLineDetail": {
"ItemRef": {
"value": "1",
"name": "Services"
}
}
}
],
"CustomerRef": {
"value": "1"
}
}
response = qbo_api.create(:invoice, payload: invoice)
p response['Id'] # => 65
customer = {
DisplayName: 'Jack Doe',
PrimaryPhone: {
FreeFormNumber: "(415) 444-1234"
}
}
response = qbo_api.update(:customer, id: 60, payload: customer)
p response.fetch('PrimaryPhone').fetch('FreeFormNumber') # => "(415) 444-1234"
response = qbo_api.delete(:invoice, id: 145)
p response['status'] # => "Deleted"
name = qbo_api.esc "Amy's Bird Sanctuary"
response = qbo_api.query(%{SELECT * FROM Customer WHERE DisplayName = '#{name}'})
response = qbo_api.get(:customer, 5)
p response['DisplayName'] # => "Dukes Basketball Camp"
response = api.cdc(entities: 'estimate', changed_since: '2011-10-10T09:00:00-07:00')
# You can also send in a Time object e.g. changed_since: Time.now
expect(response['CDCResponse'].size).to eq 1
ids = response['CDCResponse'][0]['QueryResponse'][0]['Estimate'].collect{ |e| e['Id'] }
p ids
payload = {
"BatchItemRequest":
[
{
"bId": "bid1",
"operation": "create",
"Vendor": {
"DisplayName": "Smith Family Store"
}
}, {
"bId": "bid2",
"operation": "delete",
"Invoice": {
"Id": "129",
"SyncToken": "0"
}
}
]
}
response = api.batch(payload)
expect(response['BatchItemResponse'].size).to eq 2
expect(batch_response.detect{ |b| b["bId"] == "bid1" }["Vendor"]["DisplayName"]).to eq "Smith Family Store"
customer = { DisplayName: 'Weiskopf Consulting' }
begin
response = qbo_api.create(:customer, payload: customer)
rescue QboApi::BadRequest => e
if e.message =~ /Another customer already exists with this name/
# Query for Id using DisplayName
# Do an qbo_api.update instead
end
end
# retrieves all customers
qbo_api.all(:customers) do |c|
p "#{c['Id']} #{c['DisplayName']}"
end
# retrieves all vendors by groups of 5
qbo_api.all(:vendor, max: 5) do |v|
p v['DisplayName']
end
# retrieves all customers by groups of 2 using a custom select query
where = "WHERE Id IN ('5', '6', '7', '8', '9', '10')"
qbo_api.all(:customer, max: 2, select: "SELECT * FROM Customer #{where}") do |c|
p c['DisplayName']
end
p qbo_api.is_transaction_entity?(:invoice) # => true
# Plural is supported as well
p qbo_api.is_transaction_entity?(:invoices) # => true
p qbo_api.is_transaction_entity?(:customer) # => false
p qbo_api.is_name_list_entity?(:vendors) # => true
- Check out this tutorial and screencast on spinning up an example.
git clone git://github.com/minimul/qbo_api && cd qbo_api
bundle
- Create a
.env
file- If needed create an account at https://developer.intuit.com
- Click
Get started coding
- Create an app with both the
Accounting
&Payments
selected. - Go to the
Development
tab and copy and paste the consumer key and secret into the.env
file.
export QBO_API_CONSUMER_KEY=<Your QuickBooks apps consumer key>
export QBO_API_CONSUMER_SECRET=<Your QuickBooks apps consumer secret>
- Note: the
.env
file will be automatically loaded after you run the next step. - Start up the example app
ruby example/app.rb
- Goto
http://localhost:9393
- Use the
Connect to QuickBooks
button to connect to your QuickBooks sandbox, which you receive when signing up at https://developer.intuit.com. - After successfully connecting to your sandbox run:
http://localhost:9393/customer/5
- You should see "Dukes Basketball Camp" displayed
- Checkout
example/app.rb
to see what is going on under the hood.
- Check out this tutorial and screencast on handling a webhook request. Also checkout
example/app.rb
for the request handling code.
Bug reports and pull requests are welcome on GitHub at https://github.com/minimul/qbo_api.
- Check out this tutorial and screencast on running the specs
git clone git://github.com/minimul/qbo_api && cd qbo_api
bundle
- Create a
.env
file- If you are just running the specs then at minimum your
.env
needs to look like the following:
- If you are just running the specs then at minimum your
export QBO_API_CONSUMER_KEY=
export QBO_API_CONSUMER_SECRET=
export QBO_API_ACCESS_TOKEN=
export QBO_API_ACCESS_TOKEN_SECRET=
export QBO_API_COMPANY_ID=12345
bundle exec rspec spec/
- All specs that require interaction with the API must be recorded against your personal QuickBooks sandbox. More coming on how to create or modifying existing specs against your sandbox.
- Check out this tutorial and screencast on contributing to qbo_api.
Protip: Once your .env file is completely filled out you can use the console to play around in your sandbox
bin/console
>> require_relative 'spec/spec_helper'
>> VCR.configure { |c| c.allow_http_connections_when_no_cassette = true }
>> q = QboApi.new(creds.to_h)
>> q.get :customer, 1
The gem is available as open source under the terms of the MIT License.