SOAP API (podpora ukončena 1.7.2017)

Owned by Marek Červenka
Last updated: čvc 15, 2019
3 min read

POZOR: Podpora protokolu SOAP bude ukončena k 1.7.2017. Funkce budou dostupné v rámci REST API local (deprecated)



SOAP (celým názvem Simple Object Access Protocol) je protokolem pro výměnu zpráv založených na XML přes síť, hlavně pomocí HTTP. Formát SOAP tvoří základní vrstvu komunikace mezi webovými službami a poskytuje prostředí pro tvorbu složitější komunikace.

Existuje několik různých druhů šablon pro komunikaci na protokolu SOAP. Nejznámější z nich je RPC šablona, kde jeden z účastníků komunikace je klient a na druhé straně je server. Server ihned odpovídá na požadavky klienta.

SOAP je nástupce XML-RPC, ačkoliv si zapůjčuje jeho způsob přenosu dat a další vlastnosti. Obálka, hlavička a tělo komunikace je ale pravděpodobně z WDDX.

Původně ho navrhl Dave Winer, Don Box, Bob Atkinson a Mohsen Al-Ghosein v roce 1998 za podpory firmy Microsoft (kde tou dobou Atkinson a Al-Ghosein pracovali). Dnes je SOAP specifikace držena XML skupinou tvořící internetové protokoly z W3C konsorcia.


Zdroj http://cs.wikipedia.org/wiki/SOAP


Tento dokument popisuje základní metody pro integraci pobočkové ústředny s Informačním systémem, CRM a dalšími systémy. Umožňuje ovládat ústřednu z pohledu administrace tzn. založit linku, změnit parametry atp. Dále umožňuje získávat informace o aktuálních stavech jako jsou aktuální hovory, stav vyzvánění u linek. Umožňuje také periodicky získávat CDR.

Ověření

Probíhá na bázi http basic auth. Heslován je přístup k wsdl souboru. Komunikace je šifrovaná. Login a heslo pro přístup k souboru je přebírán z definice uživatelů v ústředně („Uživatelé“).

URL pro autentizaci: https://IP_ustredny/…ap/ipbx.wsdl

Pro připojení k SOAP serveru je nutné v administračním rozhraní ústředny vytvořit uživatele s právy SOAP.


SOAP typy proměnných

Celé názvosloví bylo zvoleno tak, aby korespondovalo s již zavedeným názvoslovím ve světě PBX.
Místo Line byl zvolen zkrácený název Exten od slova Extension, které znamená v překladu pobočková linka.

Dokumentace viz http://cdn.ipex.cz/ipbx.wsdl


getExtenCalls -> protože linka může současně vést několik hovorů, funkce vrací pole vedených
hovorů. Informace o aktuálních hovorech v ústředně.


SOAP funkce

Zde definujeme funkce, které potřebujeme pro základní interakci našeho IS s ústřednou.

Management linek


  •     getExten Získá nastavení linky. Vrací pole informací o lince (typ LineInfo).
  •     extenInfo Vrací nastavení linky a SIP kanálu.
  •     getCELList Získá serializované pole události.
  •     createExten Vytvoří linku.
  •     deleteExten Zrušení linky.
  •     getAllExten Nastavení všech linek. získání pole informací o linkách (každá typ LineInfo).
  •     updateExten Změna parametru linky.
  •     getExtenCalls Zjištění stavu linky.
  •     redirectExten Změna parametru linky.
  •     getDialplanList Seznam číslovacích plánů.
  •     getOutRouteList Seznam odchozích směrování.
  •     getAllExtenCalls Zjištění stavu všech linek.
  •     deleteSpecialExten Smazani speciální linky a zařízení.
  •     cancelRedirectExten Zruší přesměrování linky lineNumber.
  •     getAllActiveExtenCalls identicka funkce jako getAllExtenCalls, ale tato funkce zobrazuje je ty linky, ktere hovori.




Hovory

  • originateExten(fromNumber,lineNumber) vyvolá hovor z fromNumber linky(číslo linky) na lineNumber(na jakékoliv číslo)
  • getExtenCalls získá seznam aktuálních hovorů, které probíhají pro danou linku
  • getAllExtenCalls získá seznam aktuálních hovorů, které probíhají na všech linkách
  • isRingingExten(lineNumber) vrátí číslo, které zvoní na lince lineNumber. Když nikdo nevolá vrátí false.
  • monitorExten(lineNumber,listenerLineNumber) nastavit příposlech
  • actionTransfer provede přepojení hovoru. Parametry jsou zdrojový kanál a id cílové linky.
  • hangupExten Ukončení hovorů zadané linky.


Výpisy

  • getCDRList(fromDate,toDate) získá výpis hovorů (pole, kde budou obsaženy všechny informace z CDR výpisu) omezený úsekem zadaných dat


Statistiky Call Centra


Nahrávání

  • setRecordingExtenOn(lineNumber) nastaví, že linka bude nahrávaná
  • setRecordingExtenOff(lineNumber) nastaví, že linka nebude nahrávaná
  • getMonitorFile(fileName) - stáhne nahrávku hovoru

Ovládání seznamu kontaktů

  • createContact vytvoří nový kontakt
  • deleteContact odstraní kontakt
  • getContact vrací podrobné informace o jednom kontaktu
  • getAllContacts vrací celý seznam kontaktů. U jednotlivých kontaktů vrací id, celé jméno a telefonní čísla.

Systémové funkce

  • reloadConfiguration provede nové načtení konfigurace ústředny. Načtení konfigurace je potřeba provést po použití funkcí createExten, updateExten, setRecordingExtenOn a setRecordingExtenOff.


Příklady


Příklad odchozího volání v jazyce PHP. Zavolá linku uživatele, který chce odchozí hovor
uskutečnit. Po zvednutí sluchátka je iniciován hovor na volané číslo.

<?php
$username="soap";
$password="soapheslo";
$client = new

SoapClient("https://IP_ustredny/ipbx/soap/wsdl.php",array('encoding'=>'UTF-8','trace'=>1,'exceptions'=>1,'login'=>$username,'password'=>$password));

// zavolej na telefonni cislo
try {
     $out=$client->__soapCall("originateExten",array("from"=>"85","to"=>"0575750957","callerId"=>"85"));
     print_r($out);
}
     catch (Exception $e)
{
print_r($e);
};
?>


Další příklady k jednotlivým funkcím jsou k dispozici v repozitáři examples - https://bitbucket.org/ipex/examples