BkperApp

The main entry point to interact with BkperApp

Script ID: 1fSZnepYcDUjxCsrWYD3452UJ5nJiB4js0cD45WWOAjMcKJR_PKfLU60X

getAuthorizationHtml(continueUrl?:

string

, continueText?:

string

):

GoogleAppsScript.HTML.HtmlOutput

Gets the authorization screen html template for the user to authorize the API

getBook(id:

string

):

Book

Gets the Book with the specified bookId from url param.

This is the main Entry Point to start interacting with BkperApp

Example:

var book = BkperApp.getBook("agtzfmJrcGVyLWhyZHITCxIGTGVkZ2VyGICAgIDggqALDA");
book.record("#fuel for my Land Rover 126.50 28/01/2013");

getBooks():

Book

[]

Gets all Book the user has access.

isUserAuthorized():

boolean

Check if the user is already althorized with OAuth2 to the bkper API

Account

This class defines an Account of a Book.

It mantains a balance of all amount credited and debited in it by Transactions.

An Account can be grouped by Groups.

getBalance(raw?:

boolean

):

number

Gets the balance based on credit nature of this Account

The balance of this account

getCheckedBalance(raw?:

boolean

):

number

Gets the checked balance based on credit nature of this Account

The checked balance of this Account

getDescription():

string

Gets the account description

getId():

string

Gets the account internal id

getName():

string

Gets the account name

getNormalizedName():

string

The name of this account without spaces and special characters

isActive():

boolean

Tell if this account is Active or otherwise Archived

isCredit():

boolean

Tell if the account has a Credit nature or Debit otherwise

Credit accounts are just for representation purposes. It increase or decrease the absolute balance. It doesn’t affect the overall balance or the behavior of the system.

The absolute balance of credit accounts increase when it participate as a credit/origin in a transaction. Its usually for Accounts that increase the balance of the assets, like revenue accounts.

        Crediting a credit
  Thus ---------------------> account increases its absolute balance
        Debiting a debit


        Debiting a credit
  Thus ---------------------> account decreases its absolute balance
        Crediting a debit

As a rule of thumb, and for simple understanding, almost all accounts are Debit nature (NOT credit), except the ones that “offers” amount for the books, like revenue accounts.

isInGroup(group:

string

|

Group

):

boolean

Tell if this account is in the Group

isPermanent():

boolean

Tell if the account is permanent.

Permanent Accounts are the ones which final balance is relevant and keep its balances over time.

They are also called Real Accounts

Usually represents assets or tangibles, capable of being perceived by the senses or the mind, like bank accounts, money, debts and so on.

True if its a permanent Account

Balance

Class that represents an Account, Group or #hashtag balance on a window of time (Day / Month / Year).

getCheckedCumulativeBalance():

number

The cumulative checked balance to the date, since the first transaction posted.

getCheckedPeriodBalance():

number

The checked balance on the date period.

getCumulativeBalance():

number

The cumulative balance to the date, since the first transaction posted.

getDate():

Date

Date object constructed based on Book time zone offset. Usefull for

If Month or Day is zero, the date will be constructed with first Month (January) or Day (1).

getDay():

number

The day of the balance. Days starts on 1 to 31.

Day can be 0 (zero) in case of Monthly or Early Periodicity of the BalancesReport

getFuzzyDate():

number

The Fuzzy Date of the balance, based on Periodicity of the BalancesReport query, composed by Year, Month and Day.

The format is YYYYMMDD. Very usefull for ordering and indexing

Month and Day can be 0 (zero), depending on the granularity of the Periodicity.

Example:

20180125 - 25, January, 2018 - DAILY Periodicity

20180100 - January, 2018 - MONTHLY Periodicity

20180000 - 2018 - YEARLY Periodicity

getMonth():

number

The month of the balance. Months starts on 1 (January) to 12 (December)

Month can be 0 (zero) in case of Early Periodicity of the BalancesReport

getPeriodBalance():

number

