CENTRALINO CLOUD - IPPBX OlimonTel API Rest

CENTRALINO CLOUD – IPPBX OlimonTel

API Rest – Descrizione generale

OlimonTel PBX offre un set di API REST che possono essere invocate da sistemi esterni per compiere azioni di tipo dispositivo (es. creazione di un interno, generazione di un backup e download, ecc.) o di consultazione (download del registro chiamate, ecc.).

L’accesso alle API può avvenire tramite HTTPS, previa autenticazione, secondo il meccanismo descritto di seguito.

Meccanismo di autenticazione

Il meccanismo di autenticazione delle API REST utilizza le stesse credenziali utente valide per l’accesso web. In particolare, ogni richiesta deve contenere un HTTP header custom, monouso, il cui nome è X-authenticate. La procedura di autenticazione è one-way, ossia non richiede l’invio di un challenge da parte del server, ma tutte le informazioni necessarie all’autenticazione sono generate esclusivamente lato client.

La proprietà di uso singolo dell’header di autenticazione previene gli attacchi per duplicazione, garantendo che la conoscenza dell’header X-authenticate di una certa richiesta non permetta di effettuarne un’altra illecita.

Costruzione dell’X-authenticate header

L’header è composto da una serie di dati in chiaro ed un digest costruito utilizzando tali dati, unitamente alla password dell’utente che effettua la richiesta. Di seguito un esempio di un X-authenticate header completo:

X-authenticate: RestApiUsernameToken Username="admin", Domain="default", Digest="+PJg7Tb3v98XnL6iJVv+v5hwhYjdzQ2tIWxvJB2cE40=", Nonce="bfb79078ff44c35714af28b7412a702b", Created="2016-04-29T15:48:26Z"

I dati che sono utilizzati (e trasmessi nella richiesta) nella costruzione dell’header sono:

Username: lo username dell’utente (es. admin)
Domain: il dominio del tenant di appartenza dell’utente. Nel caso di sistemi mono-tenant, il dominio predefinito è «default»
Nonce: una stringa casuale esadecimale generata dal client , di lunghezza almeno pari a 8 caratteri. Ad ogni richiesta è necessario rigenerare un nuovo nonce, in quanto il sistema tiene traccia di tutti quelli utilizzati in precedenza, per un periodo pari al tempo di validità del nonce, che è pari a 5 minuti. Dopo 5 minuti è possibile riutilizzare un nonce utilizzato in precedenza; la protezione da attacchi basati su replica è in questo caso garantita dal timestamp di creazione del nonce
Created: indica il timestamp di creazione del nonce; se l’ora di ricezione della richiesta differisce dall’ora impostata sul OlimonTel PBX per più di 5 minuti, la richiesta viene considerata invalida e rifiutata. Questo garantisce che il riuso di un X-authenticate header con lo stesso nonce non sia possibile né entro i 5 minuti del tempo di vita di un nonce (per la protezione da replica implementata) né oltre tale tempo di vita. Il formato della stringa del timestamp (riportato al timezone UTC) è «YYYY-MM-DDThh:mm:ssZ».

Digest = sha256(Nonce + digestPassword + Username + Domain + Created)

Dato che sul OlimonTel PBX le password utente non sono salvate in chiaro ma sotto forma di hash non reversibile, per la generazione del Digest è necessario utilizzare l’hash della password con la stessa procedura utilizzata nel PBX (indicata come digestPassword) e non la password in chiaro.

La procedura di calcolo della digestPassword richiede, oltre alla password dell’utente, una ulteriore stringa denominata salt, univoca per tenant. Il salt può essere ottenuto dal OlimonTel PBX mediante una API REST apposita, invocabile in modo anonimo (senza autenticazione):

rest/salt/

dove la stringa ,nel caso di macchina single tenant, vale «default». Nel caso di sistema multi-tenant, per poter utilizzare le API a disposizione di pbxadmin, è possibile ottenere il salt relativo mediante l’API

rest/salt/pbxAdmin

La formula di calcolo della digestPassword è (i caratteri { e } fanno parte della stringa di cui si esegue lo sha256 e devono essere inseriti):

digestPassword = sha256(password{})

