Overview

The standard way to access the Bkper API is through our Google Apps Script library BkperApp.

clasp npm (scoped) GSTests status

With BkperApp you can create many solutions on G Suite, such as the Sheets and Forms Add-ons, simple automations or advanced solutions with Google Apps Script API, and you can manage your scripts in the Dashboard.

It works the same way your favorite Google Apps Script library works, like CalendarApp, DocumentApp, SpreadsheetApp etc, and it is safely authorized using OAuth2 protocol:

Authorization

To authorize the library, you just need to run the OAuth2 flow only once per account. This can be easily done when you install any Add-ons, or at bkper.app

Setup

This library is already published as an Apps Script, making it easy to include in your project. To add it to your script, do the following in the Apps Script code editor:

  1. Click on the menu item “Resources > Libraries…”
  2. In the “Add a Library” text box, enter the Script ID “1fSZnepYcDUjxCsrWYD3452UJ5nJiB4js0cD45WWOAjMcKJR_PKfLU60X” and click the “Select” button.
  3. Choose a version in the dropdown box (usually best to pick the latest version).
  4. Click the “Save” button.

Development

Altough you can work on the Online editor really quickly, we strongly recommend clasp to develop locally with Typescript on VS Code editor, which is really powerfull and free, so you get:

  • Code Autocomplete
  • Contextual documentation
  • Compile time error checking
  • Code navigation - really helpful!
  • Calling hierarchy searching
  • Use of new javascript features such as classes, interfaces, arrow functions etc
  • Easier code redability
  • Automatic refactoring

Add Typescript Definitions:

1) Add the package:

npm i -S @bkper/bkper-app-types

or

yarn add --dev @bkper/bkper-app-types

2) Configure tsconfig.json:

{
    "compilerOptions": {
        "typeRoots" : ["node_modules/@bkper", "node_modules/@types" ]
    }
}

Learn more about @types, typeRoots and types

Don’t forget to keep your code always in sync with version control system such as GitHub or Cloud Source Repositories

Record Transactions

To record your first Transaction, after authorizing and setup, copy and paste the function bellow:

function recordATransaction() {

  var book = BkperApp.getBook("agtzfmJrcGVyLWhyZHIOCxIGTGVkZ2VyGNKJAgw");

  book.record("#gas 63.23");

}

Exchange the parameter of the function getBook for the id of the Book you want to record the Transaction. This is the same parameter found on the URL accessed on bkper.com:

bookId

Now run the recordATransaction function and see the record appearing on the bkper screen:

Recording

You can also record transactions in batch by passing an Array of strings as the record method parameter:

function batchRecordTransactions() {

  var book = BkperApp.getBook("agtzfmJrcGVyLWhyZHIOCxIGTGVkZ2VyGNKJAgw");

  var transactions = new Array();

  transactions.push("#breakfast 15.40");
  transactions.push("#lunch 27.45");
  transactions.push("#dinner 35.86");

  book.record(transactions);

}

The above code will send all records in a bulk. Very useful for importing large amount of data without the risk of reaching script limits.

List Transactions

Each book is a large database and every interaction is done in terms of queries. Everytime you “select” an Account by clicking on left menu at bkper.com, you are actually filtering transactions by that Account.

Every query is shown in the search box on top of the page:

Query

When you retrieve transactions, the getTransactions method returns an TransactionIterator to let you handle potentially large datasets:

function listTransactions() {

  var book = BkperApp.getBook("agtzfmJrcGVyLWhyZHITCxIGTGVkZ2VyGICAgKCtg6MLDA");

  //GetTransactions returns an interator to deal with potencial large datasets
  var transactionIterator = book.getTransactions("account:'Bank' after:01/04/2014");

  while (transactionIterator.hasNext()) {
    var transaction = transactionIterator.next();
    Logger.log(transaction.getDescription());
  }

}

Run the queryTransactions function, exchanging your bookId, with the same query, check the log output and you will see the same descriptions:

Search log

List Accounts

You can access all Account objects, in a way similar to the left sidebar:

function listAccounts() {
  //Open the book
  var book = BkperApp.getBook("agtzfmJrcGVyLWhyZHIOCxIGTGVkZ2VyGNKJAgw");

  var accounts = book.getAccounts();
  for (var i=0; i < accounts.length; i++) {
    var account = accounts[i];
    if (account.isPermanent() && account.isActive()) {
      Logger.log(account.getName() + ": " + account.getBalance());
    }
  }
}