API

Interfejs API od Zadarma pozwala na korzystanie z serwisu dla własnych aplikacji, a także integrację z dowolnymi systemami CRM i programami dla call centrów. Realizacja API jest otwarta, każdy programista poradzi sobie z nią ze względu na niski stopień skomplikowania.

W API dostępne są wszystkie niezbędne fukcję:

  • wyświetlenie ustawień SIP i centrali;
  • wyświetlenie statystyk i salda konta;
  • wysłanie połączeń (CallBack na numery zewnętrzne i wewnętrzne) oraz wiadomości SMS;
  • powiadomienia zewnętrznego serwera o połączeniu przychodzącym w centrali, a także zewnętrzne trasowanie połaczeń.

Link do API: https://api.zadarma.com

Wersja API: v1

Końcowy link do metody: https://api.zadarma.com/v1/METHOD/

Pobierz gotowe klasy PHP, Python dla pracy z API z naszego GitHub.

Autoryzacja

Każde żądanie, które wymaga autoryzacji, wysyłane jest z dodatkowym nagłówkiem typu:
"Authorization: klucz_użytkownika: podpis"

Klucze do autoryzacji należy wygenerować w Panelu klienta.

Podpis tworzony jest według następującego algorytmu:

  • szereg przekazywanych danych (GET, POST, PUT, DELETE) układa się alfabetycznie według nazwy klucza;
  • z otrzymanego szeregu tworzy się linia zapytania (np, funkcja http_build_query w PHP), przykład „from=DATEFROM&to=DATETO…”;
  • i dalej – łączy się według formuły: linia = imię_metoda linia_zapytania md5 (linia_zapytania), gdzie “imię_metoda” – linia zapytania, rozpoczynając od domeny (z zaznaczeniem wersji API), do początku wyliczenia parametrów, na przykład - /v1/sip/"
  • otrzymana linia łączy się dzięki algorytmowi sha1 z sekretnym kluczem użytkownika: hash = hash (linia, sekretny klucz)
  • następnie hash kodowany jest w base64 podpis = base64_encode (hash)

Przykład na PHP:

ksort($params);

$paramsStr = http_build_query($params, null, '&', PHP_QUERY_RFC1738);

$sign = base64_encode(hash_hmac('sha1', $method . $paramsStr . md5($paramsStr), $secret));

$header = 'Authorization: ' . $userKey . ':' . $sign;

Gotowy do pracy PHP z API, można pobrać z GitHub.

Format odpowiedzi: json (domyślnie) i xml.

Żeby otrzymać odpowiedź od API w formacie xml, dodaje się do żądania parametr "format=xml".

Ograniczenia

Odpowiedź również przedstawia informację o limitach i obecnym żądaniu, na przykład:

X-Zadarma-Method: /v1/
X-RateLimit-Reset: 1434371160
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99

gdzie,

  • X-Zadarma-Method - obecna metoda składania żądania;
  • X-RateLimit-Remaining - ilość pozostałych żądań, z uwzględnieniem limitu na metodę i użytkownika;
  • X-RateLimit-Limit - łączna liczba ograniczeń zapytania na minutę;
  • X-RateLimit-Reset - czas zresetowania limitu.

Ograniczenia ogólne - 100 zapytań na minutę, na metodach statystycznych - 10 zapytań na minutę.

W przypadku blokady metoda wyświetla odpowiedź z nagłówkiem 429 "You exceeded the rate limit".

Odpowiedź składa się z obowiązkowego klucza "status" (success lub error). Następnie, w zależności od metody, przedstawiane są własne klucze z żądanymi informacjami.

W przypadku błędu wyświetla się dodatkowy klucz "message" z opisem błędu.

Również wszystkie odpowiedzi przedstawiane są z odpowiednimi nagłówkami HTTP.

Przykład odpowiedzi błędu:

JSON:

	{
		"status":"error",
		"message":"Check phone's number"
	}

XML:

	<?xml version="1.0"?>
	<answer>
		<status>error</status>
		<message>Check phone's number</message>
	</answer>

