Інтерфейс API

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

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

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

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

Версія API: v1

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

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

Інструкція з інтеграції власної CRM і телефонії Zadarma

Авторизація

Кожен запит, який потребує авторизації, супроводжується додатковим заголовком, види:
"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/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)

Параметри:

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

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

  • pbx_number – внутрішній номер АТС, наприклад 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 – внутрішній номер АТС, наприклад 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).
  • call_type (опціонально) - напрям дзвінків ('in' для вхідних, 'out' для вихідних). Якщо не вказано, виводяться всі дзвінки.
  • 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',
        }, ...
    ]
}

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

 

  • Клієнти
  • customers
    Повертає список клієнтів.
  • customers/<c_id>
    Повертає клієнта за його ID.
  • customers
    Створює нового клієнта з зазначеними даними.
  • customers/<c_id>
    Оновлює існуючого клієнта з зазначеним ID.
  • customers/<c_id>
    Видаляє клієнта за його ID.
  • Теги
  • customers/labels
    Повертає список всіх тегів і статистику за ними.
  • customers/labels
    Створює новий тег.
  • customers/labels/<l_id>
    Видаляє тег з системи за його ID.
  • Додаткові властивості
  • customers/custom-properties
    Повертає всі додаткові властивості.
  • Стрічка клієнта
  • customers/<c_id>/feed
    Повертає записи в стрічці клієнта.
  • customers/<c_id>/feed
    Додає текстову замітку в стрічку клієнта з можливістю прикріплення файлів.
  • customers/<c_id>/feed/<i_id>
    Оновлює вміст існуючої текстової замітки за її ID.
  • customers/<c_id>/feed/<i_id>
    Видаляє замітку в стрічці клієнта за її ID.
  • Співробітники
  • customers/<c_id>/employees
    Повертає список співробітників клієнта за його ID.
  • customers/<c_id>/employees/<e_id>
    Повертає співробітника клієнта за його ID.
  • customers/<c_id>/employees
    Створює і зберігає нового співробітника для заданого клієнта.
  • customers/<c_id>/employees/<e_id>
    Оновлює існуючого співробітника із зазначеним ID.
  • customers/<c_id>/employees/<e_id>
    Видаляє співробітника за його ID.
  • Завдання
  • events
    Повертає список завдань.
  • events/<event_id>
    Повертає завдання за його ID.
  • events
    Створює нове завдання зі спеціальними даними.
  • events/<event_id>
    Оновлює існуюче завдання із зазначеним ID.
  • events/<event_id>/close
    Завершує (закриває) завдання.
  • events/<event_id>
    Видаляє завдання за його ID.
  • Ліди
  • leads
    Повертає список лідів.
  • leads/<lead_id>
    Повертає лід за його ID.
  • leads
    Створює новий лід із зазначеними даними.
  • leads/<lead_id>
    Оновлює існуючий лід із зазначеним ID.
  • leads/<lead_id>
    Видаляє лід за його ID.
  • Користувачі
  • users
    Повертає список користувачів.
  • users/<user_id>
    Повертає користувача за його ID.
  • users/<user_id>/working-hours
    Повертає робочі години користувача.
  • users/groups
    Повертає групи і права користувачів кожної з них.
  • Дзвінки
  • calls
    Повертає список дзвінків.
  • Узагальнені контакти
  • contacts
    Повертає список всіх контактів (клієнти, співробітники, ліди, користувачі) з номерами телефонів.
  • contacts/identify
    Ідентифікує контакт (клієнта, співробітника, ліда, користувача) за номером телефону.
  • Файли
  • files/<file_id>
    Віддає файл за його ID.

GET /v1/zcrm/customers

Повертає список клієнтів.

