API

Інтерфейс API від Zadarma дозволяє використовувати сервіс для власних додатків, а також для стикування з будь-якими CRM-системами та програмами для коллцентра. Реалізація API відкрита, з нею впорається будь-який розробник через невисокий ступінь складності.

В API доступні всі основні функції:

  • відображення і зміна налаштувань SIP та АТС;
  • відображення статистики та балансу;
  • відправка дзвінків (CallBack на зовнішні і внутрішні номери) та SMS-повідомлень;
  • повідомлення зовнішнього серверу про кожний вхідний дзвінок в АТС, а також зовнішню маршрутизацію дзвінків.

Посилання на API https://api.zadarma.com

Версія API: v1

Фінальне посилання на метод: https://api.zadarma.com/v1/METHOD/

Скачайте готові класи PHP, Python для роботи з API на нашому GitHub.

Авторизація

Кожен запит, який потребує авторизації, супроводжується додатковим заголовком, види:
"Authorization: ключ_пользователя: підпис"

Ключі для авторизації необхідно отримати в особистому кабінеті.

Підпис складається за наступним алгоритмом:

  • масив з переданих параметрів (GET, POST, PUT, DELETE) сортується за назвою ключа за алфавітом;
  • з отриманого масиву формується рядок запиту (наприклад, функція http_build_query в PHP), приклад "from=DATEFROM&to=DATETO…";
  • і далі - з'єднується за формулою: рядок = імя_методу рядок_запиту md5 (рядок_запиту), де "імя_методу" - рядок запиту, починаючи від домену (із зазначенням версії АПИ), до початку перерахування параметрів, наприклад - /v1/sip/"
  • отриманий рядок кешируєтся за алгоритмом sha1 з таємним ключем користувача: хеш = hash( рядок, таємний_ключ )
  • і далі хеш кодується в base64 подпись = base64_encode( хеш )

Приклад на 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;

Готовий клас PHP для роботи з API, можете скачати на GitHub.

Формати відповіді: json (за замовчуванням) та xml.

Щоб отримати відповідь від АПИ в форматі xml, в рядок запиту додається параметр "format=xml".

Обмеження

У відповіді також міститься інформація про ліміти і поточний запит, наприклад:

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

где,

  • X-Zadarma-Method - поточний викликаємий метод;
  • X-RateLimit-Remaining - кількість залишившихся запитів, з урахуванням ліміту на метод і на користувача;
  • X-RateLimit-Limit - цифра загального ліміту звернень в хвилину;
  • X-RateLimit-Reset - час скидання ліміту.

Загальні обмеження - 100 запитів в хвилину, на методи статистики - 10 запитів в хвилину.

У разі блокування, метод віддає відповідь з429 заголовком "You exceeded the rate limit".

Відповідь складається з обов'язкового ключа"status" (success или error). Далі, в залежності від методу, віддаються свої ключі з інформацією, яка запитується.

У разі помилки, віддається додатковий ключ "message" з описом помилки.

Також, усі відповіді супроводжуються відповіднимиHTTP-заголовками.

Приклад відповіді помилки:

JSON:

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

XML:

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

Доступні методи:

  • /v1/info/balance/
    баланс користувача.
  • /v1/info/price/
    вартість дзвінка з урахуванням поточного тарифу користувача.
  • /v1/info/timezone/
    часовий пояс користувача.
  • /v1/tariff/
    інформація про поточний тариф користувача.
  • /v1/request/callback/
    callback.
  • /v1/sip/
    список SIP-номерів користувача.
  • /v1/sip/<SIP>/status/
    online-статус SIP-номерів користувача.
  • /v1/sip/callerid/
    зміна CallerID.
  • /v1/sip/redirection/
    відображення поточних переадресацій за SIP-номерами користувача.
  • /v1/direct_numbers/
    інформація про віртуальні номери користувача.
  • /v1/sim/
    інформація про SIM-карти користувача.
  • /v1/sip/redirection/
    включення / вимикання переадресації за номером SIP.
  • /v1/sip/redirection/
    зміна параметрів переадресації.
  • /v1/pbx/internal/
    відображення внутрішніх номерів АТС.
  • /v1/pbx/internal/<PBXSIP>/status/
    online-статус внутрішнього номеру АТС.
  • /v1/pbx/internal/recording/
    увімкнення запису розмов на внутрішньому номері АТС.
  • /v1/pbx/record/request/
    запит на файл запису розмови.
  • /v1/pbx/redirection/
    зміна параметрів переадресації на внутрішній номер АТС.
  • /v1/pbx/redirection/
    отримання параметрів переадресації на внутрішній номер АТС.
  • /v1/sms/send/
    відправка SMS.
  • /v1/statistics/
    отримання загальної статистики.
  • /v1/statistics/pbx/
    статистика за АТС.
  • /v1/statistics/callback_widget/
    статистика за віджетом зворотнього дзвінка.
  • 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>

