Basic types

The API uses the following basic types:

Type	Example	Format, when sending to API	Format, when receiving from API
string / lstring	Hello World	Hello World	Hello World
number (integer)	29	29	29
float	12.59	12.59	12.59
boolean	true	true / 1 / yes	1
	false	false / 0 / no	0
email	test@invalid.inv	test@invalid.inv	test@invalid.inv
date	5. august 2011	2011-08-05 use this if possible	2011-08-05
		05-08-2011
		5-8-2011
		05/08/2011
		(etc)
time	18:45	18:45:00 use this if possible	18:45:00
		18:45
		18.45
		(etc)
binary	N/A	N/A	N/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:

contract	number	A contract number (provided by Ventu)
username	string	A user name (provided by Ventu)
password	string	A password (provided by Ventu)
commands	collection	A collection of the commands which are to be executed.

The envelope can also contain the following field:

haltonerror	0 or 1	If 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)
imei	string	If the client is a mobile phone, then the phone can identify itself using its phone number.
pushtoken	string	If the client can received push messages then this field specifies a token for the messages; format is <platform>:<token>
remoteagent	string	The API client can identify itself by providing a short identifier string, which will be recorded in the Microbizz log and help troubleshooting.
_private	mixed	Will be included in the reply
apikey	string	An API key (provided by Ventu); this is ignored
language	string	Which language to use for translations, this must be a language that is enabled in Microbizz; eg. "en", "da", "sv", "de", "fr" etc. Notice that “se” and “sv” both refer to swedish.
foregroundservice	bool	Set to 0 if GPS foreground service is disabled; if not set then it is assumed to be enabled

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:

status	boolean	Always 0 when an error occurred.
msg	string	An error message.
date	date	The date on the server, when the envelope was received.
time	time	The time on the server, when the envelope was received.

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

status	boolean	Always 1 when envelope is correct. This isn't an indicator for whether the commands executed.
msg	string	OK
results	collection	A collection of results for each of the provided commands, in the same order as the commands.
date	date	The date on the server, when the command execution started.
time	time	The time on the server, when the command execution started.
milliseconds	number	How long time it took Microbizz to generate the reply.
_private	mixed	The value from the command envelope

Command

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

command

string

The 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:

uniqueid

string

Unique 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

_private

mixed

Any data, will be included in the reply

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

reminderactions

string

Set to "off" to disable executing reminder actions

If the command fails it will return the following set:

status	boolean	Always 0 when an error occurred.
msg	string	An error message.
errno	number	The 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:

status

boolean

Always 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 number	Meaning

Error number	Meaning
1	Generic error
2	Duplicate command: the command had a unique ID that has recently been seen
3	Unknown command: the command unknown/misspelt/supported
4	Not allowed
5	Bad date format
6	Missing module
7	Missing required field
8	Unknown field
200	Service not available
201	PriceProtal service not available
900	Task not found
901	Not allowed to do that on a closed task
1000	Check out failed because the hour registration overlapped an existing hour registration
1100	Registration day is already open
2000	Failed to save file due to lack of disc space