Class: XeroGateway::Gateway

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Dates, Http
Defined in:
lib/xero_gateway/gateway.rb

Direct Known Subclasses

PartnerApp, PrivateApp

Constant Summary

Constants included from Http

Http::OPEN_TIMEOUT, Http::READ_TIMEOUT, Http::ROOT_CA_FILE

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Dates

included

Methods included from Http

#http_get, #http_post, #http_put

Constructor Details

#initialize(consumer_key, consumer_secret, options = {}) ⇒ Gateway

The consumer key and secret here correspond to those provided to you by Xero inside the API Previewer.



15
16
17
18
 
# File 'lib/xero_gateway/gateway.rb', line 15

def initialize(consumer_key, consumer_secret, options = {})
  @xero_url = options[:xero_url] || "https://api.xero.com/api.xro/2.0"
  @client   = OAuth.new(consumer_key, consumer_secret, options)
end

Instance Attribute Details

#client ⇒ Object

Returns the value of attribute client.



7
8
9
 
# File 'lib/xero_gateway/gateway.rb', line 7

def client
  @client
end

#logger ⇒ Object

Returns the value of attribute logger.



7
8
9
 
# File 'lib/xero_gateway/gateway.rb', line 7

def logger
  @logger
end

#xero_url ⇒ Object

Returns the value of attribute xero_url.



7
8
9
 
# File 'lib/xero_gateway/gateway.rb', line 7

def xero_url
  @xero_url
end

Instance Method Details

#build_contact(contact = {}) ⇒ Object

Factory method for building new Contact objects associated with this gateway.



59
60
61
62
63
64
65
 
# File 'lib/xero_gateway/gateway.rb', line 59

def build_contact(contact = {})
  case contact
    when Contact then   contact.gateway = self
    when Hash then      contact = Contact.new(contact.merge({:gateway => self}))
  end
  contact
end

#build_credit_note(credit_note = {}) ⇒ Object

Factory method for building new CreditNote objects associated with this gateway.



279
280
281
282
283
284
285
 
# File 'lib/xero_gateway/gateway.rb', line 279

def build_credit_note(credit_note = {})
  case credit_note
    when CreditNote then     credit_note.gateway = self
    when Hash then        credit_note = CreditNote.new(credit_note.merge(:gateway => self))
  end
  credit_note
end

#build_invoice(invoice = {}) ⇒ Object

Factory method for building new Invoice objects associated with this gateway.



166
167
168
169
170
171
172
 
# File 'lib/xero_gateway/gateway.rb', line 166

def build_invoice(invoice = {})
  case invoice
    when Invoice then     invoice.gateway = self
    when Hash then        invoice = Invoice.new(invoice.merge(:gateway => self))
  end
  invoice
end

#create_bank_transaction(bank_transaction) ⇒ Object

Creates a bank transaction in Xero based on a bank transaction object.

Bank transaction and line item totals are calculated automatically.

Usage :

