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