Dostępne metody:

  • /v1/info/balance/
    saldo użytkownika.
  • /v1/info/price/
    cena na połączenia zgodnie z wybraną taryfą użytkownika.
  • /v1/info/timezone/
    strefa czasowa użytkownika.
  • /v1/tariff/
    informacja o obecnej taryfie użytkownika.
  • /v1/request/callback/
    callback.
  • /v1/sip/
    lista loginów SIP.
  • /v1/sip/<SIP>/status/
    online status SIP loginów.
  • /v1/sip/callerid/
    zmiana CallerID.
  • /v1/sip/redirection/
    wyświetlanie obecnych przekierowań na loginach SIP użytkownika.
  • /v1/direct_numbers/
    informacja o numerach wirtualnych użytkownika.
  • /v1/sim/
    informacja o kartach SIM użytkownika.
  • /v1/sip/redirection/
    włączenie/wyłączenie przekierowania na loginie SIP.
  • /v1/sip/redirection/
    zmiana przekierowania.
  • /v1/pbx/internal/
    wyświetlanie numerów wewnętrznych wirtualnej centrali.
  • /v1/pbx/internal/<PBXSIP>/status/
    online status numeru wewnętrznego.
  • /v1/pbx/internal/recording/
    włączenie nagrywania rozmów na numerze wewnętrznym.
  • /v1/pbx/record/request/
    żądanie na pobranie nagrania rozmowy.
  • /v1/sms/send/
    wysłanie SMS.
  • /v1/statistics/
    otrzymanie ogólnych statystyk.
  • /v1/statistics/pbx/
    statystyki centrali wirtualnej telefonicznej.
  • /v1/statistics/callback_widget/
    statystyki Widgetu CallBack.
  • JSON
  • XML
{
    "status":"success",
    "balance":10.34,
    "currency":"USD"
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <balance>10.34</balance>
    <currency>USD</currency>
</answer>

Parametry:

  • number – numer telefonu
  • caller_id (nieobowiązkowy) – CallerID, jaki będzie wyświetlony przy wykonaniu połączenia.
  • JSON
  • XML
{
    "status":"success",
    "info":{
        "prefix":"4420",
        "description":"United Kingdom, London",
        "price":"0.009",
        "currency":"USD",
    }
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <info>
        <prefix>4420</prefix>
        <description>United Kingdom, London</description>
        <price>0.009</price>
        <currency>USD</currency>
    </info>
</answer>

  • JSON
  • XML
{
    "status":"success",
    "unixtime":1483228800,
    "datetime":"2017-01-01 00:00:00",
    "timezone":"UTC+0"
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <unixtime>1483228800</unixtime>
    <datetime>2017-01-01 00:00:00</datetime>
    <timezone>UTC+0</timezone>
</answer>

  • JSON
  • XML
{
    "status":"success",
    "info": {
        "tariff_id":5,
        "tariff_name":"Standart, special",
        "is_active":false,
        "cost":0,
        "currency":USD,
        "used_seconds":1643,
        "used_seconds_mobile":34,
        "used_seconds_fix":726,
        "tariff_id_for_next_period":5,
        "tariff_for_next_period":Standart, special
    }
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <info>
        <tariff_id>5</tariff_id>
        <tariff_name>Standart, special</tariff_name>
        <is_active>false</is_active>
        <cost>0</cost>
        <currency>USD</currency>
        <used_seconds>1643</used_seconds>
        <used_seconds_mobile>726</used_seconds_mobile>
        <used_seconds_fix>726</used_seconds_fix>
        <tariff_id_for_next_period>5</tariff_id_for_next_period>
        <tariff_for_next_period>Standart, special</tariff_for_next_period>
    </info>
</answer>

gdzie

  • tariff_id– ID obecnej taryfy użytkownika;
  • tariff_name – nazwa obecnej taryfy użytkownika;
  • is_active – czy jest aktywna obecna taryfa lub nie;
  • cost – cena taryfy;
  • currency – waluta taryfy;
  • used_seconds – ilość wykorzystanych sekund taryfy;
  • used_seconds_mobile – ilość wykorzystanych sekund taryfy na komórkowe;
  • used_seconds_fix – ilość wykorzystanych sekund taryfy na stacjonarne;
  • tariff_id_for_next_period – ID taryfy użytkownika na następny okres;
  • tariff_for_next_period – nazwa taryfy użytkownika na następny okres.

Parametry:

  • from – Twój numer telefonu lub SIP, lun numer wewnętrzny centrali, lub numer scenariuszu, na jaki jest kierowany callback;
  • to – numer telefonu lub SIP, na jaki dzwonisz;
  • sip (nieobowiązkowy) – numer SIP użytkownika numer wewnętrzny centrali (np. 100), przez który będzie kierowane połączenie. Będzie wykorzystany CallerID tego numeru, w statystkach będzie wyświetlony dany numer SIP/centrali, jeśli dla danego numeru jest włączone nagrywanie rozmów lub prefiksy na połączenia wychodzące - będzie to użyte
  • predicted (nieobowiązkowy) – jeśli podany ten parametr, żądani jest predykatywne (system wykonuje połączenia na numer "to" i tylko w przypadku odpowiedzi, następnie dzwoni na numer abonenta).
  • JSON
  • XML
{
    "status":"success",
    "from": 442037691880,
    "to": 442037691881,
    "time": 1435573082
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <from>442037691880</from>
    <to>442037691881</to>
    <time>1435573082</time>
</answer>

  • JSON
  • XML
{
    "status":"success",
    "sips":[
        {
            "id":"00001",
            "display_name":"SIP 1",
            "lines":3
        },
        {
            "id":"00002",
            "display_name":"SIP 2",
            "lines":3
        }
    ],
    "left":3
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <sips>
        <value>
            <id>00001</id>
            <display_name>SIP 1</display_name>
            <lines>3</lines>
        </value>
        <value>
            <id>00002</id>
            <display_name>SIP 2</display_name>
            <lines>3</lines>
        </value>
    </sips>
    <left>1</left>
</answer>

gdzie

  • id– SIP-id;
  • display_name – wyświetlone imię;
  • lines – ilość linii;
  • left – ilość pozostałych SIP, jaki można utworzyć (zależy od salda na koncie i ilości już utworzonych SIP).
  • JSON
  • XML
{
    "status":"success",
    "sip":"00001",
    "is_online":"false"
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <sip>00001</sip>
    <is_online>false</is_online>
</answer>

Parametry:

  • id – SIP id, jakiemu zmieniasz CallerID;
  • number – numer, na jaki zmieniasz w formacie międzynarodowym (z listy numerów potwierdzonych lub wykupionych).
  • JSON
  • XML
{
    "status":"success",
    "sip":"00001",
    "new_caller_id":"442037691880"
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <sip>00001</sip>
    <new_caller_id>442037691880</new_caller_id>
</answer>

Parametry:

  • id – (nieobowiązkowy) wybór konkretnego SIP id.
  • JSON
  • XML
{
    "status":"success",
    "info": [
        {
        "sip_id":"00001",
        "status":"on",
        "condition":"always",
        "destination":"phone",
        "destination_value":"442037691880",
        },
    ...
    ]
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <info>
        <value>
            <sip_id>00001</sip_id>
            <status>on</status>
            <condition>always</condition>
            <destination>phone</destination>
            <destination_value>442037691880</destination_value>
        </value>
    ...
    </info>
</answer>

gdzie

  • sip_id– SIP id użytkownika;
  • status – obecny status: on lub off;
  • condition – warunek przekierowania: always –zawsze (domyślnie), unavailable – w przypadku nie odpowiedzi lub nie dostępności;
  • destination – na jaki numer przekierowanie: phone – na numer telefonu, pbx – numer wewnętrzny centrali;
  • destination_value – na jaki numer przekierowanie: phone – na numer telefonu lub ID centrali.
  • JSON
  • XML
{
    "status":"success",
    "info": [
        {
            "number":"442037691880",
            "status":"on",
            "country":"Great Britain",
            "description":"London",
            "number_name":null,
            "sip":00001,
            "sip_name":null,
            "start_date":"2015-01-01 18:14:44",
            "stop_date":"2016-02-11 18:14:40",
            "monthly_fee":2,
            "currency":USD,
            "channels":2,
            "autorenew":"true",
            "is_on_test":"false",
            "type":"common"
        },
    ...
    ]
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <info>
        <value>
            <number>442037691880</number>
            <status>on</status>
            <country>Великобритания</country>
            <description>Лондон</description>
            <number_name>null</number_name>
            <sip>00001</sip>
            <sip_name>Example</sip_name>
            <start_date>2015-01-01 18:14:44</start_date>
            <stop_date>2016-02-11 18:14:40</stop_date>
            <monthly_fee>2</monthly_fee>
            <currency>USD</currency>
            <channels>2</channels>
            <autorenew>true</autorenew>
            <is_on_test>false</is_on_test>
            <type>common</type>
        </value>
    ...
    </info>
</answer>

W zależności od typu numeru parametry mogą się różnić! Opis parametrów:

  • number – podłączony numer wirtualny użytkownika;
  • status – status numeru;
  • country – kraj (dla common i revenue);
  • description – opis: miasto lub typ (dla common i revenue);
  • number_name – "imię" numeru wirtualnego (ustawione użytkownikiem);
  • sip – SIP, podpięty do numeru;
  • sip_name – "imię" SIP, podpięte do numeru;
  • start_date – data aktywacji numeru użytkownikiem;
  • stop_date – data końca ważności numeru użytkownika;
  • monthly_fee – cena za numer (dla common);
  • currency – waluta podanej ceny (dla common);
  • channels – ilość linii na numerze (dla common);
  • minutes – całkowity czas rozmów przychodzących za obecny miesiąc (dla revenue);
  • autorenew – czy jest włączone automatyczne przedłużanie numeru (dla common, revenue, rufree);
  • is_on_test – czy jest włączony "test" dla numeru;
  • type – typ numeru: common (numer wirtualny), inum (darmowy numer międzynarodowy), rufree (darmowy numer moskiewski), revenue (darmowy numer moskiewski 495)
  • JSON
  • XML
{
    "status":"success",
    "sims": [
        {
            "iccid":"8923416550000723980",
            "name":"My Sim",
            "sip":"00001",
            "phone_number":" 447978027321",
            "redirect_to":"simcard",
            "status":"enabled",
            "internet":"on"
        },
    ...
    ]
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <sims>
        <value>
            <iccid>8923416550000723980</iccid>
            <name>My Sim</name>
            <sip>00001</sip>
            <phone_number> 447978027321</phone_number>
            <redirect_to>simcard</redirect_to>
            <status>enabled</status>
            <internet>on</internet>
        </value>
    ...
    </sims>
</answer>

gdzie

  • iccid – ID karty SIM;
  • name – "Imię" karty SIM;
  • sip – do jakiego SIP podpięta karta;
  • phone_number – numer telefonu karty;
  • redirect_to – gdzie kierowane połączenia przychodzące z karty (przykład: simcard, );
  • status – obecny status karty SIM;
  • internet – włączony lub wyłączony Internet.

Parametry:

  • id – SIP id;
  • status – status przekierowania na wybrany numer SIP.
  • JSON
  • XML
{
    "status":"success",
    "sip":"00001",
    "current_status":"on"
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <sip>00001</sip>
    <current_status>on</current_status>
</answer>

Parametry:

  • id – SIP id;
  • type – typ przekierowania – na telefon;
  • number – numer telefonu.
  • JSON
  • XML
{
    "status":"success",
    "sip":"00001",
    "destination":"442037691880"
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <sip>00001</sip>
    <destination>442037691880</destination>
</answer>

  • JSON
  • XML
{
    "status":"success",
    "pbx_id":1234,
    "numbers": [
        100,
        101,
        ...
    ]
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <pbx_id>1234</pbx_id>
    <numbers>
        <value>100</value>
        <value>101</value>
        ...
    </numbers>
</answer>

gdzie

  • pbx_id – id użytkownika centrali;
  • numbers – lista numerów wewnętrznych.
  • JSON
  • XML
{
    "status":"success",
    "pbx_id":1234,
    "number":100,
    "is_online":"false"
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <pbx_id>1234</pbx_id>
    <number>100</number>
    <is_online>false</is_online>
</answer>

gdzie

  • pbx_id – id centrali telefonicznej;
  • number – numer wewnętrzny centrali;
  • is_online – online status (true|false).

Parametry:

  • id – numer wewnętrzny centrali;
  • status – status: "on" - włączony, "off" - wyłączony, "on_email" - włącz nagranie tylko na email, "off_email" - wyłącz nagranie tylko na email, "on_store" - włącz nagranie do chmury, "off_store" - wyłącz nagranie do chmury;
  • email – (nieobowiązkowy) zmiana email, na jaki będą kierowane nagrania rozmów. Możesz podać do 3-trzech adresów email, rozdzielając przecinkiem.
  • JSON
  • XML
{
    "status":"success",
    "internal_number":100,
    "recording":"on",
    "email":"test@test.com"
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <internal_number>100</internal_number>
    <recording>on</recording>
    <email>on</email>
</answer>

Parametry:

  • call_id – indywidualny id połączenia, ten id jest podany w nazwie pliku z nagraniem (indywidualny dla każdego nagrania w statystykach);
  • pbx_call_id – stały ID zewnętrznego połączenia w ramach Centrali (nie zmienia się według scenariuszu, menu głosowego, transferu itd.,wyświetlany jest w statystykach i powiadomieniach).;
  • lifetime – (nieobowiązkowy) czas ważności linku w sekundach ( min. - 180, maks. - 5184000, domyślnie - 1800).

Uwaga: wystarczy podać jeden z dwóch paramentów (pbx_call_id или call_id), przy podaniu pbx_call_id linków w odpowiedzi na żądanie może być kilka.

  • JSON
  • XML

Przykład odpowiedzi kiedy ustawiony tylko call_id, tylko jeden link:

{
    "status":"success",
    "link": "https://api.zadarma.com/v1/pbx/record/download/NjM3M..NzM2Mg/1-1458313316.343456-100-2016-01-11-100155.mp3",
    "lifetime_till": "2016-01-01 23:56:22"
}

Przykład odpowiedzi kiedy ustawiony tylko pbx_call_id, сlinków może być kilka:

{
    "status":"success",
    "links":[
        "https://api.zadarma.com/v1/pbx/record/download/NjM3M..NzM2Mg/1-1458313316.343456-100-2016-01-11-100155.mp3",
        "https://api.zadarma.com/v1/pbx/record/download/pw7Cj..iOzn99/1-1458313475.213487-101-2016-01-11-100211.mp3"
    ],
    "lifetime_till": "2016-01-01 23:56:22"
}

Przykład odpowiedzi kiedy ustawiony tylko call_id, tylko jeden link:

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <link>https://api.zadarma.com/v1/pbx/record/download/NjM3M..NzM2Mg/1-1458313316.343456-100-2016-01-11-100155.mp3</link>
    <lifetime_till>2016-01-01 23:56:22</lifetime_till>
</answer>

Przykład odpowiedzi kiedy ustawiony tylko pbx_call_id, сlinków może być kilka:

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <links>
        <value>https://api.zadarma.com/v1/pbx/record/download/NjM3M..NzM2Mg/1-1458313316.343456-100-2016-01-11-100155.mp3</value>
        <value>https://api.zadarma.com/v1/pbx/record/download/pw7Cj..iOzn99/1-1458313475.213487-101-2016-01-11-100211.mp3</value>
    </links>
    <lifetime_till>2016-01-01 23:56:22</lifetime_till>
</answer>

Parametry:

  • link – link do pobrania nagrania;
  • lifetime_till – czas ważności linku.

Parametry:

  • number – numer telefonu, do jakiego będzie wysłane SMS (można podać kilka numerów, rozdzielając przecinkiem);
  • message – wiadomość (standardowe ograniczenia na ilość znaków SMS, w przypadku przekroczenia limitu – dzieli się na kilka woadmości SMS);
  • caller_id – (nieobowiązkowy) numer telefonu, od którego zostanie wysłana wiadomość SMS (można podać tylko z listy potwierdzonych numerów).
Uwaga: wysyłka SMS dostępna tylko za granicę Rosyjskiej Federacji.
  • JSON
  • XML
{
    "status":"success",
    "messages":1,
    "cost":0.24,
    "currency":"USD"
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <value>
        <messages>1</messages>
        <cost>0.24</cost>
        <currency>1</currency>
    </value>
</answer>

Parametry:

  • start - data początku wyświetlenia statystyk (format - Y-m-d H:i:s);
  • end - data końcowa wyświetlenia statystyk (format - Y-m-d H:i:s);
  • sip (nieobowiązkowy) - filtr dla konkretnego loginu SIP;
  • cost_only (nieobowiązkowy) - podgląd tylko kosztów na rozmowy za wybrany okres;
  • type (nieobowiązkowy - tylko dla wspólnych statystyk) - typ żądania: wspólny (nie zaznaczony), toll oraz ru495. (dla statystyk numerów toll free 800 oraz numeru moskiewskiego 495).

Maksymalny okres otrzymania statystyk - miesiąc. W przypadku przekroczenia limitu w żądaniu - okres automatycznie jest zmieniony na na miesiąc (do 30 dni). Jeśli nie jest podana data początku statystyk - zostanie wybrana pierwsza data obecnego miesiąca. Jeśli nie jest podana data końca - zostanie wybrana dzisiejsza data i czas.

  • JSON
  • XML
{
    "status":"success",
    "start":"2015-06-01 00:00:00",
    "end":"2015-06-29 13:45:23",
    "stats":[
        {
            "id":"155112249",
            "sip":"00001",
            "callstart":"2015-06-02 12:20:25",
            "from":442037691880,
            "to":442037691881,
            "description":"United Kingdom, London",
            "disposition":"busy",
            "billseconds":0,
            "cost":0.1950,
            "billcost":0.0000,
            "currency":"USD"
        },
        …
    ]
}

?type=cost_only:
{
    "status":"success",
    "start":"2015-06-01 00:00:00",
    "end":"2015-06-29 14:03:57",
    "stats":[
        {
            "cost":38.094,
            "currency":"USD",
            "seconds":9785
        }
    ]
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <start>2015-06-01 00:00:00</start>
    <end>2015-06-29 13:58:22</end>
    <stats>
        <value>
            <id>155112249</id>
            <sip>00001</sip>
            <callstart>2015-06-02 12:20:25</callstart>
            <description>United Kingdom, London</description>
            <disposition>busy</disposition>
            <billseconds>0</billseconds>
            <cost>0.195</cost>
            <billcost>0</billcost>
            <currency>USD</currency>
            <from>442037691880</from>
            <to>442037691881</to>
        </value>
        …
    </stats>
</answer>

?type=cost_only:
<?xml version="1.0"?>
<answer>
    <status>success</status>
    <start>2015-06-01 00:00:00</start>
    <end>2015-06-29 14:03:30</end>
    <stats>
    <value>
        <cost>38.094</cost>
        <currency>USD</currency>
        <seconds>9785</seconds>
    </value>
    </stats>
</answer>

gdzie

  • start – data początku wyświetlenia statystyk;
  • end – data końcowa wyświetlenia statystyk;
  • id – id połączenia;
  • sip – SIP login;
  • callstart – czas rozpoczęcia połączenia;
  • description – opis kierunki połaczenia;
  • disposition – stan połączenia:
    • 'answered' – rozmowa,
    • 'busy' – zajęte,
    • 'cancel' - odrzucone,
    • 'no answer' - brak odpowiedzi,
    • 'failed' - nieudane,
    • 'no money' - brak środków, przekroczony limit,
    • 'unallocated number' - numer nie istnieje,
    • 'no limit' - przekroczony limit,
    • 'no day limit' - przekroczony dzienny limit,
    • 'line limit' - przekroczony limit linii,
    • 'no money, no limit' - przekroczony limit;
  • billseconds – czas trwania w sekundach;
  • cost – cena za minutę na sany kierunek;
  • billcost – cena opłaconych minut;
  • currency – waluta;
  • from – numer osoby dzwoniącej;
  • to – numer na który było wykonane połączenia.

Parametry:

  • start - data początku wyświetlenia statystyk (format - Y-m-d H:i:s);
  • end - data końcowa wyświetlenia statystyk (format - Y-m-d H:i:s);
  • version - format wyświetlenia (2 - nowy, 1 - stary);
  • JSON
  • XML
{
    "status":"success",
    "start":"2015-06-01 00:00:00",
    "end":"2015-06-30 23:59:59",
    "version":2,
    "stats":[
        {
            "call_id":1439981389.2702773,
            "sip":200,
            "callstart":"2015-06-01 15:04:00",
            "clid":200,
            "destination":5,
            "disposition":"answered",
            "seconds":5,
            "is_recorded":true,
            "pbx_call_id":"in_ae6b03b3b0765d127ec0b739209346bbc4f0d52d"
        },
        …
    ]
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
        <start>2015-06-01 00:00:00</start>
        <end>2015-06-30 23:59:59</end>
        <version>2</version>
        <stats>
        <value>
            <call_id>1439981389.2702773</call_id>
            <sip>200</sip>
            <callstart>2015-06-01 15:04:00</date>
            <clid>200</clid>
            <destination>5</destination>
            <disposition>answered</disposition>
            <seconds>5</seconds>
            <is_recorded>true</is_recorded>
            <pbx_call_id>in_ae6b03b3b0765d127ec0b739209346bbc4f0d52d</pbx_call_id>
        </value>
        …
    </stats>
</answer>

gdzie

  • start – data początku wyświetlenia statystyk;
  • end – data początku wyświetlenia statystyk;
  • version - format wyświetlenia (2 - nowy, 1 - stary);
  • call_id – indywidualny id połączenia, ten id jest podany w nazwie pliku z nagraniem (indywidualny dla każdego nagrania w statystykach);
  • sip – SIP login;
  • callstart – czas rozpoczęcia połączenia;
  • clid – CallerID;
  • destination – numer na który było wykonane połączenia;
  • disposition – stan połączenia:
    • 'answered' – rozmowa,
    • 'busy' – zajęte,
    • 'cancel' - odrzucone,
    • 'no answer' - brak odpowiedzi,
    • 'failed' - nieudane,
    • 'no money' - brak środków, przekroczony limit,
    • 'unallocated number' - numer nie istnieje,
    • 'no limit' - przekroczony limit,
    • 'no day limit' - przekroczony dzienny limit,
    • 'line limit' - przekroczony limit linii,
    • 'no money, no limit' - przekroczony limit;
  • seconds – czas trwania w sekundach;
  • is_recorded – (true, false) czy jest nagranie rozmowy lub nie;
  • pbx_call_id – stały ID zewnętrznego połączenia w ramach Centrali (nie zmienia się według scenariuszu, menu głosowego, transferu itd.,wyświetlany jest w statystykach i powiadomieniach);

Parametry:

  • start - data początku wyświetlenia statystyk (format - Y-m-d H:i:s);
  • end - data końcowa wyświetlenia statystyk (format - Y-m-d H:i:s);
  • widget_id - (nieobowiązkowy) - identyfikator widgetu, w przypadku braku tego parametru - statystyki dla wszystkich widgetów;
Maksymalny okres otrzymania statystyk - miesiąc. W przypadku przekroczenia limitu w żądaniu - okres automatycznie jest zmieniony na na miesiąc (do 30 dni). Jeśli nie jest podana data początku statystyk - zostanie wybrana pierwsza data obecnego miesiąca. Jeśli nie jest podana data końca - zostanie wybrana dzisiejsza data i czas.
  • JSON
  • XML
{
    "status":"success",
    "start":"2016-09-01 00:00:00",
    "end":"2016-09-30 23:59:59",
    "stats":[
        {
            "id":"57d16d6a1e46c53d1f8ce323",
            "widget_id":"1",
            "sip":"00001",
            "ip":"127.0.0.1",
            "actions":[
                {
                    "kind":"come",
                    "date":"2016-09-08 16:53:45",
                    "referrer_url":"http://test.domain.com/page1/",
                    "url":"http://home.domain.com/page2/"
                },
                {
                    "kind":"show",
                    "date":"2016-09-08 16:53:46",
                    "rate":15
                },
                {
                    "kind":"call_request",
                    "date":"2016-09-08 16:54:07",
                    "number":"442037691880",
                    "request_call_date":"2016-09-09 10:00:00",
                    "redial":"n"
                },
                {
                    "kind":"close",
                    "date":"2016-09-08 16:54:35"
                }
            ]
        },
        ...
    ]
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <start>2016-09-01 00:00:00</start>
    <end>2016-09-30 23:59:59</end>
    <stats>
        <value>
            <id>57d16d6a1e46c53d1f8ce323</id>
            <widget_id>1</widget_id>
            <sip>00001</sip>
            <ip>127.0.0.1</ip>
            <actions>
                <value>
                    <kind>come</kind>
                    <date>2016-09-08 16:53:45</date>
                    <referrer_url>http://test.domain.com/page1/</referrer_url>
                    <url>http://home.domain.com/page2/</url>
                </value>
                <value>
                    <kind>show</kind>
                    <date>2016-09-08 16:53:46</date>
                    <rate>15</rate>
                </value>
                <value>
                    <kind>call_request</kind>
                    <date>2016-09-08 16:54:07</date>
                    <number>442037691880</number>
                    <request_call_date>2016-09-09 10:00:00</request_call_date>
                    <redial>n</redial>
                </value>
                <value>
                    <kind>close</kind>
                    <date>2016-09-08 16:54:35</date>
                </value>
            </actions>
        </value>
            ...
    </stats>
</answer>

gdzie

  • start – data początku wyświetlenia statystyk;
  • end – data końcowa wyświetlenia statystyk;
  • id – id secji;
  • widget_id – id widgetu;
  • sip – SIP login;
  • ip – IP adres użytkownika;
  • kind – typ wydarzenia:
    • 'come' – użytkownik odwiedził stronę z widgetem,
    • 'show' – otwarty formularz widgetu,
    • 'call' – zamówienie połączenia,
    • 'call_request' – zamówienie zaplanowanego połączenia,
    • 'rate' – użytkownik ocenił rozmowę,
    • 'fail' – użytkownik zaznaczył opcję, że rozmowa się nie odbyła,
    • 'close' – użytkownik zamknął formularz widgetu;
  • date – data i czas wydarzenia;
  • referrer_url – adres strony, z jakiej użytkownik odwiedził stronę z widgetem (tylko dla wydarzenia 'come');
  • url – adres strony widgeu (tylko dla wydarzenia 'come');
  • rate – dla wydarzenia 'show' - ilość uzyskanych punktów, dla wydarzenia 'rate' - ocena rozmowy;
  • request_call_date – data i czas zaznaczony użytkownikiem, jako wygodny termin odebrania połaczenia (tylko dla wydarzenia 'call_request');
  • redial – (true, false) czy zostało zrealizowane połączenie zwrotne lub nie (tylko dla wydarzenia 'call_request');
  • number – numer podany użytkownikiem (dla wydarzeń 'call', 'call_request', 'rate', 'fail').

Parametry:

  • numbers – lista numerów w formacie międzynarodowym.

Jeśli numbers zawiera 1 numer, wynik będzie wysłany od razu, jeśli podana jest lista numerów, wynik zostanie wysłany mailowo, lub na podany adres url

Zwróć uwagę: ustawienia danej metody można zmieniać tylko w Panelu klienta na stronie aktualizacji.

Przykład odpowiedzi dla 1 numeru:


{
    "status":"success",
    "info":{
        'mcc' : '250',
        'mnc': '01',
        'mccName': 'Russia',
        'mncName': 'Mobile TeleSystems',
        'ported': false,
        'roaming': false,
        'errorDescription': 'No Error'
    }
}

Przykład odpowiedzi dla kliku numerów:


{
    "status":"success"
}

Przykład wyniku, wysłanego na adres, podany na stronie aktualizacji:


{
    'success': true,
    'description': 'Проверено успешно',
    'result': [
        {
            'mcc': '250',
            'mnc': '01',
            'ported': false,
            'roaming': false,
            'errorDescription': 'No Error',
            'mccName': 'Russia',
            'mncName': 'Mobile TeleSystems',
            'number': '791234567890',
        }, ...
    ]
}

Informacja o połączeniach przychodzących

System Zadarma może wysyłać informację o każdym połączeniu przychodzącym na centralę telefoniczną i kierować połączenia na odpowiedni numer wewnętrzny w zależności od odpowiedzi. Aby to zrobić, należy utworzyć otwarty publicznie dostępny link, jaki będzie otrzymywał POST-żądania z informacjami od systemu Zadarma.

Typy powiadomień:

Dostępne metody:

  • NOTIFY_START
    czas rozpoczęcia połączenia przychodzącego na centralę.
  • NOTIFY_INTERNAL
    czas rozpoczęcia połączenia na wewnętrzny numer centrali.
  • NOTIFY_ANSWER
    odpowiedź przy połączeniu na numer wewnętrzny lub numer zewnętrzny.
  • NOTIFY_END
    czas zakończenia połączenia przychodzącego na wewnętrzny numer centrali.
  • NOTIFY_OUT_START
    czas rozpoczęcia połączenia wychodzącego z centrali.
  • NOTIFY_OUT_END
    czas zakończenia połączenia wychodzącego z centrali.
  • NOTIFY_RECORD
    nagranie rozmowy jest gotowe do pobrania.

Parametry, jakie są wysyłane do linku dla powiadomień:

  • event – wydarzenie (NOTIFY_START)
  • call_start – czas rozpoczęcia rozmowy;
  • pbx_call_id – id połączenia;
  • caller_id – numer osoby dzwoniącej;
  • called_did – numer, na który było wykonane połączenie.

Parametry, jakie są wysyłane do linku dla powiadomień:

  • event – wydarzenie (NOTIFY_INTERNAL)
  • call_start – czas rozpoczęcia rozmowy;
  • pbx_call_id – id połączenia;
  • caller_id – numer osoby dzwoniącej;
  • called_did – numer, na który było wykonane połączenie.
  • internal – (nieobowiązkowy) wewnętrzny numer.

Parametry, jakie są wysyłane do linku dla powiadomień:

  • event – wydarzenie (NOTIFY_ANSWER)
  • caller_id – numer osoby dzwoniącej;
  • destination – numer, na który było wykonane połączenie;
  • call_start – czas rozpoczęcia rozmowy;
  • pbx_call_id – id połączenia;
  • internal – (nieobowiązkowy) wewnętrzny numer.

Parametry, jakie są wysyłane do linku dla powiadomień:

  • event – wydarzenie (NOTIFY_END)
  • call_start – czas rozpoczęcia rozmowy;
  • pbx_call_id – id połączenia;
  • caller_id – numer osoby dzwoniącej;
  • called_did – numer, na który było wykonane połączenie;
  • internal – (nieobowiązkowy) wewnętrzny numer;
  • duration – czas trwania w sekundach;
  • disposition – stan połączenia:
    • 'answered' – rozmowa,
    • 'busy' – zajęte,
    • 'cancel' - odrzucone,
    • 'no answer' - brak odpowiedzi,
    • 'failed' - nieudane,
    • 'no money' - brak środków, przekroczony limit,
    • 'unallocated number' - numer nie istnieje,
    • 'no limit' - przekroczony limit,
    • 'no day limit' - przekroczony dzienny limit,
    • 'line limit' - przekroczony limit linii,
    • 'no money, no limit' - przekroczony limit;
  • status_code – kod statusu połączenia Q.931;
  • is_recorded – 1 - nagrywanie połączenia, 0 - bez nagrywania;
  • call_id_with_rec – id połączenia z funkcją nagrywania (polecamy ściągać pliki z nagraniami nie wcześniej jak 40 sekund po zawiadomieniu, bo dla prawidłowego zapisania nagrania potrzebny jest czas).

Parametry, jakie są wysyłane do linku dla powiadomień:

  • event – wydarzenie (NOTIFY_OUT_START)
  • call_start – czas rozpoczęcia połączenia;
  • pbx_call_id – id połączenia;
  • destination – numer na który było wykonane połączenie;
  • internal – (nieobowiązkowy) wewnętrzny numer.

Parametry, jakie są wysyłane do linku dla powiadomień:

  • event – wydarzenie (NOTIFY_OUT_END)
  • call_start – czas rozpoczęcia połączenia;
  • pbx_call_id – id połączenia;
  • caller_id – numer osoby dzwoniącej;
  • destination – numer na który było wykonane połączenia;
  • internal – (nieobowiązkowy) wewnętrzny numer;
  • duration – czas trwania w sekundach;
  • disposition – stan połączenia:
    • 'answered' – rozmowa,
    • 'busy' – zajęte,
    • 'cancel' - odrzucone,
    • 'no answer' - brak odpowiedzi,
    • 'failed' - nieudane,
    • 'no money' - brak środków, przekroczony limit,
    • 'unallocated number' - numer nie istnieje,
    • 'no limit' - przekroczony limit,
    • 'no day limit' - przekroczony dzienny limit,
    • 'line limit' - przekroczony limit linii,
    • 'no money, no limit' - przekroczony limit;
  • status_code – kod statusu połączenia Q.931;
  • is_recorded – 1 - nagrywanie połączenia, 0 - bez nagrywania;
  • call_id_with_rec –id połączenia z funkcją nagrywania (polecamy ściągać pliki z nagraniami nie wcześniej jak 40 sekund po zawiadomieniu, bo dla prawidłowego zapisania nagrania potrzebny jest czas).

Parametry, jakie są wysyłane do linku dla powiadomień:

  • event – wydarzenie (NOTIFY_RECORD)
  • call_id_with_rec – indywidualny id z nagraniem rozmowy;
  • pbx_call_id – stały ID zewnętrznego połączenia w ramach Centrali (nie zmienia się według scenariuszu, menu głosowego, transferu itd.,wyświetlany jest w statystykach i powiadomieniach).

Ustawić link do powiadomień, a także włączyć/wyłączyć rodzaje powiadomień możesz w zakładce API panelu klienta.

Aby system zaakceptował link, należy na początku skryptu koniecznie dodać kod weryfikacyjny.

Przykład na PHP:

<?php if (isset($_GET['zd_echo'])) exit($_GET['zd_echo']); ?>

W celu zwiększenia bezpieczeństwa proponujemy zezwolić dostęp do Twojego linku tylko z IP 185.45.152.42.

Również, jeśli utworzyłeś klucze dostępu API, w każdym żądaniu na Twój link będzie wysłany dodatkowy nagłówek "Signature", po jakim możesz zweryfikować integralność i autentyczność danych.

Sporządzanie weryfikacyjnego podpisu dla powiadamienia o połączeniach przychodzących, przykład na PHP:

$signatureTest = base64_encode(hash_hmac('sha1', $_POST['caller_id'] . $_POST['called_did'] . $_POST['call_start'], API_SECRET));

Do NOTIFY_OUT_START и NOTIFY_OUT_END:

$signatureTest = base64_encode(hash_hmac('sha1', $_POST['internal'] . $_POST['destination'] . $_POST['call_start'], API_SECRET));

Do NOTIFY_RECORD:

$signatureTest = base64_encode(hash_hmac('sha1', $_POST['pbx_call_id'] . $_POST['call_id_with_rec'], API_SECRET));

Do NOTIFY_ANSWER:

$signatureTest = base64_encode(hash_hmac('sha1', $_POST['caller_id'] . $_POST['destination'] . $_POST['call_start'], API_SECRET));

Dla żądania NOTIFY_START można «w trakcie» zmieniać scenariusz dla obecnego połączenia, wysyłając w odpowiedzi informację:

{
    "redirect": ID,
    "caller_name": NAME
}

gdzie,

  • redirect – id scenariuszu przekierowania (w formacie 0-1 gdzie 0 numer menu głosowego, 1 numer scenariuszu) lub wewnętrzny numer centrali telefonicznej, "blacklist" - w tym przypadku połączenie zostanie odrzucone z sygnałem zajętości;
  • caller_name –można nadać nazwę numerowi połączenia przychodzącego.

Maksymalny czas odpowiedzi z informacją o redirect, a nazwa numeru - 2 sekundy.

Przykładowy skrypt możesz sprawdzić w naszym repozytorium na GitHub.