bank_transaction = XeroGateway::BankTransaction.new({
  :type => "RECEIVE",
  :date => 1.month.from_now,
  :reference => "YOUR INVOICE NUMBER",
})
bank_transaction.contact = XeroGateway::Contact.new(:name => "THE NAME OF THE CONTACT")
bank_transaction.contact.phone.number = "12345"
bank_transaction.contact.address.line_1 = "LINE 1 OF THE ADDRESS"
bank_transaction.line_items << XeroGateway::LineItem.new(
  :description => "THE DESCRIPTION OF THE LINE ITEM",
  :unit_amount => 100,
  :tax_amount => 12.5,
  :tracking_category => "THE TRACKING CATEGORY FOR THE LINE ITEM",
  :tracking_option => "THE TRACKING OPTION FOR THE LINE ITEM"
)
bank_transaction.bank_account = XeroGateway::Account.new(:code => 'BANK-ABC)

create_bank_transaction(bank_transaction)



376
377
378
 
# File 'lib/xero_gateway/gateway.rb', line 376

def create_bank_transaction(bank_transaction)
  save_bank_transaction(bank_transaction)
end

#create_contact(contact) ⇒ Object

Creates a contact in Xero

Usage :

contact = XeroGateway::Contact.new(:name => “THE NAME OF THE CONTACT #Time.now.to_i”) contact.email = “[email protected]” contact.phone.number = “12345” contact.address.line_1 = “LINE 1 OF THE ADDRESS” contact.address.line_2 = “LINE 2 OF THE ADDRESS” contact.address.line_3 = “LINE 3 OF THE ADDRESS” contact.address.line_4 = “LINE 4 OF THE ADDRESS” contact.address.city = “WELLINGTON” contact.address.region = “WELLINGTON” contact.address.country = “NEW ZEALAND” contact.address.post_code = “6021”

create_contact(contact)



85
86
87
 
# File 'lib/xero_gateway/gateway.rb', line 85

def create_contact(contact)
  save_contact(contact)
end

#create_credit_note(credit_note) ⇒ Object

Creates an credit_note in Xero based on an credit_note object.

CreditNote and line item totals are calculated automatically.

Usage : 

credit_note = XeroGateway::CreditNote.new({
  :credit_note_type => "ACCREC",
  :due_date => 1.month.from_now,
  :credit_note_number => "YOUR CREDIT_NOTE NUMBER",
  :reference => "YOUR REFERENCE (NOT NECESSARILY UNIQUE!)",
  :line_amount_types => "Inclusive"
})
credit_note.contact = XeroGateway::Contact.new(:name => "THE NAME OF THE CONTACT")
credit_note.contact.phone.number = "12345"
credit_note.contact.address.line_1 = "LINE 1 OF THE ADDRESS"    
credit_note.line_items << XeroGateway::LineItem.new(
  :description => "THE DESCRIPTION OF THE LINE ITEM",
  :unit_amount => 100,
  :tax_amount => 12.5,
  :tracking_category => "THE TRACKING CATEGORY FOR THE LINE ITEM",
  :tracking_option => "THE TRACKING OPTION FOR THE LINE ITEM"
)

create_credit_note(credit_note)



312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
 
# File 'lib/xero_gateway/gateway.rb', line 312

def create_credit_note(credit_note)
  request_xml = credit_note.to_xml
  response_xml = http_put(@client, "#{@xero_url}/CreditNotes", request_xml)
  response = parse_response(response_xml, {:request_xml => request_xml}, {:request_signature => 'PUT/credit_note'})
  
  # Xero returns credit_notes inside an <CreditNotes> tag, even though there's only ever
  # one for this request
  response.response_item = response.credit_notes.first
  
  if response.success? && response.credit_note && response.credit_note.credit_note_id
    credit_note.credit_note_id = response.credit_note.credit_note_id 
  end
  
  response
end

#create_credit_notes(credit_notes) ⇒ Object

Creates an array of credit_notes with a single API request.

Usage :

credit_notes = [XeroGateway::CreditNote.new(...), XeroGateway::CreditNote.new(...)]
result = gateway.create_credit_notes(credit_notes)



335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
 
# File 'lib/xero_gateway/gateway.rb', line 335

def create_credit_notes(credit_notes)
  b = Builder::XmlMarkup.new
  request_xml = b.CreditNotes {
    credit_notes.each do | credit_note |
      credit_note.to_xml(b)
    end
  }
  
  response_xml = http_put(@client, "#{@xero_url}/CreditNotes", request_xml, {})

  response = parse_response(response_xml, {:request_xml => request_xml}, {:request_signature => 'PUT/credit_notes'})
  response.credit_notes.each_with_index do | response_credit_note, index |
    credit_notes[index].credit_note_id = response_credit_note.credit_note_id if response_credit_note && response_credit_note.credit_note_id
  end
  response
end

#create_invoice(invoice) ⇒ Object

Creates an invoice in Xero based on an invoice object.

Invoice and line item totals are calculated automatically.

Usage : 

invoice = XeroGateway::Invoice.new({
  :invoice_type => "ACCREC",
  :due_date => 1.month.from_now,
  :invoice_number => "YOUR INVOICE NUMBER",
  :reference => "YOUR REFERENCE (NOT NECESSARILY UNIQUE!)",
  :line_amount_types => "Inclusive"
})
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 => 100,
  :tax_amount => 12.5,
  :tracking_category => "THE TRACKING CATEGORY FOR THE LINE ITEM",
  :tracking_option => "THE TRACKING OPTION FOR THE LINE ITEM"
)

create_invoice(invoice)



199
200
201
 
# File 'lib/xero_gateway/gateway.rb', line 199

def create_invoice(invoice)
  save_invoice(invoice)
end

#create_invoices(invoices) ⇒ Object

Creates an array of invoices with a single API request.

Usage :

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



225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/xero_gateway/gateway.rb', line 225

def create_invoices(invoices)
  b = Builder::XmlMarkup.new
  request_xml = b.Invoices {
    invoices.each do | invoice |
      invoice.to_xml(b)
    end
  }
  
  response_xml = http_put(@client, "#{@xero_url}/Invoices", request_xml, {})

  response = parse_response(response_xml, {:request_xml => request_xml}, {:request_signature => 'PUT/invoices'})
  response.invoices.each_with_index do | response_invoice, index |
    invoices[index].invoice_id = response_invoice.invoice_id if response_invoice && response_invoice.invoice_id
  end
  response
end

#create_manual_journal(manual_journal) ⇒ Object

Creates a manual journal in Xero based on a manual journal object.

Manual journal and line item totals are calculated automatically.

Usage : # TODO



427
428
429
 
# File 'lib/xero_gateway/gateway.rb', line 427

def create_manual_journal(manual_journal)
  save_manual_journal(manual_journal)
end

#get_accounts ⇒ Object

Gets all accounts for a specific organization in Xero.



474
475
476
477
 
# File 'lib/xero_gateway/gateway.rb', line 474

def get_accounts
  response_xml = http_get(@client, "#{xero_url}/Accounts")
  parse_response(response_xml, {}, {:request_signature => 'GET/accounts'})
end

#get_accounts_list(load_on_init = true) ⇒ Object

Returns a XeroGateway::AccountsList object that makes working with the Xero list of accounts easier and allows caching the results.



483
484
485
 
# File 'lib/xero_gateway/gateway.rb', line 483

def get_accounts_list(load_on_init = true)
  AccountsList.new(self, load_on_init)
end

#get_bank_transaction(bank_transaction_id) ⇒ Object

Retrieves a single bank transaction

Usage : get_bank_transaction(“297c2dc5-cc47-4afd-8ec8-74990b8761e9”) # By ID

get_bank_transaction("OIT-12345") # By number



414
415
416
417
418
419
 
# File 'lib/xero_gateway/gateway.rb', line 414

def get_bank_transaction(bank_transaction_id)
  request_params = {}
  url = "#{@xero_url}/BankTransactions/#{URI.escape(bank_transaction_id)}"
  response_xml = http_get(@client, url, request_params)
  parse_response(response_xml, {:request_params => request_params}, {:request_signature => 'GET/BankTransaction'})
end

#get_bank_transactions(options = {}) ⇒ Object

Retrieves all bank transactions from Xero

Usage : get_bank_transactions

get_bank_transactions(:bank_transaction_id => " 297c2dc5-cc47-4afd-8ec8-74990b8761e9")

Note : modified_since is in UTC format (i.e. Brisbane is UTC+10)



400
401
402
403
404
405
406
407
408
 
# File 'lib/xero_gateway/gateway.rb', line 400

def get_bank_transactions(options = {})
  request_params = {}
  request_params[:BankTransactionID]  = options[:bank_transaction_id] if options[:bank_transaction_id]
  request_params[:ModifiedAfter]      = options[:modified_since] if options[:modified_since]

  response_xml = http_get(@client, "#{@xero_url}/BankTransactions", request_params)

  parse_response(response_xml, {:request_params => request_params}, {:request_signature => 'GET/BankTransactions'})
end

#get_contact_by_id(contact_id) ⇒ Object

Retrieve a contact from Xero Usage get_contact_by_id(contact_id)



48
49
50
 
# File 'lib/xero_gateway/gateway.rb', line 48

def get_contact_by_id(contact_id)
  get_contact(contact_id)
end

#get_contact_by_number(contact_number) ⇒ Object

Retrieve a contact from Xero Usage get_contact_by_id(contact_id)



54
55
56
 
# File 'lib/xero_gateway/gateway.rb', line 54

def get_contact_by_number(contact_number)
  get_contact(nil, contact_number)
end

#get_contacts(options = {}) ⇒ Object

Retrieve all contacts from Xero

Usage : get_contacts(:order => :name)

get_contacts(:modified_since => Time)

Note : modified_since is in UTC format (i.e. Brisbane is UTC+10)



27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/xero_gateway/gateway.rb', line 27

def get_contacts(options = {})
  request_params = {}

  if !options[:updated_after].nil?
    warn '[warning] :updated_after is depracated in XeroGateway#get_contacts.  Use :modified_since'
    options[:modified_since] = options.delete(:updated_after)
  end

  request_params[:ContactID]     = options[:contact_id] if options[:contact_id]
  request_params[:ContactNumber] = options[:contact_number] if options[:contact_number]
  request_params[:OrderBy]       = options[:order] if options[:order]      
  request_params[:ModifiedAfter] = options[:modified_since] if options[:modified_since]
  request_params[:where]         = options[:where] if options[:where]

  response_xml = http_get(@client, "#{@xero_url}/Contacts", request_params)

  parse_response(response_xml, {:request_params => request_params}, {:request_signature => 'GET/contacts'})
end

#get_credit_note(credit_note_id_or_number) ⇒ Object

Retrieves a single credit_note

Usage : get_credit_note(“297c2dc5-cc47-4afd-8ec8-74990b8761e9”) # By ID

get_credit_note("OIT-12345") # By number



268
269
270
271
272
273
274
275
276
 
# File 'lib/xero_gateway/gateway.rb', line 268

def get_credit_note(credit_note_id_or_number)
  request_params = {}
  
  url  = "#{@xero_url}/CreditNotes/#{URI.escape(credit_note_id_or_number)}"
   
  response_xml = http_get(@client, url, request_params)

  parse_response(response_xml, {:request_params => request_params}, {:request_signature => 'GET/CreditNote'})
end

#get_credit_notes(options = {}) ⇒ Object

Retrieves all credit_notes from Xero

Usage : get_credit_notes

get_credit_notes(:credit_note_id => " 297c2dc5-cc47-4afd-8ec8-74990b8761e9")

Note : modified_since is in UTC format (i.e. Brisbane is UTC+10)



248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
 
# File 'lib/xero_gateway/gateway.rb', line 248

def get_credit_notes(options = {})
  
  request_params = {}
  
  request_params[:CreditNoteID]     = options[:credit_note_id] if options[:credit_note_id]
  request_params[:CreditNoteNumber] = options[:credit_note_number] if options[:credit_note_number]
  request_params[:OrderBy]       = options[:order] if options[:order]      
  request_params[:ModifiedAfter] = options[:modified_since] if options[:modified_since]

  request_params[:where]         = options[:where] if options[:where]

  response_xml = http_get(@client, "#{@xero_url}/CreditNotes", request_params)

  parse_response(response_xml, {:request_params => request_params}, {:request_signature => 'GET/CreditNotes'})
end

#get_currencies ⇒ Object

Gets all currencies for a specific organisation in Xero



507
508
509
510
 
# File 'lib/xero_gateway/gateway.rb', line 507

def get_currencies
  response_xml = http_get(@client, "#{xero_url}/Currencies")
  parse_response(response_xml, {}, {:request_signature => 'GET/currencies'})
end

#get_invoice(invoice_id_or_number) ⇒ Object

Retrieves a single invoice

Usage : get_invoice(“297c2dc5-cc47-4afd-8ec8-74990b8761e9”) # By ID

get_invoice("OIT-12345") # By number



155
156
157
158
159
160
161
162
163
 
# File 'lib/xero_gateway/gateway.rb', line 155

def get_invoice(invoice_id_or_number)
  request_params = {}
  
  url  = "#{@xero_url}/Invoices/#{URI.escape(invoice_id_or_number)}"
   
  response_xml = http_get(@client, url, request_params)

  parse_response(response_xml, {:request_params => request_params}, {:request_signature => 'GET/Invoice'})
end

#get_invoices(options = {}) ⇒ Object

Retrieves all invoices from Xero

Usage : get_invoices

get_invoices(:invoice_id => " 297c2dc5-cc47-4afd-8ec8-74990b8761e9")

Note : modified_since is in UTC format (i.e. Brisbane is UTC+10)



135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/xero_gateway/gateway.rb', line 135

def get_invoices(options = {})
  
  request_params = {}
  
  request_params[:InvoiceID]     = options[:invoice_id] if options[:invoice_id]
  request_params[:InvoiceNumber] = options[:invoice_number] if options[:invoice_number]
  request_params[:OrderBy]       = options[:order] if options[:order]      
  request_params[:ModifiedAfter] = options[:modified_since] if options[:modified_since]

  request_params[:where]         = options[:where] if options[:where]

  response_xml = http_get(@client, "#{@xero_url}/Invoices", request_params)

  parse_response(response_xml, {:request_params => request_params}, {:request_signature => 'GET/Invoices'})
end

#get_manual_journal(manual_journal_id) ⇒ Object

Retrieves a single manual journal

Usage : get_manual_journal(“297c2dc5-cc47-4afd-8ec8-74990b8761e9”) # By ID

get_manual_journal("OIT-12345") # By number



464
465
466
467
468
469
 
# File 'lib/xero_gateway/gateway.rb', line 464

def get_manual_journal(manual_journal_id)
  request_params = {}
  url = "#{@xero_url}/ManualJournals/#{URI.escape(manual_journal_id)}"
  response_xml = http_get(@client, url, request_params)
  parse_response(response_xml, {:request_params => request_params}, {:request_signature => 'GET/ManualJournal'})
end

#get_manual_journals(options = {}) ⇒ Object

Retrieves all manual journals from Xero

Usage : get_manual_journal

getmanual_journal(:manual_journal_id => " 297c2dc5-cc47-4afd-8ec8-74990b8761e9")

Note : modified_since is in UTC format (i.e. Brisbane is UTC+10)



450
451
452
453
454
455
456
457
458
 
# File 'lib/xero_gateway/gateway.rb', line 450

def get_manual_journals(options = {})
  request_params = {}
  request_params[:ManualJournalID]  = options[:manual_journal_id] if options[:manual_journal_id]
  request_params[:ModifiedAfter]      = options[:modified_since] if options[:modified_since]

  response_xml = http_get(@client, "#{@xero_url}/ManualJournals", request_params)

  parse_response(response_xml, {:request_params => request_params}, {:request_signature => 'GET/ManualJournals'})
end

#get_organisation ⇒ Object

Gets Organisation details



499
500
501
502
 
# File 'lib/xero_gateway/gateway.rb', line 499

def get_organisation
  response_xml = http_get(@client, "#{xero_url}/Organisation")
  parse_response(response_xml, {}, {:request_signature => 'GET/organisation'})
end

#get_tax_rates ⇒ Object

Gets all Tax Rates for a specific organisation in Xero



515
516
517
518
 
# File 'lib/xero_gateway/gateway.rb', line 515

def get_tax_rates
  response_xml = http_get(@client, "#{xero_url}/TaxRates")
  parse_response(response_xml, {}, {:request_signature => 'GET/tax_rates'})
end

#get_tracking_categories ⇒ Object

Gets all tracking categories for a specific organization in Xero.



490
491
492
493
494
 
# File 'lib/xero_gateway/gateway.rb', line 490

def get_tracking_categories
  response_xml = http_get(@client, "#{xero_url}/TrackingCategories")

  parse_response(response_xml, {}, {:request_signature => 'GET/TrackingCategories'})
end

#update_bank_transaction(bank_transaction) ⇒ Object

Updates an existing Xero bank transaction

Usage :

bank_transaction = xero_gateway.get_bank_transaction(some_bank_transaction_id) bank_transaction.due_date = Date.today

xero_gateway.update_bank_transaction(bank_transaction)



389
390
391
392
 
# File 'lib/xero_gateway/gateway.rb', line 389

def update_bank_transaction(bank_transaction)
  raise "bank_transaction_id is required for updating bank transactions" if bank_transaction.bank_transaction_id.nil?
  save_bank_transaction(bank_transaction)
end

#update_contact(contact) ⇒ Object

Updates an existing Xero contact

Usage :

contact = xero_gateway.get_contact(some_contact_id) contact.email = “a_new_email_ddress”

xero_gateway.update_contact(contact)



98
99
100
101
 
# File 'lib/xero_gateway/gateway.rb', line 98

def update_contact(contact)
  raise "contact_id or contact_number is required for updating contacts" if contact.contact_id.nil? and contact.contact_number.nil?
  save_contact(contact)
end

#update_contacts(contacts) ⇒ Object

Updates an array of contacts in a single API operation.

Usage :

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

Will update contacts with matching contact_id, contact_number or name or create if they don’t exist.



112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
 
# File 'lib/xero_gateway/gateway.rb', line 112

def update_contacts(contacts)
  b = Builder::XmlMarkup.new
  request_xml = b.Contacts {
    contacts.each do | contact |
      contact.to_xml(b)
    end
  }
  
  response_xml = http_post(@client, "#{@xero_url}/Contacts", request_xml, {})

  response = parse_response(response_xml, {:request_xml => request_xml}, {:request_signature => 'POST/contacts'})
  response.contacts.each_with_index do | response_contact, index |
    contacts[index].contact_id = response_contact.contact_id if response_contact && response_contact.contact_id
  end
  response
end

#update_invoice(invoice) ⇒ Object

Updates an existing Xero invoice

Usage :

invoice = xero_gateway.get_invoice(some_invoice_id) invoice.due_date = Date.today

xero_gateway.update_invoice(invoice)



213
214
215
216
 
# File 'lib/xero_gateway/gateway.rb', line 213

def update_invoice(invoice)
  raise "invoice_id is required for updating invoices" if invoice.invoice_id.nil?
  save_invoice(invoice)
end

#update_manual_journal(manual_journal) ⇒ Object

Updates an existing Xero manual journal

Usage :

manual_journal = xero_gateway.get_manual_journal(some_manual_journal_id)

xero_gateway.update_manual_journal(manual_journal)



439
440
441
442
 
# File 'lib/xero_gateway/gateway.rb', line 439

def update_manual_journal(manual_journal)
  raise "manual_journal_id is required for updating manual journals" if manual_journal.manual_journal_id.nil?
  save_manual_journal(manual_journal)
end