Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Enables ruby / rails applications to communicate with the Xero API

branch: xero_gateway_1…

This branch is 1 commit ahead and 130 commits behind master

Fetching latest commit…

Cannot retrieve the latest commit at this time

README.textile

Xero API wrapper

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/

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.

Usage

    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)"
    )

Implemented interface methods

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

Gets a contact record for a specific Xero organisation

    result = gateway.get_contact_by_id(contact_id)
    contact = result.contact if result.success?

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

Gets a contact record for a specific Xero organisation

    gateway.get_contact_by_number(contact_number)

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

Gets all contact records for a particular Xero customer.

    gateway.get_contacts(:type => :all, :sort => :name, :direction => :desc)
    gateway.get_contacts(:type => :all, :updated_after => 1.month.ago) # modified since 1 month ago

PUT /api.xro/1.0/contact

Saves a contact record for a particular Xero customer.

    contact = gateway.build_contact
    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"
contact.save

POST /api.xro/1.0/contact

Updates an existing contact record.

    contact_retrieved_from_xero.email = "something_new@something.com"
    contact_retrieved_from_xero.save

POST /api.xro/1.0/contacts

Creates a list of contacts or updates them if they have a matching contact_id, contact_number or name.
This method uses only a single API request to create/update multiple contacts.

    contacts = [XeroGateway::Contact.new(:name => 'Joe Bloggs'), XeroGateway::Contact.new(:name => 'Jane Doe')]
    result = gateway.update_contacts(contacts)

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

Gets an invoice record for a specific Xero organisation

    gateway.get_invoice_by_id(invoice_id)

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

Gets an invoice record for a specific Xero organisation

    gateway.get_invoice_by_number(invoice_number)

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

Gets all invoice records for a particular Xero customer.

    gateway.get_invoices
    gateway.get_invoices(1.month.ago) # modified since 1 month ago

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.

    invoice = gateway.build_invoice({
      :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.name = "THE NAME OF THE CONTACT"
    invoice.contact.phone.number = "12345"
    invoice.contact.address.line_1 = "LINE 1 OF THE ADDRESS"    
    invoice.add_line_item({
      :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"
    })

invoice.create

PUT /api.xro/1.0/invoices

Inserts multiple invoices for a specific organization in Xero (currently only adding new invoices is allowed).
This method uses only a single API request to create/update multiple contacts.

    invoices = [XeroGateway::Invoice.new(...), XeroGateway::Invoice.new(...)]
    result = gateway.create_invoices(invoices)

GET /api.xro/1.0/accounts

Gets all accounts for a specific organization in Xero.

    gateway.get_accounts

For more advanced (and cached) access to the accounts list, use the following.

    accounts_list = gateway.get_accounts_list

Finds account with code of ‘200’

    sales_account = accounts_list.find_by_code(200)

Finds all EXPENSE accounts. For a list of valid account types see XeroGateway::Account::TYPE

   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')

GET /api.xro/1.0/tracking

Gets all tracking categories and their options for a specific organization in Xero.

    gateway.get_tracking_categories
Something went wrong with that request. Please try again.