BkperApp

The main entry point to interact with BkperApp

Script ID: 1hMJszJGSUVZDB3vmsWrUZfRhY1UWbhS0SQ6Lzl06gm1zhBF3ioTM7mpJ

getBook(id:

string

):

Book

Gets the Book with the specified bookId from url param.

This is the main Entry Point to start interacting with the bkper-gs library.

Example:

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

getBooks():

Book

[]

Gets all Books the user has access.

newAmount(n:

number

|

string

|

Amount

):

Amount

Create a new Amount wrapping a given number, or arbitrary-precision math calculations.

normalizeName(name:

string

):

string

Normalize a name

setApiKey(key:

string

|

null

):

void

Sets the API key to identify the agent.

API keys are intended for agent identification only, not for authentication. Learn more

See how to create your api key here.

setOAuthTokenProvider(tokenProvider:

OAuthTokenProvider

):

void

Sets the OAuthTokenProvider.

If none set, the default built-in ScriptApp will be used.

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.

addGroup(group:

string

|

Group

):

Account

Add a group to the Account.

Returns This Account, for chainning.

create():

Account

Perform create new account.

Returns The created Account, for chainning.

deleteProperty(key:

string

):

Account

Delete a custom property

Returns This Account, for chainning.

getBalance():

Amount

Gets the balance on the current month, based on the credit nature of this Account.

Returns The balance of this account.

getBalanceRaw():

Amount

Gets the raw balance on the current month, no matter the credit nature of this Account.

Returns The balance of this account.

getDescription():

string

Gets the account description

deprecated ** Use properties instead

getGroups():

Group

[]

Get the Groups of this account.

getId():

string

Gets the account internal id.

getName():

string

Gets the account name.

getNormalizedName():

string

Returns The name of this account without spaces or special characters.

getProperties(): any

Gets the custom properties stored in this Account.

getProperty(keys:

string

[]):

string

Gets the property value for given keys. First property found will be retrieved

getPropertyKeys():

string

[]

Gets the custom properties keys stored in this Account.

getType():

AccountType

Returns The type for of this account.

hasTransactionPosted():

boolean

Tell if the Account has any transaction already posted.

Accounts with transaction posted, even with zero balance, can only be archived.

isActive():

boolean

Tell if this account is Active or otherwise Archived.

deprecated ** Use isArchived instead

isArchived():

boolean

Tell if this account is 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.

Returns True if its a permanent Account

remove():

Account

Perform delete account.

removeGroup(group:

string

|

Group

):

Account

Remove a group from the Account.

setArchived(archived:

boolean

):

Account

Set account archived/unarchived.

Returns This Account, for chainning.

setGroups(groups:

string

[] |

Group

[]):

Account

Sets the groups of the Account.

Returns This Account, for chainning.

setName(name:

string

):

Account

Sets the name of the Account.

Returns This Account, for chainning.

setProperties(properties: any):

Account

Sets the custom properties of the Account

Returns This Account, for chainning.

setProperty(key:

string

, value:

string

):

Account

Sets a custom property in the Account.

Returns This Account, for chainning.

setType(type:

AccountType

):

Account

Sets the type of the Account.

Returns This Account, for chainning

update():

Account

Perform update account, applying pending changes.

AccountsDataTableBuilder

A AccountsDataTableBuilder is used to setup and build two-dimensional arrays containing accounts.

archived(include:

boolean

):

AccountsDataTableBuilder

Defines whether the archived accounts should included.

Returns This builder, for chaining.

build():

any

[][]

Returns A two-dimensional array containing all Accounts.

groups(include:

boolean

):

AccountsDataTableBuilder

Defines whether include account groups.

Returns This builder with respective include groups option, for chaining.

properties(include:

boolean

):

AccountsDataTableBuilder

Defines whether include custom account properties.

Returns This builder with respective include properties option, for chaining.

Amount

This class defines an amount for arbitrary-precision decimal arithmetic.

It inherits methods from big.js library

abs():

Amount

Returns an absolute Amount.

cmp(n:

number

|

string

|

Amount

):

-1

|

0

|

1

Compare

div(n:

number

|

string

|

Amount

):

