Basic types

The API uses the following basic types:

TypeExampleFormat, when sending to APIFormat, when receiving from API
string / lstringHello WorldHello WorldHello World
number (integer)292929
float12.5912.5912.59
booleantruetrue / 1 / yes1

falsefalse / 0 / no0
emailtest@invalid.invtest@invalid.invtest@invalid.inv
date5. august 20112011-08-052011-08-05


05-08-2011


5-8-2011


05/08/2011


(etc)
time18:4518:45:0018:45:00


18:45


18.45


(etc)
binaryN/AN/AN/A


binary data should be base64 encoded.

A string should at most be 255 characters. A lstring should at most be 16.777.215 characters


Definitions

All communications are facilitated using JSON. In this documentation we use the following terms, to reference different JSON structures.

Set

A set is defined as field:value pairs, defined in JSON as:

{field1: value1, field2: value2,...}

A value can be a basic type, another set or a collection.

Collection

A collection is defined as a list of values, defined in JSON as:

[value1, value2,...]

A value can be a basic type, a set or another collection.


Envelope

All communication to the API must be contained in an envelope, as described in this section. The envelope is a set containing the following fields:

contractnumberA contract number (provided by Ventu)
usernamestringA user name (provided by Ventu)
passwordstringA password (provided by Ventu)
commandscollectionA collection of the commands which are to be executed.


The envelope can also contain the following field:

haltonerror0 or 1If set to 1, the API will halt execution if a command throws an error, otherwise the API will just continue to the next command (default behavior)
imeistringIf the client is a mobile phone, then the phone can identify itself using its phone number.
pushtokenstringIf the client can received push messages then this field specifies a token for the messages; format is <platform>:<token>
remoteagentstringThe API client can identify itself by providing a short identifier string, which will be recorded in the Microbizz log and help troubleshooting.
_privatemixedWill be included in the reply
apikeystringAn API key (provided by Ventu); this is ignored 


An example envelope can look like this in JSON:

{"contract": xxx,"apikey":"xxx","username":"xxx","password":"xxx","commands": []}

If there is an error in the envelope, the following set will be returned:

statusbooleanAlways 0 when an error occurred.
msgstringAn error message.
datedateThe date on the server, when the envelope was received.
timetimeThe time on the server, when the envelope was received.


If the envelope is correct, the following set will be returned:

statusbooleanAlways 1 when envelope is correct. This isn't an indicator for whether the commands executed.
msgstringOK
resultscollectionA collection of results for each of the provided commands, in the same order as the commands.
datedateThe date on the server, when the command execution started.
timetimeThe time on the server, when the command execution started.
millisecondsnumberHow long time it took Microbizz to generate the reply.
_privatemixedThe value from the command envelope


Command

A command is a set containing at least the following field:

commandstringThe command to be executed.


The rest of the fields in the set are determined by the command executed, but all commands may also include a uniqueid field which is used by Microbizz to try to detect if an app resends the same messages repeatedly:

uniqueidstringUnique ID of the message, should include the time+date of when the command was created, f.ex. msgid-0002342312-2019-08-30_073032-sdfkfowkk23, although the exact format is not important


Just like the envelope, each command may also include the field with private data which will be included in the reply

_privatemixedAny data, will be included in the reply

The command may also include a flag to disable executing reminder actions:

reminderactionsstringSet to "off" to disable executing reminder actions


If the command fails it will return the following set:

statusbooleanAlways 0 when an error occurred.
msgstringAn error message.
errnonumberThe error number, only relevant if status=0, see list of err numbers below


If the command succeeds it will return a set containing at least the following field:

statusbooleanAlways 1 when command succeeded.


The rest of the fields in the set are determined by the command executed.

Error numbers

Some commands may return an error number in the errno field; this is only relevant if the status field is set to 0.

Error numberMeaning
1Generic error
2Duplicate command: the command had a unique ID that has recently been seen
3Unknown command: the command unknown/misspelt/supported
900Task not found
901Not allowed to do that on a closed task
1000Check out failed because the hour registration overlapped an existing hour registration
2000Failed to save file due to lack of disc space