Ad esempio, supponendo che la password dell’utente sia «admin» e il salt sia uguale a «b5a8fdcf2f8d5acdad33c4a072a97d7a», la digestPassword risultante è:

digestPassword = sha256(admin{b5a8fdcf2f8d5acdad33c4a072a97d7a}) = dd7b0be7fa37d6cbaf0b842bf7532f229cb79ab8d54d509c2aa7eea27a53cd5e

Come esempio, con i dati seguenti:

Nonce: bfb79078ff44c35714af28b7412a702b
digestPassword: dd7b0be7fa37d6cbaf0b842bf7532f229cb79ab8d54d509c2aa7eea27a53cd5e
Username: admin
Domain: default
Created: 2016-04-29T15:48:26Z

si ottiene:

Digest = base64(sha256binary(bfb79078ff44c35714af28b7412a702bdd7b0be7fa37d6cbaf0b842bf7532f229cb79ab8d54d509c2aa7eea27a53cd5eadmindefault2016-04-29T15:48:26Z))

che vale +PJg7Tb3v98XnL6iJVv+v5hwhYjdzQ2tIWxvJB2cE40=.

Nota

La funzione sha256binary(..) indica la funzione sha256(..) che restituisce l’output in formato binario e non in formato esadecimale.

La stringa completa risultante da inserire all’interno dell’header X-authenticate è quindi quella indicata all’inizio del paragrafo e riportata di seguito:

X-authenticate: RestApiUsernameToken Username="admin", Domain="default", Digest="+PJg7Tb3v98XnL6iJVv+v5hwhYjdzQ2tIWxvJB2cE40=", Nonce="bfb79078ff44c35714af28b7412a702b", Created="2016-04-29T15:48:26Z"

API di Operation

Informazioni preliminari

Il formato supportato per le richieste e le risposte per tutte le API di operation è JSON, devono quindi essere impostati gli header Content-Type ed Accept al valore application/json.

/rest/operation/{serviceName}/{key}

Tramite questa API è possibile agire sulle impostazioni operative di vari servizi, sia in lettura con il verbo GET, sia in scrittura con il verbo POST, sia in cancellazione con il verbo DELETE.

Parametri

Nome	Obbligatorio	Descrizione
serviceName	sì	I valori ammessi per questo parametro sono:BUSYLEVEL: agisce sul livello di occupatoCFBS: (Call Forward Busy) agisce sull’inolto incondizionato in caso di occupatoCFIM: (Call Forward Immediate) agisce sull’inolto incondizionatoCFNA: (Call Forward Not Answer) agisce sull’inoltro in caso di non rispostaCFUN: (Call Forward Unavaiilable) agisce sull’inolto in caso di non disponibileCLIP: RISERVATODND: (Do Not Disturb) agisce sul «non disturbare»EXTEN_HUNTING: agisce sull’ordine di distribuzione della chiamata ai vari account dell’internoFORKMOBILE: agisce sul fork delle chiamate verso il numero mobileHUNTING: DEPRECATO
key	sì	L’interno sul quale si vuole operare. Gli utenti che hanno un ruolo che permette il livello di accesso di scrittura o lettura sull’azione SERVICE_OPERATION possono operare senza restrizioni su tutti gli interni del PBX, mentre gli utenti standard del tenant (o utenti il cui ruolo ha livello di accesso nessuno o lista sull’azione SERVICE_OPERATION) possono operare solamente sul proprio interno.

Body della richiesta

Il body dovrà essere

{
  "operationData": "valore"
}

Maggiori dettagli sui valori ammessi sono forniti nel dettaglio di ciascun servizio.

Body della risposta
La struttura di base della risposta (per le richieste GET e POST) è comune a tutti i servizi ed è la seguente

{
   "tenantUuid": "tenentUuid",
   "serviceName": "serviceName",
   "key": "key",
   "operationData": serviceData
}

Le richieste DELETE invece non prevedono body di risposta.

Maggiori dettagli sul valore di operationData sono forniti nel dettaglio di ciascun servizio.

Codici di risposta