The balance on the date period.

getUncheckedCumulativeBalance():

number

The unchecked cumulative balance to the date, since the first transaction posted.

getUncheckedPeriodBalance():

number

The unchecked balance on the date period.

getYear():

number

The year of the balance

BalancesContainer

The container of balances of an Account, Group or #hashtag

The container is composed of a list of Balances for a window of time, as well as its period and cumulative totals.

createDataTable():

BalancesDataTableBuilder

Creates a BalancesDataTableBuilder to generate a two-dimensional array with all BalancesContainers

getBalances():

Balance

[]

All Balances of the container

getBalancesContainer(name:

string

):

BalancesContainer

Gets a specific BalancesContainer.

NOTE: Only for Groups balance containers. Accounts and hashtags return null.

getBalancesContainers():

BalancesContainer

[]

Gets all child BalancesContainers.

NOTE: Only for Groups balance containers. Accounts and hashtags return empty.

getBalancesReport():

BalancesReport

The parent BalancesReport of the container

getCumulativeBalance():

number

The cumulative balance to the date, since the first transaction posted.

getCumulativeBalanceText():

string

The cumulative balance formatted according to Book decimal format and fraction digits.

getName():

string

The Account name, Group name or #hashtag

getPeriodBalance():

number

The balance on the date period.

getPeriodBalanceText():

string

The balance on the date period formatted according to Book decimal format and fraction digits

isCredit():

boolean

Gets the credit nature of the BalancesContainer, based on Account, Group or #hashtag this container represents.

For Account, the credit nature will be the same as the one from the Account

For Group, the credit nature will be the same, if all accounts containing on it has the same credit nature. False if mixed.

For #hashtag, the credit nature will be true.

BalancesDataTableBuilder

A BalancesDataTableBuilder is used to setup and build two-dimensional arrays containing balance information.

build():

any

[][]

Gets an two-dimensional array with the balances.

For TOTAL BalanceType, the table format looks like:

  _____________________
 |    NAME   | AMOUNT  |
 | Expenses  | 4568.23 |
 | Incomes   | 5678.93 |
 |    ...    |   ...   |
 |___________|_________|

Two columns, and each Group | Account | #hashtag per line.

For PERIOD or CUMULATIVE BalanceType, the table will be a time table, and the format looks like:

 _____________________________________________
 |    DATE    | Expenses | Incomes |    ...   |
 | 15/01/2014 | 2345.23  | 3452.93 |    ...   |
 | 15/02/2014 | 2345.93  | 3456.46 |    ...   |
 | 15/03/2014 | 2456.45  | 3567.87 |    ...   |
 |    ...     |   ...    |   ...   |    ...   |
 |___________ |__________|_________|__________|

First column will be the Date column, and one column for each Group, Account or #hashtag.

formatDate():

BalancesDataTableBuilder

Defines whether the dates should be formatted based on date pattern and periodicity of the Book.

This builder with respective formatting option.

formatValue():

BalancesDataTableBuilder

Defines whether the value should be formatted based on decimal separator of the Book.

This builder with respective formatting option.

setBalanceType(balanceType:

BalanceType

):

BalancesDataTableBuilder

Fluent method to set the BalanceType for the builder.

This builder with respective balance type.

BalancesReport

Class representing a Balance Report, generated when calling Book.getBalanceReport

createDataTable():

BalancesDataTableBuilder

Creates a BalancesDataTableBuilder to generate a two-dimensional array with all BalancesContainers.

getBalancesContainer(groupName:

string

):

BalancesContainer

Gets a specific BalancesContainers.

getBalancesContainers():

BalancesContainer

[]

Gets all BalancesContainers of the report.

getBook():

Book

The Book that generated the report.

getPeriodicity():

Periodicity

The Periodicity of the query used to generate the report.

hasOnlyOneGroup():

boolean

Check if the report has only one Group specified on query.

Book

A Book represents General Ledger for a company or business, but can also represent a Ledger for a project or department