Amount

Divide by

eq(n:

number

|

string

|

Amount

):

boolean

Equals to

gt(n:

number

|

string

|

Amount

):

boolean

Greater than

gte(n:

number

|

string

|

Amount

):

boolean

Greater than or equal

lt(n:

number

|

string

|

Amount

):

boolean

Less than

lte(n:

number

|

string

|

Amount

):

boolean

Less than or equal to

minus(n:

number

|

string

|

Amount

):

Amount

Minus

mod(n:

number

|

string

|

Amount

):

Amount

Modulo - the integer remainder of dividing this Amount by n.

Similar to % operator

plus(n:

number

|

string

|

Amount

):

Amount

Sum

round(dp?:

number

):

Amount

Round to a maximum of dp decimal places.

times(n:

number

|

string

|

Amount

):

Amount

Multiply

toFixed(dp?:

number

):

string

Returns a string representing the value of this Amount in normal notation to a fixed number of decimal places dp.

toNumber():

number

Returns a primitive number representing the value of this Amount.

toString():

string

Returns a string representing the value of this Amount.

App

This class defines an App installed in a Book.

getDescription():

string

Returns The description of this App

getId():

string

Returns The id of this App

getName():

string

Returns The name of this App

Backlog

This class defines the Backlog of a Book.

A Backlog is a list of pending bot tasks in a Book

getCount():

number

Returns The count of this Backlog

Balance

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

getCumulativeBalance():

Amount

The cumulative balance to the date, based on the credit nature of the container

getCumulativeBalanceRaw():

Amount

The raw cumulative balance to the date.

getCumulativeCredit():

Amount

The cumulative credit to the date.

getCumulativeDebit():

Amount

The cumulative debit to the date.

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():

Amount

The balance on the date period, based on credit nature of the container.

getPeriodBalanceRaw():

Amount

The raw balance on the date period.

getPeriodCredit():

Amount

The credit on the date period.

getPeriodDebit():

Amount

The debit on the date period.

getYear():

number

The year of the balance

BalancesContainer

The container of balances of an Account or Group

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

addBalancesContainer(container:

BalancesContainer

):

BalancesContainer

Adds an Account container to a Group container.

NOTE: Only for Group balance containers.

createDataTable():

BalancesDataTableBuilder

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

getAccount():

Account

The Account associated with this container

getAccountBalancesContainers():

BalancesContainer

[]

Gets all Account BalancesContainers.

getBalances():

Balance

[]

All Balances of the container

getBalancesContainer(name:

string

):

BalancesContainer

Gets a specific BalancesContainer.

getBalancesContainers():

BalancesContainer

[]

Gets all child BalancesContainers.

NOTE: Only for Group balance containers. Accounts returns null.

getBalancesReport():

BalancesReport

The parent BalancesReport of the container

getCumulativeBalance():

Amount

The cumulative balance to the date.

getCumulativeBalanceRaw():

Amount

The cumulative raw balance to the date.

getCumulativeBalanceRawText():

string

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

getCumulativeBalanceText():

string

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

getCumulativeCredit():

Amount

The cumulative credit to the date.

getCumulativeCreditText():

string

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

getCumulativeDebit():

Amount

The cumulative debit to the date.

getCumulativeDebitText():

string

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

getDepth():

number

The depth in the parent chain up to the root.

getGroup():

Group

The Group associated with this container

getName():

string

The Account or Group name

getNormalizedName():

string

The Account or Group name without spaces or special characters.

getParent():

BalancesContainer

The parent BalanceContainer

getPeriodBalance():

Amount

The balance on the date period.

getPeriodBalanceRaw():

Amount

The raw balance on the date period.

getPeriodBalanceRawText():

string

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

getPeriodBalanceText():

string

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

getPeriodCredit():

Amount

The credit on the date period.

getPeriodCreditText():

string

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

getPeriodDebit():

Amount

The debit on the date period.

getPeriodDebitText():

string

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

getProperties(): any

Gets the custom properties stored in this Account or Group.

getProperty(keys:

string

[]):

string

Gets the property value for given keys. First property found will be retrieved

getPropertyKeys():

string

[]

