Integrated Web Server

Documentation •
In this article

Banana Accounting has an integrated web server that allow to access the accounting data through a browser or another software through a RESTful API, that can be accessed through with an http protocol. 

This feature is only available with the Advanced plan.

Excel, Word, Access and other software have the ability to integrate documents and data made available through the internet protocol.

For security reasons, the web server can't be used to write to the accounting file, and Banana Accounting+ can't connect to external URLs.

Starting the web server

The web server enables you to access the accounting data through http.
The web server is started from the Program Options dialog under the Tools menu.

RestAPI Navigator

Once the web server is started you can navigate to the server by typing the address "http://localhost:8081/" in your browser.

Once you connect to the server will open a RestAPI navigator, that allows you to navigate the files opened in Banana Accounting Files and their content. 

  • See the list of all open file.
  • See the list of
    • Tables
    • Columns
    • Available commands
  • Access the content in different format 

The URL you see on the browser is the one you will use in the RestApi.
 

Settings

The settings of the file server, like the listening port number and others, are stored in the httpconfig.ini file.

The location of the file is the following:

  • Windows: "C:/Users/{user_name}/AppData/Local/Banana.ch/BananaPlus/10.0/httpconfig.ini"
  • Mac: "/Users/{user_name}/Library/Application Support/Banana.ch/BananaPlus/10.0/httpconfig.ini"
  • Linux: "/home/{user_name}/.local/share/data/Banana.ch/BananaPlus/10.0/httpconfig.ini"

In case the file is not found as indicated above, you can follow the steps below to find and access it:

  • Click on menu Tools > Program Options.
  • Select the tab Advanced.
  • Click on System info button under Develop section.
  • Select the entry Web Server > Settings file path.
  • Click on Open path button to open the directory where the httpconfig.ini file is located.
  • Open the file httpconfig.ini with any text editor to edit the file.
    To apply the changes made in the httpconfig.ini file it's required to save the file, close and reopen Banana Accounting Plus.


     

Certificates

The web server can operate in either HTTP and HTTPS mode.
If you want to use HTTPS, you must provide your own certificate and private key by saving them (.key and .pem files) in the Ssl directory of Banana application and update the sslCertFile and sslKeyFile parameters in the `httpconfig.ini` file to match the names of these files.

Windows example:

[Https]
sslKeyFile=C:/Users/username/AppData/Roaming/Banana.ch/BananaPlus/10.0/Ssl/banana-server.key
sslCertFile=C:/Users/username/AppData/Roaming/Banana.ch/BananaPlus/10.0/Ssl/banana-server.pem

macOS example:

[Https]
sslKeyFile=/Users/username/Library/Application Support/Banana.ch/BananaPlus/10.0/Ssl/banana-server.key
sslCertFile=/Users/username/Library/Application Support/Banana.ch/BananaPlus/10.0/Ssl/banana-server.pem

Security

The web server provides several security settings to help protect access to the accounting data and to control which requests are accepted:

  • an access token (or password) can be configured to protect against unauthorized access using Banana/accessToken parameter. Further details on configuring and using the access token are provided later in this section.
  • define the trusted hostnames (since version 10.2.16) that web server accepts incoming requests from. The list of hostnames is set in the Banana/allowedHosts parameter and helps protecting against DNS rebinding attacks by ensuring that the web server only accepts requests addressed to trusted hostnames.
    Although not recommended, hostname validation can be disabled by setting this parameter to *.
  • define which origins are allowed to access the web server through cross-origin requests (CORS) using the Banana/accessControlAllowOrigin parameter. Specify the origins to allow, including the protocol (HTTP or HTTPS) and, if applicable, the port number.
    The settings parameter Banana/accessControlAllowOrigin=https://www.banana.ch+is needed to allow the Banana Excel Addin to access the web server. Although not recommended, you can use * to allow requests from any origin.
[Banana]
accessControlAllowOrigin=https://www.banana.ch+accessToken=MyPasswordX
allowedHosts=127.0.0.1, localhost

In this case the caller have to send the request with the same accessToken set in the http header "X-Banana-Access-Token" or in the query parameter "acstkn". If the token doesn't match the server will answer with a 401 unauthorized.

http://localhost:8081/v2?acstkn=MyPasswordX+

Since version 10.2.12 of Banana Accounting, a password is required to use the web server.

Banana provides two options for using the required password:

  • authenticationMode=random-token
    • Every time the web server is started, the program automatically sets a random access token.
    • The generated random access token is written in the file webserver-session.json.
      To see the session file path:
      • use the command Tools > Program Options > Advanced > System Info
      • Scroll down and find the Web Server > Session file path.
    • This access token must to be used when accessing the web server.
  • authenticationMode=fixed-token
    • When setting a personal access token, in the httpcofing.ini file:
      • write the password in the accessToken parameter.
      • set the parameter authenticationMode to fixed-token.
    • This ensure the program uses the personal chosen password and not the random one.

To see the actual access token (personal or auto generated):

  • Go to Tools > Program Options > Advanced > System Info.
  • Scroll down and find the Web Server > Active access token.
  • You can copy the access token by selecting the row, and using the command CTRL+C (Windows) or CMD+C (macOS). Only the access token string will be copied.

API

The latest version of Banana Accounting Plus (version 10.1.7 or more recent) support both versions V1 and V2.

Previous versions of Banana Accounting support only the V1 version. The version V1 is no longer developed.

  • API Version V2
    This is the currently developed version. It is supported by Banana Accounting Plus (version 10.1.7 or more recent).
    This version is fully compatible with V1 version (what worked with V1 also works with V2).
  • API Version V1 (outdated)
    This is the legacy version, supported by Banana9 and BananaPlus. It is no longer developed.

Data formats

Date

Date values are in ISO 8601 format 'YYYY-MM-DD'.

Decimal

Decimal values have a '.' (dot) as decimal separator and doesn't have a group separator. For example: '12345.67'.
Decimal values are rounded according to the accounting settings.

Text

Text values can contain any character supported by UTF-8.

Time

Time values are in ISO 8601 format 'HH:MM:SS'. The formats 'HH:MM' and 'HH:MM:SS.ZZZ are also accepted.

help_id
webserver
How can we help you better?

Let us know what topic we should expand or add to make this page more useful.

Send us your feedback

Share this article: Twitter | Facebook | LinkedIn | Email