Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
minimal xero adapter for ruby
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.

tiny lib for xero

existing ruby xero libraires are crowded with models : Payroll, Contact, Invoice that map each xml structure available through api

But what if I dont care with Payroll or I have already one ... Will I have to build an XXX::Invoice with mine ?

Here is the minimal workflow for a POST request to xero :

  • send a http request, with xml in params (in body for PUT, ohnoes)
  • sign request with oauth
  • parse response

What this library does is the minimal wire, that is a functional api to GET|POST|PUT any xero call, with the following workflow

  • use your model to build proper xml
  • call xero-min
  • parse response to get data your app need

Library was built and tested for a private app



  • typhoeus, to configure uri, headers, body, params : any option is passed to request
  • nokogiri to parse xml response

Create a client

cli ='your_consumer_key', 'your_secret_key')

make it behave as a private app


Get some data

You will get a Nokogiri node for an xml content type, raw body for pdf, an exception for other returned mime types

  • You can scrap xml data thanks to Nokogiri and extract what you require, no more, no less
  • You can do what you want with pdf, pipe it or write to file ...

specifying what to get

The two following statements are equivalent

client.get! :invoices
client.get! ''

# => get all invoices, default content type is 'text/xml'

To get a particular invoice, the following statements are equivalent

client.get! ''
client.get! invoice: 'INV-0001'

# do not forget braces for first ar

To specify the accepted content type, use either

client.get! '', accept: 'application/json'
client.get! {invoice: 'INV-0001'}, accept: 'application/json'

extract [id, name] for each contact

doc = client.get! :contacts
doc.xpath('//Contact').map{|c| ['ContactID', 'Name'].map{|e| c.xpath("./#{e}").text}}

post! or put! some data

lib is raw : you have to post well-formed xml, as it is what xero understand

client.put! :contacts, body: xml! '', body: xml

What xml to post! or put! ?

XeroMin::Erb implements basic xml building

bill = {id: '4d73c0f91c94a2c47500000a', name: 'Billy', first_name: 'Bill', last_name: 'Kid', email: ''}
xml=erb.render contact: bill

and xml should be


see XeroMin::Erb source code for precisions, templates for example, documentation

Use anything else you feel more comfortable with


doc = client.get! :contacts

doc = ''

doc = client.get! "#{client.url_for(:contacts)}/#{}"

What is the return value from post! or get! ?

It is a Nokogiri node if post is success, extract what you need

invoice.ref = node.xpath('/Response/Invoices/Invoice/InvoiceNumber').first.content

Else, it raise a XeroMin::Problem with a message


use PUT to post data ... or use POST + params: {xml: xml} rather than body: xml with following patch :

Something went wrong with that request. Please try again.