Codice HTTP	Descrizione
200	Nessun errore, la richiesta è stata eseguita correttamente
400	Solamente in caso di POST, indica che il body della richiesta non è corretto
403	L’utente che ha effettuato la richiesta non ha i privilegi necessari. Questo si verifica quando si verificano entrambe le seguenti condizioni l’interno identificato dal parametro key non è assegnato all’utente che ha fatto la richiestal’utente che ha fatto la richiesta non ha il giusto livello di accesso (lettura per la `GET`, scrittura per `POST` e `DELETE`) sull’azione `SERVICE_OPERATION` Se una o entrambe le condizioni precedenti sono false (ovvero l’interno è assegnato all’utente che ha fatto la richiesta, oppure l’utente ha il giusto livello di accesso per l’azione SERVICE_OPERATION), l’accesso è consentito

Servizio BUSYLEVEL

GET /rest/operation/BUSYLEVEL/{key}

Questa API permette di conoscere l’attuale valore di livello di occupato impostato per un certo interno, il parametro key nel path. Supponendo di voler ottenere lo stato operativo corrente del livello di occupato per l’interno 101, l’API da invocare sarà

GET https:///rest/operation/BUSYLEVEL/101

La risposta avrà la struttura seguente

{
   "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
   "serviceName": "BUSYLEVEL",
   "key": "101",
   "operationData": false
}

Il valore di operationData restituito può essere sia il valore booleano false, che sta ad indicare l’assenza di un’impostazione operativa per il livello di occupato, sia il numero intero precedentemente impostato tramite l’API POST.

{
   "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
   "serviceName": "BUSYLEVEL",
   "key": "101",
   "operationData": 1
}

Nota

In assenza di un’impstazione operativa il livello di occupato per l’intero sarà quello impostato nel template associato all’interno, oppure – in caso di override abilitato per il livello di occupato – quello impostato nell’interno.

Quando il valore di operationData è 0 significa che il livello di occupato è impostato ad infinito.

POST /rest/operation/BUSYLEVEL/{key}

Questa API permette di impostare il valore di livello di occupato per un certo interno, il parametro key nel path. Supponendo di voler impostare il livello di occupato per l’interno 101 ad 1, l’API da invocare sarà

POST https:///rest/operation/BUSYLEVEL/101

Il body della richiesta dovrà essere

{
   "operationData": 1
}

Nota

Il valore di operationData può essere anche una stringa, ma questa deve necessariamente contenere un numero intero altrimenti verrà restituita una risposta 400.

Body valido:

{
    "operationData": "1"
}

Body non valido:

{
    "operationData": "uno"
}

Il formato del body restituito dall’API di POST è lo stesso della GET, il valore di operationData nella risposta rifletterà quello presente nella richiesta a riscontro dell’avvenuta modifica.

DELETE /rest/operation/BUSYLEVEL/{key}
Questa API permette di cancellare l’impostazione operativa per il livello di occupato impostato per un certo interno, il parametro key nel path. Supponendo di voler cancellare il livello di occupato impostato per l’interno 101, l’API da invocare sarà

DELETE https:///rest/operation/BUSYLEVEL/101

Servizio CFBS

GET /rest/operation/CFBS/{key}

Questa API permette di conoscere l’attuale impostazione operativa di inoltro su occupato per un certo interno, il parametro key nel path. Supponendo di voler ottenere lo stato operativo corrente per l’interno 101, l’API da invocare sarà

GET https:///rest/operation/CFBS/101

La risposta avrà la struttura seguente

{
    "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
    "serviceName": "CFBS",
    "key": "101",
    "operationData": false
}

Il valore di operationData restituito può essere sia il valore booleano false, che sta ad indicare la disabilitazione del servizio, sia una stringa contenente il numero impostato per l’inoltro.

Risposta in caso di inoltro impostato

{
    "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
    "serviceName": "CFBS",
    "key": "101",
    "operationData": "102"
}

POST /rest/operation/CFBS/{key}

Questa API permette di impostare il numero al quale inoltrare la chiamata in caso di occupato per un certo interno, il parametro key nel path. Supponendo di voler impostare l’inoltro per l’interno 101 verso l’interno 102, l’API da invocare sarà

POST https:///rest/operation/CFBS/101

Nota

