API Reference
Start developing plugins for BizFusion.

 

Programming


The BizFusion API is a REST based API that only supports data in JSON format.

The manual contains a reference of all the objects/operations that are available to developers.
Every Read operation returns an array of JSON objects or a single JSON object.
Each Create and Update operation expects a record in JSON format.

The API is limited to 10.000 calls per day.
Any request made after the limit will automatically result in an error.

Methods


Each object has one or more methods that you can call.
Each method has an associated URL and you invoke the method by calling its URL.

Method names start with one of the following prefixes: Get, Post, Put or Delete.
These prefixes correspond to the HTTP Get, HTTP Post, HTTP Put and HTTP Delete verbs that you
need to specify when calling the URL of the object.

HTTP Get = Retrieve data
HTTP Post = Create data
HTTP Put = Update data
HTTP Delete = Delete data

E.g. the Account object has the method Get, which returns all the ledger accounts in the system.
You simply call the URL: '/api/Account' to invoke this method.
This method returns all the ledger accounts in a JSON array.

This object also has a method called 'GetByEnumId'.
You call the URL: '/api/AccountSet/ByEnumId?enumId={some_enum_value}' to invoke this method.
This method returns a single JSON object.

The various 'Get' and 'GetByX' methods can be invoked by simply calling their URL.
But how do you create, update or delete records?

Create Records


You use the Post methods to create records.
These methods have a record parameter like e.g. AccountDTO.
You specify this parameter in the request body of your HTTP Post.
The data must be in JSON format.

E.g. the request body for a new account looks like:
{"AccountId":0, "AccountName":"Account ABC", "AccountGroupId":1}.

Note that you don't have to supply a value for field account id.
You can even leave this property out of the request body.
Primary key values are always automatically generated by the system.

Send this record in a Post request to URL: 'api/Account' and the new record will be created.
The response body will contain the newly created record.
The account id field will contain the newly created primary key.

Update Records


You use the Put methods to update records.
You first need to retrieve the record that you wish to update.
E.g. call url 'api/Account/{some_record_id}' to retrieve an account.
This will give you a record in JSON format that you can adjust.

Change the record and create a new PUT request for url: 'api/Account?id={some_record_id}'.
The body of the request contains the account that needs to be updated.
The body is in JSON format and looks like:

{"AccountId":123, "AccountName":"Account XYZ", "AccountGroupId":2, "Timestamp":"ABCDEF123"}.

Notice that the record has a timestamp value. This value is used to check for concurrency.
A concurrency exception is thrown if someone else has changed the record before you.
You need to know a record's Timestamp value before you can Update or Delete it.
That's why you always need to retrieve the record first.

The response message will contain the updated record and timestamp value.

Delete Records


You use the Delete methods to delete records.
You first need to retrieve the record before you can delete it.
This step is required, because you need to know the timestamp value of the record.
E.g. call url: 'api/Account/{some_record_id}' to retrieve an account that you want to delete.

You can then send a HTTP Delete request to url: '/api/Account?id={some_record_id}&timestamp={timestamp_value}'.
You specify the timestamp value as part of the request url.
The URL will invoke the delete method on the object.

The response will contain a boolean of the result.

Enums


Certain records can be retrieved via their enum value.
You can e.g. retrieve the Debtors account by specifying its enum value.
Each object that can be retrieved via an enum value has a 'GetByEnumId' method that you can call.
The URL for this method call looks like: '/api/AccountSet/ByEnumId?enumId=7'.

Note that the enum value does not correspond to the primary key value of the object.
The two are often the same, but that's not something that you should rely on.

Concurrency


Concurrency is handled with timestamp fields.
The system only looks at the timestamp value when you perform an update or delete.
A concurrency exception is thrown if the timestamp value has changed in the database.

Timestamp values are automatically set by the database.
That's why you always need to retrieve a record before you can update or delete it.
It's the only way to get the right timestamp value.

A timestamp is technically a byte array, but it's represented as a single Base64 encoded string
in your DTO object.

Filters


Objects have various GetById, GetByPeriod and GetByEnum methods.
It's very common to get an object by its ID.
E.g. you often want to find a customer by her ID.
But what if you want to find a customer by her name?
There is no GetByCustomerName method that you can call.
That's where filters come in.

You can call url: "/api/CustomerSet/ByField?field=CustomerName&value=Jane Doe"
to find a customer by her name.