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/
    статистика за віджетом зворотнього дзвінка.
  • /v1/info/number_lookup/
    актуалізація контактів.
  • 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 - дата початку перегляду статистики(формат - YYYY-MM-DD HH:MM:SS);
  • end - дата завершення перегляду статистики (формат - YYYY-MM-DD HH:MM:SS);
  • 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 - дата початку перегляду статистики (формат - YYYY-MM-DD HH:MM:SS);
  • end - дата завершення перегляду статистики (формат - YYYY-MM-DD HH:MM:SS);
  • 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 - дата початку перегляду статистики (формат - YYYY-MM-DD HH:MM:SS);
  • end - дата завершення перегляду статистики (формат - YYYY-MM-DD HH:MM:SS);
  • 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').

Параметри:

  • numbers – список номерів для актуалізації в міжнародному форматі.

Якщо numbers містить 1 номер, результат буде повернений одразу, якщо вказано список номерів, результат буде відправлений за адресою, вказаною на сторінці актуалізації контактів, або відправлений на email, якщо адреса не задана.

Зверніть увагу: налаштування даного методу здійснюються на сторінці актуалізації номерів в особистому кабінеті.

Приклад відповіді для 1 номеру:


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

Приклад відповіді для декількох номерів:


{
    "status":"success"
}

Приклад результату, відправленого за адресою, зазначеною на сторінці актуалізації:


{
    '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 – номер, на який подзвонили.

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

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

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

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

де,

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

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

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

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

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

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

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

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

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

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

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

  • 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 секунд після повідомлення, тому що для збереження файлу запису потрібен час).

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

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

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

  • event – подія (NOTIFY_OUT_START)
  • call_start – час початку дзвінка;
  • pbx_call_id – id дзвінка;
  • destination – вхідний номер;
  • caller_id – номер, налаштований на внутрішньому номері АТС або встановлений в правилах набору за напрямками. Якщо номер не встановлено, то передається 0;
  • internal – (опціональний) внутрішній номер.

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

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

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

  • event – подія (NOTIFY_OUT_END)
  • call_start – час початку дзвінка;
  • pbx_call_id – id дзвінка;
  • caller_id – номер, налаштований на внутрішньому номері АТС або встановлений в правилах набору за напрямками. Якщо номер не встановлено, то передається 0;
  • 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 секунд після повідомлення, тому що для збереження файлу запису потрібен час).

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

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

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

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

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

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

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

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

Приклад на PHP:

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

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

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

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

Інші повідомлення:

Параметр "result" в цих повідомленнях заданий в JSON форматі. Ви можете отримати його в XML форматі, вказавши параметр у посиланні format=xml.

  • NUMBER_LOOKUP
    звіт про перевірку номерів.
  • CALL_TRACKING
    інформацію про дзвінки на номери, які підключені до коллтрекінгу.

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

  • event – событие (NUMBER_LOOKUP)
  • success – прапорець успішності перевірки;
  • description – текстовий опис статусу завершення перевірки;
  • result – дані звіту;
    • number – номер, що перевіряється;
    • mcc – мобільний код країни;
    • mnc – код мобільної мережі;
    • ported – ознака перенесення до іншого оператора;
    • roaming – ознака знаходження у роумінгу;
    • error – статус помилки;
    • errorDescription – текстовий опис помилки;
    • mccName – назва країни;
    • mncName – назва оператора;

Складання перевірочного підпису:

$signatureTest = base64_encode(hash_hmac('sha1', $_POST['result'], API_SECRET));

Відправляється раз на 15 хвилин, при наявності нових дзвінків.

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

  • event – подія (CALL_TRACKING)
  • result - масив
    • tracker - ID трекеру (можна дізнатися на сторінці установки коду);
    • start - час початку дзвінка;
    • duration - тривалість дзвінка в секундах;
    • caller_id - номер телефонуючого;
    • caller_did - номер, на який подзвонили;
    • country - (опціонально) країна, з якої було здійснено дзвінок;
    • ga_id - (опціонально, якщо в налаштуваннях вказано Id Google Analytics) id відвідувача в Google Analytics;
    • metrika_id - (опціонально, якщо в налаштуваннях вказано Id Yandex.Metrika) id відвідувача в Yandex.Metrika;

Складання перевірочного підпису:

$signatureTest = base64_encode(hash_hmac('sha1', $_POST['result'], API_SECRET));