Per questo servizio, il valore da impostare deve essere una sequenza arbitraria di cifre decimali racchiusa tra doppi apici. Questo accorgimento è fondamentale per poter impostare inoltri verso numerazioni che iniziano con lo 0. Se il dato fosse trattato come numero intero questo non sarebbe possibile. Dovendo essere interpretato come stringa, il dato stesso deve essere racchiuso tra caratteri " (doppio apice) di cui dovrà essere fatto l’escape.

Il body della richiesta dovrà essere

{
    "operationData": "\"102\""
}

DELETE /rest/operation/CFBS/{key}
Questa API permette di cancellare l’impostazione operativa per l’inoltro su occupato impostato per un certo interno, il parametro key nel path. Supponendo di voler cancellare l’inoltro impostato per l’interno 101, l’API da invocare sarà

DELETE https:///rest/operation/CFBS/101

Servizio CFIM
GET /rest/operation/CFIM/{key}

Questa API permette di conoscere l’attuale impostazione operativa di inoltro incondizionato per un certo interno, il parametro key nel path. Supponendo di voler ottenere lo stato operativo corrente per l’interno 101, l’API da invocare sarà

GET https:///rest/operation/CFIM/101

La risposta avrà la struttura seguente

{
    "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
    "serviceName": "CFIM",
    "key": "101",
    "operationData": false
}

Risposta in caso di inoltro impostato

{
    "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
    "serviceName": "CFIM",
    "key": "101",
    "operationData": "102"
}

POST /rest/operation/CFIM/{key}

Questa API permette di impostare il numero al quale inoltrare la chiamata in maniera incondizionata per un certo interno, il parametro key nel path. Supponendo di voler impostare l’inoltro per l’interno 101 verso l’interno 102, l’API da invocare sarà

POST https:///rest/operation/CFIM/101

Nota

Il body della richiesta dovrà essere

{
    "operationData": "\"102\""
}

DELETE /rest/operation/CFIM/{key}
Questa API permette di cancellare l’impostazione operativa per l’inoltro incondizionato impostato per un certo interno, il parametro key nel path. Supponendo di voler cancellare l’inoltro impostato per l’interno 101, l’API da invocare sarà

DELETE https:///rest/operation/CFIM/101

Servizio CFNA

GET /rest/operation/CFNA/{key}
Questa API permette di conoscere l’attuale impostazione operativa di inoltro su non risposta per un certo interno, il parametro key nel path. Supponendo di voler ottenere lo stato operativo corrente per l’interno 101, l’API da invocare sarà

GET https:///rest/operation/CFNA/101

La risposta avrà la struttura seguente

{
    "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
    "serviceName": "CFNA",
    "key": "101",
    "operationData": false
}

Risposta in caso di inoltro impostato

{
    "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
    "serviceName": "CFNA",
    "key": "101",
    "operationData": "102"
}

POST /rest/operation/CFNA/{key}

Questa API permette di impostare il numero al quale inoltrare la chiamata in caso di non risposta per un certo interno, il parametro key nel path. Supponendo di voler impostare l’inoltro per l’interno 101 verso l’interno 102, l’API da invocare sarà

POST https:///rest/operation/CFNA/101

Il body della richiesta dovrà essere

{
    "operationData": "\"102\""
}

DELETE /rest/operation/CFNA/{key}
Questa API permette di cancellare l’impostazione operativa per l’inoltro su non risposta impostato per un certo interno, il parametro key nel path. Supponendo di voler cancellare l’inoltro impostato per l’interno 101, l’API da invocare sarà

DELETE https:///rest/operation/CFNA/101

Servizio CFUN

GET /rest/operation/CFUN/{key}
Questa API permette di conoscere l’attuale impostazione operativa di inoltro su non disponibile per un certo interno, il parametro key nel path. Supponendo di voler ottenere lo stato operativo corrente per l’interno 101, l’API da invocare sarà

GET https:///rest/operation/CFUN/101

La risposta avrà la struttura seguente

{
    "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
    "serviceName": "CFUN",
    "key": "101",
    "operationData": false
}

Risposta in caso di inoltro impostato

{
    "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
    "serviceName": "CFUN",
    "key": "101",
    "operationData": "102"
}

POST /rest/operation/CFUN/{key}

Questa API permette di impostare il numero al quale inoltrare la chiamata in caso di non disponibile per un certo interno, il parametro key nel path. Supponendo di voler impostare l’inoltro per l’interno 101 verso l’interno 102, l’API da invocare sarà

