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 | |
| test@invalid.inv | test@invalid.inv | test@invalid.inv | |
| date | 5. august 2011 | 2011-08-05 | 2011-08-05 |
| 05-08-2011 | |||
| 5-8-2011 | |||
| 05/08/2011 | |||
| (etc) | |||
| time | 18:45 | 18:45:00 | 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:
...
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:
...
A value can be a basic type, a set or another collection.
Concept
The API is used to pass one or more commands to Microbizz. The commands are given in a collection, which again is wrapped in an envelope containing identification information such as the API-key, user name and/or password. When all commands has been executed, a structure is returned with the result of each command.
Versioning
Fields and commands are never removed from the API, but new fields can be implemented both in objects and command results. Therefore it is important that implementations against the API allows for this, in order to be forward-compatible.
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) |
| apikey | string | An API key (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 |
An example envelope can look like this in JSON:
...
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 |
If the command fails it will return the following set:
| status | boolean | Always 0 when an error occurred. |
| msg | string | An error message. |
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.