Gets the custom properties keys stored in the associated Account or Group.

hasGroupBalances():

boolean

Tell if the balance container is from a parent group

isCredit():

boolean

Gets the credit nature of the BalancesContainer, based on Account or Group.

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.

isFromAccount():

boolean

Tell if this balance container if from an Account

isFromGroup():

boolean

Tell if this balance container if from a Group

isPermanent():

boolean

Tell if this balance container is permament, based on the Account or Group.

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

They are also called Real Accounts

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

Returns True if its a permanent Account

removeBalancesContainer(container:

BalancesContainer

):

BalancesContainer

Removes an Account container from a Group container.

NOTE: Only for Group balance containers.

BalancesDataTableBuilder

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

build():

any

[][]

Builds an two-dimensional array with the balances.

expanded(expanded:

boolean

|

number

):

BalancesDataTableBuilder

Defines whether Groups should expand its child accounts. true to expand itself, -1 to expand all subgroups. -2 to expand all accounts.

Returns This builder with respective expanded option, for chaining.

formatDates(format:

boolean

):

BalancesDataTableBuilder

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

Returns This builder with respective formatting option, for chaining.

formatValues(format:

boolean

):

BalancesDataTableBuilder

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

Returns This builder with respective formatting option, for chaining.

hideDates(hide:

boolean

):

BalancesDataTableBuilder

Defines whether the dates should be hidden for PERIOD or CUMULATIVE BalanceType.

Returns This builder with respective hide dates option, for chaining.

hideNames(hide:

boolean

):

BalancesDataTableBuilder

Defines whether the Accounts and Groups names should be hidden.

Returns This builder with respective hide names option, for chaining.

period(period:

boolean

):

BalancesDataTableBuilder

Defines whether should force use of period balances for TOTAL BalanceType.

Returns This builder with respective trial option, for chaining.

properties(include:

boolean

):

BalancesDataTableBuilder

Defines whether include custom Accounts and Groups properties.

Returns This builder with respective include properties option, for chaining.

raw(raw:

boolean

):

BalancesDataTableBuilder

Defines whether should show raw balances, no matter the credit nature of the Account or Group.

Returns This builder with respective trial option, for chaining.

transposed(transposed:

boolean

):

BalancesDataTableBuilder

Defines whether should rows and columns should be transposed.

For TOTAL BalanceType, the transposed table looks like:

  _____________________________
 |  Expenses | Income  |  ...  |
 | -4568.23  | 5678.93 |  ...  |
 |___________|_________|_______|

Two rows, and each Account or Group per column.

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

  _______________________________________________________________
 |            | 15/01/2014 | 15/02/2014 | 15/03/2014 |    ...    |
 |  Expenses  | -2345.23   | -2345.93   | -2456.45   |    ...    |
 |  Income    |  3452.93   |  3456.46   |  3567.87   |    ...    |
 |     ...    |     ...    |     ...    |     ...    |    ...    |
 |____________|____________|____________|____________|___________|

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

Returns This builder with respective transposed option, for chaining.

trial(trial:

boolean

):

BalancesDataTableBuilder

Defines whether should split TOTAL BalanceType into debit and credit.

Returns This builder with respective trial option, for chaining.

Fluent method to set the BalanceType for the builder.

Returns This builder with respective balance type, for chaining.

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.

getAccountBalancesContainers():

BalancesContainer

[]

Gets all Account BalancesContainers.

getBalancesContainer(name:

string

):

BalancesContainer

Gets a specific BalancesContainer.

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;

addCollaborator(email:

string

, permission:

Permission

):

void

Adds a collaborator to the Book.

audit():

void

Trigger Balances Audit async process.

batchCheckTransactions(transactions:

Transaction

[]):

void

Batch check Transactions on the Book.

batchCreateAccounts(accounts:

Account

[]):

Account

[]

Create Accounts on the Book, in batch.

Returns The Accounts created

batchCreateGroups(groups:

Group

[]):

Group

[]

Create Groups on the Book, in batch.

Returns The Groups created

batchCreateTransactions(transactions:

Transaction

[]):

Transaction

[]

Batch create Transactions on the Book.

Returns The Transactions created