POST https:///rest/operation/CFUN/101

Nota

Il body della richiesta dovrà essere

{
    "operationData": "\"102\""
}

DELETE /rest/operation/CFUN/{key}

Questa API permette di cancellare l’impostazione operativa per l’inoltro su non disponibile impostato per un certo interno, il parametro key nel path. Supponendo di voler cancellare l’inoltro impostato per l’interno 101, l’API da invocare sarà

DELETE https:///rest/operation/CFUN/101

Servizio DND
GET /rest/operation/DND/{key}

Questa API permette di conoscere l’attuale impostazione operativa del “non disturbare” per un certo interno, il parametro key nel path. Supponendo di voler ottenere lo stato operativo corrente per l’interno 101, l’API da invocare sarà

GET https:///rest/operation/DND/101

La risposta avrà la struttura seguente

{
    "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
    "serviceName": "DND",
    "key": "101",
    "operationData": false
}

Il valore di operationData restituito sarà un boolean, false che indica la disabilitazione del servizio, e true che indica l’abilitazione del servizio.

POST /rest/operation/DND/{key}

Questa API permette di abilitare/disabilitare il “non disturbare” per un certo interno, il parametro key nel path. Supponendo di voler abilitare il servizio per l’interno 101, l’API da invocare sarà

POST https:///rest/operation/DND/101

Nota

Per questo servizio il valore da impostare deve essere il valore booleano true o false, ma questo deve essere racchiuso tra doppi apici (diventando di fatto una stringa).

Il body della richiesta dovrà essere

{
    "operationData": "true"
}

DELETE /rest/operation/DND/{key}

Questa API permette di cancellare l’impostazione operativa del “non disturbare” impostato per un certo interno, il parametro key nel path. Supponendo di voler cancellare l’impostazione fatta per l’interno 101, l’API da invocare sarà

DELETE https:///rest/operation/DND/101

Servizio FORKMOBILE
GET /rest/operation/FORKMOBILE/{key}
Questa API permette di conoscere l’attuale impostazione operativa del fork delle chiamate verso il numero mobile per un certo interno, il parametro key nel path. Supponendo di voler ottenere lo stato operativo corrente per l’interno 101, l’API da invocare sarà

GET https:///rest/operation/FORKMOBILE/101

La risposta avrà la struttura seguente

{
    "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
    "serviceName": "FORKMOBILE",
    "key": "101",
    "operationData": false
}

Il valore di operationData restituito sarà un boolean, false che indica la disabilitazione del servizio, e true che indica l’abilitazione del servizio.

POST /rest/operation/FORKMOBILE/{key}
Questa API permette di abilitare/disabilitare il fork delle chiamate verso il numero mobile per un certo interno, il parametro key nel path. Supponendo di voler abilitare il servizio per l’interno 101, l’API da invocare sarà

POST https:///rest/operation/FORKMOBILE/101

Nota

Per questo servizio il valore da impostare deve essere il valore booleano true o false, ma questo deve essere racchiuso tra doppi apici (diventando di fatto una stringa).

Il body della richiesta dovrà essere

{
    "operationData": "true"
}

DELETE /rest/operation/FORKMOBILE/{key}

Questa API permette di cancellare l’impostazione operativa del fork delle chiamate verso il numero mobile impostato per un certo interno, il parametro key nel path. Supponendo di voler cancellare l’impostazione fatta per l’interno 101, l’API da invocare sarà

DELETE https:///rest/operation/FORKMOBILE/101

Servizio EXTEN_HUNTING

GET /rest/operation/EXTEN_HUNTING/{key}

Questa API permette di conoscere l’attuale impostazione operativa dell’ordine di distribuzione della chiamata ai vari account associati all’interno (di seguito “hunting” per semplicità) per un certo interno, il parametro key nel path. Supponendo di voler ottenere lo stato operativo corrente per l’interno 101, l’API da invocare sarà

GET https:///rest/operation/EXTEN_HUNTING/101

La risposta avrà la struttura seguente

 
{
   "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
   "serviceName": "EXTEN_HUNTING",
   "key": "101",
   "operationData": [
       {
           "priority": 1,
           "accounts": [
               {
                   "id": 1
               },
               {
                   "id": 6
               },
               {
                   "id": 7
               }
           ]
       }
   ]
}

