How to Use Xero API for Invoicing in Ruby on Rails

Mateusz Czerwiński

Jun 28, 2016 • 6 min read
Netguru-Biuro-2018-6984-1

Xero is a popular accounting software with API endpoints available for developers. Here I will show you how to create invoices using Xero API.

What You Will Use

  • www.xero.com, especially its APIs
  • One of two gems to communicate with Xero API:
  • Xero for Developers - documentation for developers which allows them to be more familiar with this solution
  • Description of Xero API
    • Private
      • Private applications use 2-legged OAuth and bypass the user authorisation workflow in the standard OAuth process. Private applications are linked to a single Xero organisation which is chosen when you register your application. Access tokens for private applications don’t expire unless the application is deleted or disconnected from within the Xero organisation.
    • Public
      • Public applications use the standard 3-legged OAuth process where a user can authorise your application to have access to their Xero organisation. Public applications can either be web-based or installed on desktop/mobile. Access tokens expire after 30 minutes.
    • Partner
      • Partner applications are public applications that have been upgraded to support long-term access tokens.

Xeroizer gem

Pros:

  • allows connecting with Private, Public and Partner APIs,
  • allows using the full functionality of API.

Cons:

  • requires SSL certificate (generated by OpenSSL).

Xero Gateway gem

Pros:

  • allows connecting with Private, Public and Partner APIs.

Cons:

  • not all methods are implemented.

Take a look at Xero Getting Started Guide where you can find useful information and a simple guide which allows you to go through an implementation process easily. We are going to use a Xero demo company example because it is a free solution and it's possible to reset it. You can also use the trial version of Xero.com. Here is a link which allows a developer to configure a Xero demo company app: https://developer.xero.com/documentation/getting-started/development-accounts/.

This blogpost might be useful for working with 2 and 3-legged OAuth: What is 2-legged OAuth

In this tutorial, we are going to use a private version of API. It requires generating certificates and is a bit simpler than other kinds of access to API.

Step 1

Create Xero demo app

Step 2

Create a private application (guide).
Please see a section titled Using OpenSSL. The key generation requires only these steps in your console:

openssl genrsa -out privatekey.pem 1024
openssl req -new -x509 -key privatekey.pem -out publickey.cer -days 1825
openssl pkcs12 -export -out public_privatekey.pfx -inkey privatekey.pem -in publickey.cer

Step 3

You will end up with three files:

  • privatekey.pem
  • public_privatekey.pfx
  • publickey.cer

Move them to app/certs in your application folder.

Step 4

Install the gem you prefer (I will show you examples for both of them below)

gem 'xeroizer'

or

gem 'xero_gateway'

and run bundle install.

Step 5

Retrieve Xero API credentials (guide) and place them in your secrets.yml

development:
secret_key_base:
xero_consumer_key:
xero_consumer_secret:
cert_path: 'app/certs/privatekey.pem'

Step 6: Example Request with Xeroizer

Here is a piece of code with allows a developer to connect with API and return the whole list with which it is rendered inside the view.

[code]

[code]

Step 7: Example Request with Xero Gateway

Here is a piece of code with allows a developer to connect with API and return the whole list with which it is rendered inside a view

[code]

[code]

Summary

The examples above are very simple and show a simple request along with the returned data transformation. The main logic of it is very straightforward and both gems can be used interchangeably.
Among these two gems, I recommend Xeroizer because it allows a developer to work with Xero API easily and has got a nice syntax to invoke different parts of it. Also, it maps every Xero API method into Ruby classes which could be manipulated easily with other things. It's worth to mention that xero_gateway is a wrapper for API.

Exceptions and Unexpected Situations

If you encounter any problems with API, you might be able to find an error at https://app.xero.com/Application/History where you can see the latest queries to API.

Related topics

More posts by this author

Mateusz Czerwiński

Codestories Newsletter