Documentazione API web v 1.0

Documentazione API web v 1.0 Web: www.kalliopepbx.it Supporto tecnico: kalliope-pbx@netresults.it 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: kalliope-pbx@netresults.it 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 URL 1 : 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 descrizione 0 Success Comando completato con successo 1 Internal Error Errore interno all API 2 Missing or unknown command 3 Authentication error 4 Missing or wrong argument 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 Documentazione API web v1.0-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 Descrizione number type M O Numero telefonico che deve essere chiamato, eventualmente comprensivo di prefisso internazionale Tipologia di numero. Può assumere i valori - 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 descrizione 10 Error 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 begin end startflag M M O La data ed ora di inizio dell intervallo temporale di interesse, in 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-07- 01+14%3A52%3A30). 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 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 10 Invalid date time 11 Invalid date time interval Uno dei due parametri begin o end è mancante o formattato in modo non conforme L istante begin è successivo all istante end Documentazione API web v1.0-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 direction seriale univoco della forma YYYYMMnnnnnnnn (YYYY=anno, MM=mese, nnnnnnnn=sequenziale all interno del mese. 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 caller_name called_num called_name called_callgroup gateway_id gateway_name status Numero telefonico del chiamante. 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 Numero telefonico del chiamato Identificativo del chiamante, analogo al caller_name In caso di chiamate in ingresso destinate ad un gruppo o ad una coda, contiene il nome del gruppo/coda. ID del gateway, come definito su KalliopePBX Nome assegnato al gateway assume valori numerici che hanno il seguente significato: - 1 chiamata fallita - 2 numero chiamato occupato - 3 congestione - 4 chiamata non risposta - 8 chiamata risposta billsec 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 answer end duration Istante di inizio della chiamata Istante di risposta Istante di fine della chiamata 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