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. |
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 |
|---|
| 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 |
| 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 |
|
|
