Xtract API

Xtract has official SDKs for different programming languages.

Ruby SDK

This gem is the official library provided by Xtract to interact with our API.

You can read the API docs directly from here.

Installation

Add this line to your application's Gemfile:

gem 'xtract-sdk'

And then execute:

$> bundle

Or install it yourself as:

$> gem install xtract-sdk

Usage

First you need to configure your api key obtained from the platform:

XtractSDK.configure do |config|
    config.api_key = 'API_KEY'
end

Also you can pass the key when creating the client directly:

client = XtractSDK::Client.new(api_key: 'API_KEY')

Then you can create a client and start making requests. We provide a convenient way to do this:

Get invoices

client = XtractSDK::Client.new
    invoices = client
        .invoices
        .client_tax_id('SOME_TAX_ID')
        .call

    invoices.each do |invoice|
      puts invoice.id
      puts invoice.products
end

These are all the filtering options:

client_business_name
client_tax_id
provider_business_name
provider_tax_id
date_from
date_to
expiration_date_from
expiration_date_to
number
electronic_authorization_id
created_at_from
created_at_to
accounted ('pending', 'in_progress', 'completed', 'with_errors')
imputed (true, false)

Get an invoice

client = XtractSDK::Client.new
invoices = client.invoice(ID)

puts invoice.id
puts invoice.products

Update an invoice

client = XtractSDK::Client.new
client.update_invoice(ID, { accounted: 'completed' }) #=> :ok

Errors

You can check here all the error classes that the library raises.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/xtractapp/ruby-sdk.

Sin SDK

require 'http'

response = HTTP.get(
  'https://api.xtract.app/api/v1/invoices',
  headers: {
    authorization: 'API_KEY'
  },
  params: {
    provider_tax_id: '123456789'
  }
)

puts response.body

NodeJS

const axios = require('axios');

axios
  .get(
    'https://api.xtract.app/api/v1/invoices',
    {
      headers: {
        authorization: 'API_KEY'
      },
      params: {
        provider_tax_id: '123456789'
      }
    }
  )
  .then(res => {
    console.log(res.data);
  });

Java

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.xtract.app/api/v1/invoices?provider_tax_id=123456789")
  .addHeader("Authorization", "API_KEY")
  .build();

Response response = client.newCall(request).execute();
GsonBuilder builder = new GsonBuilder();
Invoices invoices = builder.create().fromJson(response.body().string(), Invoices.class);
System.out.println(invoices);

Google Apps Script

This repo contains the code that powers the Xtract API connector library that you can use directly from Google Apps Script. If you don't want to use the library you can copy and modify the code in this repo as you need.

The library's script ID is 1oW5XdZwVg31CSl9LYMEiuvm0BcWz8omozSXqdl9uJxFa-WAPclG4fPwg

Using the library

First create a new Apps Script Project. This can be done directly here or after creating a new spreadsheet you can click

Extensions -> Apps Script

After this you can start coding the code that will interact between you spreadsheet and the Xtract API.

On your left click

Libraries +

and paste the script ID mentioned before.

Create 2 sheets one called

Filters

and the other one called

Report

Then you can get started with the following example:

const API_KEY = 'CHANGE_WITH_YOUR_ACCOUNT_KEY';

// Add a menu at the top of the spreadsheet to easily execute
const onOpen = () => { // eslint-disable-line
  const ui = SpreadsheetApp.getUi();
  const menu = ui.createMenu('Xtract');
  menu.addItem('Generate report', 'generateReport');
  menu.addToUi();
};

// This function gets called after pressing the generate report button
const generateReport = () => { // eslint-disable-line
  const invoices = Xtract.fetchInvoices(API_KEY, {});
  const rows = [];

  invoices.forEach((invoice, idx) => {
    rows.push([idx, invoice.number]);
  });

  const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Report');
  sheet.clearContents();
  sheet.getRange(1, 1, rows.length, rows[0].length).setValues(rows);
};

If you want to add some filters you can do the following:

const API_KEY = 'CHANGE_WITH_YOUR_ACCOUNT_KEY';
const REPORT_SHEET_NAME = 'Report';
const FILTERS_SHEET_NAME = 'Filters';
/*
  Location of the filters
    - Key is the query param used to call the API
    - Value is the cell where you can get the value
 */
const FILTERS_POSITIONS = {
  date_from: 'B2',
  date_to: 'B3',
  provider_tax_id: 'B4',
};

const onOpen = () => { // eslint-disable-line
  const ui = SpreadsheetApp.getUi();
  const menu = ui.createMenu('Xtract');
  menu.addItem('Generate report', 'generateReport');
  menu.addToUi();
};

const generateReport = () => { // eslint-disable-line
  const filters = Xtract.getFilters(FILTERS_SHEET_NAME, FILTERS_POSITIONS);
  const invoices = Xtract.fetchInvoices(API_KEY, filters);
  const rows = [];

  invoices.forEach((invoice, idx) => {
    rows.push([idx, invoice.number]);
  });

  const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName(REPORT_SHEET_NAME);
  sheet.clearContents();
  sheet.getRange(1, 1, rows.length, rows[0].length).setValues(rows);
};