Параметри

  • search (необов'язково) - рядок пошуку. Пошук здійснюється комбіновано за:
    • ім'ям клієнта
    • номерами телефонів клієнта
    • описом клієнта
    • адресою і поштовому індексу
    • веб-сайтом
    • e-mail адресою
    • мессенджером
    • іменами співробітників
    • номерами телефонів співробітників
    • описом співробітників
    • e-mail адресами співробітників
    • мессенджерами співробітників
  • filter (необов'язково) - фільтр клієнтів. Структура фільтра:
    {
    "status": "company",
    "type": "client",
    "country": "GB",
    "city": "London",
    "label": 12,
    "employees_count": "50",
    "responsible": 20
    }
    
    де:
    • status — статус клієнта. Допустимі значення:
      • individual — фіз. особа
      • company — компанія
    • type — тип клієнта. Допустимі значення:
      • potential — потенційний клієнт
      • client — клієнт
      • reseller — реселлер
      • partner — партнер
    • country — країна клієнта. Код з двох літер (RU, US і т.і.)
    • city — місто клієнта (рядок)
    • label — тег (ідентифікатор)
    • employees_count — кількість співробітників. Допустимі значення:
      • 50 — менше 50
      • 50_250 — 50 – 250
      • 250_500 — 250 – 500
    • responsible — відповідальний (ідентифікатор користувача)
    Будь-який з параметрів фільтра може бути опущений, тобто не є обов'язковим.
  • sort (необов'язково) — сортування клієнтів. Структура параметра:
    {
      "attr": "name",
      "desc": 0
    }
    
    де:
    • attr — поле сортування. Допустимі значення:
      • name — ім'я клієнта
      • status — статус клієнта
      • type — тип клієнта
    • desc — напрямок сортування. Допустимі значення:
      • 0 — за зростанням
      • 1 — за зменшенням
  • take (для посторінкового виведення) - скільки дзвінків повернути (за замовчуванням 20)
  • skip (для посторінкового виведення) - скільки клієнтів пропустити (за замовчуванням 0)

Відповідь

{
  "totalCount": 82,
  "customers": [
    {
      "id": 65,
      "name": "Good company",
      "status": "company",
      "type": "client",
      "responsible_user_id": 20,
      "employees_count": "50",
      "comment": "",
      "country": "GB",
      "city": "London",
      "address": "",
      "zip": "",
      "website": "",
      "created_at": "2020-04-28 05:47:47",
      "created_by": 20,
      "lead_source": "manual",
      "lead_created_at": null,
      "lead_created_by": null,
      "phones": [
        {
          "type": "work",
          "phone": "+44123456789"
        }
      ],
      "contacts": [
        {
          "type": "email_work",
          "value": "good_company@example.com"
        }
      ],
      "labels": [
        {
          "id": 12,
          "label": "Best clients"
        }
      ]
    }
  ]
}

де:

  • totalCount — загальна кількість клієнтів (з урахуванням рядка пошуку і фільтра)
  • customers —масив клієнтів (з урахуванням посторінкового виведення). Кожен елемент масиву містить наступні параметри:
    • id — ідентифікатор клієнта
    • name — ім'я клієнта
    • status — статус клієнта. Можливі значення:
      • individual — фіз. особа
      • company — компанія
    • type — тип клієнта. Можливі значення:
      • potential — потенційний клієнт
      • client — клієнт
      • reseller — реселлер
      • partner — партнер
    • responsible_user_id — відповідальний (ідентифікатор користувача)
    • employees_count — кількість співробітників. Можливі значення:
      • 50 — менше 50
      • 50_250 — 50 – 250
      • 250_500 — 250 – 500
    • comment — опис клієнта
    • country — країна клієнта. Код з двох літер (RU, US і т.і.)
    • city — місто клієнта
    • address — адреса клієнта
    • zip — поштовий індекс
    • website — веб-сайт клієнта
    • created_at — дата і час створення клієнта (у форматі YYYY-MM-DD HH:mm:ss)
    • created_by — ким був створений (ідентифікатор користувача)
    • lead_source — джерело. Можливі значення:
      • manual — вручну
      • call_incoming — вхідний дзвінок
      • call_outgoing — вихідний дзвінок
      • form — форма
    • lead_created_at — дата і час створення ліда, якщо клієнт був створений з ліда (в форматі YYYY-MM-DD HH:mm:ss)
    • lead_created_by — ким був створений лід, якщо клієнт був створений з ліда (ідентифікатор користувача)
    • phones — масив телефонних номерів клієнта. Кожен номер містить наступні поля:
      • type — тип номера. Можливі значення:
        • work — робочий
        • personal — особистий
      • phone — значення номеру
    • contacts — масив контактів клієнта. Кожен контакт містить наступні поля:
      • type — тип контакту. Можливі значення:
        • email_work — робочий e-mail
        • email_personal — особистий e-mail
        • skype
        • telegram
        • viber
        • whatsapp
      • value — значення контакту
    • labels — масив тегів, призначених клієнту. Кожен тег містить наступні поля:
      • id — ідентифікатор тега
      • label — значення тега

GET /v1/zcrm/customers/<c_id>

Повертає клієнта за його ID.

Параметри адреси

  • c_id — ідентифікатор клієнта

Відповідь

{
  "id": 65,
  "name": "Good company",
  "status": "company",
  "type": "client",
  "responsible_user_id": 20,
  "employees_count": "50",
  "comment": "",
  "country": "GB",
  "city": "London",
  "address": "",
  "zip": "",
  "website": "",
  "created_at": "2020-04-28 05:47:47",
  "created_by": 20,
  "lead_source": "manual",
  "lead_created_at": null,
  "lead_created_by": null,
  "phones": [
    {
      "type": "work",
      "phone": "+44123456789"
    }
  ],
  "contacts": [
    {
      "type": "email_work",
      "value": "good_company@example.com"
    }
  ],
  "labels": [
    {
      "id": 12,
      "label": "Best clients"
    }
  ],
  "custom_properties": [
    {
      "id": 18,
      "key": "loyalty",
      "title": "Loyalty",
      "value": "high"
    }
  ]
}

де:

  • id — ідентифікатор клієнта
  • name — ім'я клієнта
  • status — статус клієнта. Можливі значення:
    • individual — фіз. особа
    • company — компанія
  • type — тип клієнта. Можливі значення:
    • potential — потенційний клієнт
    • client — клієнт
    • reseller — реселлер
    • partner — партнер
  • responsible_user_id — відповідальний (ідентифікатор користувача)
  • employees_count — кількість співробітників. Можливі значення:
    • 50 — менше 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500
  • comment — опис клієнта
  • country — країна клієнта. Код з двох літер (RU, US і т.і.)
  • city — місто клієнта
  • address — адреса клієнта
  • zip — поштовий індекс
  • website — веб-сайт клієнта
  • created_at — дата і час створення клієнта `YYYY-MM-DD HH:mm:ss`)
  • created_by — ким був створений (ідентифікатор користувача)
  • lead_source — джерело. Можливі значення:
    • manual — вручну
    • call_incoming — вхідний дзвінок
    • call_outgoing — вихідний дзвінок
    • form — форма
  • lead_created_at — дата і час створення ліда, якщо клієнт був створений з ліда (в форматі `YYYY-MM-DD HH:mm:ss`)
  • lead_created_by — ким був створений лід, якщо клієнт був створений з ліда (ідентифікатор користувача)
  • phones — масив телефонних номерів клієнта. Кожен номер містить наступні поля:
    • type — тип номера. Можливі значення:
      • work — робочий
      • personal — особистий
    • phone — значення номеру
  • contacts — масив контактів клієнта. Кожен контакт містить наступні поля:
    • type — тип контакту. Можливі значення:
      • email_work — робочий e-mail
      • email_personal — особистий e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — значення контакту
  • labels — масив тегів, призначених клієнту. Кожен тег містить наступні поля:
    • id — ідентифікатор тега
    • label — значення тега
  • custom_properties — масив додаткових властивостей. Кожна додаткова властивість містить наступні поля:
    • id — ідентифікатор додаткової властивості
    • key — унікальне ім'я додаткової властивості
    • title — назва додаткової властивості, що відображається
    • value — значення додаткової властивості

POST /v1/zcrm/customers

Створює нового клієнта з зазначеними даними.

  • customer — дані нового клієнта. Структура клієнта:

Параметри

{
    "name": "Good company",
    "status": "company",
    "type": "client",
    "responsible_user_id": 20,
    "employees_count": "50",
    "comment": "",
    "country": "GB",
    "city": "London",
    "address": "",
    "zip": "",
    "website": "",
    "lead_source": "manual",
    "phones": [
      {
        "type": "work",
        "phone": "+44123456789"
      }
    ],
    "contacts": [
      {
        "type": "email_work",
        "value": "good_company@example.com"
      }
    ],
    "labels": [
      { "id": 12 },
      { "id": 13 }
  ],
    "custom_properties": [
    {
        "id": 18,
        "value": "high"
      }
    ]
}

де:

  • name — ім'я клієнта
  • status — статус клієнта. Допустимые значения:
    • individual — фіз. особа
    • company — компанія
  • type — тип клієнта. Допустимі значення:
    • potential — потенційний клієнт
    • client — клієнт
    • reseller — реселлер
    • partner — партнер
  • responsible_user_id — відповідальний (ідентифікатор користувача)
  • employees_count — кількість співробітників. Допустимі значення:
    • 50 — менше 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500
  • comment — опис клієнта
  • country — країна клієнта. Код з двох літер (RU, US і т.і.)
  • city — місто клієнта
  • address — адреса клієнта
  • zip — поштовий індекс
  • website — веб-сайт клієнта
  • lead_source — джерело. Допустимі значення:
    • manual — вручну
    • call_incoming — вхідний дзвінок
    • call_outgoing — вихідний дзвінок
    • form — форма
  • phones — масив телефонних номерів. Кожен номер повинен містити такі поля:
    • type — тип номера. Можливі значення:
      • work — робочий
      • personal — особистий
    • phone — значення номеру
  • contacts — масив контактів клієнта. Кожен контакт повинен містити наступні поля:
    • type — тип контакту. Можливі значення:
      • email_work — робочий e-mail
      • email_personal — особистий e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — значення контакту
  • labels — масив тегів, що додаються до клієнта. Кожен елемент повинен містити:
    • id — ідентифікатор існуючого тега
  • custom_properties — масив додаткових властивостей. Кожен елемент повинен містити:
    • id — ідентифікатор додаткової властивості либо:
    • key — унікальне ім'я додаткової властивості
    • value — значення додаткової властивості

Відповідь:

{
"id": 65
}

де:

  • id — ідентифікатор створеного клієнта

PUT /v1/zcrm/customers/<c_id>

Оновлює існуючого клієнта з зазначеним ID.

Параметри адреси

  • c_id — ідентифікатор клієнта

Параметри

  • customer — нові дані клієнта. Структура клієнта:
{
    "name": "Good company",
    "status": "company",
    "type": "client",
    "responsible_user_id": 20,
    "employees_count": "50",
    "comment": "",
    "country": "GB",
    "city": "London",
    "address": "",
    "zip": "",
    "website": "",
    "lead_source": "manual",
    "phones": [
      {
        "type": "work",
        "phone": "+44123456789"
      }
    ],
    "contacts": [
      {
        "type": "email_work",
        "value": "good_company@example.com"
      }
    ],
    "labels": [
      { "id": 12 },
      { "id": 13 }
  ],
    "custom_properties": [
    {
        "id": 18,
        "value": "high"
      }
    ]
}

де:

  • name — ім'я клієнта
  • status — статус клієнта. Допустимі значення:
    • individual — фіз. особа
    • company — компанія
  • type — тип клієнта. Допустимі значення:
    • potential — потенційний клієнт
    • client — клієнт
    • reseller — реселлер
    • partner — партнер
  • responsible_user_id — відповідальний (ідентифікатор користувача)
  • employees_count — кількість співробітників. Допустимі значення:
    • 50 — менше 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500
  • comment — опис клієнта
  • country — країна клієнта. Код з двох літер (RU, US і т.і.)
  • city — місто клієнта
  • address — адреса клієнта
  • zip — поштовий індекс
  • website — веб-сайт клієнта
  • lead_source — джерело. Допустимі значення:
    • manual — вручну
    • call_incoming — вхідний дзвіник
    • call_outgoing — вихідний дзвіник
    • form — форма
  • phones — масив телефонних номерів. Кожен номер повинен містити такі поля:
    • type — тип номера. Можливі значення:
      • work — робочий
      • personal — особистий
    • phone — значення номеру
  • contacts — масив контактів клієнта. Кожен контакт повинен містити наступні поля:
    • type — тип контакту. Можливі значення:
      • email_work — робочий e-mail
      • email_personal — особистий e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — значення контакту
  • labels — масив тегів, що додаються до клієнта. Кожен елемент повинен містити:
    • id — ідентифікатор існуючого тега
  • custom_properties — масив додаткових властивостей. Кожен елемент повинен містити:
    • id — ідентифікатор додаткової властивості або:
    • key — унікальне ім'я додаткової властивості
    • value — значення додаткової властивості

DELETE /v1/zcrm/customers/<c_id>

Видаляє клієнта за його ID.

Параметри адреси

  • c_id — ідентифікатор клієнта

GET /v1/zcrm/customers/labels

Повертає список всіх тегів і статистику за ними.

Відповідь

{
  "totalCount": 5,
  "labels": [
    {
      "id": 12,
      "label": "Best clients",
      "count": 14
    }
  ]
}

де:

  • totalCount — загальна кількість тегів в системі
  • labels — масив тегів. Кожен тег має наступні поля:
    • id — ідентифікатор тега
    • label — ім'я тега
    • count — кількість клієнтів і лідів, що використовують даний тег

POST /v1/zcrm/customers/labels

Створює новий тег.

Параметри

  • name — ім'я нового тега

Відповідь

{
  "id": 13,
  "label": "Best clients",
  "count": 0
}

де:

  • id — ідентифікатор створеного тега
  • label — ім'я тега
  • count — кількість клієнтів і лідів, що використовують даний тег (тут завжди дорівнює 0)

DELETE /v1/zcrm/customers/labels/<l_id>

Видаляє тег з системи за його ID.

Параметри адреси

  • l_id — ідентифікатор тега

GET /v1/zcrm/customers/custom-properties

Повертає всі додаткові властивості.

Відповідь

{
  "totalCount": 8,
  "customProperties": [
    {
      "id": 18,
      "key": "loyalty",
      "title": "Loyalty"
    }
  ]
}

де:

  • totalCount — загальна кількість додаткових властивостей.
  • customProperties — масив додаткових властивостей. Кожна додаткова властивість містить наступні поля:
    • id —ідентифікатор додаткової властивості
    • key — унікальне ім'я додаткової властивості
    • title — назва додаткової властивості, що відображається

GET /v1/zcrm/customers/<c_id>/feed

Повертає записи в стрічці клієнта.

Параметри адреси

  • c_id — ідентифікатор клієнта

Відповідь

{
  "totalCount": 17,
  "items": [
    {
      "id": 37825,
      "type": "note",
      "content": "Call to client",
      "time": "2020-06-08 06:55:02",
      "user_id": 20,
      "user_name": "John Smith",
      "call_id": null,
      "call_type": null,
      "call_status": null,
      "call_phone": null,
      "call_duration": null,
      "call_record": null,
      "call_contact_name": null,
      "attached_files": [
        {
          "file_id": 576,
          "original_filename": "filename.doc"
        }
      ]
    }
  ]
}

де:

  • totalCount — загальна кількість записів
  • items — масив записів. Кожен запис містить наступні атрибути:
    • id — ідентифікатор запису
    • type — тип запису. Можливі значення:
      • event — подія
      • note — текстова замітка
      • call — дзвінок
    • content — вміст запису. Якщо тип запису - замітка, цей атрибут містить текстовий зміст замітки. Якщо тип запису - подія, цей атрибут містить ідентифікатор події, наприклад:
      • CUSTOMER_CREATED — подія створення клієнта
      • LEAD_CREATED — подія створення ліда
    • time — час запису в форматі `YYYY-MM-DD hh:mm:ss`
    • user_id — ідентифікатор користувача, який створив запис
    • user_name — ім'я користувача, який створив запис
    • call_id — ідентифікатор дзвінка (якщо тип запису - дзвінок)
    • call_type — тип дзвінка. Можливі значення:
      • incoming — вхідний дзвінок
      • outgoing — вихідний дзвінок
    • call_status — статус дзвінка. Можливі значення:
      • answer — успішний дзвінок
      • noanswer — без відповіді
      • cancel — скасований
      • busy — зайнято
      • failed — не вдався
    • call_phone — телефонний номер дзвінка
    • call_duration — тривалість дзвінка в секундах
    • call_record — чи увімкнено запис дзвінка
    • call_contact_name — ім'я контакту дзвінка
    • attached_files — масив прикріплених до замітки файлів (якщо тип запису - замітка). Кожен елемент масиву містить наступні атрибути:
      • file_id — ідентифікатор файлу
      • original_filename — оригінальне ім'я файлу

POST /v1/zcrm/customers/<c_id>/feed

Додає текстову замітку в стрічку клієнта з можливістю прикріплення файлів.

Параметри адреси

  • c_id — ідентифікатор клієнта

Параметри

  • content — текстовий зміст замітки
  • files — масив файлів, що вкладаються

Відповідь

{
  "id": 37825,
  "type": "note",
  "content": "Call to client",
  "time": "2020-06-08 06:55:02",
  "user_id": 20,
  "user_name": "John Smith",
  "attached_files": [
    {
      "file_id": 576,
      "original_filename": "filename.doc"
    }
  ]
}

де:

  • id — ідентифікатор запису
  • type — тип запису. В даному випадку дорівнює:
    • note — текстова замітка
  • content — текстовий зміст замітки
  • time — час запису в форматі `YYYY-MM-DD hh:mm:ss`
  • user_id — ідентифікатор користувача, який створив запис
  • user_name — ім'я користувача, який створив запис
  • attached_files — масив прикріплених до замітки файлів (якщо тип запису - замітка). Кожен елемент масиву містить наступні атрибути:
    • file_id — ідентифікатор файлу
    • original_filename — оригінальне ім'я файлу

PUT /v1/zcrm/customers/<c_id>/feed/<i_id>

>Оновлює вміст існуючої текстової замітки за її ID.

Параметри адреси

  • c_id — ідентифікатор клієнта
  • i_id — ідентифікатор текстової замітки

Параметри

  • content — новий текст замітки

DELETE /v1/zcrm/customers/<c_id>/feed/<i_id>

Видаляє замітку в стрічці клієнта за її ID.

Параметри адреси

  • c_id — ідентифікатор клієнта
  • i_id — ідентифікатор текстової замітки

GET /v1/zcrm/customers/<c_id>/employees

Повертає список співробітників клієнта за його ID.

Параметри адреси

  • c_id — ідентифікатор клієнта

Відповідь

{
  "totalCount": 5,
  "employees": [
    {
      "id": 23,
      "customer_id": 11,
      "name": "John Smith",
      "position": "manager",
      "position_title": "",
      "comment": "",
      "phones": [
        {
          "type": "work",
          "phone": "+44123456789"
        }
      ],
      "contacts": [
        {
          "type": "email_work",
          "value": "john@example.com"
        }
      ]
    }
  ]
}

де:

  • totalCount — кількість співробітників клиента
  • employees — масив співробітників клієнта. Кожен елемент масиву містить наступні атрибути:
    • id — ідентифікатор співробітника
    • customer_id — ідентифікатор клієнта, до якого прив'язаний співробітник
    • name — ім'я співробітника
    • position — посада сотрудника. Можливі значення:
      • ceo — ген. директор
      • director — директор
      • manager — менеджер
      • sales_manager — менеджер з продажів
      • hr — HR
      • support — підтримка
      • custom — довільна
    • position_title — найменування довільної посади (для position = custom)
    • comment — опис співробітника
    • phones — масив телефонних номерів співробітника. Кожен номер містить наступні поля:
      • type — тип номеру. Можливі значення:
        • work — робочий
        • personal — особистий
      • phone — значення номеру
    • contacts — масив контактів співробітника. Кожен контакт містить наступні поля:
      • type — тип контакта. Можливі значення:
        • email_work — робочий e-mail
        • email_personal — особистий e-mail
        • skype
        • telegram
        • viber
        • whatsapp
      • value — значення контакту

GET /v1/zcrm/customers/<c_id>/employees/<e_id>

Повертає співробітника клієнта за його ID.

Параметри адреси

  • c_id — ідентифікатор клієнта
  • e_id — ідентифікатор співробітника

Відповідь

{
  "id": 23,
  "customer_id": 11,
  "name": "John Smith",
  "position": "manager",
  "position_title": "",
  "comment": "",
  "phones": [
    {
      "type": "work",
      "phone": "+44123456789"
    }
  ],
  "contacts": [
    {
      "type": "email_work",
      "value": "john@example.com"
    }
  ]
}

де:

  • id — ідентифікатор співробітника
  • customer_id — ідентифікатор клієнта, до якого прив'язаний співробітник
  • name — ім'я співробітника
  • position — посада сотрудника. Можливі значення:
    • ceo — ген. директор
    • director — директор
    • manager — менеджер
    • sales_manager — менеджер з продажів
    • hr — HR
    • support — підтримка
    • custom — довільна
  • position_title — найменування довільної посади (для position = custom)
  • comment — опис співробітника
  • phones — масив телефонних номерів співробітника. Кожен номер містить наступні поля:
    • type — тип номеру. Можливі значення:
      • work — робочий
      • personal — особистий
    • phone — значення номеру
  • contacts — масив контактів співробітника. Кожен контакт містить наступні поля:
    • type — тип контакта. Можливі значення:
      • email_work — робочий e-mail
      • email_personal — особистий e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — значення контакту

POST /v1/zcrm/customers/<c_id>/employees

Створює і зберігає нового співробітника для заданого клієнта.

Параметри адреси

  • c_id — ідентифікатор клієнта

Параметри

  • employee — дані нового співробітника. Структура співробітника:
{
    "name": "John Smith",
    "position": "manager",
    "position_title": "",
    "comment": "",
    "phones": [
      {
        "type": "work",
        "phone": "+44123456789"
      }
    ],
    "contacts": [
      {
        "type": "email_work",
        "value": "john@example.com"
      }
    ]
  }

де:

  • name — ім'я співробітника
  • position — посада співробітника. Допустимі значення:
    • ceo — ген. директор
    • director — директор
    • manager — менеджер
    • sales_manager — менеджер з продажів
    • hr — HR
    • support — підтримка
    • custom — довільна
  • position_title — найменування довільної посади (для position = custom)
  • comment — опис співробітника
  • phones — масив телефонних номерів співробітника. Кожен номер містить наступні поля:
    • type — тип номеру. Можливі значення:
      • work — робочий
      • personal — особистий
    • phone — значення номеру
  • contacts — масив контактів співробітника. Кожен контакт містить наступні поля:
    • type — тип контакта. Можливі значення:
      • email_work — робочий e-mail
      • email_personal — особистий e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — значення контакту

Відповідь

{
  "id": 23
}

де:

  • id — ідентифікатор нового співробітника

PUT /v1/zcrm/customers/<c_id>/employees/<e_id>

Оновлює існуючого співробітника із зазначеним ID.

Параметри адреси

  • c_id — ідентифікатор клієнта
  • e_id — ідентифікатор співробітника

Параметри

  • employee — нові дані співробітника. Структура:
{
    "name": "John Smith",
    "position": "manager",
    "position_title": "",
    "comment": "",
    "phones": [
      {
        "type": "work",
        "phone": "+44123456789"
      }
    ],
    "contacts": [
      {
        "type": "email_work",
        "value": "john@example.com"
      }
    ]
}

де:

  • name — ім'я співробітника
  • position — посада співробітника. Допустимі значення:
    • ceo — ген. директор
    • director — директор
    • manager — менеджер
    • sales_manager — менеджер з продажів
    • hr — HR
    • support — підтримка
    • custom — довільна
  • position_title — найменування довільної посади (для position = custom)
  • comment — опис співробітника
  • phones — масив телефонних номерів співробітника. Кожен номер містить наступні поля:
    • type — тип номеру. Можливі значення:
      • work — робочий
      • personal — особистий
    • phone — значення номеру
  • contacts — масив контактів співробітника. Кожен контакт містить наступні поля:
    • type — тип контакта. Можливі значення:
      • email_work — робочий e-mail
      • email_personal — особистий e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — значення контакту

DELETE /v1/zcrm/customers/<c_id>/employees/<e_id>

Видаляє співробітника за його ID.

Параметри адреси

  • c_id — ідентифікатор клієнта
  • e_id — ідентифікатор співробітника

GET /v1/zcrm/events

Повертає список завдань.

Параметри

  • search (необов'язково) — рядок пошуку. Пошук здійснюється комбіновано за:
    • назвою завдань
    • описом завдань
    • коментарем до завершених завданнь
  • filter (необов'язково) — фільтр завдань. Структура фільтра:
    {
        "responsible": 456,
        "createdBy": 456,
        "start": "2020-06-03 02:56:00",
        "end": "2020-06-12 02:56:00",
        "completed": 1
    }

    де:

    • responsible — відповідальний (ідентифікатор користувача)
    • createdBy — створив (ідентифікатор користувача)
    • start — показати завдання, що починаються після зазначеного часу (в форматі `YYYY-MM-DD hh:mm:ss`)
    • end — показати завдання, що починаються до зазначеного часу (в форматі `YYYY-MM-DD hh:mm:ss`)
    • completed — встановіть в 1, щоб показати в тому числі завершені завдання
  • sort (необов'язково) - сортування завдань. Структура параметра:
    {
        "attr": "start",
        "desc": 0
    }

    де:

    • attr — поле сортування. Допустимі значення:
      • responsible — відповідальний користувач
      • title — назва завдання
      • start — час початку завдання
      • end — час завершення завдання
    • desc — напрямок сортування. Допустимі значення:
      • 0 — за зростанням
      • 1 — за зменшенням

Відповідь

{
  "totalCount": 4,
  "events": [
    {
      "id": 40,
      "type": "task",
      "title": "Call to GoodCompany",
      "description": "",
      "start": "2020-05-26 09:00:00",
      "end": "2020-05-26 12:30:00",
      "allDay": false,
      "created_by": 234,
      "responsible_user": 234,
      "phone": "",
      "call_done": 0,
      "completed": 0,
      "completed_comment": "",
      "members": [234, 235],
      "customers": [
        {
          "id": 3486,
          "name": "GoodCompany",
          "status": "company",
          "type": "client",
          "lead_source": "manual",
          "lead_status": "not_processed",
          "contact_type": "customer"
        }
      ]
    }
  ]
}

де

  • totalCount — загальна кількість завдань
  • events — масив завдань. Кожне завдання містить наступні атрибути:
    • id — ідентифікатор завдання
    • type — тип завдання. Можливі значення:
      • task — завдання
      • call — дзвінок
    • title — назва завдання
    • description — опис завдання (в форматі Quill Delta: https://quilljs.com/docs/delta/)
    • start — дата і час початку завдання (в форматі `YYYY-MM-DD hh:mm:ss`)
    • end — дата і час закінчення завдання (в форматі `YYYY-MM-DD hh:mm:ss`)
    • allDay — завдання на весь день (`true` або `false`) — дата визначається параметром start
    • created_by — ідентифікатор користувача, який створив завдання
    • responsible_user — ідентифікатор користувача, відповідального за завдання
    • phone — номер телефону для дзвінка (якщо тип завдання — дзвінок)
    • call_done — вказує, чи був здійснений дзвінок
    • completed — вказує, що завдання позначено як завершене
    • completed_comment — коментар до завершеного завдання
    • members — масив учасників завдання (тільки ідентифікатори користувачів)
    • customers — масив клієнтів і лідів, прикріплених до завдання. Кожен елемент масиву містить наступні поля:
      • id — ідентифікатор клієнта / ліда
      • name — ім'я клієнта / ліда
      • status — статус клієнта. Можливі значення:
        • individual — фіз. особа
        • company — компанія
      • type — тип клієнта. Можливі значення:
        • potential — потенційний клієнт
        • client — клієнт
        • reseller — реселлер
        • partner — партнер
      • lead_source — джерело ліда. Можливі значення:
        • manual — вручну
        • call_incoming — вхідний дзвінок
        • call_outgoing — вихідний дзвінок
        • form — форма
      • lead_status — статус ліда. Можливі значення:
        • not_processed — не був оброблений
        • in_progress — в обробці
        • finished — завершений
      • contact_type — тип контакта. Можливі значення:
        • customer — клієнт
        • lead — лід

GET /v1/zcrm/events/<event_id>

Повертає завдання за його ID.

Відповідь

{
  "id": 40,
  "type": "task",
  "title": "Call to GoodCompany",
  "description": "",
  "start": "2020-05-26 09:00:00",
  "end": "2020-05-26 12:30:00",
  "allDay": false,
  "created_by": 234,
  "responsible_user": 234,
  "phone": "",
  "call_done": 0,
  "completed": 0,
  "completed_comment": "",
  "members": [234, 235],
  "customers": [
    {
      "id": 3486,
      "name": "GoodCompany",
      "status": "company",
      "type": "client",
      "lead_source": "manual",
      "lead_status": "not_processed",
      "contact_type": "customer"
    }
  ]
}

де

  • id — ідентифікатор завдання
  • type — тип завдання. Можливі значення:
    • task — задача
    • call — звонок
  • title — назва завдання
  • description — опис завдання (в форматі Quill Delta: https://quilljs.com/docs/delta/)
  • start — дата і час початку завдання (в форматі `YYYY-MM-DD hh:mm:ss`)
  • end — дата і час закінчення завдання (в форматі `YYYY-MM-DD hh:mm:ss`)
  • allDay — завдання на весь день (`true` або `false`)
  • created_by — ідентифікатор користувача, який створив завдання
  • responsible_user — ідентифікатор користувача, відповідального за завдання
  • phone — номер телефону для дзвінка (якщо тип завдання — дзвінок)
  • call_done — вказує, чи був здійснений дзвінок
  • completed — вказує, що завдання позначено як завершене
  • completed_comment — коментар до завершеного завдання
  • members — масив учасників завдання (тільки ідентифікатори користувачів)
  • customers — масив клієнтів і лідів, прикріплених до завдання. Кожен елемент масиву містить наступні поля:
    • id — ідентифікатор клієнта / лида
    • name — ім'я клієнта / ліда
    • status — статус клієнта. Можливі значення:
      • individual — фіз. особа
      • company — компанія
    • type — тип клієнта. Можливі значення:
      • potential — потенційний клієнт
      • client — клієнт
      • reseller — реселлер
      • partner — партнер
    • lead_source — джерело ліда. Можливі значення:
      • manual — вручну
      • call_incoming — вхідний дзвінок
      • call_outgoing — вихідний дзвінок
      • form — форма
    • lead_status — статус ліда. Можливі значення:
      • not_processed — не був оброблений
      • in_progress — в обробці
      • finished — завершений
    • contact_type — тип контакта. Можливі значення:
      • customer — клієнт
      • lead — лід

POST /v1/zcrm/events

Створює нове завдання зі спеціальними даними.

Параметри

  • event — дані нового завдання. Структура:
{
    "type": "task",
    "title": "Call to GoodCompany",
    "description": "",
    "start": "2020-05-26 09:00:00",
    "end": "2020-05-26 12:30:00",
    "allDay": false,
    "responsible_user": 234,
    "phone": "",
    "members": [234, 235],
    "customers": [3486, 3487]
}

де

  • type — тип завдання. Допустимі значення:
    • task — завдання
    • call — дзвінок
  • title — назва завдання
  • description — опис завдання (в форматі Quill Delta: https://quilljs.com/docs/delta/)
  • start — дата і час початку завдання (в форматі `YYYY-MM-DD hh:mm:ss`)
  • end — дата і час завершення завдання (в форматі `YYYY-MM-DD hh:mm:ss`)
  • allDay — завдання на весь день (`true` або `false`)
  • responsible_user — ідентифікатор користувача, відповідального за завдання
  • phone — номер телефону для дзвінка (якщо тип завдання - дзвінок)
  • members — масив учасників завдання (тільки ідентифікатори користувачів)
  • customers — масив прикріплених клієнтів і лідів (тільки ідентифікатори клієнтів і лідів)

Відповідь

{
  "id": 7216
}

де

  • id — ідентифікатор створеного завдання

PUT /v1/zcrm/events/<event_id>

Оновлює існуюче завдання із зазначеним ID.

>

Параметри

  • event — нові дані завдання. Структура:
{
    "title": "Call to GoodCompany",
    "description": "",
    "start": "2020-05-26 09:00:00",
    "end": "2020-05-26 12:30:00",
    "allDay": false,
    "created_by": 234,
    "responsible_user": 234,
    "phone": "",
    "members": [234, 235],
    "customers": [3486, 3487]
}

де

  • title — назва завдання
  • description — опис завдання (в форматі Quill Delta: https://quilljs.com/docs/delta/)
  • start — дата і час початку завдання (в форматі `YYYY-MM-DD hh:mm:ss`)
  • end — дата і час завершення завдання (в форматі `YYYY-MM-DD hh:mm:ss`)
  • allDay — завдання на весь день (`true` або `false`)
  • responsible_user — ідентифікатор користувача, відповідального за завдання
  • phone — номер телефону для дзвінка (якщо тип завдання - дзвінок)
  • members — масив учасників завдання (тільки ідентифікатори користувачів)
  • customers — масив прикріплених клієнтів і лідів (тільки ідентифікатори клієнтів і лідів)

POST /v1/zcrm/events/<event_id>/close

Завершує (закриває) завдання.

Параметри

  • comment (необов'язково) — коментар

DELETE /v1/zcrm/events/<event_id>

Видаляє завдання за його ID.

Немає параметрів

GET /v1/zcrm/leads

Повертає список лідів.

Параметри

  • search (необов'язково) — рядок пошуку. Пошук здійснюється комбіновано за:
    • ім'ям ліда
    • номерами телефонів ліда
    • описом ліда
    • адресою і поштовому індексу
    • веб-сайтом
    • адресам e-mail
    • мессенджерами
  • filter (необов'язково) - фільтр лідів. Структура фільтра:
    {
        "source": "call_incoming",
        "responsible": 32,
        "label": 12,
        "createdAfter": "2020-06-11 12:24:00",
        "createdBefore": "2020-06-26 12:24:00"
    }

де

  • source — джерело ліда. Допустимі значення:
    • manual — доданий вручну
    • call_incoming — вхідний дзвінок
    • call_outgoing — вихідний дзвінок
    • form — форма зворотнього зв'язку
  • responsible — відповідальний (ідентифікатор користувача). Параметр також допускає спеціальні значення:
    • null — поверне всі призначені кому-небудь ліди
    • –1 — поверне нерозібрані ліди
    • –2 — поверне всі ліди (і призначені, і нерозібрані)
  • label — тег (ідентифікатор)
  • createdAfter — показати тільки ліди, створені після зазначеного часу (формат: `YYYY-MM-DD hh:mm:ss`)
  • createdBefore — показати тільки ліди, створені до зазначеного часу (формат: `YYYY-MM-DD hh:mm:ss`)
Будь-який з параметрів фільтра може бути опущений, тобто не є обов'язковим.
  • sort (необов'язково) — сортування лідів. Структура параметра:
    {
        "attr": "name",
        "desc": 0
    }

    де

    • attr — поле сортування. Допустимі значення:
      • name — ім'я ліда
      • lead_source — джерело ліда
      • lead_status — статус ліда
      • responsible_user_id — відповідальний користувач
      • lead_created_at — час створення ліда
    • desc — напрямок сортування. Допустимі значення:
      • 0 — за зростанням
      • 1 — за зменшенням
  • take (для посторінкового виведення) - скільки лідів повернути (за замовчуванням 20)
  • skip (для посторінкового виведення) — скільки лідів пропустити (за замовчуванням 0)

Відповідь

{
  "totalCount": 100,
  "uncategorizedCount": 10,
  "leads": [
    {
      "id": 3486,
      "name": "GoodCompany",
      "responsible_user_id": 234,
      "employees_count": "50",
      "comment": "",
      "country": "GB",
      "city": "London",
      "address": "",
      "zip": "",
      "website": "",
      "lead_status": "not_processed",
      "lead_source": "manual",
      "lead_created_at": "2020-04-28 05:47:47",
      "lead_created_by": 234,
      "phones": [
        {
          "type": "work",
          "phone": "+44123456789"
        }
      ],
      "contacts": [
        {
          "type": "email_work",
          "value": "good_company@example.com"
        }
      ],
      "labels": [
        {
          "id": 22,
          "label": "Best clients"
        }
      ]
    }
  ]
}

де

  • totalCount — загальна кількість знайдених лідів (з урахуванням рядка пошуку і фільтра)
  • uncategorizedCount — загальна кількість нерозібраних лідів (з урахуванням пошуку і фільтра)
  • leads — масив лідів (з урахуванням посторінкового виведення). Кожен елемент масиву містить наступні параметри:
    • id — ідентифікатор ліда
    • name — ім'я ліда
    • responsible_user_id — відповідальний (ідентифікатор користувача)
    • employees_count — кількість співробітників. Можливі значення:
      • 50 — менше 50
      • 50_250 — 50 – 250
      • 250_500 — 250 – 500
    • comment — опис ліда
    • country — країна ліда. Код з двох літер (RU, US і т.і.)
    • city — місто ліда
    • address — адреса ліда
    • zip — поштовий індекс
    • website — веб-сайт ліда
    • lead_status — статус ліда. Можливі значення:
      • not_processed — не оброблений
      • in_progress — в обробці
      • finished — завершений
    • lead_source — джерело ліда. Можливі значення:
      • manual — вручну
      • call_incoming — вхідний дзвінок
      • call_outgoing — вихідний дзвінок
      • form — форма
    • lead_created_at — дата і час створення ліда (в форматі`YYYY-MM-DD HH:mm:ss`)
    • lead_created_by — ким був створений лід (ідентифікатор користувача)
    • phones — масив телефонних номерів ліда. Кожен номер містить наступні поля:
      • type — тип номера. Можливі значення:
        • work — робочий
        • personal — особистий
      • phone — значення номеру
    • contacts — масив контактів ліда. Кожен контакт містить наступні поля:
      • type — тип контакту. Можливі значення:
        • email_work — робочий e-mail
        • email_personal — особистий e-mail
        • skype
        • telegram
        • viber
        • whatsapp
      • value — значення контакту
    • labels — масив тегів, призначених ліду. Кожен тег містить наступні поля:
      • id — ідентифікатор тега
      • label — значення тега

GET /v1/zcrm/leads/<lead_id>

Повертає лід за його ID.

Відповідь

{
  "id": 3486,
  "name": "GoodCompany",
  "responsible_user_id": 234,
  "employees_count": "50",
  "comment": "",
  "country": "GB",
  "city": "London",
  "address": "",
  "zip": "",
  "website": "",
  "lead_status": "not_processed",
  "lead_source": "manual",
  "lead_created_at": "2020-04-28 05:47:47",
  "lead_created_by": 234,
  "phones": [
    {
      "type": "work",
      "phone": "+44123456789"
    }
  ],
  "contacts": [
    {
      "type": "email_work",
      "value": "good_company@example.com"
    }
  ],
  "labels": [
    {
      "id": 22,
      "label": "Best clients"
    }
  ],
  "custom_properties": [
    {
      "id": 12,
      "key": "loyalty",
      "title": "Loyalty",
      "value": "high"
    }
  ]
}

де

  • id — ідентифікатор ліда
  • name — ім'я ліда
  • responsible_user_id — відповідальний (ідентифікатор користувача)
  • employees_count — кількість співробітників. Можливі значення:
    • 50 — менше 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500
  • comment — описание лида
  • country — країна ліда. Код з двох літер (RU, US і т.і.)
  • city — місто ліда
  • address — адреса ліда
  • zip — поштовий індекс
  • website — веб-сайт ліда
  • lead_status — статус ліда. Можливі значення:
    • not_processed — не оброблений
    • in_progress — в обробці
    • finished — завершений
  • lead_source — джерело ліда. Можливі значення:
    • manual — вручну
    • call_incoming — вхідний дзвінок
    • call_outgoing — вихідний дзвінок
    • form — форма
  • lead_created_at — дата і час створення ліда (в форматі `YYYY-MM-DD HH:mm:ss`)
  • lead_created_by — ким був створений лід (ідентифікатор користувача)
  • phones — масив телефонних номерів ліда. Кожен номер містить наступні поля:
    • type — тип номера. Можливі значення:
      • work — робочий
      • personal — особистий
    • phone — значення номеру
  • contacts — масив контактів ліда. Кожен контакт містить наступні поля:
    • type — тип контакту. Можливі значення:
      • email_work — робочий e-mail
      • email_personal — особистий e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — значення контакту
  • labels — масив тегів, призначених ліду. Кожен тег містить наступні поля:
    • id — ідентифікатор тега
    • label — значення тега

POST /v1/zcrm/leads

Створює новий лід із зазначеними даними.

Параметри

  • convert — конвертувати лід в клієнта. Допустимі значення:
    • 0 — не конвертувати, створити лід
    • 1 — створити клієнта
    • 2 — неякісний (операція буде скасована - ні лід, ні клієнт не будуть створені)
  • lead — дані нового ліда. Структура ліда:
    {
        "name": "GoodCompany",
        "responsible_user_id": 234,
        "employees_count": "50",
        "comment": "",
        "country": "RU",
        "city": "Москва",
        "address": "",
        "zip": "",
        "website": "",
        "lead_source": "manual",
        "lead_status": "in_progress",
        "phones": [
          {
            "type": "work",
            "phone": "+44123456789"
          }
        ],
        "contacts": [
          {
            "type": "email_work",
            "value": "good_company@example.com"
          }
        ],
        "labels": [
          { "id": 22 },
          { "id": 23 }
      ],
        "custom_properties": [
        {
            "id": 12,
            "value": "high"
          }
        ]
    }

    де

    • name — ім'я ліда
    • responsible_user_id — відповідальний (ідентифікатор користувача)
    • employees_count — кількість співробітників. Допустимі значення:
      • 50 — менше 50
      • 50_250 — 50 – 250
      • 250_500 — 250 – 500
    • comment — опис ліда
    • country — країна ліда. Код з двох літер (RU, US і т.і.)
    • city — місто ліда
    • address — адреса ліда
    • zip — поштовий індекс ліда
    • website — веб-сайт ліда
    • lead_source — джерело ліда. Допустимі значення:
      • manual — вручну
      • call_incoming — вхідний дзвінок
      • call_outgoing — вихідний дзвінок
      • form — форма
    • lead_status — статус ліда. Допустимі значення:
      • not_processed — не оброблений
      • in_progress — в обробці
      • finished — завершений
    • phones — масив телефонних номерів. Кожен номер повинен містити такі поля:
      • type — тип номера. Можливі значення:
        • work — робочий
        • personal — особистий
      • phone — значення номеру
    • contacts — масив контактів ліда. Кожен контакт повинен містити наступні поля:
      • type — тип контакту. Можливі значення:
        • email_work — робочий e-mail
        • email_personal — особистий e-mail
        • skype
        • telegram
        • viber
        • whatsapp
      • value — значення контакту
    • labels — масив тегів, що додаються до ліду. Кожен елемент повинен містити:
      • id — ідентифікатор існуючого тега
      • custom_properties — масив додаткових властивостей. Кожен елемент повинен містити:
        • id — ідентифікатор додаткової властивості або:
        • key — унікальне ім'я додаткової властивості
        • value — значення додаткової властивості

Відповідь

{
  "id": 123
}

де

  • id — ідентифікатор створеного ліда

PUT /v1/zcrm/leads/<lead_id>

Оновлює існуючий лід із зазначеним ID.

Параметри

  • convert — конвертувати лід в клієнта. Допустимі значення:
    • 0 — не конвертувати
    • 1 — створити клієнта
    • 2 — неякісний (видалити лід)
  • lead — нові дані ліда. Структура ліда:
{
    "name": "GoodCompany",
    "responsible_user_id": 234,
    "employees_count": "50",
    "comment": "",
    "country": "GB",
    "city": "London",
    "address": "",
    "zip": "",
    "website": "",
    "lead_source": "manual",
    "lead_status": "in_progress",
    "phones": [
      {
        "type": "work",
        "phone": "+44123456789"
      }
    ],
    "contacts": [
      {
        "type": "email_work",
        "value": "good_company@example.com"
      }
    ],
    "labels": [
      { "id": 22 },
      { "id": 23 }
  ],
    "custom_properties": [
    {
        "id": 12,
        "value": "high"
      }
    ]
}

де

  • name — ім'я ліда
  • responsible_user_id — відповідальний (ідентифікатор користувача)
  • employees_count — кількість співробітників. Допустимі значення:
    • 50 — менше 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500
  • comment — опис ліда
  • country — країна ліда. Код з двох літер (RU, US і т.і.)
  • city — місто ліда
  • address — адреса ліда
  • zip — поштовий індекс ліда
  • website — веб-сайт ліда
  • lead_source — джерело ліда. Допустимі значення:
    • manual — вручну
    • call_incoming — вхідний дзвінок
    • call_outgoing — вихідний дзвінок
    • form — форма
  • lead_status — статус ліда. Допустимі значення:
    • not_processed — не оброблений
    • in_progress — в обробці
    • finished — завершений
  • phones — масив телефонних номерів. Кожен номер повинен містити такі поля:
    • type — тип номера. Можливі значення:
      • work — робочий
      • personal — особистий
    • phone — значення номеру
  • contacts — масив контактів ліда. Кожен контакт повинен містити наступні поля:
    • type — тип контакту. Можливі значення:
      • email_work — робочий e-mail
      • email_personal — особистий e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — значення контакту
  • labels — масив тегів, що додаються до ліду. Кожен елемент повинен містити:
    • id — ідентифікатор існуючого тега
  • custom_properties — масив додаткових властивостей. Кожен елемент повинен містити:
    • id — ідентифікатор додаткової властивості або:
    • key — унікальне ім'я додаткової властивості
    • value — значення додаткової властивості

DELETE /v1/zcrm/leads/<lead_id>

Видаляє лід за його ID.

Немає параметрів

GET /v1/zcrm/users

Повертає список користувачів.

Відповідь

{
  "totalCount": 2,
  "users": [
    {
      "id": 234,
      "email": "john_smith@example.com",
      "name": "John Smith",
      "group_id": 653,
      "is_superadmin": 1,
      "enabled": 1,
      "created_at": "2020-04-27 01:01:31",
      "avatar": 2457,
      "role": "",
      "status": "",
      "language": "en",
      "color": "220",
      "color_hex": "5678BD",
      "internal_number": "100",
      "timezone": "Europe/London",
      "first_day": 1,
      "device": "webphone",
      "phone_widget_location": "right",
      "phones": [
        {
          "phone": "+44123456789",
          "type": "work"
        }
      ],
      "contacts": [
        {
          "type": "email_work",
          "value": "smith@example.com"
        }
      ]
    }
  ]
}

де

  • totalCount — загальна кількість користувачів
  • users — масив користувачів. Кожен елемент масиву містить наступні атрибути::
    • id — ідентифікатор користувача
    • email — e-mail облікового запису користувача
    • name — ім'я користувача
    • group_id — ідентифікатор групи користувача
    • is_superadmin — вказує, чи є користувач суперадміністратором (1 або 0)
    • enabled — чи розблокован користувач (1 або 0)
    • created_at — дата і час створення користувача (в форматі `YYYY-MM-DD hh:mm:ss`)
    • avatar — аватар користувача (ідентифікатор файлу)
    • role — посада користувача
    • status — статус користувача
    • language — мова інтерфейсу користувача. Можливі варіанти:
      • de — німецька
      • en — англійська
      • es — іспанська
      • pl — польська
      • ru — російська
      • ua — українська
    • color — колір завдань користувача в інтерфейсі ZCRM (тільки значення hue — від 0 до 359)
    • color_hex — колір завдань користувача в інтерфейсі ZCRM (hex-уявлення)
    • internal_number — внутрішній номер АТС користувача
    • timezone — часова зона користувача
    • first_day — визначає, який день тижня є початком тижня:
      • 0 — неділя
      • 1 — понеділок
    • device — що використовується для дзвінків. Можливі значення:
      • webphone — веб-телефон
      • softphone — сторонній софтфон
    • phone_widget_location — розташування віджета веб-телефону. Можливі значення:
      • left — розташовувати віджет телефону зліва
      • right — розташовувати віджет телефону справа
    • phones — масив телефонних номерів користувача. Кожен номер містить наступні поля:
      • phone — значення номеру
      • type — тип номеру. Можливі значення:
        • work — робочий
        • personal — особистий
    • contacts — масив контактів користувача. Кожен контакт містить наступні поля:
      • type — тип контакту. Можливі значення:
        • email_work — робочий контактний e-mail
        • email_personal — особистий контактний e-mail
        • skype
        • telegram
        • viber
        • whatsapp
      • value — значення контакту

GET /v1/zcrm/users/<user_id>

Повертає користувача за його ID.

Відповідь

{
  "id": 234,
  "email": "john_smith@example.com",
  "name": "John Smith",
  "group_id": 653,
  "is_superadmin": 1,
  "enabled": 1,
  "created_at": "2020-04-27 01:01:31",
  "avatar": 2457,
  "role": "",
  "status": "",
  "language": "ru",
  "color": "220",
  "color_hex": "5678BD",
  "internal_number": "100",
  "timezone": "Europe/London",
  "first_day": 1,
  "device": "webphone",
  "phone_widget_location": "right",
  "phones": [
    {
      "phone": "+44123456789",
      "type": "work"
    }
  ],
  "contacts": [
    {
      "type": "email_work",
      "value": "smith@example.com"
    }
  ],
  "pending_email_change_request": false
}

де

  • id — ідентифікатор користувача
  • email — e-mail облікового запису користувача
  • name — ім'я користувача
  • group_id — ідентифікатор групи користувача
  • is_superadmin — вказує, чи є користувач суперадміністратором (1 або 0)
  • enabled — чи розблокован користувач (1 або 0)
  • created_at — дата і час створення користувача (в форматі `YYYY-MM-DD hh:mm:ss`)
  • avatar — аватар користувача (ідентифікатор файлу)
  • role — посада користувача
  • status — статус користувача
  • language — мова інтерфейсу користувача. Можливі варіанти:
    • de — німецька
    • en — англійська
    • es — іспанська
    • pl — польська
    • ru — російська
    • ua — українська
  • color — колір завдань користувача в інтерфейсі ZCRM (только значение hue — от 0 до 359)
  • color_hex — цвет пользователя в интерфейсе ZCRM (hex-уявлення)
  • internal_number —внутрішній номер АТС користувача
  • timezone — часова зона користувача
  • first_day — визначає, який день тижня є початком тижня:
    • 0 — неділя
    • 1 — понеділок
  • device — що використовується для дзвінків. Можливі значення:
    • webphone — веб-телефон
    • softphone — сторонній софтфон
  • phone_widget_location — розташування віджета веб-телефону. Можливі значення:
    • left — розташовувати віджет телефону зліва
    • right — розташовувати віджет телефону справа
  • phones — масив телефонних номерів користувача. Кожен номер містить наступні поля:
    • phone — значення номеру
    • type — тип номеру. Можливі значення:
      • work — робочий
      • personal — особистий
  • contacts — масив контактів користувача. Кожен контакт містить наступні поля:
    • type — тип контакту. Можливі значення:
      • email_work — робочий контактний e-mail
      • email_personal — особистий контактний e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — значення контакту
  • pending_email_change_request — якщо був відправлений запит на зміну e-mail облікового запису, але запит поки не підтверджений, цей параметр буде встановлений в true

GET /v1/zcrm/users/<user_id>/working-hours

Повертає робочі години користувача.

Відповідь

{
  "schedulePeriod": 7,
  "scheduleWorkingHours": [
    {
      "time_start": "2020-06-15 09:00:00",
      "time_end": "2020-06-15 18:00:00"
    }
  ],
  "scheduleFixes": [
    {
      "index": 2,
      "repeat_index": 1,
      "time_start": "2020-06-24 09:00:00",
      "time_end": "2020-06-24 13:00:00",
      "deleted": 0
    }
  ],
  "customWorkingHours": [
    {
      "time_start": "2020-06-27 11:00:00",
      "time_end": "2020-06-27 15:00:00"
    }
  ]
}

де

  • schedulePeriod — періодичність розкладу, як воно повторюється. Для звичайного робочого тижня це 7 днів, для графіка «день через день» це 2 дні і т.і.
  • scheduleWorkingHours — масив робочих періодів. Кожен робочий період містить наступні атрибути:
    • time_start — початок робочого часу в форматі `YYYY-MM-DD hh:mm:ss`
    • time_end — кінець робочого часу в форматі `YYYY-MM-DD hh:mm:ss`
  • scheduleFixes — масив змін, внесених в робочі періоди, визначені в параметрі scheduleWorkingHours. Кожен елемент масиву містить наступні атрибути:
    • index — індекс елемента в scheduleWorkingHours, тобто який робочий період змінений
    • repeat_index — індекс повтору розкладу, в якому відбувається зміна робочого періоду
    • time_start — новий початок робочого часу в форматі `YYYY-MM-DD hh:mm:ss`
    • time_end — новий кінець робочого часу в форматі `YYYY-MM-DD hh:mm:ss`
    • deleted — якщо дорівнює 1, робочий період повністю видалений
  • customWorkingHours — масив призначених для користувача, одиничних робочих періодів. Кожен робочий період містить наступні атрибути:
    • time_start — початок робочого часу в форматі `YYYY-MM-DD hh:mm:ss`
    • time_end —кінець робочого часу в форматі `YYYY-MM-DD hh:mm:ss`

GET /v1/zcrm/users/groups

Повертає групи і права користувачів кожної з них.

Відповідь

{
  "totalCount": 4,
  "groups": [
    {
      "id": 45,
      "type": "manager",
      "title": "",
      "permissions": {
        "customers_create": true,
        "customers_edit": true,
        "customers_delete": true,
        "customers_import_export": true,
        "customers_view_all": false,
        "calendar_other_users_access": false,
        "calls_other_users_access": false,
        "leads_view": false,
        "leads_edit": false,
        "leads_delete": false,
        "leads_import_export": false,
        "team_add": false,
        "team_edit": false
      }
    }
  ]
}

де

  • totalCount — загальна кількість груп
  • groups — масив груп. Кожна група містить такі атрибути:
    • id — ідентифікатор групи
    • type — тип групи. Можливі значення:
      • admin — адміністратори
      • manager — менеджери
      • chat_operator — оператори
      • trainee — стажери
      • custom — користувача
    • title — ім'я групи користувача (для type = custom)
    • permissions — права користувачів групи. Адміністратори мають повний доступ, тому для адміністраторів даний об'єкт буде порожнім. Решта групи містять наступні атрибути (кожен з яких може дорівнювати `true` або `false`):
      • customers_create — дозволено створення клієнтів
      • customers_edit — дозволено редагування клієнтів
      • customers_delete — дозволено видалення клієнтів
      • customers_import_export — дозволені імпорт і експорт клієнтів
      • customers_view_all — дозволений перегляд всіх клієнтів, в тому числі призначених іншим користувачам
      • calendar_other_users_access — дозволений перегляд завдань інших користувачів
      • calls_other_users_access — дозволений доступ до дзвінків інших користувачів
      • leads_view — дозволений перегляд лідів інших користувачів
      • leads_edit — дозволено редагування лідів інших користувачів
      • leads_delete — дозволено видалення лідів інших користувачів
      • leads_import_export — дозволені імпорт і експорт лідів
      • team_add — дозволено додавання і запрошення користувачів в команду
      • team_edit — дозволено редагування користувачів

GET /v1/zcrm/calls

Повертає список дзвінків.

Параметри

  • search (необов'язково) — рядок пошуку. Пошук здійснюється комбіновано за:
    • номерами телефонів
    • іменами контактів (клієнтів, співробітників, лідів або користувачів)
  • filter (необов'язково) — фільтр дзвінків. Структура фільтра:
    {
        "user": 23,
        "type": "incoming",
        "status": "answer",
        "dateFrom": "2020-06-03 14:56:00",
        "dateTo": "2020-06-26 14:56:00"
    }

    де

    • user — користувач (ідентифікатор)
    • type — тип дзвінка. Допустимі значення:
      • incoming — вхідний дзвінок
      • outgoing — вихідний дзвінок
    • status — статус дзвінка. Допустимі значення:
      • answer — успішний дзвінок
      • noanswer — без відповіді
      • cancel — скасований
      • busy — зайнято
      • failed — не вдався
    • dateFrom — показати тільки дзвінки, які буди здійснені після зазначеного часу (формат: `YYYY-MM-DD hh:mm:ss`)
    • dateTo — показати тільки дзвінки, які буди здійснені до зазначеного часу (формат: `YYYY-MM-DD hh:mm:ss`)
Будь-який з параметрів фільтра може бути опущений, тобто не є обов'язковим.
  • sort (необов'язково) — сортування дзвінків. Структура параметра:
      {
        "attr": "time",
        "desc": 0
      }

    де

    • attr — поле сортування. Допустимі значення:
      • phone — номер телефону
      • status — статус дзвінка
      • duration — тривалість дзвінка
      • time — час дзвінка
    • desc — напрямок сортування. Допустимі значення:
      • 0 — за зростанням
      • 1 — за зменшенням
  • take (для посторінкового виведення) - скільки дзвінків повернути (за замовчуванням 20)
  • skip (для посторінкового виведення) - скільки дзвінків пропустити (за замовчуванням 0)

Відповідь

{
  "totalCount": 233,
  "calls": [
    {
      "id": 127,
      "type": "outgoing",
      "status": "answer",
      "phone": "+44123456789",
      "user_id": 179,
      "time": "2019-07-31 17:58:40",
      "duration": 9,
      "pbx_call_id": "out_807ghh1h7f09fa7a188dbf8a6998b1c9ghg4ij06",
      "record": 1,
      "record_url_till": "2020-07-24 20:08:10",
      "contact_type": "customer",
      "contact_name": "GoodCompany",
      "contact_customer_id": 3486,
      "contact_employee_id": null,
      "employee_customer_id": null,
      "contact_user_id": null,
      "is_lead": 1,
      "record_urls": [
        {
          "url": "https://api.zadarma.com/v1/pbx/record/download/[...]/[...]/[...].mp3"
        }
      ]
    }
  ]
}

де

  • totalCount — загальна кількість дзвінків (з урахуванням рядка пошуку і фільтра)
  • calls — масив дзвінків (з урахуванням посторінкового виведення). Кожен елемент масиву містить наступні параметри:
    • id — ідентифікатор дзвінка
    • type — тип дзвінка. Допустимі значення:
      • incoming — вхідний дзвінок
      • outgoing — вихідний дзвінок
    • status — статус дзвінка. Допустимі значення:
      • answer — успішний дзвінок
      • noanswer — без відповіді
      • cancel — скасований
      • busy — зайнято
      • failed — не вдався
    • phone — номер телефону
    • user_id — пользователь, инициировавший или принявший звонок
    • time — час дзвінка в форматі `YYYY-MM-DD hh:mm:ss`
    • duration — тривалість дзвінка в секундах
    • pbx_call_id — ідентифікатор дзвінка в АТС Zadarma
    • record — чи увімкнено запис дзвінка
    • record_url_till — час, до якого посилання на запис розмови буде працювати
    • contact_type — тип контакту. Можливі значення:
      • customer — клієнт або лід (див. параметр is_lead)
      • employee — співробітник клієнта
      • user — користувач
    • contact_name — ім'я контакту
    • contact_customer_id — ідентифікатор клієнта або ліда (якщо дзвінок пов'язаний з клієнтом)
    • contact_employee_id — ідентифікатор співробітника (якщо дзвінок пов'язаний зі співробітником)
    • employee_customer_id — ідентифікатор батьківської сутності (якщо дзвінок пов'язаний зі співробітником)
    • contact_user_id — ідентифікатор користувача (якщо дзвінок пов'язаний з користувачем)
    • is_lead — показує, чи пов'язаний дзвінок з лідом
    • record_urls — масив записів розмови (може бути відсутнім, тому що повинен бути спеціально запитаний). Кожен елемент масиву - об'єкт, що містить наст. поле:
      • url — посилання на запис розмови

GET /v1/zcrm/contacts

Повертає список всіх контактів (клієнти, співробітники, ліди, користувачі) з номерами телефонів.

Параметри

  • search (необов'язково) - рядок пошуку. Пошук здійснюється комбіновано за:
    • іменам і телефонам клієнтів, лідів, співробітників і користувачів
    • внутрішнім номерам користувачів АТС
  • take (для посторінкового виведення) - скільки дзвінків повернути (за замовчуванням 20)
  • skip (для посторінкового виведення) - скільки клієнтів пропустити (за замовчуванням 0)

Відповідь

{
  "totalCount": 128,
  "contacts": [
    {
      "contact_type": "customer",
      // clients attributes...
    },
    {
      "contact_type": "employee",
      // employee attributes...
    },
    {
      "contact_type": "lead",
      // leads attributes...
    },
    {
      "contact_type": "user",
      // users attributes...
    }
  ]
}

де

  • totalCount — загальна кількість контактів (з урахуванням рядка пошуку)
  • contacts — масив контактів. Кожен з контактів в залежності від його типу (клієнт, співробітник, лід, користувач) матиме власний набір атрибутів.

    Клієнт

    {
        "contact_type": "customer",
        "id": 3486,
        "name": "GoodCompany",
        "status": "company",
        "type": "client",
        "phone": {
          "phone": "+44123456789",
          "type": "work"
        },
        "responsible": {
          "id": 234,
          "name": "John Smith",
          "ext_num": "100"
        }
    }

    де

    • contact_type — тип контакта:
      • customer — клієнт
    • id — ідентифікатор клієнта
    • name — ім'я клієнта
    • status — статус клієнта. Можливі значення:
      • individual — фіз. особа
      • company — компанія
    • type — тип клієнта. Можливі значення:
      • potential — потенційний клієнт
      • client — клієнт
      • reseller — реселлер
      • partner — партнер
    • phone — номер телефону. Містить наступні поля:
      • phone — безпосередньо номер
      • type — тип номеру. Можливі значення:
        • work — робочий
        • personal — особистий
    • responsible — відповідальний користувач. Містить наступні поля:
      • id — ідентифікатор користувача
      • name — ім'я користувача
      • ext_num — внутрішній номер АТС користувача

    Співробітник клієнта

    {
            "contact_type": "employee",
            "id": 8,
            "name": "John Smith",
            "phone": {
              "phone": "+44123456789",
              "type": "work"
            },
            "position": {
              "position": "manager",
              "title": ""
            },
            "customer": {
              "id": 3486,
              "name": "GoodCompany"
            },
            "responsible": {
              "id": 234,
              "name": "John Smith",
              "ext_num": "100"
            }
    }

    де

    • contact_type — тип контакта:
      • employee — співробітник
    • id — ідентифікатор співробітника
    • name — ім'я співробітника
    • phone — номер телефону. Містить наступні поля:
      • phone — безпосередньо номер
      • type — тип номеру. Можливі значення:
        • work — робочий
        • personal — особистий
    • position — посада співробітника. Містить наступні поля:
      • position — значення посади. Можливі значення:
        • ceo — ген. директор
        • director — директор
        • manager — менеджер
        • sales_manager — менеджер з продажів
        • hr — HR
        • support — підтримка
        • custom — довільна
      • title — найменування довільної посади (для position = custom)
    • customer — клієнт, до якого прикріплений співробітник. Містить наступні поля:
      • id — ідентифікатор клієнта
      • name — ім'я клієнта
      • responsible — користувач, відповідальний за батьківського клієнта. Містить наступні поля:
        • id — ідентифікатор користувача
        • name — ім'я користувача
        • ext_num — внутрішній номер АТС користувача

    Лід

    {
    "contact_type": "lead",
    "id": 3486,
    "name": "GoodCompany",
    "phone": {
      "phone": "+44123456789",
      "type": "work"
    },
    "responsible": {
      "id": 234,
      "name": "John Smith",
      "ext_num": "100"
    }
    }

    де

    • contact_type — тип контакта:
      • lead — лід
    • id — ідентифікатор ліда
    • name — ім'я ліда
    • phone — номер телефону. Містить наступні поля:
      • phone — безпосередньо номер
      • type — тип номеру. Можливі значення:
        • work — робочий
        • personal — особистий
    • responsible — відповідальний користувач. Містить наступні поля:
      • id — ідентифікатор користувача
      • name — ім'я користувача
      • ext_num — внутрішній номер АТС користувача

    Користувач

    {
        "contact_type": "user",
        "id": 234,
        "name": "John Smith",
        "avatar": 2457,
        "role": "",
        "status": "",
        "phone": {
          "phone": "100",
          "type": "internal"
        },
        "group": {
          "type": "admin",
          "title": ""
        }
      }

    де

    • contact_type — тип контакту:
      • user — користувач
    • id — ідентифікатор користувача
    • name — ім'я користувача
    • avatar — аватар користувача (ідентифікатор файлу)
    • role — роль користувача
    • status — статус користувача
    • phone — номер телефону. Містить наступні поля:
      • phone — безпосередньо номер
      • type — тип номеру. Можливі значення:
        • work — робочий
        • personal — особистий
        • internal — внутрішній номер АТС
    • group — група користувача. Містить наступні поля:
      • type — тип групи. Можливі значення:
        • admin — адміністратори
        • manager — менеджери
        • chat_operator — оператори
        • trainee — стажери
        • custom — користувача
      • title — ім'я користувача групи (для type = custom)

GET /v1/zcrm/contacts/identify

Ідентифікує контакт (клієнта, співробітника, ліда, користувача) за номером телефону.

Параметри

  • phone — номер телефону

Відповідь

Відповідь буде залежати від типу знайденого контакту (клієнт, співробітник, лід, користувач).

Клієнт

{
  "contact_type": "customer",
  "id": 3486,
  "name": "GoodCompany",
  "status": "company",
  "type": "client",
  "phone": {
    "phone": "+44123456789",
    "type": "work"
  },
  "responsible": {
    "id": 234,
    "name": "Jim Beam",
    "ext_num": "100"
  }
}

де

  • contact_type — тип контакта:
    • customer — клієнт
  • id — ідентифікатор клієнта
  • name — ім'я клієнта
  • status — статус клієнта. Можливі значення:
    • individual — фіз. особа
    • company — компанія
  • type — тип клієнта. Можливі значення:
    • potential — потенційний клієнт
    • client — клієнт
    • reseller — реселлер
    • partner — партнер
  • phone — номер телефону. Містить наступні поля:
    • phone — безпосередньо номер
    • type — тип номеру. Можливі значення:
      • work — робочий
      • personal — особистий
  • responsible — відповідальний користувач. Містить наступні поля:
    • id — ідентифікатор користувача
    • name — ім'я користувача
    • ext_num — внутрішній номер АТС користувача

Співробітник клієнта

{
  "contact_type": "employee",
  "id": 8,
  "name": "John Smith",
  "phone": {
    "phone": "+44123456789",
    "type": "work"
  },
  "position": {
    "position": "manager",
    "title": ""
  },
  "customer": {
    "id": 3486,
    "name": "GoodCompany"
  },
  "responsible": {
    "id": 234,
    "name": "Jim Beam",
    "ext_num": "100"
  }
}

де

  • contact_type — тип контакта:
    • employee — співробітник
  • id — ідентифікатор співробітника
  • name — ім'я співробітника
  • phone — номер телефону. Містить наступні поля:
    • phone — безпосередньо номер
    • type — тип номеру. Можливі значення:
      • work — робочий
      • personal — особистий
  • position — посада співробітника. Містить наступні поля:
    • position — значення посади. Можливі значення:
      • ceo — ген. директор
      • director — директор
      • manager — менеджер
      • sales_manager — менеджер з продажів
      • hr — HR
      • support — підтримка
      • custom — довільна
    • title — найменування довільної посади (для position = custom)
  • customer — клієнт, до якого прикріплений співробітник. Містить наступні поля:
    • id — ідентифікатор клієнта
    • name — ім'я клієнта
  • responsible — користувач, відповідальний за батьківського клієнта. Містить наступні поля:
    • id — ідентифікатор користувача
    • name — ім'я пользователя
    • ext_num — внутрішній номер АТС користувача

Лід

{
  "contact_type": "lead",
  "id": 3486,
  "name": "GoodCompany",
  "phone": {
    "phone": "+44123456789",
    "type": "work"
  },
  "responsible": {
    "id": 234,
    "name": "Jim Beam",
    "ext_num": "100"
  }
}

де

  • contact_type — тип контакта:
    • lead — лід
  • id — ідентифікатор ліда
  • name — ім'я ліда
  • phone — номер телефону. Містить наступні поля:
    • phone — безпосередньо номер
    • type — тип номеру. Можливі значення:
      • work — робочий
      • personal — особистий
  • responsible — відповідальний користувач. Містить наступні поля:
    • id — ідентифікатор користувача
    • name — ім'я користувача
    • ext_num — внутрішній номер АТС користувача

Користувач

{
  "contact_type": "user",
  "id": 234,
  "name": "John Smith",
  "avatar": 2457,
  "role": "",
  "status": "",
  "phone": {
    "phone": "100",
    "type": "internal"
  },
  "group": {
    "type": "admin",
    "title": ""
  }
}

де

  • contact_type — тип контакту:
    • user — користувач
  • id — ідентифікатор користувача
  • name — ім'я користувача
  • avatar — аватар користувача (ідентифікатор файлу)
  • role — роль користувача
  • status — статус користувача
  • phone — номер телефону. Містить наступні поля:
    • phone — безпосередньо номер
    • type — тип номеру. Можливі значення:
      • work — робочий
      • personal — особистий
      • internal — внутрішній номер АТС
  • group — група користувача. Містить наступні поля:
    • type — тип групи. Можливі значення:
      • admin — адміністратори
      • manager — менеджери
      • chat_operator — оператори
      • trainee — стажери
      • custom — користувача
    • title — ім'я користувача групи (для type = custom)

GET /v1/zcrm/files/<file_id>

Віддає файл за його ID.

Немає параметрів

 

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

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

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

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

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

  • 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 та NOTIFY_IVR можливо «на льоту» змінювати сценарій роботи за поточним дзвінком, відправивши у відповідь один з наступних варіантів:

Відтворити файл:

{
    "ivr_play": "ID"
}

де,

  • ivr_play – значення з колонки ID у списку завантажених/начитаних файлів для потрібного файлу.

Відтворити популярну фразу:

{
    "ivr_saypopular": 1,
    "language": "en"
}

де,

  • ivr_saypopular – номер фрази зі списку;

Відтворити цифри:

{
    "ivr_saydigits": "12",
    "language": "en"
}

Відтворити число (відповідно до правил складних числівників):

{
    "ivr_saynumber": "123",
    "language": "en"
}

де,

  • language може приймати одне зі значень: ru, ua, en, es, pl;

Якщо були вказані ivr_saydigits або ivr_saynumber, в наступній події NOTIFY_IVR буде додано параметр:

"ivr_saydigits": "COMPLETE" або "ivr_saynumber": "COMPLETE"

У кожному із зазначених запитів вище може бути присутнім запит введення цифр від абонента:

{
    "wait_dtmf": {
        "timeout": TIMEOUT,
        "attempts": ATTEMPTS,
        "maxdigits": MAXDIGITS,
        "name": NAME,
        "default": DEFAULT,
    }
}

де,

  • timeout - час очікування введення цифр в секундах;
  • attempts - кількість спроб набору цифри від абонента;
  • maxdigits - максимальна кількість цифр, введення яких чекати;
  • name - ім'я, яке буде повернуто у відповіді;
  • default - дія, якщо не було набрано жодної цифри. Можливі значення:
    • id сценарію редиректу (в форматі 0-1, де 0 - номер голосового меню, 1 - номер сценарію);
    • меню АТС в форматі 0-main, де 0 - це id меню;
    • внутрішній номер АТС (тризначний номер);
    • hangup - закінчити дзвінок.

У наступній події NOTIFY_IVR буде додатково вказано параметр:

{
  	"wait_dtmf": {
	    "name": NAME,
	    "digits": DIGITS,
	    "default_behaviour": "1"
    }
}

де,

  • name - ім'я, що вказано в попередній відповіді;
  • digits - цифри, введені абонентом;
  • default_behaviour - вказано, якщо абонент нічого не натиснув і спрацювала поведінка за замовчуванням;

Перевести дзвінок:

{
    "redirect": ID,
    "return_timeout": TIMEOUT (Необов'язково)
}

де,

  • redirect - id сценарію редиректу (в форматі 0-1, де 0 - номер голосового меню, 1 - номер сценарію); або в форматі 1, де 1 - номер сценарію (номер голосового меню в цьому випадку 0); або меню АТС в форматі 0-main, де 0 - це id меню; або внутрішній номер АТС (тризначний номер); або "blacklist" - в цьому випадку дзвінок буде відхилено із сигналом зайнято ;
  • return_timeout - Значення в секундах. Можливі значення:
    • 0, дзвінок не повернеться на меню;
    • >= 3 - тривалість дзвінка внутрішнього номеру, перш ніж дзвінок повернеться на меню
  • default_behaviour - вказано, якщо абонент нічого не натиснув і спрацювала поведінка за замовчуванням;

Завершити дзвінок:

{
    "hangup": 1
}

У кожній з відповідей можна додатково вказати:

Задати ім'я для імені вхідного номеру:

{
	"caller_name": NAME
}

де,

  • caller_name - ім'я номеру.

Списки популярних фраз:

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

  • 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' - перевищено ліміт;
  • last_internal – внутрішній номер, останній учасник дзвінка (після трансферу або перехоплення);
  • 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));

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

  • event – подія (NOTIFY_IVR)
  • 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

Задати посилання за яким можливо буде повідомляти, а також вмикати / вимикати кожен вид повідомлень, зробити це можливо в розділі 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
    інформацію про дзвінки на номери, які підключені до коллтрекінгу.
  • SMS
    інформацію про вхідні SMS.

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

  • 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;
    • url - адреса сторінки, з якої був дзвінок;
    • utm_source, utm_medium, utm_campaign, utm_term, utm_content - (опціонально, якщо при переході на сайт були вказані utm мітки) utm мітки, за якими відвідувач перейшов на сайт востаннє;
    • first_utm - (опціонально, якщо при першому переході на сайт були вказані utm мітки, відмінні від тих, за якими був зроблений перехід в останній раз) масив з utm мітками зазначеними вище, за якими відвідувач перейшов на сайт у перший раз;

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

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

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

  • event – подія (SMS)
  • result – масив;
  • caller_id – номер відправника;
  • caller_did – номер отримувача;
  • text – текст повідомлення.

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

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