iono Documentation - API

iono 2 has an extensive API available providing an abstracted interface to the core classes through one single API class. With this API you can create, edit and delete invoices, licenses, extras and users.

Why use it?

This API is ideal for use when you need to easily create/edit/delete something from your iono installation without doing it manually. This could be coupled with an event hook to create a user in iono when one is created in another program. This is how the vBulletin integration works, for example.

Using the API

Initialisation

Before you can use any of the main API functions you need to include and instantiate the class:

<?php
// Include class
require_once('api_code.php');

// Useful variables
$api_key = '05b0c8e4924e';
$iono_path = '/www/iono/svn/branch-2.x/upload';

// Instantiate  
$api = new iono_api_code();

// Set up for iono  
$api->set_iono_path($iono_path);

check_errors($api);

// Login
$api->login($api_key);
check_errors($api);
?>

Initialisation must be done in this order since the set_iono_path() method includes files and classes that are used in other methods in the class. In this example there is a function called check_errors() which checks whether the API class has returned an API Error. This is defined as follows:

<?php
/**
* Checks for errors in the API object
*
* @param iono_api_base $api_object
*/  
function check_errors(&$api_object)  
{
	if ($api_object->has_error())
	{
		die($api_object->get_error());
	}
}
?>

Using the API

Now that you have an instance of the API class, and have logged in successfully you can now use it to manage your installation of iono. The method declarations are almost identical (some may have more default values though) to their corresponding ones in the iono_* classes. For instance, in the iono_users class, the user adding method is declared as:

function add($status, $admin, $username, $password, $email, $first_name, $last_name, 
$company, $address1, $address2, $city, $county, $postalcode, $country, $phone, 
$orders_validation, $notes, $send_email = true, $validate = true)

In the API this is defined as:

function user_add($status, $admin, $username, $password, $email, $first_name, 
$last_name, $company = '', $address1, $address2 = '', $city, $county = '', 
$postalcode, $country, $phone = '', $orders_validation = 0, $notes = '', 
$send_email = true, $validate = true)

The return values for methods are varied. They all will return false if the API account key is not permitted to use this section of the API (these permissions can be changed in the API Accounts Settings from the iono admin panel).

API Errors

Two types of error may be returned by the API. Firstly there are the status IDs which come back from the relevant iono_* class and the methods within. These are returned as integers, with 1 usually denoting the operation was successful.

The others are errors which have been detected/encountered by the API itself. These are strings in the format API-E-x, where x is some integer. If x is 0 then the operation was successful.

The errors are as follows:

Usually if there is an error it will actually be sent back in the return value, but this is not always the case. To be sure that no API error was triggered there is a has_error() method implemented in the API. This returns true/false depending on whether an error is present or not. For actually retrieving the error, the get_error() method can be used.

Examples

Adding a user

<?php  
// Create an admin user with the username dsalisbury and password ahd243t. The user is   
// notified of this via email  
$result = $api->user_add(1, 1, 'dsalisbury', 'ahd243t', 'blackhole@olate.co.uk', 'David',   
'Salisbury', 'Olate Ltd.',  '1 A road', '', 'Some Town', 'Some County', 'TW1 5FS',   
'United Kingdom', '01234567890', 0,  'This user is a developer for Olate Ltd.', true, 
true);  

check_errors($api);    
if ($result == 1)  
{  	
	echo 'The user dsalisbury was added sucessfully'; 
}    
?>

Changing license restrictions

<?php   
// Set up array of restrictions and have it expire in 1 week from now  
$license_id = 41;  
$restrictions = array(  	
		'hostname' => 'sub.domain.tld',  	
		'ip_address' => '123.456.789.123',  	
		'allowed_installs' => 10,  	
		'expires' => '+1 week' // This is a string compatible with strtotime()  
		);    
// Run update  
$result = $api->license_set_restrictions($license_id, $restrictions);    

if ($result == 1)  
{  	
	echo 'License restrictions updated';  
}    
?>

Searching

The iono 2 API features search functions for users, products and extras. These are user_search(), license_search() and extra_search() and all take an array of search criteria in the format of fieldname => value. Not all fields are supported for searching but you can add new ones in by adding them to the $allowed_constraint_fields and $allowed_constraint_field_types arrays in each of the functions, making sure to select the right datatype from INT, STR, STR_HTML and FLOAT for each field you add.

All three functions will return an array. If only one row is found then it will just be an array of fields for that row, otherwise it will be an array of all rows found (i.e. an array of arrays of fields).

Searching for a user

<?php     
echo "User Search by User ID<br />";  
var_dump($api->user_search(array('user_id' => '1')));    

echo "User Search by Email Address<br />";  
var_dump($api->user_search(array('email' => 'email@address.com')));    
?>

Other Examples

echo "user search by id<br />";  
var_dump($api->user_search(array('user_id' => '1')));    

echo "user search by email<br />";  
var_dump($api->user_search(array('email' => 'example@example.com')));    

