UCRM - API Usage


Overview


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

NOTES & REQUIREMENTS:
The use of the API is addressed to advanced users with some basic scripting knowledge, who have the tools and necessary servers to develop and execute their own API scripts.
 
For those who don't wish to develop their own scripts, we recommend using CRM Plugins, which can be uploaded, configured and used without any special knowledge.

Table of Contents


  1. Usage
  2. Documentation
  3. Example Script
  4. Related Articles

Usage


Back to Top

CRM module provides an API to import, retrieve or update any data stored in the CRM part of the UNMS database. For instance, this is what you could achieve using this API:

  • Batch imports of large data: for example, the import of thousands of clients.
  • Batch exports: for example invoices, payments, etc.
  • Update existing entities: for example, change any invoicing attribute for all clients.
  • The API also enables you to manage the shaping or suspending of any vendor's devices.

Documentation


Back to Top

  • API doc for the stable version of UNMS’ CRM module can be found at unmscrm.docs.apiary.io
  • API doc for the beta version of UNMS’ CRM module can be found at ucrmbeta.docs.apiary.io
  • API doc for UCRM v2 can be found at ucrm.docs.apiary.io
  • The API documentation for the UNMS Network module is available in each UNMS controller at https://<yourdomain>/api-docs/. In Settings > Users > API Tokens it is possible to generate an authentication token and then use it for the script.

Example Script


Back to Top

Find an example script in PHP below which demonstrates how to update all the clients in the CRM module. 

In the script, you will notice a simple class UcrmApiAccess which handles the connection and commands processing. You don't need to change this class. Below, you will see how to use this class. First, all the clients are retrieved from your UCRM. Then, each client is processed one by one. In this case, there are 4 invoicing attributes set to null for each client. And of course, you can do whatever you need: update clients’ addresses, set default tax for a subset of your clients, etc.

To use this script with your UCRM instance, change the API_URL and APP_KEY constants to your values—you can find them in your UCRM at System > Security > App keys.

<?php

class UcrmApiAccess
{
   const API_URL = 'https://ucrm-demo.ubnt.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

UCRM - Plugins


We're sorry to hear that!