xero-node

Requirements

node version 10.13.0 or higher

SDK Documentation

• version 3 - deprecated end of 2020 documentation
• version 4 documentation

Release of SDK with oAuth 2 support

Version 4.x of Xero NodeJS SDK only supports oAuth2 authentication and the following API sets.

• accounting

Bank feeds support in OAuth 2

An early release in a separate package is availalbe bank feeds API.

Looking for OAuth 1.0a support?

We've moved this code into the oauth1 branch.

Usage

Installation This SDK is published as an npm package called xero-node.

npm install --save xero-node

Getting Started

Create a Xero App

Follow these steps to create your Xero app

• Create a free Xero user account (if you don't have one)
• Login to Xero developer center
• Click "Try oAuth2" link
• Enter your App name, company url, privacy policy url.
• Enter the redirect URI (this is your callback url - localhost, etc)
• Agree to terms and condition and click "Create App".
• Click "Generate a secret" button.
• Copy your client id and client secret and save for use later.
• Click the "Save" button. You secret is now hidden.

Typescript example

A "kitchen sync" app is available that demonstrates interacting with each endpoint. Just download the code and configure.

Javascript Example

This is a barebones example showing how to authenticate and display the name of the Xero organisation you've connected to.

'use strict';

const express = require('express');
const session = require('express-session');
const xero_node = require('xero-node')

const port = process.env.PORT || 3000
const client_id = 'YOUR-CLIENT_ID'
const client_secret = 'YOUR-CLIENT_SECRET'
const redirectUri = `http://localhost:${port}/callback`
const scopes = 'openid profile email accounting.transactions accounting.settings offline_access'

const xero = new xero_node.XeroClient({
  clientId: client_id,
  clientSecret: client_secret,
  redirectUris: [redirectUri],
  scopes: scopes.split(" ")
});

let app = express()

app.set('port', port)
app.use(express.static(__dirname + '/public'))
app.use(session({
    secret: 'something crazy',
    resave: false,
    saveUninitialized: true,
    cookie: { secure: false }
}));

app.get('/', function(req, res) {
  res.send('<a href="/connect">Connect to Xero</a>');
})

app.get('/connect', async function(req, res) {
  try {
    let consentUrl = await xero.buildConsentUrl();
    res.redirect(consentUrl);
  } catch (err) {
    res.send("Sorry, something went wrong");
  }
})

app.get('/callback', async function(req, res) {
    const url = "http://localhost:5000/" + req.originalUrl;
    await xero.setAccessTokenFromRedirectUri(url);

    // Optional: read user info from the id token
    let tokenClaims = await xero.readIdTokenClaims();
    const tokenSet = await xero.readTokenSet();

    req.session.tokenClaims = tokenClaims;
    req.session.tokenSet = tokenSet;
    req.session.xeroTenantId = xero.tenantIds[0];
    res.redirect('/organisation');
})

app.get('/organisation', async function(req, res) {
  try {
    const response = await xero.accountingApi.getOrganisations(xero.tenantIds[0])
    res.send("Hello, " + response.body.organisations[0].name);
  } catch (err) {
    res.send("Sorry, something went wrong");
  }
})

app.listen(port, function() {
  console.log("Your Xero basic public app is running at localhost:" + port)
})

Project Structure

src/
  |-  gen/        autogenerated TypeScript
  `-  *.ts        handwritten TypeScript
dist/             compiled JavaScript
package.json