h1. Xero API wrapper

h2. Introduction

This library is designed to help ruby based applications communicate with the publicly available API for Xero.  If you are unfamiliar with the API, you should first read the documentation, located here "http://blog.xero.com/developer/":http://blog.xero.com/developer/

h2. Prerequisites

To use the Xero API you must have a Xero API Key.  If you don't know what this is, and don't know how to get one, this library is probably not for you.

h2. Usage

<pre><code>    require 'xero_gateway'
    gateway = XeroGateway::Gateway.new(
      :customer_key => "THE_CUSTOMER_KEY_GENERATED_FOR_YOUR_APP",
      :api_key => "YOUR_XERO_API_KEY",
      :xero_url => "THE URL FOR THE XERO API (test or live)"
    )</code></pre>


h2. Implemented interface methods



h3. GET /api.xro/1.0/contact (get_contact_by_id)

Gets a contact record for a specific Xero organisation
<pre><code>
	result = gateway.get_contact_by_id(contact_id)
	contact = result.contact if result.success?
</code></pre>



h3. GET /api.xro/1.0/contact (get_contact_by_number)

Gets a contact record for a specific Xero organisation
<pre><code>
	gateway.get_contact_by_number(contact_number)
</code></pre>



h3. GET /api.xro/1.0/contacts (get_contacts)

Gets all contact records for a particular Xero customer.
<pre><code>
	gateway.get_contacts(:type => :all, :sort => :name, :direction => :desc)
</code></pre>



h3. PUT /api.xro/1.0/contact

Saves a contact record for a particular Xero customer. If the contact record does not exist (based on either ContactID or ContactNumber) then it’s created, otherwise it’s updated.
<pre><code>
    contact = XeroGateway::Contact.new
	contact.name = "The contacts name"
    contact.email = "whoever@something.com"
    contact.phone.number = "555 123 4567"
    contact.address.line_1 = "LINE 1 OF THE ADDRESS"
    contact.address.line_2 = "LINE 2 OF THE ADDRESS"
    contact.address.city = "WELLINGTON"
    contact.address.region = "WELLINGTON"
    contact.address.country = "NEW ZEALAND"
    contact.address.post_code = "6021"
	
	gateway.create_contact(contact)
</code></pre>



h3. GET /api.xro/1.0/invoice (get_invoice_by_id)

Gets an invoice record for a specific Xero organisation
<pre><code>
	gateway.get_invoice_by_id(invoice_id)
</code></pre>



h3. GET /api.xro/1.0/invoice (get_invoice_by_number)

Gets an invoice record for a specific Xero organisation
<pre><code>
	gateway.get_invoice_by_number(invoice_number)
</code></pre>



h3. GET /api.xro/1.0/invoices (get_invoices)

Gets all invoice records for a particular Xero customer.
<pre><code>
	gateway.get_invoices(modified_since = nil)
</code></pre>



h3. PUT /api.xro/1.0/invoice

Inserts an invoice for a specific organization in Xero. (Currently only adding new invoices is allowed).
<pre><code>
    invoice = XeroGateway::Invoice.new({
      :invoice_type => "ACCREC",
      :due_date => 1.month.from_now,
      :invoice_number => "YOUR INVOICE NUMBER",
      :reference => "YOUR REFERENCE (NOT NECESSARILY UNIQUE!)",
      :tax_inclusive => true,
      :includes_tax => false,
      :sub_total => 1000,
      :total_tax => 125,
      :total => 1250
    })
    invoice.contact = XeroGateway::Contact.new(:name => "THE NAME OF THE CONTACT")
    invoice.contact.phone.number = "12345"
    invoice.contact.address.line_1 = "LINE 1 OF THE ADDRESS"    
    invoice.line_items << XeroGateway::LineItem.new(
      :description => "THE DESCRIPTION OF THE LINE ITEM",
      :unit_amount => 1000,
      :tax_amount => 125,
      :line_amount => 1000,
      :tracking_category => "THE TRACKING CATEGORY FOR THE LINE ITEM",
      :tracking_option => "THE TRACKING OPTION FOR THE LINE ITEM"
    )
	
	gateway.create_invoice(invoice)
</code></pre>



h3. GET /api.xro/1.0/accounts

Gets all accounts for a specific organization in Xero.
<pre><code>
	gateway.get_accounts
</code></pre>