You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
> This describes to ~200+ accounting API endpoints and their expected params. There are also method reference docs for the Assets, Files, Projects, and Payroll endpoints sets, though we are still working on accurately generating usable parameter examples for all! (feedback welcome)
11
+
### Model Docs
12
+
*[Models](/docs/)
13
+
> Directory of markdown files, describing the object models for the Accounting, Asset, Projects, Files, Payroll (AU, UK, NZ) Xero API sets.
21
14
## Sample Apps
22
-
We have two apps showing SDK usage.
23
-
*https://github.com/XeroAPI/xero-ruby-oauth2-starter (**Sinatra** - session based / getting started)
24
-
*https://github.com/XeroAPI/xero-ruby-oauth2-app (**Rails** - token management / full examples)
15
+
We have two sample apps showing SDK usage:
16
+
*https://github.com/XeroAPI/xero-ruby-oauth2-starter (**Sinatra** - bare minimum to hello world and simple session based storage)
17
+
*https://github.com/XeroAPI/xero-ruby-oauth2-app (**Rails** - token management with robust usage examples)
25
18
26
19
27
20
28
-
---
21
+
## Xero Pre-Requisites
22
+
* Create a [free Xero user account](https://www.xero.com/us/signup/api/)
23
+
* Login to your Xero developer [/myapps](https://developer.xero.com/myapps) dashboard & create an API application
24
+
* Copy the credentials from your API app and store/access them using a secure ENV variable strategy
25
+
* Resaearch and include the [neccesary scopes](https://developer.xero.com/documentation/oauth2/scopes) for your app's functionality as a space-seperated list, ex. "`SCOPES="openid profile email accounting.transactions accounting.settings"`"
26
+
27
+
28
+
29
29
## Installation
30
-
To install this gem to your current gemset.
30
+
To install this gem to your project:
31
31
```
32
32
gem install 'xero-ruby'
33
33
```
34
-
Or add to your gemfile and run `bundle install`.
34
+
Or more commonly in Ruby on Rails usage add to your gemfile and run `bundle install`:
35
35
```
36
36
gem 'xero-ruby'
37
37
```
38
38
39
-
## Getting Started
40
-
* Create a [free Xero user account](https://www.xero.com/us/signup/api/)
41
-
* Login to your Xero developer [/myapps](https://developer.xero.com/myapps) dashboard & create an API application and note your API app's credentials.
42
-
43
-
### Creating a client
44
-
* Get the credential values from an API application at https://developer.xero.com/myapps/.
45
-
* Include [neccesary scopes](https://developer.xero.com/documentation/oauth2/scopes) as a space-seperated list
46
-
* example => "`openid profile email accounting.transactions accounting.settings`"
If you want additional logging or timeout, you can add/override any configuration option by passing the optional named parameter object `config`.
55
+
For additional logging or timeout, add or override any [config](/lib/xero-ruby/configuration.rb) option by passing an optional named parameter `config: {..}`.
All API requests require a valid access token to be set on the client.
61
+
## OAuth2.0 Authorization & Callback
62
+
All API requests require a valid access token to be set on the xero_client.
69
63
70
-
To generate a valid `token_set` send a user to the `authorization_url`:
64
+
### Step 1
65
+
Send the user to the `authorization_url` after you have configured your xero_client
71
66
```ruby
72
67
@authorization_url= xero_client.authorization_url
73
68
74
69
redirect_to @authorization_url
75
70
```
76
71
77
-
Xero will then redirect back to the URI defined in your `redirect_uri` config.
78
-
79
-
*This must match **exactly** with the variable in your /myapps dashboard.*
80
-
81
-
In your callback, calling `get_token_set_from_callback` will exchange the temporary code Xero return, with a valid `token_set` that you can use to make API calls.
72
+
### Step 2
73
+
On successful authorization, Xero identity will redirect to the URI defined in your `redirect_uri` config which must match **exactly** with the variable in your /myapps dashboard.
74
+
```
75
+
=> /oauth/redirect_uri
76
+
```
77
+
### Step 3
78
+
In your server defined callback route, exchange the temporary code for a valid `token_set` that will get set on your client.
At this point you should save the token_set as JSON in a datastore in relation to the authenticating user or entity.
86
83
87
-
# save token_set JSON in a datastore in relation to the user authentication
88
-
89
-
puts params['state']
90
-
=> "this-can-be-a-custom-state-parameter"
84
+
The sample [Rails app](https://github.com/XeroAPI/xero-ruby-oauth2-app/blob/master/app/controllers/application_controller.rb#L11) shows a solid pattern you can tweak to fit your needs:
Note that an `access_token` is valid for 30 minutes but a `refresh_token` can be used once in up to a 60 day window. If a refresh_token is used to refresh access you must replace the entire token_set.
92
112
93
-
## Making API calls once you have a token_set
94
-
Once you already have a token_set stored from this initual user interaction, you can setup a new client by passing the whole token_set to `refresh_token_set` or `set_token_set`.
113
+
Both the `id_token` & `access_token` are JWT's, and can be decoded for to see additional metadata described in the Token Helpers section:
114
+
## Making API calls with a valid token_set
115
+
After the initial user interaction you can simply setup a xero_client by passing the whole token_set to the client.
95
116
```ruby
96
117
xero_client.set_token_set(user.token_set)
97
118
98
119
xero_client.refresh_token_set(user.token_set)
99
-
# this will set the access_token on the client, and return a refreshed `token_set` you need to save.
100
120
```
101
-
A `token_set` contains data about your API connection most importantly :
102
-
*`access_token`
103
-
*`refresh_token`
104
-
*`expiry`
105
-
106
-
**An `access_token` is valid 30 minutes and a `refresh_token` is valid for 60 days**
107
-
108
-
Example Token set:
109
-
> You can decode the `id_token` & `access_token` for additional metadata by using a [decoding library](https://github.com/jwt/ruby-jwt):
110
-
```json
121
+
This sets the access_token on the client, and returns a refreshed `token_set` you should save in your database for the next time you need to connect to Xero's API.
#Xero's tokens can potentially facilitate (n) org connections in a single token.
127
-
# It is important to store the `tenantId` of the Organisation your user wants to read/write data.
187
+
#To completely Revoke a user's access token and all their connections
188
+
xero_client.revoke_token(token_set)
128
189
129
-
#The `updatedDateUtc` will show you the most recently authorized Tenant (AKA Organisation)
190
+
#In case there are > 1 tenants connected the `updatedDateUtc` will show you the most recently authorized tenant (aka organisation) - it is important to store the `tenantId` of the Org your user specified in their API authorization
#example of how to store the `tenantId` of the specific tenant (aka organisation)
222
+
#Example 'active tenant' logic storage of the tenant the user specified, xero_client.connections[0] is not a safe assumption in case they authorized multiple orgs.
1) Not all `opts` parameter combinations are available for all endpoints, and there are likely some undiscovered edge cases. If you encounter a filter / sort / where clause that seems buggy open an issue and we will dig.
336
378
337
379
2) Some opts string values may need PascalCasing to match casing defined in our [core API docs](https://developer.xero.com/documentation/api/api-overview).
338
380
*`opts = { order: 'UpdatedDateUtc DESC'}`
339
381
340
382
3) If you have use cases outside of these examples let us know.
341
-
342
-
## Sample App
343
-
The best resource to understanding how to best leverage this SDK is the sample applications showing all the features of the gem.
Copy file name to clipboardExpand all lines: docs/accounting/AccountingApi.md
+4-1Lines changed: 4 additions & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -6623,7 +6623,9 @@ opts = {
6623
6623
6624
6624
page:1, # Integer | e.g. page=1 - Up to 100 contacts will be returned in a single API call.
6625
6625
6626
-
include_archived:true# Boolean | e.g. includeArchived=true - Contacts with a status of ARCHIVED will be included in the response
6626
+
include_archived:true, # Boolean | e.g. includeArchived=true - Contacts with a status of ARCHIVED will be included in the response
6627
+
6628
+
summary_only:false# Boolean | Use summaryOnly=true in GET Contacts endpoint to retrieve a smaller version of the response object. This returns only lightweight fields, excluding computation-heavy fields from the response, making the API calls quick and efficient.
6627
6629
}
6628
6630
6629
6631
begin
@@ -6647,6 +6649,7 @@ Name | Type | Description | Notes
6647
6649
**i_ds** | [**Array<String>**](String.md)| Filter by a comma separated list of ContactIDs. Allows you to retrieve a specific set of contacts in a single call. | [optional]
6648
6650
**page** | **Integer**| e.g. page=1 - Up to 100 contacts will be returned in a single API call. | [optional]
6649
6651
**include_archived** | **Boolean**| e.g. includeArchived=true - Contacts with a status of ARCHIVED will be included in the response | [optional]
6652
+
**summary_only** | **Boolean**| Use summaryOnly=true in GET Contacts endpoint to retrieve a smaller version of the response object. This returns only lightweight fields, excluding computation-heavy fields from the response, making the API calls quick and efficient. | [optional][default to false]
0 commit comments