Getting started with the API

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.

Initial Configuration

In order to communicate with the Microbizz API one need an API key, a contract number and a valid username / password on that contract. These four pieces of information should be stored in the external app, as they are used as identification against Microbizz. Each component should be stored as strings.

Communication with the API is facilitated using JSON structures sent over HTTP(S). Therefore the external app should be able to handle both JSON data structures and HTTP(S) requests. The default character encoding is UTF-8.

The API is transactional meaning that every request is self contained, and so is the results returned. Each request are made up of an envelope, containing one or more commands.

The simplest of requests can look like this:

{"contract":X,
 "apikey":"X",
 "username":"X",
 "password":"X",
 "remoteagent":"Microbizz test",
 "commands":[{"command":"Echo",
              "text":"Hello World"}]}

This request causes the API to respond with:

{"status":1,
 "msg":"OK",
 "results":[{"status":1,
             "answer":"Hello world"}],
 "date":"2013-01-01",
 "time":"09:25:47"} 

Going over the request, it consists of first providing the four identifying parameters, and then an optional parameter remoteagent is used to identify the remote client. This makes debugging easier for Microbizz personel when a lot of external systems are accessing the solution. The commands are then wrapped in the commands structure. In this example, only one command is given, but several commands could be given here.

The returned answer consists of an result envelope and the results lined up in the results structure. There is one result for each command passed.

Sending requests

Requests are preferably sent over HTTPS for security reasons, but can also be sent over normal HTTP with the normal risks of an unencrypted transaction.

The endpoint URL is https://system.microbizz.dk/api/endpoint.php and the request is passed as either a GET or POST parameter named json.

The example provided above, could be transmitted using GET as:

https://system.microbizz.dk/api/endpoint.php?json=%7B%22contract%22%3A%22X%22%2C%22apikey%22%3A%22X%22%2C%22username%22%3A%22X%22%2C%22password%22%3A%22X%22%2C%22remoteagent%22%3A%22Microbizz+test%22%2C%22commands%22%3A%5B%7B%22command%22%3A%22Echo%22%2C%22text%22%3A%22Hello+World%22%7D%5D%7D

POST using curl

$command = array(...);

$envelope = array('contract' => 2391, 'apikey' => '3333-4444-5555-6666-7777-8888', 'username' => 'api@domain.inv', 'password' => 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', 'haltonerror' => 1, 'commands' => array($command));

$json = json_encode($envelope);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://system.microbizz.dk/api/endpoint.php");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, true);

$data = array('json' => $json);

curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
$output = curl_exec($ch);

Common mistakes

Remember to URL-encode the parameter.

Remember that GET requests are limited in size. Prefer POST.

Remember that complex or large queries can take time to process, when setting timeouts.