batchTrashTransactions(transactions:

Transaction

[], trashChecked?:

boolean

):

void

Batch trash Transactions on the Book.

batchUncheckTransactions(transactions:

Transaction

[]):

void

Batch uncheck Transactions on the Book.

batchUpdateTransactions(transactions:

Transaction

[], updateChecked?:

boolean

):

void

Batch update Transactions on the Book.

continueTransactionIterator(query:

string

, continuationToken:

string

):

TransactionIterator

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

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

countTransactions(query?:

string

):

number

Retrieve the number of transactions based on a query.

Returns The number of matching Transactions

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.

Returns The created Account object

deprecated **

createAccounts(accounts:

string

[][]):

Account

[]

Create Accounts on the Book, in batch.

The first column of the matrix will be used as the Account name.

The other columns will be used to find a matching AccountType.

Names matching existent accounts will be skipped.

deprecated **

createAccountsDataTable():

AccountsDataTableBuilder

Create a AccountsDataTableBuilder, to build two dimensional Array representations of Accounts dataset.

Returns Accounts data table builder.

Example:

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

var accountsDataTable = book.createAccountsDataTable().build();

createBalancesDataTable(query:

string

):

BalancesDataTableBuilder

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

See Query Guide to learn more

Returns The balances data table builder

Example:

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

var balancesDataTable = book.createBalancesDataTable("account:'Credit card' after:7/2018 before:8/2018").build();

createGroups(groups:

string

[]):

Group

[]

Create Groups on the Book, in batch.

deprecated **

createGroupsDataTable():

GroupsDataTableBuilder

Create a GroupsDataTableBuilder, to build two dimensional Array representations of Groups dataset.

Returns Groups data table builder.

Example:

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

var groupsDataTable = book.createGroupsDataTable().build();

createTransactionsDataTable(query?:

string

):

TransactionsDataTableBuilder

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

See Query Guide to learn more

Returns Transactions data table builder.

Example:

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

var transactionsDataTable = book.createTransactionsDataTable("account:'Bank Account' before:1/2019").build();

deleteProperty(key:

string

):

Book

Delete a custom property

Returns This Book, for chainning.

formatAmount(amount:

Amount

):

string

Formats an amount according to DecimalSeparator and fraction digits of the Book.

Returns The value formated

formatDate(date:

Date

, timeZone?:

string

):

string

Formats a date according to date pattern of the Book.

Returns The date formated

formatValue(value:

Amount

):

string

Formats a value according to DecimalSeparator and fraction digits of the Book.

Returns The value formated

deprecated **

getAccount(idOrName:

string

):

Account

Gets an Account object

Returns The matching Account object

getAccounts():

Account

[]

Returns All Accounts of this Book

getApps():

App

[]

Retrieve installed Apps for this Book

Returns The Apps objects

getBacklog():

Backlog

Retrieve the pending events Backlog for this Book

Returns The Backlog object

getBalancesReport(query:

string

):

BalancesReport

Create a BalancesReport based on query

Returns The balances report

Example:

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

var balancesReport = book.getBalancesReport("group:'Equity' after:7/2018 before:8/2018");

var accountBalance = balancesReport.getBalancesContainer("Bank Account").getCumulativeBalance();

getClosingDate():

string

Returns The closing date of the Book in ISO format yyyy-MM-dd

getCollection():

Collection

Returns The collection of this book

getDatePattern():

string

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

getDecimalSeparator():

DecimalSeparator

Returns The decimal separator of the Book

getEvents(afterDate?:

string

, beforeDate?:

string

, onError?:

boolean

, resource?:

Transaction

|

Account

|

Group

):

EventIterator

Get Book events based on search parameters.

Returns The Events result as an iterator.

getFile(id:

string

):

File

Retrieve a File by id

Returns The matching File object

getFractionDigits():

number

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

getGroup(idOrName:

string

):

Group

Gets a Group object

Returns The matching Group object

getGroups():

Group

[]

Returns All Groups of this Book

getId():

string

Same as bookId param

Returns The id of this Book

getLastUpdateMs():

number

Returns The last update date of the book, in in milliseconds

getLockDate():

string

