UCRM - API Usage

Overview


This article explains the purpose of the UCRM API and demonstrates its usage with a simple example script. 

Table of Contents


  1. Usage
  2. Example Script

Usage


Back to Top

UCRM provides an API to import, retrieve or update any data stored in UCRM. For instance, this is what you could achieve using the UCRM API:

  • Batch imports of large data. For example, the import of thousands of clients.
  • Batch exports. (Ex. 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.

If you would like more information, please refer to the following API documentation: 


Example Script


Back to Top

We created an example script in PHP to show how to update all the clients in UCRM. This example will work on UCRM version 2.2.2-beta1 and above.

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 valuesyou 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;

 

Powered by Zendesk