Overview

This article explains the purpose of the API for the UISP CRM module and demonstrates its usage with a simple example script.

Table of Contents

1. Using the API
2. API Information and Documentation
3. Example Script
4. Related Articles

Using the API

Back to Top

The UISP CRM module provides an API to import, retrieve, or update any data stored in the UISP CRM database. The API can be used to:

• Batch imports of large data For example, importing thousands of clients at once.
• Batch exports For example, exporting invoices and payments.
• Update existing entities For example, change any invoicing attribute for all clients.
• Control The API also enables you to manage the shaping or suspending of any vendor's devices.

API Information and Documentation

Back to Top

• API doc for the stable version of UISP CRM module can be found at unmscrm.docs.apiary.io
• API doc for the beta version of the UISP CRM module can be found at ucrmbeta.docs.apiary.io
• The API documentation for the UISP Network module is available at the https://hostname/api-docs/ address on each console.

Script authentication tokens can be generated in the    Settings > Users > API tokens section.

Example Script

Back to Top

Below is a PHP example script that demonstrates how to update all the clients in the CRM module. In the script, a simple class called UcrmApiAccess is used which handles the connection and commands processing. You don't need to change this class. 

1. First, all the clients are retrieved from CRM.

2. Then, each client is processed one by one. In this case, there are 4 invoicing attributes set to null for each client.

3. Use the script to modify whatever you need, such as updating client addresses or setting a default tax for a subset of your clients.

4. To use this script with your CRM instance, change the API_URL and APP_KEY constants to your values. The values can be found in the CRM > System > Security > App keys section.

<?php

class UcrmApiAccess
{
    const API_URL = 'https://unms.ui.com/api/v1.0';
    const APP_KEY = '5YbpCSto7ffl/P/veJ/GK3U7K7zH6ZoHil7j5dorerSN8o+rlJJq6X/uFGZQF2WL';

    /**
     * @param string $url
     * @param string $method
     * @param array  $post
     *
     * @return array|null
     */
    public static function doRequest($url, $method = 'GET', $post = [])
    {
        $method = strtoupper($method);

        $ch = curl_init();

        curl_setopt(
            $ch,
            CURLOPT_URL,
            sprintf(
                '%s/%s',
                self::API_URL,
                $url
            )
        );
        curl_setopt($ch, CURLOPT_TIMEOUT, 30);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HEADER, false);

        curl_setopt(
            $ch,
            CURLOPT_HTTPHEADER,
            [
                'Content-Type: application/json',
                sprintf('X-Auth-App-Key: %s', self::APP_KEY),
            ]
        );

        if ($method === 'POST') {
            curl_setopt($ch, CURLOPT_POST, true);
        } elseif ($method !== 'GET') {
            curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
        }

        if (! empty($post)) {
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($post));
        }

        $response = curl_exec($ch);

        if (curl_errno($ch) !== 0) {
            echo sprintf('Curl error: %s', curl_error($ch)) . PHP_EOL;
        }

        if (curl_getinfo($ch, CURLINFO_HTTP_CODE) >= 400) {
            echo sprintf('API error: %s', $response) . PHP_EOL;
            $response = false;
        }

        curl_close($ch);

        return $response !== false ? json_decode($response, true) : null;
    }
}

// Setting unlimited time limit (updating lots of clients can take a long time).
set_time_limit(0);

if (php_sapi_name() !== 'cli') {
    echo '<pre>';
}

// Get collection of all Clients.
$clients = UcrmApiAccess::doRequest('clients') ?: [];
echo sprintf('Found %d clients.', count($clients)) . PHP_EOL;

// Go through all Clients and update them.
// In this case we are updating all invoice options to use system defaults.
foreach ($clients as $client) {
    $response = UcrmApiAccess::doRequest(
        sprintf('clients/%d', $client['id']),
        'PATCH',
        [
            'sendInvoiceByPost' => null,
            'invoiceMaturityDays' => null,
            'stopServiceDue' => null,
            'stopServiceDueDays' => null,
        ]
    );

    if ($response !== null) {
        echo sprintf('Client ID %d successfully updated.', $client['id']) . PHP_EOL;
    } else {
        echo sprintf('There was an error in updating client ID %d.', $client['id']) . PHP_EOL;
    }
}

echo 'Done.' . PHP_EOL;

Related Articles

Back to Top

UISP - CRM: Plugins

UISP - How to Upgrade from UCRM to UISP