This document describes how to configure, connect to, and interact with the API. For information on expanding the API with your own custom code see Extending the API. All examples are presented using PHP.
Configuration
Before you begin using the API you must first create a set of API credentials for the company you wish to connect to. For information on creating API credentials consult the System > API Access section of the User Manual.
...
The API supports Basic Authentication for web requests. When connecting to the API via a command line the API credentials must be passed as parameters. See Using the Command Line Interface for more information on connecting to the API via command line.
Note |
---|
title | Running PHP in CGI or FCGId mode? |
---|
|
Update your .htaccess file to pass an environment variable to Blesta so it can capture the basic authentication details as per the following snippet: Code Block |
---|
| RewriteEngine on
...
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
|
|
...
To connect remotely, first determine the URL of the API for your installation. The default path is http://yourdomain.com/installpath/api/. Where yourdomain.com is the domain you've installed Blesta in, and installpath is the path to Blesta. If your server does not support .htaccess then the URL should instead appear as http://yourdomain.com/installpath/index.php/api/.
Warning |
---|
|
Because each request contains your API key, and may contain additional sensitive information, you should only process requests remotely over a secure connection (i.e. only use HTTPS) |
...
The API encourages the proper use of GET, POST, PUT, and DELETE when interacting with the API. For all POST requests the API will pass only post parameters to the requested resource. For PUT only put parameters will be passed. Similarly, for all GET and DELETE requests, the API will pass only get parameters to the requested resource.
POST
Use POST requests when creating new records. For example, when adding a new user record via api/users/add.json.
GET
Use GET requests when retrieving record data. For example, when fetching a user record via api/users/get.json.
PUT
Warning |
---|
title | Choose the Request Type Carefully |
---|
|
It is highly discouraged to use GET or DELETE for API requests where you are providing sensitive information. That sensitive information will be included as plain-text as get parameters in the URI. Instead, use POST or PUT to pass that sensitive information securely in the request body rather than the URI. |
POST
Use POST requests when creating new Use PUT requests when updating records. For example, when updating adding a new user record via api/users/editadd.json.
DELETE
GET
Use GET requests when retrieving record data. For example, when fetching a user record via api/users/get.json.
PUT
Use PUT requests when updating records. For example, when updating a user record via api/users/edit.json.
DELETE
Use Use DELETE requests when deleting records. For example, when deleting a user record via api/users/delete.json.
...
Below are a few basic examples to get you started.
API Request | Description | PHP | CURL |
---|
encryption/systemEncrypt | Encrypts the given value using 256-bit AES in CBC mode using a SHA-256 HMAC hash as the key, based on the system configured setting in Blesta.system_key |
Expand |
---|
|
Code Block |
---|
language | php |
---|
linenumbers | true |
---|
| <?php
require_once "blesta_api.php";
$user = "username";
$key = "key";
$url = "https://yourdomain.com/installpath/api/";
$api = new BlestaApi($url, $user, $key);
$response = $api->post("encryption", "systemEncrypt", array('value' => "my text"));
print_r($response->response());
print_r($response->errors());
?>
|
|
|
Expand |
---|
|
curl https://yourdomain.com/installpath/api/encryption/systemEncrypt.json -u username:key -d 'value=my text' |
|
|
encryption/systemDecrypt | Decrypts the given value using 256-bit AES in CBC mode using SHA-256 HMAC hash as the key, based on the system configured setting in Blesta.system_key |
Expand |
---|
|
Code Block |
---|
language | php |
---|
linenumbers | true |
---|
| <?php
require_once "blesta_api.php";
$user = "username";
$key = "key";
$url = "https://yourdomain.com/installpath/api/";
$api = new BlestaApi($url, $user, $key);
$response = $api->post("encryption", "systemDecrypt", array('value' => "b2J2aW91c2x5IG5vdCByZWFsbHkgZW5jcnlwdGVk"));
print_r($response->response());
print_r($response->errors());
?>
|
|
|
Expand |
---|
|
curl https://yourdomain.com/installpath/api/encryption/systemDecrypt.json -u username:key -d 'value=b2J2aW91c2x5IG5vdCByZWFsbHkgZW5jcnlwdGVk' |
|
|
invoices/add | Creates a new invoice using the given data |
Expand |
---|
|
Code Block |
---|
language | php |
---|
linenumbers | true |
---|
| <?php
require_once "blesta_api.php";
$user = "username";
$key = "key";
$url = "https://yourdomain.com/installpath/api/";
$api = new BlestaApi($url, $user, $key);
$data = array(
'vars' => array(
'client_id' => 1,
'date_billed' => date("c"),
'date_due' => date("c"),
'currency' => "USD",
'lines' => array(
array(
'description' => "Line item #1",
'amount' => "5.99"
),
array(
'description' => "Line item #2",
'amount' => "3.75",
'qty' => 2
)
),
'delivery' => array("email")
)
);
$response = $api->post("invoices", "add", $data);
print_r($response->response());
print_r($response->errors());
?>
|
|
|
Expand |
---|
|
curl https://yourdomain.com/installpath/api/invoices/add.json -u username:key -d 'vars[client_id]=1' -d 'vars[date_billed]=2013-11-20T16:43:00-07:00' -d 'vars[date_due]=2013-11-20T16:43:00-07:00' -d 'vars[currency]=USD' -d 'vars[lines][0][description]=Line item #1' -d 'vars[lines][0][amount]= |
|
|
5.99'-d 'vars[lines][1][description]=Line item #25.99' -d 'vars[lines][1][description]=Line item #2' -d 'vars[lines][1][amount]=3.75' -d 'vars[lines][1][qty]=2' -d 'vars[delivery][0]=email' |
|
|
users/auth | Determines whether the user credentials are valid to be authenticated with Blesta |
Expand |
---|
|
Code Block |
---|
language | php |
---|
linenumbers | true |
---|
| <?php
require_once "blesta_api.php";
$user = "username";
$key = "key";
$url = "https://yourdomain.com/installpath/api/";
$api = new BlestaApi($url, $user, $key);
$data = array(
'username' => 'myuser',
'vars' => array(
'username' => 'myuser',
'password' => 'mypassword'
),
'type' => 'any'
);
$response = $api->post("users", "auth", $data);
print_r($response->response());
print_r($response->errors());
?>
|
|
|
Expand |
---|
|
curl https://yourdomain.com/installpath/api/users/auth.json -u username:key -d 'username=myuser' -d 'vars[ |
|
|
lines][1][amount3.75lines][1][qty]=2password]=mypassword' -d ' |
|
|
vars[delivery][0]=emailHow to Read the Source Docs
...