Versions Compared
| Version | Old Version 11 | New Version Current |
|---|---|---|
| Changes made by | ||
| Saved on |
Key
- This line was added.
- This line was removed.
- Formatting was changed.
Basic types
The API uses 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 | |
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 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. |
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 a uniqueid field 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. |
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 |
|---|---|
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 |
| Table of Contents | ||
|---|---|---|
|
Basic types
The API uses the following basic types:
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:
The envelope can also contain the following field:
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:
If the envelope is correct, the following set will be returned:
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:
msgid-0002342312-2019-08-30_073032-sdfkfowkk23, although the exact format is not importantJust like the envelope, each command may also include the field with private data which will be included in the reply
If the command fails it will return the following set:
If the command succeeds it will return a set containing at least the following field:
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.
4 | Not allowed |
5 | Bad date format |
6 | Missing module |
7 | Missing required field |
8 | Unknown field |
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 |
| Table of Contents | ||
|---|---|---|
|