Returns The lock date of the Book in ISO format yyyy-MM-dd

getName():

string

Returns The name of this Book

getOwnerName():

string

Returns The name of the owner of the Book

getPeriodStartMonth():

Month

Returns The start month when YEAR period set

getPermission():

Permission

Returns The permission for the current user

getProperties(): any

Returns The custom properties stored in this Book

getProperty(keys:

string

[]):

string

Returns The property value for given keys. First property found will be retrieved

getSavedQueries(): []

Returns All saved queries from this book

getTimeZone():

string

Returns The time zone of the Book

getTimeZoneOffset():

number

Returns The time zone offset of the book, in minutes

getTotalTransactions():

number

Returns The total number of posted transactions

getTotalTransactionsCurrentMonth():

number

Returns The total number of posted transactions on current month

getTotalTransactionsCurrentYear():

number

Returns The total number of posted transactions on current year

getTransaction(id:

string

):

Transaction

Retrieve a Transaction by id

Returns The matching Transaction object

getTransactions(query?:

string

):

TransactionIterator

Get Book transactions based on a query.

See Query Guide to learn more

Returns The Transactions result as an iterator.

Example:

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

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

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

newAccount():

Account

Instantiate a new Account

Returns The new Account, for chainning.

Example:

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

book.newAccount()
 .setName('Some New Account')
 .setType('INCOMING')
 .addGroup('Revenue').addGroup('Salary')
 .setProperties({prop_a: 'A', prop_b: 'B'})
 .create();

newFile():

File

Instantiate a new File

Returns The new File, for chainning.

Example:

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

book.newFile()
 .setBlob(UrlFetchApp.fetch('https://bkper.com/images/index/integrations4.png').getBlob())
 .create();

newGroup():

Group

Instantiate a new Group

Returns The new Group, for chainning.

Example:

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

book.newGroup()
 .setName('Some New Group')
 .setProperty('key', 'value')
 .create();

newTransaction():

Transaction

Instantiate a new Transaction

Returns The new Transaction, for chainning.

Example:

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

book.newTransaction()
 .setDate('2013-01-25')
 .setDescription("Filling tank of my truck")
 .from('Credit Card')
 .to('Gas')
 .setAmount(126.50)
 .create();

parseAmount(value:

string

):

Amount

Parse an amount string according to DecimalSeparator and fraction digits of the Book.

Returns The Amount parsed

parseDate(date:

string

):

Date

Parse a date string according to date pattern and timezone of the Book.

Also parse ISO yyyy-mm-dd format.

Returns The date parsed

parseValue(value:

string

):

Amount

Parse a value string according to DecimalSeparator and fraction digits of the Book.

deprecated **

record(transactions:

string

|

any

[] |

any

[][], timeZone?:

string

):

void

Record Transactions 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");

deprecated **

removeCollaborator(email:

string

):

void

Removes a collaborator from the Book.

round(amount:

Amount

):

Amount

Rounds an amount according to the number of fraction digits of the Book

Returns The Amount rounded

setClosingDate(closingDate:

string

|

null

):

Book

Sets the closing date of the Book in ISO format yyyy-MM-dd.

Returns This Book, for chainning.

setDatePattern(datePattern:

string

):

Book

Sets the date pattern of the Book. Current: dd/MM/yyyy MM/dd/yyyy yyyy/MM/dd

Returns This Book, for chainning.

setDecimalSeparator(decimalSeparator:

DecimalSeparator

):

Book

Sets the decimal separator of the Book

Returns This Book, for chainning.

setFractionDigits(fractionDigits:

number

):

Book

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

Returns This Book, for chainning.

setLockDate(lockDate:

string

|

null

):

Book

Sets the lock date of the Book in ISO format yyyy-MM-dd.

Returns This Book, for chainning.

setName(name:

string

):

Book

Sets the name of the Book.

Returns This Book, for chainning.

setPeriodStartMonth(month:

Month

):

Book

Sets the start month when YEAR period set

Returns This Book, for chainning.

setProperties(properties: any):

Book

Sets the custom properties of the Book

Returns This Book, for chainning.

setProperty(key:

string

, value:

string

):

Book

