Documentazione API web – v 1.0

Documentazione API web – v 1.0
Web: www.kalliopepbx.it
Supporto tecnico: [email protected]
Documentazione API web – v1.0
-1-
Rev.: 05-09-2011
NetResults S.r.l.
Via Giuntini, 63 – 56023 - Navacchio di Cascina (PI)
Tel. +39 050 754730
Web: http://www.netresults.it – E-mail: [email protected]
Documentazione API web – v1.0
-2-
Rev.: 05-09-2011
Changelog
Versione 1.0 – Release KalliopePBX 3.7.4
Con il firmware 3.7.4 è stato aggiunto il supporto ad HTTPS (su porta standard 443) per
accedere all’API, mediante l’utilizzo di un certificato self-signed da una Autorità di
Certificazione interna.
La versione dell’API rimane 1.0 in quanto non sono state effettuate modifiche all’interfaccia.
Documentazione API web – v1.0
-3-
Rev.: 05-09-2011
Introduzione
A partire dalla release firmware 3.7.3, sono disponibili API web per l’integrazione di alcune
funzioni telefoniche offerte da KalliopePBX in software di terze parti. Questo documento
illustra le API introdotte, specificandone modalità di invocazione e relativo effetto/risposta.
Attualmente sono disponibili API dedicate alla consultazione del registro chiamate (CDR) ed al
servizio click-to-dial, invocate mediante metodi http GET/POST.
Ad ogni richiesta corrisponde una eventuale azione da parte di KalliopePBX ed una risposta
contenente i dati richiesti e/o l’esito della richiesta. La risposta viene fornita in formato
JSON, uno standard orientato alla rappresentazione in formato human-readable di strutture
dati generiche.
L’API è accessibile al seguente URL1:
http://<IP_KalliopePBX>/api/?<arg1>=<val1>[&<arg2>=<val2>[&…]]
Gli argomenti che vengono passati all’API includono il comando richiesto, le eventuali
credenziali di autenticazione, e gli eventuali parametri dello specifico comando. Nel seguito
vengono descritti in dettaglio il formato di invocazione dei singoli comandi ed i relativi
messaggi di risposta che costituiscono la versione corrente dell’API.
1
Con la release firmware 3.7.4 è possibile accedere all’API anche mediante HTTPS.
Documentazione API web – v1.0
-4-
Rev.: 05-09-2011
Descrizione API
L’indicazione del comando richiesto è effettuata utilizzando l’argomento “command”, che
può assumere uno dei seguenti valori:

version

c2c

cdr
Ad esclusione del comando “version”, che non richiede autenticazione, gli altri richiedono
che vengano passate all’API le credenziali di autenticazione e controllo di autorizzazione. Le
credenziali di autenticazione sono passate utilizzando i due parametri “user” e “password”:
http://<IP_KalliopePBX>/api/?command=<comando>&
user=<username>&password=<md5pwd>&...
Le credenziali utilizzate per le API sono le stesse utilizzate per il pannello WEB utente. In
aggiunta agli username degli utenti abilitati, per alcuni comandi sono validi anche gli utenti
“admin” (l’amministratore del PBX) e “cdradmin” (l’utente abilitato alla visualizzazione non
oscurata del CDR). Le password non vengono fornite in clear-text ma tramite il relativo hash
md5.
Ogni invocazione dell’API genera, oltre all’eventuale azione, una risposta in formato JSON.
Tutte le risposte hanno il medesimo formato:
{
"banner": "KalliopePBX web API",
"api_version": "1.0",
"command": <comando>,
"exit_code": <exit_code>,
"exit_msg": <exit_message>,
"data": []
}
dove:

“banner” è una stringa prefissata che identifica KalliopePBX come originatore della
risposta;

“api_version” è una stringa che contiene la versione dell’API che ha originato la
risposta;
Documentazione API web – v1.0
-5-
Rev.: 05-09-2011

“command” è una stringa che riporta il comando invocato;

“exit_code” è un codice numerico che, mediante il valore assunto, identifica l’esito
dell’invocazione del comando, secondo quanto specificato nel seguito;

“exit_msg” è una stringa contenente una descrizione sommaria dell’esito del
comando.