It contains all Accounts where Transactions are recorded/posted;

continueTransactionIterator(query:

string

, continuationToken:

string

):

TransactionIterator

Resumes a transaction iteration using a continuation token from a previous iterator.

a collection of transactions that remained in a previous iterator when the continuation token was generated

createAccount(name:

string

, group?:

string

, description?:

string

):

Account

Create an Account in this book.

The type of account will be determined by the type of others Accounts in same group.

If not specified, the type ASSET (permanent=true/credit=false) will be set.

If all other accounts in same group is in another group, the account will also be added to the other group.

The created Account object

createBalancesDataTable(query:

string

):

BalancesDataTableBuilder

Create a BalancesDataTableBuilder based on a query, to create two dimensional Array representation of balances of Account, Group or #hashtag

See Query Guide to learn more

The balances data table builder

Example:

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

var balancesDataTable = book.createBalancesDataTable("#rental #energy after:8/2013 before:9/2013").build();

createTransactionsDataTable(query?:

string

):

TransactionsDataTableBuilder

Create a TransactionsDataTableBuilder based on a query, to create two dimensional Array representations of Transactions dataset.

See Query Guide to learn more

Transactions data table builder.

Example:

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

var transactionsDataTable = book.createTransactionsDataTable("acc:'Bank' after:8/2013 before:9/2013").build();

formatDate(date:

Date

, timeZone?:

string

):

string

The date formated according to date pattern of book

formatValue(value:

number

):

string

The value formated according to DecimalSeparator and fraction digits of Book

getAccount(idOrName:

string

):

Account

Gets an Account object

The matching Account object

getAccounts():

Account

[]

Gets all Accounts of this Book

getBalanceReport(query:

string

):

BalancesReport

getBalancesReport(query:

string

):

BalancesReport

Create a BalancesReport based on query

getDatePattern():

string

The date pattern of the Book. Example: dd/MM/yyyy

getDecimalSeparator():

DecimalSeparator

The decimal separator of the Book

getFractionDigits():

number

The number of fraction digits (decimal places) supported by this Book

getGroup(idOrName:

string

):

Group

Gets a Group object

The matching Group object

getGroups():

Group

[]

Gets all Groups of this Book

getId():

string

Same as bookId param

getLastUpdateMs():

number

The last update date of the book, in in milliseconds

getLocale():

string

getName():

string

The name of this Book

getOwnerName():

string

The name of the owner of the Book

getPermission():

Permission

The permission for the current user

getSavedQueries(): []

Gets all saved queries from this book

getTimeZone():

string

The time zone of the book

getTimeZoneOffset():

number

The time zone offset of the book, in minutes

getTransactions(query?:

string

):

TransactionIterator

Get Book transactions based on a query.

See Query Guide to learn more

The Transactions result as an iterator.

Example:

var book = BkperApp.loadBook("agtzfmJrcGVyLWhyZHITCxIGTGVkZ2VyGICAgIDggqALDA");

var transactions = book.getTransactions("acc:CreditCard after:28/01/2013 before:29/01/2013");

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

record(transactions:

string

|

any

[] |

any

[][], timeZone?:

string

):

void

Record Transactions a on the Book.

The text is usually amount and description, but it can also can contain an informed Date in full format (dd/mm/yyyy - mm/dd/yyyy).

Example:

book.record("#gas 63.23");

Group

This class defines a Group of Accounts.

Accounts can be grouped by different meaning, like Expenses, Revenue, Assets, Liabilities and so on

Its useful to keep organized and for high level analysis.

getAccounts():

Account

[]

All Accounts of this group.

getId():

string

The id of this Group

getName():

string

The name of this Group

hasAccounts():

boolean

True if this group has any account in it

Transaction

This class defines a Transaction between credit and debit Accounts.

A Transaction is the main entity on the Double Entry Bookkeeping system.

getAccountBalance(raw?:

boolean

):

number

Gets the balance that the Account has at that day, when listing transactions of that Account.