Sets a custom property in the Book.

Returns This Book, for chainning.

setTimeZone(timeZone:

string

):

Book

Sets the time zone of the Book

Returns This Book, for chainning.

update():

Book

Perform update Book, applying pending changes.

Returns This Book, for chainning.

BotResponse

This class defines a Bot Response associated to an Event.

getAgentId():

string

Returns The agent id of this Bot Response

getMessage():

string

Returns The message of this Bot Response

getType():

BotResponseType

Returns The type of this Bot Response

Collection

This class defines a Collection of Books.

getBooks():

Book

[]

Returns All Books of this collection.

getId():

string

Returns The id of this Collection

getName():

string

Returns The name of this Collection

Event

This class defines an Event from a Book.

An event is an object that represents an action (such as posting or deleting a Transaction) made by an actor (such as a user or a Bot acting on behalf of a user).

getBotResponses():

BotResponse

[]

Returns The bot responses associated to this Event.

getId():

string

Returns The id of the Event.

EventIterator

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

Example:

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

var eventIterator = book.getEvents('2023-10-01', '2023-11-01', true);

while (eventIterator.hasNext()) {
 var event = eventIterator.next();
 Logger.log(event);
}

getBook():

Book

Gets the Book that originated the iterator

Returns The Book object

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.

Returns The continuation token

hasNext():

boolean

Determines whether calling next() will return a transaction.

next():

Event

Gets the next event in the collection of events.

Returns The next Event object

setContinuationToken(continuationToken:

string

):

void

Sets a continuation token from a previous paused iteration.

File

This class defines a File uploaded to a Book.

A File can be attached to a Transaction or used to import data.

create():

File

Perform create new File.

getBlob():

Blob

Gets the Blob from this file

getContent():

string

Gets the file content Base64 encoded

getContentType():

string

Gets the File content type

getId():

string

Gets the File id

getName():

string

Gets the File name

getSize():

number

Gets the file size in bytes

getUrl():

string

Gets the file serving url for accessing via browser

setBlob(blob:

Blob

):

File

Sets the File properties from a Blob

Returns This File, for chainning.

setContent(content:

string

):

File

Sets the File content Base64 encoded.

Returns This File, for chainning.

setContentType(contentType:

string

):

File

Sets the File content type.

Returns This File, for chainning.

setName(name:

string

):

File

Sets the name of the File.

Returns This File, for chainning.

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.

create():

Group

Perform create new group.

Returns The created Group, for chainning.

deleteProperty(key:

string

):

Group

Delete a custom property

Returns This Group, for chainning.

getAccounts():

Account

[]

Returns All Accounts of this group.

getChildren():

Group

[]

Returns The children Groups

getDepth():

number

Returns The depth in the parent Group chain up to the root Group

getId():

string

Returns The id of this Group

getName():

string

Returns The name of this Group

getNormalizedName():

string

Returns The name of this group without spaces and special characters

getParent():

Group

Returns The parent Group

getProperties(): any

Gets the custom properties stored in this Group

getProperty(keys:

string

[]):

string

Gets the property value for given keys. First property found will be retrieved

getPropertyKeys():

string

[]

Gets the custom properties keys stored in this Group.

getRoot():

Group

Returns The root Group

getType():

AccountType

Returns The type of the group based on its accounts. Undefined if the group has accounts of different types

hasAccounts():

boolean

Returns True if this group has any account in it

hasChildren():

boolean

Tell if this group has any children

isCredit():

boolean

Tell if this is a credit (Incoming and Liabities) group

isHidden():

boolean

Tell if the Group is hidden on main transactions menu

isMixed():

boolean

Tell if this is a mixed (Assets/Liabilities or Incoming/Outgoing) group

isPermanent():

boolean

Tell if this is a permanent (Assets and Liabilities) group

remove():

Group

Perform delete group.

setHidden(hidden:

boolean

):

Group

Hide/Show group on main menu.

setName(name:

string

):

Group

Sets the name of the Group.

Returns This Group, for chainning.

setParent(group:

Group

|

null

):

Group

Sets the parent Group.

Returns This Group, for chainning.

setProperties(properties: any):

Group

