h1. Xero API wrapper

h2. Introduction

This library is designed to help ruby / rails 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.
<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. POST /api.xro/1.0/contact

Updates an existing contact record.
<pre><code>
    contact_retrieved_from_xero.email = "something_new@something.com"
	
	gateway.update_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
	gateway.get_invoices(1.month.ago) # modified since 1 month ago
</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).

Invoice and line item totals are calculated automatically.
<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
    })
    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,
      :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>

For more advanced (and cached) access to the accounts list, use the following.
<pre><code>
	accounts_list = gateway.get_accounts_list
	
	# Finds account with code of '200'
	sales_account = accounts_list.find_by_code(200)
	
	# Finds all EXPENSE accounts
	all_expense_accounts = accounts_list.find_all_by_type('EXPENSE') 
	
	# Finds all accounts with tax_type == 'OUTPUT'
	# For a list of valid tax types see XeroGateway::Account::TAX_TYPE
	all_output_tax_accounts = accounts_list.find_all_by_tax_type('OUTPUT')
</code></pre>


h3. GET /api.xro/1.0/tracking

Gets all tracking categories and their options for a specific organization in Xero.
<pre><code>
	gateway.get_tracking_categories
</code></pre>