“data” è un array contente l’eventuale informazione richiesta a KalliopePBX (es. il
registro chiamate)
I valori dell’exit_code dipendono dal particolare comando richiesto. Sono presenti alcuni
codici comuni a tutti i comandi, raccolti nella tabella seguente insieme ai corrispondenti
messaggi, ma ciascun comando estende tale set con codici specifici (questi sono elencati
nella descrizione di ciascun messaggio).
exit_code
exit_msg
0
Success
1
Internal Error
2
Missing or unknown command
3
Authentication error
4
Missing or wrong argument
Documentazione API web – v1.0
descrizione
Comando completato con successo
Errore interno all’API
Comando
mancante,
non
specificato
o
sconosciuto
Errore di autenticazione (username e/o
password errati o vuoti)
Uno o più parametri necessari al comando
specificato sono mancanti o di tipo errato
-6-
Rev.: 05-09-2011
Comandi
Di seguito si riportano i comandi disponibili e le relative modalità di invocazione (parametri),
insieme alla descrizione dell’effetto del comando e della risposta attesa. Per quei comandi
che prevedono messaggi di errore addizionali rispetto a quelli base, ne vengono riportati
codici e descrizione.
La tabella seguente raccoglie tutti i comandi disponibili, specificando per ciascuno di essi le
versioni di API in cui è stato introdotto ed in cui ne è stato modificato.
Comando
Versione API introduzione
Versione API ultima modifica
c2c
1.0 (fw 3.7.3)
1.0 (fw 3.7.3)
cdr
1.0 (fw 3.7.3)
1.0 (fw 3.7.3)
version
1.0 (fw 3.7.3)
1.0 (fw 3.7.3)
- c2c
Implementa la funzione click-to-call (o click-to-dial). All’invocazione, il KalliopePBX farà
squillare il telefono dell’utente, e quando questi risponde (con timeout 10 secondi) verrà
generata la chiamata verso il numero richiesto.
Il comando richiede autenticazione con credenziali associate ad un interno (gli username
“admin” e “cdradmin” non sono utenti validi).
Il comando supporta i seguenti parametri (M: Mandatory, O: Optional):
Parametro
M/O
number
M
Descrizione
Numero telefonico che deve essere chiamato, eventualmente
comprensivo di prefisso internazionale
Tipologia di numero. Può assumere i valori
type
O
-
“exten” (il numero specificato è un interno del centralino),
-
“out” (il numero specificato è un numero esterno)
Nel caso in cui questo parametro sia mancante, vuoto o diverso da uno
dei precedenti, KalliopePBX gestirà la chiamata come se fosse
selezionata l’opzione “Ometti lo 0 per le chiamate esterne”,
verificando se il numero specificato corrisponde ad un interno o ad un
servizio del PBX, ed inoltrando altrimenti la chiamata verso l’esterno.
Documentazione API web – v1.0
-7-
Rev.: 05-09-2011
Oltre ai codici e messaggi di risposta standard, ne è previsto uno ulteriore:
exit_code
exit_msg
10
Error
descrizione
Errore di comunicazione con KalliopePBX
nell’attivazione della chiamata
Il comando non prevede di restituire valori nel campo “data” della risposta.
- cdr
Questo comando sostituisce ed estende la web API exportCDR introdotta nella release
firmware 3.7.2 e correntemente deprecata, fornendo uno strumento per l’accesso al registro
chiamate.
Il comando richiede autenticazione con credenziali associate ad un interno, oppure
“cdradmin”. Nel primo caso, viene restituito l’elenco delle chiamate che interessano
l’interno nell’intervallo specificato, limitatamente al periodo di validità dell’utente a cui tale
interno è associato. Nel secondo caso, vengono restituite le chiamate di tutti gli utenti. In
entrambi i casi i numeri chiamanti e chiamati vengono presentati nella loro interezza, e non
in forma anonimizzata.
Il comando supporta i seguenti parametri (M: Mandatory, O: Optional):
Parametro
M/O
Descrizione
La data ed ora di inizio dell’intervallo temporale di interesse, in
begin
M
formato ISO (Y-m-d H:i:s, es. “2011-07-01 14:52:30”), ora locale
adeguatamente codificata per poterla passare nell'URL (2011-0701+14%3A52%3A30).
end
M
La data ed ora di termine dell’intervallo temporale di interesse, in
formato analogo a “begin”
Flag che indica se l’intervallo temporale di interesse si riferisce agli
startFlag
O
istanti di inizio (se “startFlag”=”true”) o di fine (parametro mancante
o diverso da “true”) delle chiamate
Oltre ai codici e messaggi di risposta standard, ne sono previsti ulteriori:
exit_code
exit_msg
descrizione
Uno dei due parametri “begin” o “end” è
10
Invalid date time
mancante
o
formattato
in
modo
non
conforme
11
Invalid date time interval
Documentazione API web – v1.0
L’istante “begin” è successivo all’istante
“end”
-8-
Rev.: 05-09-2011
12
Internal error
Errore durante l’accesso al database del
registro chiamate
Il comando prevede di restituire le singole entry del CDR nel periodo selezionato come
elementi distinti dell’array “data”.
Per ciascun entry del CDR vengono riportate le seguenti informazioni:
dove:
“id”
seriale univoco della forma YYYYMMnnnnnnnn (YYYY=anno,
MM=mese, nnnnnnnn=sequenziale all’interno del mese.
“direction”
assume valori numerici che hanno il seguente significato:
-
1  Chiamata in ingresso (dall’esterno verso un interno)
-
2  Chiamata in uscita (da un interno verso l’esterno)
-
3  Chiamata locale (tra interni)
“caller_num”
Numero telefonico del chiamante.
“caller_name”
Identificativo del chiamante. In caso di chiamata effettuata da
un interno coincide con la stringa “Nome Cognome” impostata
sul PBX. In caso di chiamata proveniente dall’esterno questo
campo viene riempito dal centralino sfruttando la rubrica
telefonica. Se il numero non è contenuto in rubrica, questo
campo rimane vuoto
“called_num”
Numero telefonico del chiamato
“called_name”
Identificativo del chiamante, analogo al “caller_name”
“called_callgroup”
In caso di chiamate in ingresso destinate ad un gruppo o ad una
coda, contiene il nome del gruppo/coda.
“gateway_id”
ID del gateway, come definito su KalliopePBX
“gateway_name”
Nome assegnato al gateway
“status”
assume valori numerici che hanno il seguente significato:
“billsec”
-
1  chiamata fallita
-
2  numero chiamato occupato
-
3  congestione
-
4  chiamata non risposta
-
8  chiamata risposta
Durata effetiva della chiamata, dal momento della risposta al
riaggancio. Assume valori diversi da 0 solo per chiamate il cui
Documentazione API web – v1.0
-9-
Rev.: 05-09-2011
“status” sia pari a “8”; il valore di “billsec” è pari alla
differenza tra gli istanti “end” e “answer”
“start”
Istante di inizio della chiamata
“answer”
Istante di risposta
“end”
Istante di fine della chiamata
“duration”
Durata complessiva della chiamata, pari alla differenza tra gli
istanti “end” e “start”.
Il formato tipico di una invocazione e della relativa risposta sono riportate di seguito:
Request:
http://<IP_KalliopePBX>/api/?command=cdr&
user=cdradmin&
password=1234567890abcdef1234567890abcdef&
begin=2011-06-01+10%3A50%3A00&
end=2011-06-02+10%3A50%3A00&
startFlag=false
Response:
{
"banner": "KalliopePBX web API",
"api_version": "1.0",
"command": "cdr",
"exit_code": 0,
"exit_msg": "Success",
"data": [
{
"id": "20110600000017",
"direction": "2",
"caller_num": "104",
"caller_name": "Nome Cognome",
"called_num": "050123456",
"called_name": "",
"called_callgroup": "",
"gateway_id": "9001",
"gateway_name": "Patton SN4552",
"status": "8",
"billsec": "590",
"start": "2011-06-01 13:35:32",
"answer": "2011-06-01 13:35:50",
"end": "2011-06-01 13:45:40",
"duration": "608"
Documentazione API web – v1.0
- 10 -
Rev.: 05-09-2011
},
{
. . .
}
]
}
Nella response è evidenziata una chiamata in uscita (“direction”: “2”), effettuata
dall’interno 104 verso il numero 050123456 attraverso il gateway Patton SN4552 (con ID
9001); la chiamata è stata effettuata alle 13:35:52 del 01/06/2011, ed è stata risposta
(“status”: “8”) dopo 18 secondi. La conversazione è durata 590 secondi, per un totale di 608
secondi complessivi.
- version
Questo comando non richiede autenticazione (possono essere omessi i campi “user” e
“password”. Permette di verificare la corretta comunicazione con il KalliopePBX, ed ottenere
la versione delle API disponibili. Il codice di uscita del comando è sempre “0” (Success); di
seguito viene riportata l’invocazione del comando e la relativa risposta:
Request:
http://<IP_KalliopePBX>/api/?command=version
Response:
{
"banner": "KalliopePBX web API",
"api_version": "1.0",
"command": version,
"exit_code": 0,
"exit_msg": “Success”,
"data": null
}
Documentazione API web – v1.0
- 11 -
Rev.: 05-09-2011