EliXero

Usage instructions

In order to use this SDK, you will need to have created an application in the developer portal. Once you've created your application you'll need to build a configuration file that stores you consumer key and secret as well as signing certificate information if applicable.

You will need to name the file 'xero_app_config.exs' and it will need to be structured to so

config :elixero,

  private_key_path: "path_to_signing_certificate",

  consumer_key: "your_applications_consumer_key",

  consumer_secret: "your_applications_consumer_secret",

  callback_url: "callback_url_if_applicable",

  app_type: atom_denoting_app_type

Note:

Private application usage

Private applications are not required to go through the process of acquiring an request token, authorising it, and then swaping it for an access token.

Required config variables

Once you have set up your config file you can use your private application like so:

  1. Create a client
client = EliXero.create_client
  1. Use the client when calling the Xero API
EliXero.CoreApi.Invoices.find client

It's that easy.

Public application usage

Public applications must be authorised for use against a users organisation and must follow the oauth flow of acquiring a request token, having the request token authorised for an organisation, and swapping the request token for an access token, the access token must then be used when creating the client

Required config variables

Once you have set up your config file you can use your public application like so:

  1. Acquire a request token
request_token = EliXero.get_request_token
  1. Generate the authorisation url to be presented to the user
auth_url = EliXero.generate_auth_url request_token
  1. Swap the request token for an access token. Once the user has authorised the connection to an organisation and you have retrieved the verification code either from the user themself or the request back into your callback url, do the following:
access_token = EliXero.approve_access_token(request_token, "verification_code")
  1. Create a client
client = EliXero.create_client access_token
  1. Use the client when calling the Xero API
EliXero.CoreApi.Invoices.find client

Partner application usage

Partner applications are like a hybrid of both private and public applications. Partner applications use signing certificates like private applications but also require the same oauth process as public applications to recieve access tokens. Partner applications can also renew their access tokens after they expire preventing the user from needing re-authorise after 30 mins of usage.

Required config variables

Once you have set up your config file you can use your partner application like so:

  1. Acquire a request token
request_token = EliXero.get_request_token
  1. Generate the authorisation url to be presented to the user
auth_url = EliXero.generate_auth_url request_token
  1. Swap the request token for an access token. Once the user has authorised the connection to an organisation and you have retrieved the verification code either from the user themself or the request back into your callback url, do the following:
access_token = EliXero.approve_access_token(request_token, "verification_code")
  1. Create a client
client = EliXero.create_client access_token
  1. Use the client when calling the Xero API
EliXero.CoreApi.Invoices.find client

After your access token has expired, partner applications can renew them without the need for user input via authorisation. Given your existing access token is in a variable named access_token, this can be done like so:

renewed_access_token = EliXero.renew_access_token access_token

Use of filter functions

Some endpoints allow various filter methods when retrieving information from the Xero API. All filtering, with the exception of if-modified-since, is performed via query parameters. If-modified-since is done via headers.

When using filtering, a map outlining what filtering you want needs to be supplied.

Below is an example on how to do this when you want to retrieve all DRAFT, ACCREC invoices, ordered by Date desc, modified since the start of 2017,:

filter = %{:query_filters => [{"where", "Status==\"DRAFT\" AND Type==\"ACCREC\""}, {"orderby", "Date desc"}], :modified_since => "2017-01-01" }



EliXero.CoreApi.Invoices.filter cient, filter

Both :query_filters and :modified_since are not required when filtering if you only need to filter by one of them.

Installation

If available in Hex, the package can be installed as:

  1. Add elixero to your list of dependencies in mix.exs:
```elixir

def deps do

  [{:elixero, "~> 0.0.5"}]

end

```
  1. Ensure elixero is started before your application:
```elixir

def application do

  [applications: [:elixero]]

end

```