Basic types

The API uses the following basic types:

TypeExampleFormat, when sending to APIFormat, when receiving from API
string / lstringHello WorldHello WorldHello World
number (integer)292929
float12.5912.5912.59
booleantruetrue / 1 / yes1

falsefalse / 0 / no0
emailtest@invalid.invtest@invalid.invtest@invalid.inv
date5. august 20112011-08-052011-08-05


05-08-2011


5-8-2011


05/08/2011


(etc)
time18:4518:45:0018:45:00


18:45


18.45


(etc)
binaryN/AN/AN/A


binary data should be base64 encoded.

A string should at most be 255 characters. A lstring should at most be 16.777.215 characters


Definitions

All communications are facilitated using JSON. In this documentation we use the following terms, to reference different JSON structures.

Set

A set is defined as field:value pairs, defined in JSON as:

{field1: value1, field2: value2,...}

A value can be a basic type, another set or a collection.

Collection

A collection is defined as a list of values, defined in JSON as:

[value1, value2,...]

A value can be a basic type, a set or another collection.


Envelope

All communication to the API must be contained in an envelope, as described in this section. The envelope is a set containing the following fields:

contractnumberA contract number (provided by Ventu)
usernamestringA user name (provided by Ventu)
passwordstringA password (provided by Ventu)
commandscollectionA collection of the commands which are to be executed.


The envelope can also contain the following field:

haltonerror0 or 1If set to 1, the API will halt execution if a command throws an error, otherwise the API will just continue to the next command (default behavior)
imeistringIf the client is a mobile phone, then the phone can identify itself using its phone number.
pushtokenstringIf the client can received push messages then this field specifies a token for the messages; format is <platform>:<token>
remoteagentstringThe API client can identify itself by providing a short identifier string, which will be recorded in the Microbizz log and help troubleshooting.
_privatemixedWill be included in the reply
apikeystringAn API key (provided by Ventu); this is ignored 


An example envelope can look like this in JSON:

{"contract": xxx,"apikey":"xxx","username":"xxx","password":"xxx","commands": []}

If there is an error in the envelope, the following set will be returned:

statusbooleanAlways 0 when an error occurred.
msgstringAn error message.
datedateThe date on the server, when the envelope was received.
timetimeThe time on the server, when the envelope was received.


If the envelope is correct, the following set will be returned:

statusbooleanAlways 1 when envelope is correct. This isn't an indicator for whether the commands executed.
msgstringOK
resultscollectionA collection of results for each of the provided commands, in the same order as the commands.
datedateThe date on the server, when the command execution started.
timetimeThe time on the server, when the command execution started.
millisecondsnumberHow long time it took Microbizz to generate the reply.
_privatemixedThe value from the command envelope


Command

A command is a set containing at least the following field:

commandstringThe command to be executed.


The rest of the fields in the set are determined by the command executed, but all commands may also include a uniqueid field which is used by Microbizz to try to detect if an app resends the same messages repeatedly:

uniqueidstringUnique ID of the message, should include the time+date of when the command was created, f.ex. msgid-0002342312-2019-08-30_073032-sdfkfowkk23, although the exact format is not important


Just like the envelope, each command may also include the field with private data which will be included in the reply

_privatemixedANy data, will be included in the reply


If the command fails it will return the following set:

statusbooleanAlways 0 when an error occurred.
msgstringAn error message.
errnonumberThe error number, only relevant if status=0, see list of err numbers below


If the command succeeds it will return a set containing at least the following field:

statusbooleanAlways 1 when command succeeded.


The rest of the fields in the set are determined by the command executed.

Error numbers

Some commands may return an error number in the errno field; this is only relevant if the status field is set to 0.

Error numberMeaning
1Generic error
2Duplicate command: the command had a unique ID that has recently been seen
3Unknown command: the command unknown/misspelt/supported
900Task not found
901Not allowed to do that on a closed task
1000Check out failed because the hour registration overlapped an existing hour registration
2000Failed to save file due to lack of disc space