Skip to content

Latest commit

 

History

History
164 lines (131 loc) · 5.98 KB

README.md

File metadata and controls

164 lines (131 loc) · 5.98 KB
Raw

xero-ruby

Xero Ruby SDK for OAuth 2.0 generated from Xero API OpenAPI Spec

RubyGem

Current release of SDK with OAuth 2.0 support

Xero Ruby SDK supports Xero's OAuth2.0 authentication (token generation & refresh) and supports the following Xero API sets.

Coming soon

  • bank feeds
  • payroll (AU))
  • payroll (NZ/UK)
  • files
  • projects
  • xero hq

Looking for OAuth 1.0a support?

Check out the Xeroizer gem (maintained by community)

Installation

This SDK is published as a gem on RubyGems as xero-ruby To install this gem to your current gemset, run:

gem install 'xero-ruby'

Or, add this to your gemfile:

gem 'xero-ruby'

Getting Started

  • Create a free Xero user account
  • Login to your Xero developer /myapps dashboard & create an API application and note your API app's credentials.

Creating a Client

Require the gem:

require 'xero-ruby'

Then create a client by passing in a named hash object credentials:.

client_id, client_secret, redirect_uri: Get this from your API application in /myapps dashboard. scopes: Include scopes as comma seperated list, https://developer.xero.com/documentation/oauth2/scopes ex: 'openid profile email accounting.transactions'

creds = {
  client_id: ENV['CLIENT_ID'],
  client_secret: ENV['CLIENT_SECRET'],
  redirect_uri: ENV['REDIRECT_URI'],
  scopes: ENV['SCOPES']
}
xero_client ||= XeroRuby::ApiClient.new(credentials: creds)

Authorization & Callback

All API requests require a valid access token to be set on the client. If this is the first time you are calling the Xero API on a users behalf you will need to generate an authorized token set, which will look something like this:

{
  "id_token": "xxx.yyy.zz",
  "access_token": "xxx.yyy.zzz",
  "expires_in": 1800,
  "token_type": "Bearer",
  "refresh_token": "xxxxxx",
  "scope": "email profile openid accounting.transactions offline_access"
}

To generate a valid token_set with this SDK from Xero, have your user follow the authorization url:

@authorization_url = xero_client.authorization_url
# https://login.xero.com/identity/connect/authorize?response_type=code&client_id=<xxx>&redirect_uri=<redirect_uri>&scope=<scopes>

The get_token_set_from_callback method will set the token_set on the client, however you can also initialize a client and set the token_set explicitely using set_token_set or refresh_token_set.

# /my-redirect-uri
token_set = xero_client.get_token_set_from_callback(params)

# this is where you will want to save the token set for future API usage..
# ex: user.update!(xero_token_set: token_set)

# if you already saved a token_set you don't need the user to authenticate via UI
# and can just set the token on the client by refreshing it.
xero_client.refresh_token_set(user.token_set)

Token & SDK Helpers

Token Sets contain information about your API connection, but most important are the access_token, refresh_token, and the expiry:

  • An access_token is valid 30 minutes and a refresh_token is valid for 60 days
@token_set = xero_client.refresh_token_set(user.token_set)

# TIP: the `updatedDateUtc` will show you the most recently authorized Tenant (AKA Organisation)
connections = xero_client.connections
[{
  "id" => "xxx-yyy-zzz",
  "tenantId" => "xxx-yyy-zzz",
  "tenantType" => "ORGANISATION",
  "tenantName" => "Demo Company (US)",
  "createdDateUtc" => "2019-11-01T20:08:03.0766400",
  "updatedDateUtc" => "2020-04-15T22:37:10.4943410"
}]

# disconnect an org from a user's connections. Pass the connection ['id'] not ['tenantId'].
remaining_connections = xero_client.disconnect(connections[0]['id'])

# set token_set
token_set = xero_client.set_token_set(user.token_set)

# access token_set
token_set = xero_client.token_set

API Usage

  require 'xero-ruby'

  # reference `Authorization & Callback` to first store a valid token_set on the `xero_client`
  xero_client.refresh_token_set(user.token_set)

  # Accounting API set (https://github.com/XeroAPI/xero-ruby/blob/master/accounting/lib/xero-ruby/api/accounting_api.rb)
  invoices = xero_client.accounting_api.get_invoices(user.active_tenant_id).invoices
  accounts = xero_client.accounting_api.get_accounts(user.active_tenant_id).accounts
  contacts = xero_client.accounting_api.get_contacts(user.active_tenant_id).contacts

  # Asset API set (https://github.com/XeroAPI/xero-ruby/blob/master/accounting/lib/xero-ruby/api/asset_api.rb)
  asset = {
    "assetName": "AssetName: #{rand(10000)}",
    "assetNumber": "Asset: #{rand(10000)}",
    "assetStatus": "DRAFT"
  }
  asset = xero_client.asset_api.create_asset(current_user.active_tenant_id, asset)

If you have use cases outside of these examples or this readmy, please let us know!

Sample App

The best resource to understanding how to best leverage this SDK is to clone down our Sample Rails application which showcases all the features of this project. The sample app can help you quickly understand how to:

https://github.com/XeroAPI/xero-ruby-oauth2-app

  • Complete the OAuth2.0 Authorization flow
  • Store token_sets against a user object in a DB
  • Storing info about active connections
  • Change the active tenant & make api calls to multiple orgs
  • Refreshing your token sets
  • Decoding your token_set items and strategy around how/when to refresh
  • Disconnecting a connection for a user

Additional Documentation for API Endpoints

APIS

Models