API Rest

Descrizione generale

KalliopePBX 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 KalliopePBX 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».

Il campo Digest è un hash dei dati sopra descritti e della password dell’utente, e si calcola applicando la funzione di hash sha256 alla concatenazione delle stringhe Nonce, digestPassword, Username, Domain e Created (concatenazione delle stringhe senza delimitatori):

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

Dato che sul KalliopePBX 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 KalliopePBX mediante una API REST apposita, invocabile in modo anonimo (senza autenticazione):

rest/salt/<dominio_tenant>

dove la stringa <dominio_tenant> ,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{<salt>})

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"

Elenco API

La lista dettagliata e aggiornata delle API è consultabile direttamente tramite l’interfaccia web di KalliopePBX all’indirizzo

http[s]://KALLIOPE_IP_ADDRESS/api/doc

A partire dalla versione firmware 4.9.4 è disponibile inoltre una collection Postman (che sostituisce la sandbox integrata all’interno della pagina di documentazione); tale collection integra anche il codice per aggiungere automaticamente l’header di autenticazione richiesto (è necessario solo impostare l’indirizzo IP del PBX e le credenziali username/password dell’utente con cui invocare l’API).

Accedendo alla KalliopeTribe è disponibile un video che mostra l’utilizzo di tale collection per invocare in modo rapido le API di Kalliope.

È possibile scaricare il file di collection per le varie versioni firmware dai seguenti link:

È inoltre disponibile il file con la specifica swagger delle API, sempre scaricabile dal KalliopePBX, all’indirizzo:

http[s]://KALLIOPE_IP_ADDRESS/api/doc.json

Manuale per le API relative al CDR

Dal momento che le API relative al CDR sono le più comunemente utilizzate abbiamo realizzato un semplice documento di approfondimento su questa famiglia di API.

È possibile scaricare il documento da questo link.

Classi per la generazione degli header di autenticazione

Di seguito un elenco di progetti in vari linguaggi di programmazione per la generazione e validazione degli header di autenticazione.

  • phpRestApiUtils: implementazione in PHP

  • RegEx: espressione regolare utile per validare gli header generati

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 occupato

  • CFBS: (Call Forward Busy) agisce sull’inolto incondizionato in caso di occupato

  • CFIM: (Call Forward Immediate) agisce sull’inolto incondizionato

  • CFNA: (Call Forward Not Answer) agisce sull’inoltro in caso di non risposta

  • CFUN: (Call Forward Unavaiilable) agisce sull’inolto in caso di non disponibile

  • CLIP: RISERVATO

  • DND: (Do Not Disturb) agisce sul «non disturbare»

  • EXTEN_HUNTING: agisce sull’ordine di distribuzione della chiamata ai vari account dell’interno

  • FORKMOBILE: agisce sul fork delle chiamate verso il numero mobile

  • HUNTING: 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 richiesta

  • l’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://<PBX address>/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://<PBX address>/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://<PBX address>/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://<PBX address>/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://<PBX address>/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\""
}

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/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://<PBX address>/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://<PBX address>/rest/operation/CFIM/101

La risposta avrà la struttura seguente

{
    "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
    "serviceName": "CFIM",
    "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": "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://<PBX address>/rest/operation/CFIM/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\""
}

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/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://<PBX address>/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://<PBX address>/rest/operation/CFNA/101

La risposta avrà la struttura seguente

{
    "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
    "serviceName": "CFNA",
    "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": "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://<PBX address>/rest/operation/CFNA/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\""
}

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/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://<PBX address>/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://<PBX address>/rest/operation/CFUN/101

La risposta avrà la struttura seguente

{
    "tenantUuid": "07cb1c92-029a-493d-a036-9d518185c598",
    "serviceName": "CFUN",
    "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": "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://<PBX address>/rest/operation/CFUN/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\""
}

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/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://<PBX address>/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://<PBX address>/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://<PBX address>/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"
}

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/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://<PBX address>/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://<PBX address>/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://<PBX address>/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"
}

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/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://<PBX address>/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://<PBX address>/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://<PBX address>/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}]}]"
}

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.

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 tenant

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

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 pausa

  • dynamicMember: 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://<PBX address>/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://<PBX address>/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
}

Togliere dalla pausa un operatore su tutte le code

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

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