Параметри:

  • number – номер телефону
  • caller_id (опционально) – CallerID, який буде використовуватися при здійсненні дзвінка.
  • 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>

де

  • tariff_id– ID поточного тарифу користувача;
  • tariff_name – найменування поточного тарифу користувача;
  • is_active – активний або неактивний поточний тариф;
  • cost – вартість тарифу;
  • currency – валюта тарифу;
  • used_seconds – кількість використаних секунд тарифу;
  • used_seconds_mobile – кількість використаних секунд тарифу на мобільні телефони;
  • used_seconds_fix – кількість використаних секунд тарифу на стаціонарні телефони;
  • tariff_id_for_next_period – ID тарифу користувача на наступний період;
  • tariff_for_next_period – найменування тарифу користувача на наступний період.

Параметри:

  • from – ваш номер телефону або SIP, або внутрішній номер АТС, або номер сценарію АТС, на який викликається callback;
  • to – номер телефону або SIP, якому телефонують;
  • sip (опціонально) - номер SIP-користувача або внутрішній номер АТС (наприклад 100), через який відбудеться дзвінок. Буде використано CallerID цього номеру, в статистиці буде відображатися даний номер SIP / АТС, якщо для зазначеного номеру увімкнено запис дзвінків або префікси набору, вони також будуть задіяні;
  • predicted (опционально) – якщо зазначений цей прапорець, то запит є предикативним (система спочатку дзвонить на номер "to" і тільки якщо йому додзвонюється, з'єднує з вашим SIP або телефонним номером);
  • 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>

де

  • id– SIP-id;
  • display_name – ім'я, яке відображається ;
  • lines – кількість ліній;
  • left – кількість залишившихся SIP, які можна створити (залежить від балансу користувача і загальної кількості вже створених 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>

Параметри:

  • id – SIP id, якому змінюють CallerID;
  • number – номер, на який змінюють у міжнародному форматі (зі списку підтверджених або придбаних номерів користувача).
  • 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>

Параметри:

  • id – (опціональний) вибір конкретного 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>

де

  • sip_id– SIP id користувача;
  • status – поточний статус: on або off;
  • condition – умови переадресації: always - завжди (за замовчуванням), unavailable - в разі не підняття трубки або відсутності SIP-з'єднання;
  • destination – куди переадресовується: phone - на номер телефону, pbx - на АТС;
  • destination_value – номер, куди переадресовувати: номер телефону або ID АТС.
  • 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>

Залежно від типу номеру набір полів може відрізнятися! Опис полів:

  • number – куплений віртуальний номер користувача;
  • status – статус номеру;
  • country – країна (для common і revenue);
  • description – опис: місто або тип (для common і revenue);
  • number_name – "ім'я" віртуального номеру (задається користувачем);
  • sip – SIP, прив'язаний до номера;
  • sip_name –"ім'я" SIP, прив'язаного до номеру;
  • start_date – дата придбання номера користувачем;
  • stop_date – дата закінчення терміну оплати номеру користувачем;
  • monthly_fee – вартість номеру (для common);
  • currency – валюта вартості номеру (для common);
  • channels – кількість ліній на номері (для common);
  • minutes – загальна тривалість вхідних дзвінків за поточний місяць (для revenue);
  • autorenew – чи увімкнення автоподовження номеру (для common, revenue, rufree);
  • is_on_test – чи знаходиться номер на тесті;
  • type – тип номеру: common (віртуальний номер), inum (безкоштовний міжнародний номер), rufree (безкоштовний московський номер), revenue (безкоштовний московський номер 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>

де

  • iccid – ID SIM-карти;
  • name – "ім'я" SIM-карти;
  • sip – до якого SIP прив'язана карта;
  • phone_number – номер телефону карти;
  • redirect_to – куди перенаправлені вхідні дзвінки на карту (варіант: simcard, <номер телефону>);
  • status – поточний статус SIM-карти;
  • internet – відключений або включений інтернет.

Параметри:

  • id – SIP id;
  • status – виставляється статус переадресації на обраний 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>

Параметри:

  • id – SIP id;
  • type – тип переадресації: phone – на телефон;
  • number – номер телефону.
  • 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>

де

  • pbx_id – id ATC користувача;
  • numbers – список внутрішніх номерів.
  • 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>

де

    li class="custom-list__item">pbx_id – АТС-id;
  • number – внутрішній номер АТС;
  • is_online – online-статус (true|false).

Параметри:

  • id – внутрішній номерАТС;
  • status – статус: "on" - увімкнути, "off" - вимкнути, "on_email" - увімкнути тільки запис на пошту, "off_email" - вимкнути тільки запис на пошту, "on_store" - увімкнути тільки запис в сховище, "off_store" - вимкнути тільки запис в сховище;
  • email – (опціональний) зміна електронної адреси, куди будуть відправлятися записи розмов. Ви можете вказати до 3х email адрес через кому.
  • 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>

Параметри:

  • call_id –унікальний id дзвінка, цей id вказано в назві файлу із записом розмови (унікальний для кожного запису в статистиці);
  • pbx_call_id – постійний ID зовнішнього дзвінка в АТС (не змінюється при проходженні сценаріїв, голосового меню, transfer і т.д., відображається в статистиці і повідомленнях);
  • lifetime – (опціональний) срок дії посилання в секундах (мінімум - 180, максимум - 5184000, за замовчуванням - 1800).

Примітка: достатньо вказати один з двох параметрів ідентифікації (pbx_call_id або call_id), при вказівці pbx_call_id посилань у відповіді на запит може бути кілька.

  • JSON
  • XML

Приклад відповіді коли зазначено тільки call_id, посилання тільки одне:

{
    "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"
}

Приклад відповіді коли зазначено тільки pbx_call_id, посилань може бути декілька:

{
    "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"
}

Приклад відповіді коли зазначено тільки call_id, посилання тільки одне:

<?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>

Приклад відповіді коли зазначено тільки pbx_call_id, посилань може бути декілька:

<?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>

Параметри:

  • link – посилання на файл розмови;
  • lifetime_till – до якого часу посилання буде працювати.

Параметри:

Для включення и налаштування переадресації:

  • pbx_number – внутрішній номер АТС повністю, наприклад 1234-100;
  • status – on;
  • type – тип переадресації voicemail або phone;
  • destination – телефон або електронна пошта, залежно від попереднього параметра;
  • condition – умови переадресації, можливі значення: always або noanswer;
  • set_caller_id – встановлення Вашого CallerID при переадресації, можливі значення: on, off. Указується тільки при type = phone;
  • voicemail_greeting – оповіщення про переадресації, можливі значення: no, standart, own. Указується тільки при type = voicemail;
  • greeting_file – файл з оповіщенням у форматі mp3 або wav до 5 MB. Указується тільки при type = voicemail та voicemail_greeting = own;

Для виключення переадресації:

  • pbx_number – внутрішній номер АТС повністю, наприклад1234-100;
  • status – off;
  • JSON
  • XML
{
    "status":"success",
    "current_status":"on",
    "pbx_id":"1234",
    "pbx_name":"100",
    "type":"phone",
    "destination":"79123456789",
    "condition":"noanswer",
    }

<?xml version="1.0"?>
    <answer>
    <status>success</status>
    <current_status>on</current_status>
    <pbx_id>1234</pbx_id>
    <pbx_name>100</pbx_name>
    <type>phone</type>
    <destination>79123456789</destination>
    <condition>noanswer</condition>
    </answer>

Параметри:

  • pbx_number – внутрішній номер АТС повністю, наприклад 1234-100;
  • JSON
{
    "status":"success",
    "current_status":"on",
    "pbx_id":"1234",
    "pbx_name":"100",
    "type":"phone",
    "destination":"79123456789",
    "condition":"noanswer",
    }

Параметри:

  • number – номер телефону, куди відправляти SMS (можна перерахувати кілька через кому);
  • message – повідомлення (стандартні обмеження за довжиною SMS, у разі перевищення ліміту - розбивається на кілька SMS);
  • caller_id – (опціональний) номер телефону, від кого буде відправлена SMS (можна відправляти тільки зі списку підтверджених номерів користувача).
Зверніть увагу:відправка SMS можлива тільки за межі РФ.
  • 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>

Параметри:

  • start - дата початку перегляду статистики(формат - Y-m-d H:i:s);
  • end - дата завершення перегляду статистики (формат - Y-m-d H:i:s);
  • sip (опціонально) - фільтр за певним SIP-номером;
  • cost_only (опціонально) - перегляд тільки витрачених коштів за період;
  • type (опціонально - тільки на загальній статистиці) - тип запиту: загальний (не вказується в запиті), toll і ru495. (Для статистики номерів 800 і безкоштовних номерів 495);
  • skip (опціонально - не враховується при заданому параметрі cost_only) - кількість рядків, які необхідно пропустити у вибірці перед початком запиту (використовується для пагінації спільно з параметром limit, за замовчуванням дорівнює 0);
  • type (опціонально - не враховується при заданому параметрі cost_only) - обмеження на кількість виведених рядків (використовується для пагінації спільно з параметром skip, максимальне значення 1000, за замовчуванням 1000).

Максимальный период отримання статистики - місяць . У разі перевищення ліміту в запиті - період автоматично скорочується до 30 днів. Якщо не вказано дату початку вибірки, вибирається початок поточного місяця. Якщо не вказано дату кінця вибірки - вибірка обмежується поточною датою і часом.
Максимальна кількість виведених рядків для одного запиту - 1000. Для пагінації використовуйте параметри skip і limit.

  • 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>

де

  • start – дата початку відображення статистики;
  • end – дата завершення відображення статистики;
  • id – id дзвінка;
  • sip – SIP-номер;
  • callstart – час початку дзвінка;
  • description – опис напрямку дзвінка;
  • disposition – стан дзвінка:
    • 'answered' – розмова,
    • 'busy' – зайнято,
    • 'cancel' - скасовано,
    • 'no answer' - без відповіді,
    • 'failed' - не вдався,
    • 'no money' - немає коштів, перевищено ліміт,
    • 'unallocated number' - номер не існує,
    • 'no limit' - перевищено ліміт,
    • 'no day limit' - перевищено денний ліміт,
    • 'line limit' - перевищено ліміт ліній,
    • 'no money, no limit' - перевищено ліміт;
  • billseconds – кількість секунд дзвінка;
  • cost – вартість хвилини дзвінка за цим напрямком;
  • billcost – вартість оплачених хвилин;
  • currency – валюта вартості;
  • from – з якого номера телефонували;
  • to – куди дзвонили.

Параметри:

  • start - дата початку перегляду статистики (формат - Y-m-d H:i:s);
  • end - дата завершення перегляду статистики (формат - Y-m-d H:i:s);
  • version - формат виведення статистики (2 - новий, 1 - старий);
  • skip (опціонально) - кількість рядків, які необхідно пропустити у вибірці, висновок почнеться з рядка skip + 1 (використовується для пагінації спільно з параметром limit, за замовчуванням дорівнює 0);
  • limit (опціонально) - обмеження на кількість виведених рядків (використовується для пагінації спільно з параметром skip, максимальне значення 1000, за замовчуванням 1000).
  • 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>

де

  • start – дата початку відображення статистики;
  • end – дата завершення відображення статистики;
  • version - формат виведення статистики (2 - новий, 1 - старий);
  • call_id – унікальний id дзвінка, цей id вказано в назві файлу із записом розмови (унікальний для кожного запису в статистиці);
  • sip – SIP-номер;
  • callstart – час початку дзвінка;
  • clid – CallerID;
  • destination – куди дзвонили;
  • disposition – стан дзвінка:
    • 'answered' – розмова,
    • 'busy' – зайнято,
    • 'cancel' - скасовано,
    • 'no answer' - без відповіді,
    • 'failed' - не вдався,
    • 'no money' - немає коштів, перевищено ліміт,
    • 'unallocated number' - номер не існує,
    • 'no limit' - перевищено ліміт,
    • 'no day limit' - перевищено денний ліміт,
    • 'line limit' - перевищено ліміт ліній,
    • 'no money, no limit' - перевищено ліміт;
  • seconds – кількість секунд дзвінка;
  • is_recorded – (true, false) була записана розмова чи ні;
  • pbx_call_id – постійний ID зовнішнього дзвінка в АТС (не змінюється при проходженні сценаріїв, голосового меню, transfer і т.д., відображається в статистиці і повідомленнях);

Параметри:

  • start - дата початку перегляду статистики (формат - Y-m-d H:i:s);
  • end - дата завершення перегляду статистики (формат - Y-m-d H:i:s);
  • widget_id - (опціонально) - ідентифікатор віджету, в разі відсутності параметра береться статистика за всіма віджетами;
Максимальний період отримання статистики - місяц. У разі перевищення ліміту в запиті - період автоматично скорочується до 30 днів. Якщо не вказано дату початку вибірки, обирається початок поточного місяця. Якщо не вказано дату кінця вибірки - вибірка обмежується поточною датою і часом.
Максимальна кількість виведених рядків для одного запиту - 1000. Для пагінації використовуйте параметри skip і limit.
  • 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>

де

  • start – дата початку відображення статистики;
  • end – дата завершення відображення статистики;
  • id – id сесії;
  • widget_id – id віджету;
  • sip – SIP-номер;
  • ip – IP-адреса відвідувача;
  • kind – тип події:
    • 'come' – відвідувач прийшов на сторінку з віджетом,
    • 'show' – показана форма віджету,
    • 'call' – замовлення зворотнього дзвінка,
    • 'call_request' – замовлення відкладеного зворотнього дзвінка,
    • 'rate' – відвідувач оцінив розмову,
    • 'fail' – відвідувач зазначив, що зворотнього дзвінка не було,
    • 'close' – відвідувач закрив форму віджета;
  • date – дата і час події;
  • referrer_url – адреса сторінки, з якої відвідувач перейшов на сторінку з віджетом (тільки для події 'come');
  • url – адреса сторінки віджета (тільки для події 'come');
  • rate – для події 'show' - кількість набраних балів, для події 'rate' - оцінка розмови;
  • request_call_date – дата і час вказане відвідувачем, як зручне для зворотнього дзвінка (тільки для події 'call_request');
  • redial – (true, false) передзвонили чи ні у відповідь на замовлення відкладеного зворотнього дзвінка (тільки для події 'call_request');
  • number – номер введений відвідувачем (для подій 'call', 'call_request', 'rate', 'fail').

Параметри:

    support_api_page_methods_21_params_text
support_api_page_methods_21_1_text

support_api_page_methods_21_1_title


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

support_api_page_methods_21_2_title


{
    "status":"success"
}

support_api_page_methods_21_3_title


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

Інформація про вхідні дзвінки

Система Zadarma може відправляти інформацію про кожний вхідний дзвінок у віртуальній АТС і направляти дзвінок на потрібний внутрішній номер в залежності від відповіді. Для цього необхідно створити відкрите для загального доступу посилання, яке буде приймати POST-запити з інформацією з системи Zadarma.

Існуючі типи повідомлень:

Доступні методи:

  • NOTIFY_START
    початок вхідного дзвінка в АТС.
  • NOTIFY_INTERNAL
    початок вхідного дзвінка на внутрішній номер АТС.
  • NOTIFY_ANSWER
    відповідь при дзвінку на внутрішній або зовнішній номер.
  • NOTIFY_END
    кінець вхідного дзвінка на внутрішній номер АТС.
  • NOTIFY_OUT_START
    початок вихідного дзвінка з АТС.
  • NOTIFY_OUT_END
    кінець вихідного дзвінка з АТС.
  • NOTIFY_RECORD
    запис дзвінка готова для скачування.

Параметри, які відправляються на посилання для повідомлень:

  • event – подія (NOTIFY_START)
  • call_start – час початку дзвінка;
  • pbx_call_id – id дзвінка;
  • caller_id – вхідний номер;
  • called_did – номер, на який подзвонили.

Параметри, які відправляються на посилання для повідомлень:

  • event – подія (NOTIFY_INTERNAL)
  • call_start – час початку дзвінка;
  • pbx_call_id – id дзвінка;
  • caller_id – вхідний номер;
  • called_did – номер, на який подзвонили;
  • internal – (опціональний) внутрішній номер.

Параметри, які відправляються на посилання для повідомлень:

  • event – подія (NOTIFY_ANSWER)
  • caller_id – вхідний номер;
  • destination – номер, на який подзвонили;
  • call_start – час початку дзвінка;
  • pbx_call_id – id дзвінка;
  • internal – (опціональний) внутрішній номер.

Параметри, які відправляються на посилання для повідомлень::

  • event – подія (NOTIFY_END)
  • call_start – час початку дзвінка;
  • pbx_call_id – id дзвінка;
  • caller_id – вхідний номер;
  • called_did – номер, на який подзвонили;
  • internal – (опціональний) внутрішній номер;
  • duration – тривалість у секундах;
  • disposition – стан дзвінка:
    • 'answered' – розмова,
    • 'busy' – зайнято,
    • 'cancel' - скасовано,
    • 'no answer' - без відповіді,
    • 'failed' - не вдався,
    • 'no money' - немає коштів, перевищено ліміт,
    • 'unallocated number' - номер не існує,
    • 'no limit' - перевищено ліміт,
    • 'no day limit' - перевищено денний ліміт,
    • 'line limit' - перевищено ліміт ліній,
    • 'no money, no limit' - перевищено ліміт;
  • status_code – код статусу дзвінка Q.931;
  • is_recorded – 1 - є запис дзвінка, 0 - немає запису дзвінка;
  • call_id_with_rec – id дзвінка із записом (рекомендуємо завантажувати файл запису не раніше ніж через 40 секунд після повідомлення, тому що для збереження файлу запису потрібен час).

Параметри, які відправляються на посилання для повідомлень:

  • event – подія (NOTIFY_OUT_START)
  • call_start – час початку дзвінка;
  • pbx_call_id – id дзвінка;
  • destination – вхідний номер;
  • internal – (опціональний) внутрішній номер.

Параметри, які відправляються на посилання для повідомлень:

  • event – подія (NOTIFY_OUT_END)
  • call_start – час початку дзвінка;
  • pbx_call_id – id дзвінка;
  • caller_id – вхідний номер;
  • destination – номер, на який подзвонили;
  • internal – (опціональний) внутрішній номер;
  • duration – тривалість у секундах;
  • disposition – стан дзвінка:
    • 'answered' – розмова,
    • 'busy' – зайнято,
    • 'cancel' - скасовано,
    • 'no answer' - без відповіді,
    • 'failed' - не вдався,
    • 'no money' - немає коштів, перевищено ліміт,
    • 'unallocated number' - номер не існує,
    • 'no limit' - перевищено ліміт,
    • 'no day limit' - перевищено денний ліміт
    • 'line limit' - перевищено ліміт ліній,
    • 'no money, no limit' - перевищено ліміт;
  • status_code – код статуса дзвінка Q.931;
  • is_recorded – 1 - є запис дзвінка, 0 - немає запису дзвінка;
  • call_id_with_rec – id дзвінка із записом (рекомендуємо завантажувати файл запису не раніше ніж через 40 секунд після повідомлення, тому що для збереження файлу запису потрібен час).

Параметри, які відправляються на посилання для повідомлень:

  • event – подія(NOTIFY_RECORD)
  • call_id_with_rec – унікальний id дзвінка із записом розмови;
  • pbx_call_id – постійний ID зовнішнього дзвінка в АТС (не змінюється при проходженні сценаріїв, голосового меню, transfer і т.і., відображається в статистиці і повідомленнях).

Задати посилання за яким можливо буде повідомляти, а також вмикати / вимикати кожен вид повідомлень, зробити це можливо в розділі API особистого кабінету.

Для того, щоб система прийняла посилання, необхідно додати код перевірки напочатку скрипта.

Приклад на PHP:

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

Для збільшення безпеки, рекомендуємо дозволити доступ до вашого посилання тільки з IP 185.45.152.42.

Також, якщо Ви випустили ключі для доступу до API, у кожному запиті на Ваше посилання буде приходити додатковий заголовок "Signature", за яким також зможете звіряти цілісність, а також справжність даних.

Складання перевірочного підписи для сповіщення про вхідні дзвінки, приклад на PHP:

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

Для NOTIFY_OUT_START и NOTIFY_OUT_END:

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

Для NOTIFY_RECORD:

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

Для NOTIFY_ANSWER:

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

Для запиту NOTIFY_START можна швидко змінювати сценарій роботи з поточного дзвінка, відправивши у відповідь на інформацію:

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

где,

  • redirect – id сценарію редиректу (у форматі 0-1 де 0 номер голосового меню 1 номер сценарію) або внутрішній номер АТС, "blacklist" - в цьому випадку дзвінок буде відхилено з сигналом зайнято;
  • caller_name – можна дати ім'я вхідному номеру.

Максимальний час відповіді з інформацією про редирект та ім'я номеру - до 2 секунд.

Приклад скрипта можливо подивитися нанашому репозиторії наGitHub.