API Version V2 (Send Data)

Create a new file (POST method)

This method allows to programmatically create a new accounting file and apply a Document change element.

This method is similar to using a command File > Create New file.

• Create a complete new file.
• Create a new file using an existing file that is sent within the body.
• Plus you can specify a JSon Document change with data (Transactions,Accounts) to add or remove from the file.

You can use this method for experimenting with sending data to the Banana Accounting Engine. Currently it does not provide a mechanism to check that the data that has been send is correct.
Once the file is created is displayed within a Window in Banana Accounting and you can than: 

• Manually apply any command like:
  • See that the JSon Document Change give the necessary result.
  • Verify that the data is correct using the Action > Recalculate command. 
  • Print a Balance Sheet and other reports.
  • Adding or deleting data.
  • Save the file to a disk.
  • Close the file when finished.
• Use the other Rest API to retrieve information programmatically.

Examples:

/v2/doc?show
/v2/doc?show&acstkn=1234

POST method

Contrary to other request, this one send also data using a a POST request method that:

This use the https method POST with following parameters:

• method: POST
• headers: {'Content-Type': 'application/json'}
• body: JSon

Return value:

• Currently the method does not verify that the data is correct.

Programming information:

• The following examples use TypeScript both with Deno or Excel.
• You can use any programming language to create a JSon and sent the Post request to the Banana integrated webserver. 

// example of using fetch
const response = await fetch(url, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(httpBody)
        }

Body is a Json structure that can contains the following data

• fileType: JSon structure with the File Type to be created
  • accountingType 
    An object containing the Filetype
    See Info Section of the Banana.Document method.
  • ac2
    A base64 encoded data containing a full ac2 file.
  •  title
    A string with the name of the file to be displayed
• data: the JSon Document change that will be applied to the file. 

Example of a request that create a full new file

// Body of the request using a fileType
        const httpBody = {
            fileType: {
                accountingType: {
                    FileTypeGroup: 100,  // double entry accounting
                    FileTypeNumber: 100,    // double entry
                    decimals: 2    // number of decimals
                }
            },
            data: jsonData,  // Json encoded doc change file
        }

Example of a request that send an existing file

// Body of the request using an existing file
        const httpBody = {
            fileType: {
	            ac2: ac2Base64, // base 64 encoded ac2 file
                title: "Company Example"
            },
            data: jsonData,  // Json encoded doc change file
        }

Example for creating a new file

This example use using Typescript for Microsoft Excel Office Scripts:

async function createAc2(jsonData: JSON) {

    // Web server url
    let _LOCALHOST = "http://localhost:8081"; // for macOS use "https://127.0.0.1:8089";

    // Web server password
    let _PASSWORD = "MyPasswordX";

    // Request to Banana web server
    let url = _LOCALHOST + "/v2/doc?show&acstkn=" + _PASSWORD;

    // Accounting type parameters
    let fileTypeGroup = 100; // Double entry accounting
    let fileTypeNumber = 100; // without VAT
    let fileDecimals = 2;

    try {
        // Body of the request
        const httpBody = {
            fileType: {
                accountingType: {
                    docGroup: fileTypeGroup,
                    docApp: fileTypeNumber,
                    decimals: fileDecimals
                }
            },
            data: jsonData,
        }

        const response = await fetch(url, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(httpBody)
        });

    } catch (error) {
        console.log(error);
    }
}

jsonData is the structured JSON containing the accounting data. 
For more information you can find the complete code example to run in Excel Office Scripts is available on the:

•  Example 3: How to create a new accounting file using data taken from Excel .

Example using an existing AC2 file

This example use Typescript for deno.

// bananaClient.createAc2('./src/Resources/double_entry_with_vat.ac2', docChangeObj);

FINANCIAL_PLAN_SHOW_URL = http://localhost:8081/v2/doc?show&acstkn=1234
    /**
    Create a the file in Banana and Show it in Banana 
       * @param accType The path to the ac2 file to use as a base.
       * @param docChange The document change that add accounts, transactions or budgets.
       * @returns
       */
      public async createAc2(ac2FileName: string, docChange: DocumentChange): Promise<boolean> {
          try {
              // Body of the request
              const data = Deno.readFileSync(ac2FileName);
              const ac2Base64 = encode(data);
              const httpBody = {
                  fileType: {
                      ac2: ac2Base64,
                      title: "Fiancial Forecast"
                  },
                  data: docChange.toJson()
              }

              // Request to Banana server
              const httpClientTest = new HttpClient();
              await httpClientTest.postData(BananaClient.FINANCIAL_PLAN_SHOW_URL, JSON.stringify(httpBody), 'application/json');
              return true;
          } catch (error) {
              const err = String(error);
              if(err.includes("error 10061")){
                  console.log("Errore di connessione con BananaPlus, verificare che l'applicazione sia attiva!");

                  console.log("Dettaglio errore: " + err);
              }
              return false;
          }
      }

Retrieving data programmatically

Once you have created a new file, you can retrieve data programmatically with the RestAPI, in this way:

• Manually use the command Save As and give a name of the file. 
• Use the RestAPI with using the file name you have saved.
• Once you are done, close the file manually.

Modify and existing file programmatically

Currently the API does not allow to modify and existing file.

If you need to modify and existing file you need to proceed this way:

• Use the API to create a new file, by sending:
  • The content of the existing file 
  • The JSon DocumentChange with the necessary changes.
• Manually use the Save As command to overwrite the existing file.