MYOB Api
MYOB Api is an interface for accessing MYOB's AccountRight Live API.
Installation
Add this line to your application's Gemfile:
gem 'myob-api'
And then execute:
$ bundle
Or install it yourself as:
$ gem install myob-api
Usage
OAuth Authentication
If you've already got an OAuth access token, feel free to skip to API Client Setup.
The MYOB API uses 3 legged OAuth2. If you don't want to roll your own, or use the OmniAuth strategy you can authenticate using the get_access_code_url and get_access_token methods that ghiculescu has provided like so:
class MYOBSessionController
def new
redirect_to myob_client.get_access_code_url
end
def create
@token = myob_client.get_access_token(params[:code])
@company_files = myob_client.company_file.all
# then show the user a view where they can log in to their company file
end
def myob_client
@myob_client ||= Myob::Api::Client.new({
:consumer => {
:key => YOUR_CONSUMER_KEY,
:secret => YOUR_CONSUMER_SECRET,
},
})
end
end
API Client Setup
Create an api_client:
api_client = Myob::Api::Client.new({
:consumer => {
:key => YOUR_CONSUMER_KEY,
:secret => YOUR_CONSUMER_SECRET,
},
:access_token => YOUR_OAUTH_ACCESS_TOKEN,
})
If you have a refresh token (the Myob API returns one by default) you can use that too:
api_client = Myob::Api::Client.new({
:consumer => {
:key => YOUR_CONSUMER_KEY,
:secret => YOUR_CONSUMER_SECRET,
},
:access_token => YOUR_OAUTH_ACCESS_TOKEN,
:refresh_token => YOUR_OAUTH_REFRESH_TOKEN,
})
Or if you know which Company File you want to access too:
api_client = Myob::Api::Client.new({
:consumer => {
:key => YOUR_CONSUMER_KEY,
:secret => YOUR_CONSUMER_SECRET,
},
:access_token => YOUR_OAUTH_ACCESS_TOKEN,
:refresh_token => YOUR_OAUTH_REFRESH_TOKEN,
:company_file => {
:name => COMPANY_FILE_NAME,
:username => COMPANY_FILE_USERNAME,
:password => COMPANY_FILE_PASSWORD,
},
})
If you provide a company file, the gem will attempt to connect to MYOB to get the base API subdomain to use for future requests (learn more).
API Methods
Company Files
Before using the majority of API methods you will need to have selected a Company File. If you've already selected one when creating the client, feel free to ignore this.
Return a list of company files:
api_client.company_file.all
Select a company file to work with
api_client.select_company_file({
:id => COMPANY_FILE_ID,
:username => COMPANY_FILE_USERNAME,
:password => COMPANY_FILE_PASSWORD,
})
Contacts
Return a list of all contacts
api_client.contact.all
Customers
Return a list of all customers (a subset of contacts)
api_client.customer.all
Employees
Return a list of all employees
api_client.employee.all
Invoices
Return a list of all invoices
api_client.invoice.all
Pagination
Basic pagination based on NextPageLink parameter returned via API
first_page = api_client.contact.all
second_page = api_client.contact.next_page if api_client.contact.next_page?
You can also get an array of all items (which may make several API calls in the background):
api_client.contact.all_items # note this returns an array, *not* a hash the way `api_client.contact.all` does - use it if you only need data, without metadata
Filtering
You can use oData filters:
api_client.employee.all(filter: "IsActive eq true")
See http://www.odata.org/documentation/odata-version-2-0/uri-conventions/ and http://developer.myob.com/api/accountright/api-overview/retrieving-data/ for information on oData filtering.
Fetching one entity
Return an entity with given UID:
contact = api_client.contact.find(contact_uid)
Creating an entity
To create a new entity, call #save on its model, passing through a hash that represents the entity. Refer to the MYOB API documentation for required fields.
api_client.employee.save({'FirstName' => 'John', 'LastName' => 'Smith', 'IsIndividual' => true})
Updating an entity
To update an existing entity, call #save on its model, passing through a hash you got from the API. This hash should include a UID parameter (which is included by default when you get the data).
user = api_client.employee.all["Items"].last
user['FirstName'] = 'New First Name'
api_client.employee.save(user)
Todo
- Expand API methods
- Refactor client factory architecture
- Tests
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create new Pull Request