Sets the custom properties of the Group

Returns This Group, for chainning.

setProperty(key:

string

, value:

string

):

Group

Sets a custom property in the Group.

update():

Group

Perform update group, applying pending changes.

GroupsDataTableBuilder

A GroupsDataTableBuilder is used to setup and build two-dimensional arrays containing groups.

build():

any

[][]

Returns A two-dimensional array containing all Groups.

properties(include:

boolean

):

GroupsDataTableBuilder

Defines whether include custom group properties.

Returns This builder with respective include properties option, for chaining.

OAuthTokenProvider

Interface to provide OAuth2 tokens upon calling the API.

Implement your own if you need to use one other than the default built-in ScriptApp.

Its specially usefull on environments where you can use the built-in ScriptApp services such as Custom Functions in Google Sheets.

Learn more how to OAuth 2 library for Google Apps Script

getOAuthToken():

string

A valid OAuth2 access token with email scope authorized.

Transaction

This class defines a Transaction between credit and debit Accounts.

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

addFile(file:

File

|

Blob

):

Transaction

Adds a file attachment to the Transaction.

Files not previously created in the Book will be automatically created.

Returns This Transaction, for chainning.

addRemoteId(remoteId:

string

):

Transaction

Add a remote id to the Transaction.

Returns This Transaction, for chainning.

addUrl(url:

string

):

Transaction

Add a url to the Transaction. Url starts with https://

Returns This Transaction, for chainning.

check():

Transaction

Perform check transaction.

create():

Transaction

Perform create new draft transaction.

deleteProperty(key:

string

):

Transaction

Delete a custom property

Returns This Transaction, for chainning.

from(account:

string

|

Account

):

Transaction

Set the credit/origin Account of the Transaction. Same as setCreditAccount().

Returns This Transaction, for chainning.

getAccountBalance(raw?:

boolean

):

Amount

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.

getAgentId():

string

Returns The id of the agent that created this transaction

getAmount():

Amount

Returns The amount of the transaction.

getCreatedAt():

Date

Returns The date the transaction was created.

getCreatedAtFormatted():

string

Returns The date the transaction was created, formatted according to the date pattern of Book.

getCreditAccount():

Account

Returns The credit account. The same as origin account.

getCreditAccountName():

string

Returns The credit account name.

getCreditAmount(account:

Account

|

string

):

Amount

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

getDate():

string

Returns The Transaction date, in ISO format yyyy-MM-dd.

getDateFormatted():

string

Returns The Transaction date, formatted on the date pattern of the Book.

getDateObject():

Date

Returns The Transaction Date object, on the time zone of the Book.

getDateValue():

number

Returns The Transaction date number, in format YYYYMMDD.

getDebitAccount():

Account

Returns The debit account. The same as destination account.

getDebitAccountName():

string

Returns The debit account name.

getDebitAmount(account:

Account

|

string

):

Amount

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

getDescription():

string

Returns The description of this transaction.

getFiles():

File

[]

Returns The files attached to the transaction.

getId():

string

Returns The id of the Transaction.

getInformedDate():

Date

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

deprecated ** Use getDateObject instead.

getInformedDateText():

string

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

deprecated ** use getDateFormatted instead

getInformedDateValue():

number

Returns The date numbe. The number format is YYYYMMDD.

deprecated ** use getDateValue instead.

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

Returns The date time user has recorded/posted this transaction.

deprecated ** use getCreatedAt instead.

getPostDateText():

string

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

deprecated ** use getCreatedAtFormatted instead.

getProperties(): any

Gets the custom properties stored in this Transaction.

getProperty(keys:

string

[]):

string

Gets the property value for given keys. First property found will be retrieved

getPropertyKeys():

string

[]

Gets the custom properties keys stored in this Transaction.

getRemoteIds():

string

[]

Remote ids are used to avoid duplication.

Returns The remote ids of the Transaction.

getTags():

string

[]

Returns All #hashtags used on the transaction.

getUrls():

string

[]

Returns All urls of the transaction.

hasTag(tag:

string

):

boolean

Check if the transaction has the specified tag.

isChecked():

boolean

Returns True if transaction is checked.