Il valore di operationData restituito sarà un array di oggetti JSON con attributi priority ed accounts. accounts a sua volta è un array di oggetti JSON con solamente l’attributo id, ovvero l’id dell’account.

Nell’esempio riportato sopra si vede che gli account con id 1, 6 e 7 sono tutti inseriti nella priorità 1, ciò significa che al ricevimento di una chiamata questa verrà presentata contemporaneamente a tutti e tre gli account e questi squilleranno in contemporanea.

{
   "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
   "serviceName": "EXTEN_HUNTING",
   "key": "101",
   "operationData": [
       {
           "priority": 1,
           "accounts": [
               {
                   "id": 1
               }
           ]
       },
       {
           "priority": 2,
           "accounts": [
               {
                   "id": 6
               },
               {
                   "id": 7
               }
           ]
       }
   ]
}

In questo secondo esempio sono invece presenti due priorità, nella prima è presente solamente l’account con id 1 e nella seconda gli account con id 6 e 7. In questo caso, al ricevimento di una chiamata questa verrà presentata solamente all’account con id 1 e se questa non viene risposta, l’hunting procederà presentando la chiamata agli altri due account in contemporanea.

È quindi possibile personalizzare completamente la consegna delle chiamate ai vari account dell’interno.

In assenza di una configurazione specifica il comportamento di default sarà la consegna delle chiamate in contemporanea a tutti gli account dell’interno, quindi un’unica priorità con tutti gli account al suo interno.

Nota

Per il servizio EXTEN_HUNTING non è presente l’API DELETE, per tornare quindi al comportamento di default è necessario impostare l’hunting con un’unica priorità inserendo al suo interno tutti gli account associati all’interno.

POST /rest/operation/EXTEN_HUNTING/{key}

Questa API permette di impostare l’hunting per un certo interno, il parametro key nel path. Supponendo di voler impostare l’hunting per l’interno 101, l’API da invocare sarà

POST https:///rest/operation/EXTEN_HUNTING/101

Formato del body

Per questo servizio il valore da impostare deve essere l’oggetto JSON rappresentante l’hunting, lo stesso tipo di oggetto restituito dalla GET.

Supponiamo di voler impostare un hunting con due priorità dove nella prima è presente solamente l’account con id 1 e nella seconda gli account con id 6 e 7, l’oggetto JSON che rappresenta questa configurazione sarebbe

[
  {
     "priority":1,
     "accounts":[
        {
           "id":1
        }
     ]
  },
  {
     "priority":2,
     "accounts":[
        {
           "id":6
        },
        {
           "id":7
        }
     ]
  }
]

L’oggetto JSON stesso rappresentante la configurazione deve essere trasformato in una stringa mediante l’escape dei caratteri " (doppio apice).

Il body della richiesta dovrà quindi essere

{
    "operationData": "[{\"priority\": 1, \"accounts\": [{\"id\": 1}]}, {\"priority\": 2, \"accounts\": [{\"id\": 6}, {\"id\": 7}]}]"
}

GET /rest/operation/queue

Tramite questa API è possibile ottenere le informazioni sui membri dinamici e sullo stato di pausa dei membri (sia statici che dinamici) di tutte le code.

Body della risposta

La struttura della risposta si compone di un oggetto JSON con tanti attributi quante sono le code definite, dove l’attributo è il nome della coda stessa. All’interno di ciascun oggetto “coda” possono essere presenti gli attributi dynamicMembers e pause. La presenza di uno o entrambi questi attributi è vincolata al fatto che siano stati aggiunti membri dinamici alla coda o che almeno un operatore sia stato messo in pausa o tolto dalla pausa. Quando nessuna di queste condizioni si verifica l’oggetto “coda” avrà valore null.

{
   "Queue 1": {
       "pause": {
           "SIP/101-app": {
               "status": true,
               "timestamp": "2024-01-17 19:07:50.814301+01"
           },
           "SIP/101-cti": {
               "status": true,
               "timestamp": "2024-01-17 19:09:33.84229+01"
           },
           "SIP/101-phone": {
               "status": false,
               "timestamp": "2024-01-17 18:21:43.463215+01"
           }
       },
       "dynamicMembers": {
           "SIP/101-cti": 0
       }
   },
   "Queue 2": null
}