Evolved balances is returned when searching for transactions of a permanent Account.

Only comes with the last posted transaction of the day.

getAmount():

number

The amount of the transaction

getCreditAccount():

Account

The credit account. The same as origin account.

getCreditAccountName():

string

The credit account name.

getCreditAmount(account:

Account

|

string

):

number

Get the absolute amount of this transaction if the given account is at the credit side, else null

getDebitAccount():

Account

The debit account. The same as destination account.

getDebitAccountName():

string

The debit account name.

getDebitAmount(account:

Account

|

string

):

number

Gets the absolute amount of this transaction if the given account is at the debit side, else null

getDescription():

string

The description of this transaction

getId():

string

The id of the Transaction

getInformedDate():

Date

The date the user informed for this transaction, adjusted to book’s time zone

getInformedDateText():

string

The date the user informed for this transaction, formatted according to the date pattern of Book.

getInformedDateValue():

number

The date the user informed for this transaction. The number format is YYYYMMDD

getOtherAccount(account:

Account

|

string

):

Account

Gets the Account at the other side of the transaction given the one in one side.

getOtherAccountName(account:

string

|

Account

):

string

The account name at the other side of the transaction given the one in one side.

getPostDate():

Date

The date time user has recorded/posted this transaction

getPostDateText():

string

The date time user has recorded/posted this transaction, formatted according to the date pattern of Book.

getTags():

string

[]

All #hashtags used on the transaction

getUrls():

string

[]

All urls of the transaction

hasTag(tag:

string

):

boolean

Check if the transaction has the specified tag

isPosted():

boolean

True if transaction was already posted to the accounts. False if is still a Draft.

TransactionIterator

An iterator that allows scripts to iterate over a potentially large collection of transactions.

getBook():

Book

Gets the Book that originate the iterator

getContinuationToken():

string

Gets a token that can be used to resume this iteration at a later time.

This method is useful if processing an iterator in one execution would exceed the maximum execution time.

Continuation tokens are generally valid short period of time.

getFilteredByAccount():

Account

Return an account if query is filtering by a single account

hasNext():

boolean

Determines whether calling next() will return a transaction.

next():

Transaction

Gets the next transaction in the collection of transactions.

setContinuationToken(continuationToken:

string

):

void

Sets a continuation token from previous paused iteration

TransactionsDataTableBuilder

A TransactionsDataTableBuilder is used to setup and build two-dimensional arrays containing transactions.

Defines whether the value should add Attachments links

This builder with respective add attachment option.

build():

any

[][]

A two-dimensional array containing all Transactions.

Defines whether the dates should be formatted, based on date patter of the Book

This builder with respective formatting option.

Defines whether the value should be formatted based on DecimalSeparator of the Book

This builder with respective formatting option.

getFilteredByAccount():

Account

Return an account if query is filtering by a single account

BalanceType Enum

Enum that represents balance types.

Name
Description
CUMULATIVE

Cumulative balance

PERIOD

Period balance

TOTAL

Total balance

DecimalSeparator Enum

Decimal separator of numbers on book

Name
Description
COMMA

,

DOT

.

Periodicity Enum

The Periodicity of the query. It may depend on the level of granularity you write the range params.

Name
Description
DAILY

Example: after:25/01/1983, before:04/03/2013, after:$d-30, before:$d, after:$d-15/$m

MONTHLY

Example: after:jan/2013, before:mar/2013, after:$m-1, before:$m

YEARLY

Example: on:2013, after:2013, $y

Permission Enum

Enum representing permissions of user in the Book

Learn more at share article.

Name
Description
EDITOR

Manage accounts, transactions, book configuration and sharing

NONE

No permission

OWNER

Manage everything, including book visibility and deletion. Only one owner per book.

POST

View transactions, accounts, record and delete drafts

RECORD_ONLY

Record and delete drafts only. Useful to collect data only

VIEWER

View transactions, accounts and balances.

Questions?

Help Center