echo "user search by id and email<br />";  
var_dump($api->user_search(array('user_id' => 1, 'email' => 'example@example.com')));    

echo "license search by product license id<br />";  
var_dump($api->license_search(array('product_license_id' => 2)));    

echo "license search by hostname<br />";  
var_dump($api->license_search(array('hostname' => 'olate.co.uk')));    

echo "license search by key string - generated<br />";  
var_dump($api->license_search(array('license_key' => '1-1-2-1152527464-c81e728d')));    

echo "license search by key string - custom<br />";  
var_dump($api->license_search(array('license_key' => 'custom key')));    

echo "license search by field in users table<br />";  
var_dump($api->license_search(array('county' => 'Worcestershire')));    

echo "extra search by email<br />";  
var_dump($api->extra_search(array('email' => 'example@example.com')));

Function Reference - Users

user_add()

Add a user to the system.

Function definition

user_add($status, $admin, $username, $password, $email, $first_name, $last_name,  
$company = '', $address1, $address2 = '', $city, $county = '', $postalcode, $country,   
$phone = '', $orders_validation = 0, $notes = '', $send_email = false,   
$validate = false

Parameters/Return

Example code

$result = $api->user_add(0, 1, 'test_user', 'password', 'blackhole@olate.co.uk', 'David',   
'Salisbury', '', 'Address', '', 'Town', 'County', 'POST CODE', 'United Kingdom', 'Phone',   
1, 'Notes', true, false);  check_errors($api);  echo "Adding: $result<br />";

user_edit()

Edits user to specified details

Function definition

user_edit($user_id, $status = false, $admin = false, $username = false, $password = false,   
$email = false, $first_name = false, $last_name = false, $company = false, $address1 = false,   
$address2 = false, $city = false, $county = false, $postalcode = false, $country = false,   
$phone = false, $ip = false, $orders_validation = false, $notes = false)

Parameters/Return

Example code

// Try to edit - deactivate  
$result = $api->user_edit($user_id, 0);  
check_errors($api);  
echo "Editing: $result<br />";

user_delete()

Deletes given user

Function Definition

user_delete($user_id)

Parameters/Return

Example Code

// Try to delete  
$result = $api->user_delete($user_id);  
check_errors($api);  
echo "Deleting: $result<br />";

user_get_id_from_username()

Gets user ID from given username

Function Definition

user_get_id_from_username($username)

Parameters/Return

Example Code

$user_id = $api->user_get_id_from_username('test_user');  
check_errors($api);  
echo "User ID: $user_id<br />";

user_activate()

Activates given user ID

Function Definition

user_activate($user_id)

Parameters/Return

Example Code

// Try to activate  
$result = $api->user_activate($user_id);  
check_errors($api);  
echo "Activating: $result<br />";

user_get_details()

Fetches details about the specified user

Function Definition

user_get_details($user_id)

Parameters/Return

Example Code

// Get user  
$result = $api->user_get_details($user_id);  
check_errors($api);  
echo "Fetching user details:";  
var_dump($result);

Function Reference - Licenses

license_add()

Adds a license

Function Definition

license_add($product_id, $product_license_id, $invoice_id = 0, $user_id, $status,   
$license_key = '', $hostname = '', $ip = '', $installs = 0, $allowed_installs = 0,   
$expires = 1, $accessed = 0, $notes = '')

Parameters/Return

Example Code

// Try adding a license  
$license_id = $api->license_add(1, 1, 0, 1, 1, 'Custom key string 1', 'hostname', 
'ip address', 32, 900, 1, 1, 'API Testing...');  check_errors($api);  

echo "Adding license: $license_id. License data:<br />";

license_edit()

Edit a license

Function Definition

license_edit($license_id, $product_id, $product_license_id, $invoice_id, $user_id,   
$status, $license_key, $hostname, $ip, $installs, $allowed_installs, $expires,   
$accessed, $mailed_near_expiry, $mailed_expired, $notes)

Parameters/Return

Example Code

$result = $api->license_edit($license_id, 1, 1, 0, 1, 0, 'Custom key string 2',   
'Changed hostname', 'Changed IP', 21, 800, 0, 1, 0, 0, 'Changed notes field');  
check_errors($api);  echo "Editing license: $license_id.  License data:<br />";  
var_dump($api->license_get($license_id));

license_delete()

License deletion function

Function Definition

license_delete($license_id)

Parameters/Return

Example Code

$result = $api->license_delete($license_id);  
check_errors($api);  
echo "Deleting license: $result<br />";

license_set_status()

Sets status of a license

Function Definition

license_set_status($license_id, $status)

Parameters/Return

license_set_restrictions()

Changes restrictions on a given license. Restrictions take format:

$restrictions = array('hostname' => 'some hostname(s)',  
'ip_address' => 'some ip address(es)',  'allowed_installs' => n,  
'expires' => '0, 1, or something for strtotime()');

Each restriction is optional but at least one must be specified

Function Definition

license_set_restrictions($license_id, $restrictions = array())

Parameters/Return

Example Code

$restrictions = array('hostname' => 'davids',  'ip_address' => '192.168.2.15',  
'allowed_installs' => '10',  'expires' => date('r'));  

$result = $api->license_set_restrictions($license_id, $restrictions);  
echo "Setting license restrictions: $result.  License data:<br />";  

var_dump($api->license_get($license_id));  
check_errors($api);

license_get()

Fetches license details

Function Definition

license_get($license_id)

Parameters/Return

Example Code

var_dump($api->license_get($license_id));  
check_errors($api);

license_get_key()

Fetches license key for given license

Function Definition

license_get_key($license_id, $force = false)

Parameters/Return

license_get_invoice_id()

Fetches invoice ID for given license

Function Definition

license_get_invoice_id($license_id)

Parameters/Return

Function Reference - Extras

extra_add()

Adds an extra

Function Definition

extra_add($product_id, $product_extra_id, $invoice_id, $user_id, $status, 
$expires, $accessed = 0, $notes = '')

Parameters/Return

Example Code

$insert_id = $api->extra_add(1, 1, 34, 1, 1, 1, 1, 'API Test'); 
check_errors($api);  

echo "Adding extra: $insert_id.  Data:<br />";  
var_dump($api->extra_get($insert_id));

extra_edit()

Edit extra

Function Definition

extra_edit($extra_id, $product_id = null, $product_extra_id = null, $invoice_id = null,  
$user_id = null, $status = null, $expires = null, $accessed = null, 
$mailed_near_expiry = null,  $mailed_expired = null, $notes = null)

Paramaters/Return

Example Code

$result = $api->extra_edit($insert_id, null, null, 22, 1, 0, 1, null,   
null, null, 'Changed field');  check_errors($api);  

echo "Editing extra: $result.  Data:<br />";  
var_dump($api->extra_get($insert_id));

extra_get()

Get extra

Function Definition

extra_get($extra_id)

Paramaters/Return

Example Code

var_dump($api->extra_get($insert_id));

extra_delete()

Deletes extra

Function Definition

extra_delete($extra_id)

Parameters/Return

Example Code

$result = $api->extra_delete($insert_id);  
check_errors($api);  
echo "Deleting extra: $result<br />";

Function Reference - Invoices

invoice_add()

Adds an invoice

Function Definition

invoice_add($time_due, $status, $user_id, $initial_tax_rate = false, $items,   
$initial_discount = false, $initial_sub_total, $initial_tax = false,   
$initial_total, $recurring_tax_rate = false, $recurring_discount = false,   
$recurring_sub_total = false, $recurring_tax = false, $recurring_total = false,   
$recurring_period = false, $generate = false, $generate_day = false,   
$subscription_active = false, $notes = false, $email = true, $validate = false)

Parameters/Return

Example Code

$items = array(array(  		
	'name' => 'License',  		
	'description' => 'Desc field1',  		
	'product_license_id' => 1,  		
	'product_extra_id' => '',  		
	'initial_price' => 102.32,  		
	'initial_quantity' => 2,  		
	'initial_discount' => 10,  		
	'initial_total' => 194.64,  		
	'recurring_price' => 20,  		
	'recurring_quantity' => 2,  		
	'recurring_discount' => 0,  		
	'recurring_total' => 40),  	
	
	array(
	'name' => 'Extra',  		
	'description' => 'Desc field2',  		
	'product_license_id' => '',  		
	'product_extra_id' => 1,  		
	'initial_price' => 60.20,  		
	'initial_quantity' => 8,  		
	'initial_discount' => 100,  		
	'initial_total' => 381.60,  		
	'recurring_price' => 11,  		
	'recurring_quantity' => 8,  		
	'recurring_discount' => 0,  		
	'recurring_total' => 88));    
	
	$invoice_id = $api->invoice_add('+1 week', 0, 1, 17.5, $items, 110, 576.24,   
	100.84, 677.08, 17.5, 0, 128.0, 22.4, 150.4, 'M', false, false, true,   
	'Testing the API', true, true);  
	
	check_errors($api);  
	echo "Created invoice: $invoice_id<br />";

invoice_delete()

Delete an invoice

Function Definition

invoice_delete($invoice_id)

Parameters/Return

Example Code

$result = $api->invoice_delete($invoice_id);  
check_errors($api);  
echo "Deleted invoice ID $invoice_id: $result<br />";

invoice_edit()

Edit an invoice

Function Definition

invoice_edit($invoice_id, $time_due, $status, $user_id, $initial_tax_rate, $items,   
$items_new = false, $initial_discount = false, $initial_sub_total, $initial_tax = false,   
$initial_total, $recurring_tax_rate, $recurring_discount = false,   
$recurring_sub_total = false, $recurring_tax = false, $recurring_total = false,   
$recurring_period = false, $generate = false, $generate_day = false,   
$generate_next = false, $subscription_active = false, $notes = false)

Parameters/Return

invoice_approve()

Approve invoices

Function Definition

invoice_approve($invoice_id)

Parameters/Return