Dettaglio dell’attributo pause

L’attributo pause è un oggetto JSON con tanti attributi quanti sono gli account per i quali è stato modificato almeno una volta lo stato di pausa, dove l’attributo è l’identificativo SIP dell’account stesso.

Nota

L’attributo pause potrebbe non contenere tutti gli accoun assegnati alla coda, contiene solamente gli account per i quali è stat modificato almeno una volta lo stato di pausa. Gli account assegnati a una coda, che siano statici o dinamici, e che non compaiono all’interno dell’attributo pause, sono da considerarsi non in pausa.

Nota

La presenza di un account all’interno dell’attributo pause non ne determina l’assegnazione alla coda. Per determinare l’elenco degli account assegnati ad una coda deve essere fatta l’unione degli account assegnati staticamente alla coda (recuperabili con l’API GET https://<PBX address>/api/pbx/v2/queue/{id}/account) e gli account dinamici presenti nell’attributo dynamicMembers.

Ogni attributo “SIP account” è un oggetto a sua volta contenente due attributi:

status: valore booleano che identifica lo stato di pausa dell’account nella coda. Se è true l’account è in pausa, se è false non lo è
timestamp: data ed ora, in formato ISO 8601, dell’ultimo cambio di stato

Dettaglio dell’attributo dynamicMembers

L’attributo dynamicMembers è un oggetto JSON con tanti attributi quanti sono i membri dinamici aggiunti alla coda, dove l’attributo è l’identificativo SIP dell’account stesso.

L’attributo “SIP account” ha come valore un intero, rappresentante la penalty del membro dinamico all’interno della coda.

Codici di risposta

Codice HTTP

Descrizione

200

Nessun errore, la richiesta è stata eseguita correttamente

403

L’utente che ha effettuato la richiesta non ha i privilegi necessari. Questo si verifica quando, in un PBX multi-tenant, l’utente che ha fatto la richiesta è di macchina e non di tenant. L’accesso a questa API è consentito a tutti gli utenti di tenantSe una o entrambe le condizioni precedenti sono false (ovvero l’interno è assegnato all’utente che ha fatto la richiesta, oppure l’utente ha il giusto livello di accesso per l’azione SERVICE_OPERATION), l’accesso è consentito

GET /rest/operation/queue/{queueName}

Tramite questa API è possibile ottenere le informazioni sui membri dinamici e sullo stato di pausa dei membri (sia statici che dinamici) di una specifica coda.

Parametri

Nome	Obbligatorio
queueName	Il nome della coda per la quale si vogliono ottenere i dati

Body della risposta

La struttura della risposta è la stessa di quella dell’API GET https://<PBX address>/rest/operation/queue, con l’unica differenza che conterrà solamente i dati della coda richiesta.

{
   "Queue 1": {
       "pause": {
           "SIP/101-app": {
               "status": true,
               "timestamp": "2024-01-17 19:07:50.814301+01"
           },
           "SIP/101-cti": {
               "status": true,
               "timestamp": "2024-01-17 19:09:33.84229+01"
           },
           "SIP/101-phone": {
               "status": false,
               "timestamp": "2024-01-17 18:21:43.463215+01"
           }
       },
       "dynamicMembers": {
           "SIP/101-cti": 0
       }
   }
}

Codici di risposta

Codice HTTP	Descrizione
200	Nessun errore, la richiesta è stata eseguita correttamente
403	L’utente che ha effettuato la richiesta non ha i privilegi necessari. Questo si verifica quando – in un PBX multi-tenant, l’utente che ha fatto la richiesta è di macchina e non di tenant. L’accesso a questa API è consentito a tutti gli utenti di tenant
404	La coda specificata nel parametro `queueName` non è stata trovata

POST /rest/operation/queue/{operation}

Tramite questa API è possibile

aggiungere/rimuovere un operatore dinamico ad una specifica coda
aggiungere/rimuovere un operatore dinamico a tutte le code
mettere/togliere dalla pausa un operatore su una specifica coda
mettere/togliere dalla pausa un operatore da tutte le code

Parametri

Nome	Obbligatorio	Descrizione
operation	sì	I valori ammessi per questo parametro sono:pause: per agire sullo stato di pausadynamicMember: per agire sui membri dinamici

Body della risposta

Non è previsto nessun body nella risposta per questa API.

Codici di risposta

Codice HTTP	Descrizione
200	Nessun errore, la richiesta è stata eseguita correttamente
400	Il body della richiesta non è corretto
403	L’utente che ha effettuato la richiesta non ha i privilegi necessari. Questo si verifica quando – in un PBX multi-tenant, l’utente che ha fatto la richiesta è di macchina e non di tenant. L’accesso a questa API è consentito a tutti gli utenti di tenant

Gestione degli operatori dinamici

Per le operazioni sugli operatori dinamici deve essere invocata l’API

POST https:///rest/operation/queue/dynamicMember

Body della richiesta
La struttura di base dell’oggetto JSON della richiesta è

{
    "queue": "Queue 2",
    "account": "SIP/101-phone-2",
    "enabled": true,
    "penalty": 0
}

dove

Aggiunta di un operatore dinamico ad una specifica coda
Supponiamo di voler aggiungere l’account SIP/101-phone-2 come membro dinamico della coda Queue 2 con penalty 1, il body della richiesta dovrà essere

{
    "queue": "Queue 2",
    "account": "SIP/101-phone-2",
    "enabled": true,
    "penalty": 1
}

Aggiunta di un operatore dinamico a tutte le code

Supponiamo di voler aggiungere l’account SIP/101-phone-2 come membro dinamico su tutte le code con penalty 0, il body della richiesta dovrà essere

{
    "account": "SIP/101-phone-2",
    "enabled": true,
    "penalty": 0
}

Rimozione di un operatore dinamico da una specifica coda

Supponiamo di voler rimuovere l’account SIP/101-phone-2 dai membri dinamici della coda Queue 2, il body della richiesta dovrà essere

{
    "queue": "Queue 2",
    "account": "SIP/101-phone-2",
    "enabled": false
}

Rimozione di un operatore dinamico da tutte le code

Supponiamo di voler rimuovere l’account SIP/101-phone-2 dai membri dinamici di tutte le code, il body della richiesta dovrà essere

{
    "account": "SIP/101-phone-2",
    "enabled": false,
}

Gestione della pausa degli operatori

Per le operazioni sulla pausa degli operatori deve essere invocata l’API

POST https:///rest/operation/queue/pause

Body della richiesta
La struttura di base dell’oggetto JSON della richiesta è

{
    "queue": "Queue 2",
    "account": "SIP/101-phone-2",
    "enabled": true
}

dove

Nome	Obbligatorio	Descrizione
queue	no	È il nome della coda per la quale vogliamo mettere/togliere dalla pausa l’operatore. Se l’attributo non è presente nella richiesta, questa agirà su tutte le code
account	sì	È l’identificativo SIP dell’account da mettere/togliere dalla pausa
enabled	no	È un valore booleano che indica l’operazione da compiere. Se è true l’account viene messo in pausa, se è false viene tolto dalla pausa. Se l’attributo non è presente nella richiesta questo viene interpretato come false

Messa in pausa di un operatore su una specifica coda

Supponiamo di voler mettere in pausa l’account SIP/101-phone-2 sulla coda Queue 2, il body della richiesta dovrà essere

{
    "queue": "Queue 2",
    "account": "SIP/101-phone-2",
    "enabled": true
}

Messa in pausa di un operatore su tutte le code

Supponiamo di voler mettere in pausa l’account SIP/101-phone-2 su tutte le code, il body della richiesta dovrà essere

{
    "account": "SIP/101-phone-2",
    "enabled": true
}

Togliere dalla pausa un operatore su una specifica coda

Supponiamo di voler togliere dalla pausa l’account SIP/101-phone-2 sulla coda Queue 2, il body della richiesta dovrà essere

{
    "queue": "Queue 2",
    "account": "SIP/101-phone-2",
    "enabled": false
}

CENTRALINO CLOUD – IPPBX OlimonTel API Rest

Configurazioni

CENTRALINO CLOUD – IPPBX OlimonTel