isCredit(account:

Account

):

boolean

Tell if the given account is credit on the transaction

isDebit(account:

Account

):

boolean

Tell if the given account is debit on the transaction

isLocked():

boolean

Returns True if a transaction is locked by the book lock/closing date

isPosted():

boolean

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

isTrashed():

boolean

Returns True if transaction is in trash.

post():

Transaction

Perform post transaction, changing credit and debit Account balances.

remove():

Transaction

Remove the transaction, sending to trash.

deprecated **

restore():

Transaction

Restore the transaction from trash.

deprecated **

setAmount(amount:

Amount

|

number

|

string

):

Transaction

Set the amount of the Transaction.

Returns This Transaction, for chainning.

setChecked(checked:

boolean

):

Transaction

Set the check state of the Transaction.

Returns This Transaction, for chainning.

setCreditAccount(account:

string

|

Account

):

Transaction

Set the credit/origin Account of the Transaction. Same as from().

Returns This Transaction, for chainning.

setDate(date:

string

|

Date

):

Transaction

Set the date of the Transaction.

Returns This Transaction, for chainning

setDebitAccount(account:

string

|

Account

):

Transaction

Set the debit/destination Account of the Transaction. Same as to().

Returns This Transaction, for chainning.

setDescription(description:

string

):

Transaction

Set the description of the Transaction.

Returns This Transaction, for chainning.

setProperties(properties: any):

Transaction

Set the custom properties of the Transaction

Returns This Transaction, for chainning.

setProperty(key:

string

, value:

string

):

Transaction

Set a custom property in the Transaction.

Returns This Transaction, for chainning.

setUrls(urls:

string

[]):

Transaction

Set the Transaction urls. Url starts with https://

Returns This Transaction, for chainning.

to(account:

string

|

Account

):

Transaction

Set the debit/destination Account of the Transaction. Same as setDebitAccount().

Returns This Transaction, for chainning.

trash():

Transaction

Perform trash transaction.

uncheck():

Transaction

Perform uncheck transaction.

untrash():

Transaction

Perform untrash transaction.

update():

Transaction

Upddate transaction, applying pending changes.

TransactionIterator

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

Example:

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

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

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

getAccount():

Account

Returns The account, when filtering by a single account.

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.

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.

build():

any

[][]

Returns A two-dimensional array containing all Transactions.

formatDates(format:

boolean

):

TransactionsDataTableBuilder

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

Returns This builder with respective formatting option, for chaining.

formatValues(format:

boolean

):

TransactionsDataTableBuilder

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

Returns This builder with respective formatting option, for chaining.

getAccount():

Account

Returns The account, when filtering by a single account.

includeIds(include:

boolean

):

TransactionsDataTableBuilder

Defines whether include transaction ids.

Returns This builder with respective include ids option, for chaining.

includeProperties(include:

boolean

):

TransactionsDataTableBuilder

Defines whether include custom transaction properties.

Returns This builder with respective include properties option, for chaining.

includeUrls(include:

boolean

):

TransactionsDataTableBuilder

Defines whether include attachments and url links.

Returns This builder with respective include attachment option, for chaining.

AccountType Enum

Enum that represents account types.

Name
Description
ASSET

Asset account type

INCOMING

Incoming account type

LIABILITY

Liability account type

OUTGOING

Outgoing account type

BalanceType Enum

Enum that represents balance types.

Name
Description
CUMULATIVE

Cumulative balance

PERIOD

Period balance

TOTAL

Total balance

BotResponseType Enum

Enum that represents a Bot Response type

Name
Description
ERROR

Error bot response

INFO

Info bot response

WARNING

Warning bot response

DecimalSeparator Enum

Decimal separator of numbers on book

Name
Description
COMMA

,

DOT

.

Month Enum

Enum that represents a Month.

Name
Description
APRIL

AUGUST

DECEMBER

FEBRUARY

JANUARY

JULY

JUNE

MARCH

MAY

NOVEMBER

OCTOBER

SEPTEMBER

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.

POSTER

View transactions, accounts, record and delete drafts

RECORDER

Record and delete drafts only. Useful to collect data only

VIEWER

View transactions, accounts and balances.