Zadarma: API від Zadarma

Приклади роботи з API

В API доступні всі основні функції для роботи з:

Телефонія і віртуальні номери
АТС та Teamsale CRM
SMS та HLR-запити
Колтрекінг
Розпізнавання мови

Авторизація

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

"Authorization: ключ_користувача: підпис"

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

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

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

                                    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.

Заголовок Content-Type для POST запитів повинен бути application/x-www-form-urlencoded або multipart/form-data.

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

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

Обмеження

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

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

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

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 запитів в хвилину, на методи статистики - 3 запити в хвилину.

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

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

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

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

Увага: якщо постійно потрібна актуальна статистика АТС, не потрібно робити кожну хвилину запит методу statistics/pbx/. Увімкніть повідомлення webhooks та отримуйте інформацію про кожен дзвінок у момент його початку та закінчення.

Info

get /v1/info/balance/

баланс користувача

                                    {
    "status":"success", 
    "balance":10.34, 
    "currency":"USD"
}

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

get /v1/info/price/

вартість дзвінка з урахуванням поточного тарифу користувача

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

Параметри:

number – номер телефону;
caller_id (опционально) – CallerID, який буде використовуватися при здійсненні дзвінка.

get /v1/info/timezone/

часовий пояс користувача

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

get /v1/tariff/

інформація про поточний тариф користувача

                                    {
    "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 – кількість використаних секунд тарифу на стаціонарні телефони;
used_seconds_speech_recognition – кількість використаних секунд тарифу на розпізнавання мови;
tariff_id_for_next_period – ID тарифу користувача на наступний період;
tariff_for_next_period – найменування тарифу користувача на наступний період.

get /v1/request/callback/

callback

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

Параметри:

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

get /v1/request/checknumber/

підтвердження номеру

                                    {
    "status":"success",
    "from":442037691880,
    "to":442037691881,
    "lang":"fr",
    "time":1612779278
}

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

Параметри

caller_id - номер, що відображається при дзвінку, доступні тільки номери, придбані в Zadarma,
to - номер телефону або SIP, якому телефонують,
code - код, який буде відтворюватися. Тільки цифри і довжина не більше 20 символів,
lang - мова начитки. При відсутності - береться з особистого кабінету клієнта, перевіряється на наявність у мовах системи.

post /v1/info/number_lookup/

актуалізація контактів

Параметри:

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

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

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

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

(Відповідь 1)

                                    Відповідь 1:
{
    "status":"success",
    "info":{
        "mcc":"24702",
        "mnc":"02",
        "mccName":"Latvia",
        "mncName":"Tele2",
        "ported":false,
        "roaming":false,
        "errorDescription":"No Error"
    }
}

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

(Відповідь 2)

                                    Відповідь 2:
{
    "status":"success"
}

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

(Відповідь 3)

                                    Відповідь 3:
{
    "success":true,
    "description":"Success",
    "result": [
        {
            "mcc":"24702",
            "mnc":"02",
            "ported":false,
            "roaming":false,
            "errorDescription":"No Error",
            "mccName":"Latvia",
            "mncName":"Tele2",
            "number":"3712812858",
        }, ...
    ]
}

get /v1/info/lists/currencies/

Список валют

                                    {
    "status": "success",
    "currencies": [
        "USD",
        "EUR",
        "GBP",
        "PLN"
    ]
}

get /v1/info/lists/languages/

Список доступних мов в особистому кабінеті

                                    {
    "status": "success",
    "languages": [
        "en",
        "es",
        "de",
        "pl",
        "ru",
        "ua",
        "fr"
    ]
}

get /v1/info/lists/tariffs/

Список тарифів

                                    {
    "status": "success",
    "currency": "EUR",
    "tariffs": [
        {
            "tariff_id": 5,
            "name": "Standard",
            "cost": 0,
            "days": "30"
        },
        ...
    ],
    "package_tariffs": [
        {
            "id": 1,
            "name": "EU",
            "tariffs": [
                {
                    "tariff_id": 23,
                    "name": "Office",
                    "cost": 22,
                    "cost_annual": 216
                },
                ...
            ]
        },
        ...
    ]
}

Параметри:

currency – валюта

SIP

get /v1/sip/

список SIP-номерів користувача

                                    {
    "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).

get /v1/sip/<SIP>/status/

online-статус SIP-номерів користувача

                                    {
    "status":"success",
    "sip":"00001",
    "is_online":"false"
}

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

put /v1/sip/callerid/

зміна CallerID

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

get /v1/sip/redirection/

відображення поточних переадресацій за SIP-номерами користувача

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

Параметри:

id – (опціональний) вибір конкретного SIP id.

де

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

put /v1/sip/redirection/

включення / вимикання переадресації за номером SIP

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

put /v1/sip/redirection/

зміна параметрів переадресації

                                    {
    "status":"success",
    "sip":"00001",
    "destination":"442037691880"
}

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

Параметри:

id – SIP id;
type – тип переадресації: phone – на телефон;
number – номер телефону.
condition – необов'язковий параметр, умова переадресації (always - завжди, unavailable - у разі не підняття слухавки або відсутності SIP-з'єднання)

post /v1/sip/create/

Створення SIP номеру

                                    {
    "status": "success",
    "sip": "123456"
}

Параметры

name - ім'я, що відображається;
password - пароль;
callerid - номер для CallerID;
redirect_to_phone - необов'язковий параметр, переадресація SIP на телефон;
user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені.

put /v1/sip/<SIP>/password/

Зміна паролю на SIP

Параметри

                                    {
    "status":"success",
    "sip":$sip,
}

value - новий пароль;
user_id - необов'язковий параметр, доступний для використання тільки дилерам та тільки для тих користувачів, які ними створені.

Статистика

get /v1/statistics/

отримання загальної статистики

(Відповідь 1)

                                    Відповідь 1:
{
    "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"
        },
        …
    ]
}

                                    Відповідь 1:
<?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>

Параметри:

start - дата початку перегляду статистики(формат - YYYY-MM-DD HH:MM:SS);
end - дата завершення перегляду статистики (формат - YYYY-MM-DD HH:MM:SS);
sip (опціонально) - фільтр за певним SIP-номером;
cost_only (опціонально) - перегляд тільки витрачених коштів за період;
skip (опціонально - не враховується при заданому параметрі cost_only) - кількість рядків, які необхідно пропустити у вибірці перед початком запиту (використовується для пагінації спільно з параметром limit, за замовчуванням дорівнює 0);
type (опціонально - не враховується при заданому параметрі cost_only) - обмеження на кількість виведених рядків (використовується для пагінації спільно з параметром skip, максимальне значення 1000, за замовчуванням 1000).

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

?type=cost_only:

(Відповідь 2)

                                    Відповідь 2:
{
    "status":"success",
    "start":"2015-06-01 00:00:00",
    "end":"2015-06-29 14:03:57",
    "stats":[
        {
            "cost":38.094,
            "currency":"USD",
            "seconds":9785
        }
    ]
}

                                    Відповідь 2:
<?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' - без відповіді,
- 'call failed' - не вдався,
- 'no money' - немає коштів, перевищено ліміт,
- 'unallocated number' - номер не існує,
- 'no limit' - перевищено ліміт,
- 'no day limit' - перевищено денний ліміт,
- 'line limit' - перевищено ліміт ліній,
- 'no money, no limit' - перевищено ліміт;
billseconds – кількість секунд дзвінка;
cost – вартість хвилини дзвінка за цим напрямком;
billcost – вартість оплачених хвилин;
currency – валюта вартості;
from – з якого номера телефонували;
to – куди дзвонили.

get /v1/statistics/pbx/

статистика по АТС

Увага: якщо постійно потрібна актуальна статистика АТС, не потрібно робити кожну хвилину запит методу statistics/pbx/. Увімкніть повідомлення webhooks та отримуйте інформацію про кожен дзвінок у момент його початку та закінчення.

                                    {
    "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 - дата початку перегляду статистики (формат - 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' для вихідних). Якщо не вказано, виводяться всі дзвінки.

де

start – дата початку відображення статистики;
end – дата завершення відображення статистики;
version - формат виведення статистики (2 - новий, 1 - старий);
call_id – унікальний id дзвінка, цей id вказано в назві файлу із записом розмови (унікальний для кожного запису в статистиці);
sip – SIP-номер;
callstart – час початку дзвінка;
clid – CallerID;
destination – куди дзвонили;
disposition – стан дзвінка:
- 'answered' – розмова,
- 'busy' – зайнято,
- 'cancel' - скасовано,
- 'no answer' - без відповіді,
- 'call 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 і т.д., відображається в статистиці і повідомленнях);

get /v1/statistics/callback_widget/

статистика за віджетом зворотнього дзвінка

                                    {
    "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 - дата початку перегляду статистики (формат - YYYY-MM-DD HH:MM:SS);
end - дата завершення перегляду статистики (формат - YYYY-MM-DD HH:MM:SS);
widget_id - (опціонально) - ідентифікатор віджету, в разі відсутності параметра береться статистика за всіма віджетами;

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

Максимальна кількість виведених рядків для одного запиту - 1000. Для пагінації використовуйте параметри skip і limit.

де

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').

get /v1/statistics/incoming-calls/

отримання загальної статистики вхідних викликів

                                    {
    "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,
            "billseconds":0,
            "disposition":"busy",
            "description":"United Kingdom, London"
        },
        …
    ]
}

                                    <?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>
            <from>442037691880</from>
            <to>442037691881</to>
            <billseconds>0</billseconds>
            <disposition>busy</disposition>
            <description>United Kingdom, London</description>
        </value>
        …
    </stats>
</answer>

Параметри

start - дата початку перегляду статистики (формат - YYYY-MM-DD HH:MM:SS);
end - дата закінчення перегляду статистики (формат - YYYY-MM-DD HH:MM:SS);
sip (опціонально) - фильтр по определенному SIP-номеру;
skip (опціонально - не враховується при заданому параметрі cost_only) - кількість рядків, яке необхідно пропустити в вибірці, виведення почнеться з рядка skip + 1 (використовується для пагінації спільно з параметром limit, за замовчуванням дорівнює 0);
limit (опціонально - не враховується при заданому параметрі cost_only) - обмеження на кількість виведених рядків (використовується для пагінації спільно з параметром skip, максимальне значення 1000, за замовчуванням 1000).

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

Максимальна кількість виведених рядків для одного запиту - 1000. Для пагінації використовуйте параметри skip та limit.

Де:

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

АТС

post /v1/pbx/redirection/

зміна параметрів переадресації на внутрішній номер АТС

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

get /v1/pbx/redirection/

отримання параметрів переадресації на внутрішній номер АТС

                                    {
    "status":"success",
    "current_status":"on",
    "pbx_id":"1234",
    "pbx_name":"100",
    "type":"phone",
    "destination":"79123456789",
    "condition":"noanswer",
}

Параметри:

pbx_number – внутрішній номер АТС, наприклад 100;

get /v1/pbx/record/request/

запит на файл запису розмови

Параметри:

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

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

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

(Відповідь 1)

                                    Відповідь 1:
{
    "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"
}

                                    Відповідь 1:
<?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, посилань може бути декілька:

(Відповідь 2)

                                    Відповідь 2:
{
    "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"
}

                                    Відповідь 2:
<?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 – до якого часу посилання буде працювати.

post /v1/pbx/waitmelody/upload

завантаження мелодії

Параметри

file - сам файл

put /v1/pbx/waitmelody/switch

увімк/вимк мелодію для АТС

Параметри

state - стан (on - увімк, off - вимк);
melody - тип мелодії (none - за замовчуванням без мелодії, mymelody - раніше завантажена мелодія користувача)

delete /v1/pbx/waitmelody/delete

видалення мелодії

get /v1/pbx/callinfo/

отримати налаштування pbx call info

                                    {
    "status": "success",
    "url": "",
    "notifications": {
        "notify_start": "true",
        "notify_internal": "false",
        "notify_end": "true",
        "notify_out_start": "false",
        "notify_out_end": "false",
        "notify_answer": "false"
    }
}

Параметри:

user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені.

post /v1/pbx/callinfo/url/

зміна url для pbx call info

                                    {
    "status": "success",
    "url": ""
}

Параметри:

url - посилання;
user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені.

post /v1/pbx/callinfo/notifications/

зміна реакції на події NOTIFY_* для pbx call info

                                    {
    "status": "success",
    "notifications": {
        "notify_start": "true",
        "notify_internal": "false",
        "notify_end": "true",
        "notify_out_start": "false",
        "notify_out_end": "false",
        "notify_answer": "false"
    }
}

Параметри:

user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені;
notify_start - "true" або "false" необов'язковий параметр;
notify_internal - "true" або "false" необов'язковий параметр;
notify_end - "true" або "false" необов'язковий параметр;
notify_out_start - "true" або "false" необов'язковий параметр;
notify_out_end - "true" або "false" необов'язковий параметр;
notify_answer - "true" або "false" необов'язковий параметр.

delete /v1/pbx/callinfo/url/

видалення url для pbx call info

                                    {
    "status": "success",
    "url": ""
}

Параметри:

user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені.

post /v1/pbx/create/

створення АТС

                                    {
    "status": "success",
    "stop_datetime": "2021-12-31 23:59:59"
}

Параметри:

sip_id - SIP номер для прив'язки АТС, якщо не заданий спробує вибрати вільний SIP (необов'язковий параметр);
password - пароль для першого номера АТС '100';
user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені.

get /v1/pbx/webhooks/

отримати налаштування pbx webhooks

                                    {
    "status": "success",
    "url": "",
    "hooks": {
        "number_lookup": "true",
        "call_tracking": "false",
        "sms": "true",
        "speech_recognition": "true"
    }
}

Параметри:

user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені.

post /v1/pbx/webhooks/url/

зміна url для pbx webhooks

                                    {
    "status": "success",
    "url": ""
}

Параметри:

user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені;
url - посилання на ваш скрипт, з кодом перевірки <?php if (isset($_GET['zd_echo'])) exit($_GET['zd_echo']); ?> на початку скрипта.

post /v1/pbx/webhooks/hooks/

зміна реакції на події для інших повідомлень (Актуалізація контактів, Коллтрекінг, СМС і Аналітика розмов)

                                    {
    "status": "success",
    "hooks": {
        "number_lookup": "true",
        "call_tracking": "false",
        "sms": "true",
        "speech_recognition": "true"
    }
}

Параметри:

user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені;
number_lookup - "true" або "false" необов'язковий параметр;
call_tracking - "true" або "false" необов'язковий параметр;
sms - "true" або "false" необов'язковий параметр;
speech_recognition - "true" або "false" необов'язковий параметр.

delete /v1/pbx/webhooks/url/

видалення url для інших повідомлень (Актуалізація контактів, Коллтрекінг, СМС і Аналітика розмов)

                                    {
    "status": "success",
    "url": ""
}

Параметри:

user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені.

АТС (внутрішні номери)

get /v1/pbx/internal/

відображення внутрішніх номерів АТС

                                    {
    "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 – список внутрішніх номерів.

get /v1/pbx/internal/<PBXSIP>/status/

online-статус внутрішнього номеру АТС

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

де

pbx_id – АТС-id;
number – внутрішній номер АТС;
is_online – online-статус (true|false).

get /v1/pbx/internal/<PBXSIP>/info/

інформація про внутрішній номер АТС

                                    {
    "status": "success",
    "pbx_id": 12345,
    "number": 100,
    "name": "Extension 100",
    "caller_id": "+44000000000",
    "caller_id_app_change": "true",
    "caller_id_by_direction": "false",
    "lines": "3",
    "ip_restriction": "1.1.1.1",
    "record_store": "For automatic speech recognition",
    "record_email": "email@server.com",
    "supervisor_status": 1
}

                                    <?xml version="1.0"?>
<answer>
    <status>success</status>
    <pbx_id>12345</pbx_id>
    <number>100</number>
    <name>Extension 100</name>
    <caller_id>+44000000000</caller_id>
    <caller_id_app_change>true</caller_id_app_change>
    <caller_id_by_direction>false</caller_id_by_direction>
    <lines>3</lines>
    <ip_restriction>1.1.1.1</ip_restriction>
    <record_store>For automatic speech recognition</record_store>
    <record_email>email@server.com</record_email>
   <supervisor_status>1</supervisor_status>
</answer>

де:

pbx_id – атс-id;
number – внутрішній номер АТС;
name – ім'я, що відображається;
caller_id – CallerID;
caller_id_app_change – зміна CallerID з додатку (true|false);
caller_id_by_direction – CallerID за напрямком (true|false);
lines – кількість ліній;
ip_restriction – обмеження доступу за ip (false якщо не задано);
record_store – запис розмов до хмари (Without recognition|For manual recognition|For automatic speech recognition|false);
record_email – email для відправки записів розмов (false якщо не включено).

put /v1/pbx/internal/recording/

увімкнення запису розмов на внутрішньому номері АТС

                                    {
    "status":"success",
    "internal_number":100,
    "recording":"on",
    "email":"test@test.com",
    "speech_recognition":"all"
}

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

Параметри:

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

post /v1/pbx/internal/create/

створення номеру АТС

                                    {
    "status": "success",
    "numbers": [
        {
            "number": 200,
            "password": "PASSWORD"
        },
        {
            "number": 201,
            "password": "PASSWORD"
        }
    ]
}

Параметри:

user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені;
start_number - номер з якого почати створення 100 ...999 або "any" почати з будь-якого першого доступного номера в рамках діапазону 100-999;
quantity - кількість номерів, що створюється;
return_password - необов'язковий параметр, якщо 'true' у відповіді будуть паролі для новостворених номерів.

get /v1/pbx/internal/<SIP>/password/

запит пароля внутрішнього номеру АТС, пароль доступний для перегляду обмежений час

Параметри:

user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені.

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

                                    {
    "status": "success",
    "pbx_id": 114,
    "number": 200,
    "password": "PASSWORD"
}

де

password - може приймати значення hidden, якщо пароль не доступний для перегляда.

put /v1/pbx/internal/<SIP>/password/

зміна пароля на внутрішньому номері

                                    {
    "status": "success",
    "pbx_id": 114,
    "number": 200
}

Параметри:

value - новий пароль;
user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені.

put /v1/pbx/internal/<SIP>/edit/

зміна внутрішнього номеру АТС

Параметри

supervisor_status - статус супервізора, 0 - вимкнений, 1 - включений;
user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені.

АТС (IVR)

get /v1/pbx/ivr/sounds/list

список файлів у сховищі АТС

post /v1/pbx/ivr/sounds/upload

завантаження файла

Параметри:

name - ім'я файла,
file - сам файл.

delete /v1/pbx/ivr/sounds/delete

видалення файла за айді

Параметри:

id - ідентифікатор файла

get /v1/pbx/ivr/

список IVR

                                    {
    "status": "success",
    "pbx_id": 114,
    "ivrs": [
        {
            "menu_id": "0",
            "title": "",
            "type": "file",
            "status": "on",
            "waitexten": 5,
            "auto_responder": {
                "status": "on",
                "waitexten": 1,
                "working_days": [
                    {
                        "day": "mon",
                        "is_active": true,
                        "begin": {
                            "hour": 9,
                            "minute": 0
                        },
                        "end": {
                            "hour": 18,
                            "minute": 0
                        }
                    },
                    {
                        "day": "tue",
                        "is_active": true,
                        "begin": {
                            "hour": 9,
                            "minute": 0
                        },
                        "end": {
                            "hour": 18,
                            "minute": 0
                        }
                    },
                    ...
                    {
                        "day": "sun",
                        "is_active": false
                    }
                ]
            },
            "dinner_status": "on",
            "dinner_time": {
                "begin": {
                    "hour": 12,
                    "minute": 0
                },
                "end": {
                    "hour": 13,
                    "minute": 0
                }
            }
        },
        {
            "menu_id": "1",
            "title": "Menu 1",
            "type": "readtext",
            "status": "off",
            "waitexten": 5,
            "auto_responder": {
                "status": "off",
                "waitexten": 1
            }
        },
        ...
    ]
}

Параметри:

user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені.

post /v1/pbx/ivr/create/

створити IVR

                                    {
    "status": "success",
    "menu_id": 2
}

Параметриы:

user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені;
buy - 'true' - платне створення меню.

delete /v1/pbx/ivr/delete/

видалення IVR

                                    {
    "status": "success"
}

Параметри:

user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені;
menu_id - повинно бути > 0.

get /v1/pbx/ivr/scenario/

список сценаріїв IVR

                                    {
    "status": "success",
    "scenarios": [
        {
            "id": "132",
            "title": "-1",
            "push_button": -1,
            "first_sips": [
                "102"
            ],
            "second_sips": [],
            "second_sips_delay": 10,
            "third_sips": [],
            "third_sips_delay": 20
        },
        ...
    ]
}

Параметри:

user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені;
menu_id - ID меню/IVR.

post /v1/pbx/ivr/scenario/create/

створення сценарія IVR

                                    {
    "status": "success",
    "menu_id": 0,
    "scenario_id": 2
}

Параметри:

push_button - спрацьовування сценарію при натисканні кнопки: якщо абонент натискає кнопку спрацьовує сценарій без натискання, 0-9 - кнопки, 10 - автовідповідач, 11-30 - додаткові сценарії;
title - назва;
extension - внутрішній номер, або номери через пробіл, або "fax";
menu_id - ID меню/IVR;
user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені;
trigger_to_did_ext_lines - необов'язковий параметр. Вказує при дзвінках, на які номери спрацьовує сценарій. Може містити номер або список номерів через пробіл;
trigger_from_clid_numbers - необов'язковий параметр. Вказує при дзвінках із яких номерів спрацьовує сценарій. Може містити номер або список номерів через пробіл.

put /v1/pbx/ivr/scenario/edit/

зміна сценарію IVR

Тіло PUT запиту:

(Відповідь 1)

                                    Відповідь 1:
[
  "id": "630cb6b3dc666e947503a77a",
  "title": "Scenario 1",
  "queue_strategy": "off",
  "queue_announce_position": 0,
  "numbers": [
    [
      "number": 100,
      "delay": 0,
      "duration": 20
    ],
    [
      "number": 101,
      "delay": 20,
      "duration": 20
    ],
    [
      "number": 102,
      "delay": 40,
      "duration": 20
    ],
  ]
]

Опис:

id - ID сценарію;
title - назва;
queue_strategy - стратегія розподілення викликів за внутрішніми номерами в черзі (off, random, roundrobin, leastrecent, rrmemory, fewestcalls)
queue_announce_position - повідомляти номер в черзі
numbers - масив внутрішніх номерів
- параметри затримки та тривалості обдзвону внутрішнього номеру:
- number - внутрішній номер або "fax";
- delay - затримка обдзвону в секундах
- duration - тривалость обдзвону в секундах

Опис стратегій розподілення викликів за внутрішніми номерами в черзі:

off - черга вимкнена
random - розподіляти випадково
roundrobin - розподіляти рівномірно, віддавати пріоритет хто давно не розмовляв, враховувати усі дзвінки
leastrecent - розподіляти рівномірно, віддавати пріоритет хто давно не розмовляв, враховувати тільки дзвінкі із відповіддю
rrmemory - розподіляти рівномірно, віддавати пріоритет хто менше розмовляв, враховувати усі дзвінки
fewestcalls - розподіляти рівномірно, віддавати пріоритет хто менше розмовляв, враховувати тільки дзвінкі із відповіддю

Параметри затримки та тривалості обдзвону внутрішніх номерів використовуються тільки з вимкненою чергою (queue_strategy : "off").

Відповідь: (Відповідь 2)

                                    Відповідь 2:

{"status": "success"}

Помилка: (Відповідь 3)

                                    Відповідь 3:

{"status": "error","message": "Wrong parameters!"}

delete /v1/pbx/ivr/scenario/delete/

видалення сценарію IVR

                                    {
    "status": "success"
}

Параметри:

scenario_id - ID сценарія;
user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені.

Розпізнавання мови

get /v1/speech_recognition/

отримання результатів розпізнавання

                                    {        
    "status":"success",
    "lang":"en-EN",
    "recognitionStatus":"in progress",
    "otherLangs":["es-ES"],
    "words": [
        {
            "result": [
                {
                    "s": 0.02,
                    "e": 0.22,
                    "w": "word",
                },
                {
                    "s": 0.31,
                    "e": 0.56,
                    "w": "one",
                }
            ],
            "channel": 1
        }
    ],
    "phrases":[
        {
            "result": "word one",
            "channel": 1
        }
    ]
}

Параметри:

call_id – унiкальний id дзвiнка, цей id вказано в назві файлу із записом розмови (унікальний для кожного запису в статистиці);
lang - мова розпізнавання (не обов'язково);
return - результат, що повертається. Варіанти: words - слова, phrases - фрази. (не обов'язково. за замовчуванням phrases);
alternatives - чи повертати альтернативні варіанти. Варіанти: 0 - нi, 1 - так. (не обов'язково. за замовчуванням 0).

де

lang – мова;
recognitionStatus: статус розпізнавання. Варіанти:
- in progress - в процесі розпізнавання,
- error - при розпізнаванні виникла помилка,
- recognized - розпізнано
- ready for recognize - запис готовий для розпізнавання,
- not available for recognize - запис недоступний для розпізнавання.
result:
- words - масив:
  - result - список слів (масив):
    - s - час початку слова
    - e - час закiнчення слова
    - w - слово
  - channel - номер каналу
- phrases - масив:
  - result - фраза
  - channel - номер каналу

put /v1/speech_recognition/

запуск розпізнавання дзвінка в статистиці АТС, попередньо має бути включено вибіркове розпізнавання в налаштуваннях внутрішнього номеру

                                    {
    "status":"success"
}

Параметри:

call_id – унікальний id дзвінка, цей id вказано в назві файлу із записом розмови (унікальний для кожного запису в статистиці);
lang - мова розпізнавання (не обов'язково).

Віртуальні номери

get /v1/direct_numbers/

інформація про віртуальні номери користувача

                                    {
    "status":"success",
    "info": [
        {
            "number":"442030000000",
            "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 – статус номеру;
on – номер увімкнений;
parking - номер вимкнений (не було оплати), але зберігається на акаунті 7 днів і може бути відновлений після поповнення рахунку;
- checking - номер замовлений, сплачений, усі необхідні документи завантажені, очікує активації;
- checking_upload - номер замовлений, сплачений, очікується завантаження необхідних документів;
- reserved_on - номер зарезервований до оплати;
- reserved_checking - номер зарезервований до оплати, усі необхідні документи завантажені;
- reserved_checking_upload - номер зарезервований до оплати, очікується завантаження документів;
country – країна;
description – опис: місто;
number_name – "ім'я" віртуального номеру (задається користувачем);
sip – SIP, прив'язаний до номера;
sip_name –"ім'я" SIP, прив'язаного до номеру;
start_date – дата придбання номера користувачем;
stop_date – дата закінчення терміну оплати номеру користувачем;
monthly_fee – вартість номеру;
currency – валюта вартості номеру;
channels – кількість ліній на номері;
minutes – загальна тривалість вхідних дзвінків за поточний місяць (для revenue);
autorenew – чи увімкнення автоподовження номеру;
is_on_test – чи знаходиться номер на тесті;
type – тип номеру: common (віртуальний номер), order (замовлений, але не підключенний номер)

get /v1/direct_numbers/number/

інформація про куплений номер

                                    {
    "status": "success",
    "info": {
    "number": "35924913550",
        "status": "on",
        "country": "Bulgaria",
        "description": "Sofia",
        "number_name": "TT",
        "sip": "00004",
        "sip_name": "SIP",
        "start_date": "2016-06-08 14:32:17",
        "stop_date": "2016-06-29 10:52:18",
        "monthly_fee": 2,
        "currency": "USD",
        "channels": "2",
        "autorenew": "true",
        "receive_sms": null,
        "is_on_test": "false"
    }
}

Параметри

number - номер.

get /v1/direct_numbers/autoprolongation/

статус автоподовження

                                    {
    "status": "success",
    "number": "35924913550",
    "autoprolongation": "on"
}

Параметри

number - номер.

get /v1/direct_numbers/checking-wrongs/

отримання інформації про помилки перевірки документів або адреси

                                    {
   "status":"success",
   "info":{
      "wrong_document":{
         "document_type":"contract",
         "message":"The passport has expired. It is considered invalid."
      },
      "wrong_address":{
         "message":"Invalid address"
      }
   }
}

Параметри

group_id - id групи документів.

put /v1/direct_numbers/autoprolongation/

змінити статус автоподовження

                                    {
    "status": "success",
    "number": "35924913550",
    "autoprolongation": "off"
}

Параметри:

number - номер.
value - новий статус автоматичного подовження, on або off.

get /v1/direct_numbers/countries/

список країн, в яких можна замовити номер

                                    {
    "status": "success",
    "info": [
        {
            "countryCode": "61",
            "countryCodeIso": "AU",
            "name": "Australia"
        },
        ...
    ]
}

Параметри:

language - опціонально, якщо не задано видасть на мові особистого кабінету.

get /v1/direct_numbers/country/

список напрямків у країні, в яких можна замовити номер

                                    {
    "status": "success",
    "info": [
        {
            "id": "3753",
            "countryCode": "49",
            "areaCode": "800",
            "name": "800 number (Toll-free)",
            "connect_fee": 0,
            "monthly_fee": 15,
            "currency": "USD",
            "restrictions": {
                "upload": [
                    "Certificate of registration copy or passport or ID copy (both sides)",
                    "Proof of address (a copy of utility bill no older than of 6 months) - 
                    your current address (city, street, number and postal code). 
                    The address must be located in the country of ordered phone number"
                ]
            },
            "receive_sms": "false",
            "is_toll": "true",
            "feature": "Available from all networks"
            "connect_time": "0"
        },
        {
            "id": "3766",
            "countryCode": "49",
            "areaCode": "821",
            "name": "Augsburg",
            "connect_fee": 3,
            "monthly_fee": 3,
            "currency": "USD",
            "restrictions": {
                "upload": [
                    "Passport or ID copy (both sides)"
                ],
                "specify": [
                    "You current address (city, street, number and postal code). 
                    The address must be located in the region of the city 
                    where you ordered the phone number"
                ]
            },
            "receive_sms": "false",
            "is_toll": "false",
            "feature": null,
            "connect_time": "0"
        },
        ...
    ]
}

Параметри

language - опціонально, якщо не задано видасть на мові особистого кабінету;
country - iso код країни (ISO 3166-1 alpha-2).

put /v1/direct_numbers/set_caller_name/

встановлення Ім'я Номера (латиниця і цифри, до 30 знаків)

                                    {
    "status": "success",
    "number": "+44000000000",
    "caller_name": "test"
}

Параметри

number - номер;
caller_name - для того щоб прибрати - просто передати порожнє поле.

put /v1/direct_numbers/set_sip_id/

прив'язка номеру до sip або включення тестового режиму

                                    {
    "status": "success",
    "number": "+44000000000",
    "sip_id": "00001"
}

Параметри

number - номер;
sip_id - sip номер або адреса зовнішнього сервера (SIP URI);
test_mode - опціонально, (on|off) - для включення тестового режиму.

get /v1/direct_numbers/available/<DIRECTION_ID>/

номери, доступні для заказа

                                    {
    'status': 'success',
    'numbers': [
        {
            'id': 1712p0D1643D0t42r198658,
            'direction_id': 13755,
            'number': '+44000000001'
        },
        {
            'id': 184bdf85006c3f1676be200,
            'direction_id': 13755,
            'number': '+44000000000'
        },
        ...
    ]
}

Параметри:

DIRECTION_ID - ID напрямку;
mask - необов'язковий параметр, для пошуку збігів за номерами.

post /v1/direct_numbers/order/

заказ/придбання номеру

                                    {
    'status': 'success',
    'number': '+44000000000',
    'is_reserved': 'false',
    'is_activated': 'true'
}

Параметри:

number_id - ID номеру, що замовляється, отриманий методом GET /v1/direct_numbers/available/<DIRECTION_ID>/ наприклад: 1712p0D1643D0t42r198658 (якщо відсутній вибір номерів, параметр не використовується);
direction_id - ID напрямку/міста;
documents_group_id - ID групи документів користувача;
purpose - текстовий опис мети використання номеру (тільки якщо потрібно);
receive_sms - 1 - вмикання прийому SMS (тільки якщо номер підтримує прийом SMS);
period - 'month' - один місяць, '3month' - три місяці (необов'язковий параметр, прийом СМС активується на номерах, підключених мінімум на 3 місяці);
autorenew_period - необов'язковий параметр, період подовження (year, month), від нього залежить абонплата за номер, за замовчуванням month;
user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені.

post /v1/direct_numbers/prolong/

подовження номеру на довільну кількість місяців

                                    {
    'status': 'success',
    'number': '+44000000000',
    'stop_date': '2021-05-01 12:00:00',
    'total_paid': {
        'amount': 2,
        'currency': 'USD'
    }
}

Параметри:

number - номер, що подовжується;
months - кількість місяців;
user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені.

put /v1/direct_numbers/receive_sms/

увімкнення прийому SMS (лише якщо номер підтримує прийом SMS)

                                    {
    "status": "success", 
    "number": "", 
    "receive_sms": "on"
}

Параметри:

number - номер
value - значення (може бути "on" або "off")
documents_group_id - необов'язковий параметр, ID групи документів облікового запису
user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені

Групи документів

get /v1/documents/files

список файлів/документів в групі документів

                                    {
    "status": "success",
    "documents": [
        {
            "type": "passport",
            "is_verified": "true",
            "source": "upload",
            "name": "file1.jpg"
        },
        {
            "type": "receipt",
            "is_verified": "false",
            "source": "upload",
            "name": "file2.jpg"
        }
    ]
}

Параметри:

user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені;
group_id - необов'язковий параметр, ID групи документів, (0 або не вказано - основна група документів).

get /v1/documents/groups/list/

список груп документів

                                    {
    "status": "success",
    "groups": [
        {
            "id": 0,
            "email": "email@server.com",
            "salutation": 'MR',
            "nationality": null,
            "first_name": "John",
            "middle_name": "Richard",
            "last_name": "Smith",
            "organization": "Company",
            "organization_description": null,
            "organization_reg_number": null,
            "country": "DE",
            "region": "",
            "city": "Berlin",
            "address": "Brudden Strasse 8, 76611",
            "zip_code": '76611',
            "street": 'Brudden Strasse',
            "street_code": null,
            "municipality_code": null,
            "building_number": "8",
            "building_letter": null,
            "phone": "4900000000",
            "type_of_id": "",
            "id_number": "123000099",
            "issuing_authority": null,
            "issuing_date": null,
            "is_readonly": true
        }
    ]
}

Параметри:

user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені.

get /v1/documents/groups/get/<ID>/

дані по конкретній групі

                                    {
    "status": "success",
    "group": {
        "id": 0,
        "email": "email@server.com",
        "salutation": 'MR',
        "nationality": null,
        "first_name": "John",
        "middle_name": "Richard",
        "last_name": "Smith",
        "organization": "Company",
        "organization_description": null,
        "organization_reg_number": null,
        "country": "DE",
        "region": "",
        "city": "Berlin",
        "address": "Brudden Strasse 8, 76611",
        "zip_code": '76611',
        "street": 'Brudden Strasse',
        "street_code": null,
        "municipality_code": null,
        "building_number": "8",
        "building_letter": null,
        "phone": "4900000000",
        "type_of_id": "",
        "id_number": "123000099",
        "issuing_authority": null,
        "issuing_date": null,
        "is_readonly": true
    }            
}

Параметри:

ID - ID групи, 0 - основна група документів;
user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені

get /v1/documents/groups/valid/<ID>/

перевірка: чи підходить група документів для конкретного міста/напрямку

                                    {
    "status": "success",
    "is_information_match": "true",
    "is_documents_uploaded": "true",
    "is_documents_verified": "true",
    "is_address_match": "true"
}

Параметри:

ID - ID групи, 0 - основна група документів;
user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені
direction_id - ID напрямку/міста.

post /v1/documents/groups/create/

створення нової групи документів

                                    {
    "status": "success",
    "group": {
        "id": 0,
        "email": "email@server.com",
        "salutation": 'MR',
        "nationality": null,
        "first_name": "John",
        "middle_name": "Richard",
        "last_name": "Smith",
        "organization": "Company",
        "organization_description": null,
        "organization_reg_number": null,
        "country": "DE",
        "region": "",
        "city": "Berlin",
        "address": "Brudden Strasse 8, 76611",
        "zip_code": '76611',
        "street": 'Brudden Strasse',
        "street_code": null,
        "municipality_code": null,
        "building_number": "8",
        "building_letter": null,
        "phone": "4900000000",
        "type_of_id": "",
        "id_number": "123000099",
        "issuing_authority": null,
        "issuing_date": null,
        "is_readonly": true
    }            
}

Параметри:

user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені;
email - email адрес;
salutation - привітання 'MR', 'MS', 'COMPANY';
nationality - національність, код країни iso2;
first_name - ім'я;
middle_name - необов'язковий параметр, по-батькові;
last_name - прізвище;
date_of_birth - необов'язковий параметр, дата народження;
organization - необов'язковий параметр, назва організації/компанії;
organization_description - необов'язковий параметр, опис діяльності компанії;
organization_reg_number - необов'язковий параметр, реєстраційний номер компанії;
country - країна, код країни iso2;
region - необов'язковий параметр, область/регіон;
city - місто;
address - повна адреса;
zip_code - поштовий індекс;
street - вулиця;
street_code - необов'язковий параметр, код вулиці, тільки для Данії;
municipality_code - необов'язковий параметр, код муніципалітету, тільки для Данії;
building_number - номер дому;
building_letter - необов'язковий параметр, буква в номері будинку;
phone - контактний номер телефону;
type_of_id - необов'язковий параметр, тип документу: "PASSPORT", "DNI", "NIE", "RESIDENCE_PERMIT", "NATIONAL_ID_CARD", "BUSINESS_REGISTRATION";
id_number - необов'язковий параметр, номер документу;
issuing_authority - необов'язковий параметр, ким виданий документ;
issuing_date - необов'язковий параметр, дата видачі документа;
direction_id - необов'язковий параметр, ID напрямку/міста для перевірки відповідності.

put /v1/documents/groups/update/<GROUPID>/

оновлення даних групи документів

                                    {
    "status": "success",
    "group": {
        "id": 0,
        "email": "email@server.com",
        "salutation": 'MR',
        "nationality": null,
        "first_name": "John",
        "middle_name": "Richard",
        "last_name": "Smith",
        "organization": "Company",
        "organization_description": null,
        "organization_reg_number": null,
        "country": "DE",
        "region": "",
        "city": "Berlin",
        "address": "Brudden Strasse 8, 76611",
        "zip_code": '76611',
        "street": 'Brudden Strasse',
        "street_code": null,
        "municipality_code": null,
        "building_number": "8",
        "building_letter": null,
        "phone": "4900000000",
        "type_of_id": "",
        "id_number": "123000099",
        "issuing_authority": null,
        "issuing_date": null,
        "is_readonly": true
    }            
}

Параметри:

user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені
email - email адреса;
salutation - привітання 'MR', 'MS', 'COMPANY';
nationality - національність, код країни iso2;
first_name - ім'я;
middle_name - необов'язковий параметр, по-батькові;
last_name - прізвище;
date_of_birth - необов'язковий параметр, дата народження;
organization - необов'язковий параметр, назва організації/компанії;
organization_description - необов'язковий параметр, опис діяльності компанії;
organization_reg_number - необов'язковий параметр, реєстраційний номер компанії;
country - країна, код країни iso2;
region - необов'язковий параметр, область/регіон;
city - місто;
address - повна адреса;
zip_code - поштовий індекс;
street - вулиця;
street_code - необов'язковий параметр, код вулиці, тільки для Данії;
municipality_code - необов'язковий параметр, код муніципалітету, тільки для Данії;
building_number - номер дому;
building_letter - необов'язковий параметр, буква в номері будинку;
phone - контактний номер телефону;
type_of_id - необов'язковий параметр, тип документу: "PASSPORT", "DNI", "NIE", "RESIDENCE_PERMIT", "NATIONAL_ID_CARD", "BUSINESS_REGISTRATION";
id_number - необов'язковий параметр, номер документу;
issuing_authority - необов'язковий параметр, ким виданий документ;
issuing_date - необов'язковий параметр, дата видачі документа;
direction_id - необов'язковий параметр, ID напрямку/міста для перевірки відповідності.

post /v1/documents/upload/

завантаження файлу документа для групи документів

Параметри:

user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені;
group_id - ID групи, 0 - основна група документів;
document_type - тип документа: 'certificate', 'contract', 'company_letter', 'inn_ua', passport', 'phone_bill', 'photo_with_doc', 'photo_with_passport', 'receipt', 'driver_id_us_ca', 'driver_id_other';
file - uploaded file.

Приклад запиту:

                                    $zd = new \Zadarma_API_Test\Api(KEY, SECRET);
$zd->request(
    'documents/upload',
    [
        'group_id' => 0,
        'document_type' => 'passport',
        'file' => new CURLFile('passport.jpg', 'image/jpeg', 'passport.jpg')
    ],
    'post'
);

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

                                    {
    "status": "success",
    "message": "The File passport.jpg has been successfully uploaded to the website.",
    "doc_name": "passport.jpg"
}

Дилер

get /v1/reseller/account/info/

інформація про обліковий запис дилера

                                    {
    "status": "success",
    "balance": 123,
    "credit": 0,
    "currency": "USD",
    "reseller_fee": 10,
    "user_fee": 10
}

post /v1/reseller/account/money_transfer/

Переклад з балансу дилера на баланс пов'язаного облікового запису і назад

                                    {
    "status": "success",
    "user": {
        "balance": "62.0000",
        "currency": "EUR"
    },
    "reseller": {
        "balance": "94.825",
        "currency": "USD"
    }
}

Параметри

amount - сума;
currency - валюта;
type - напрямок переказу "to_reseller" и "to_user".

get /v1/reseller/users/phones/

Список номерів контактних телефонів користувача

                                    {
    "status": "success",
    "list": [
        {
            "id": 0,
            "number": "49025000897",
            "is_proved": false
        }
    ]
}

Параметри

user_id - id юзера;

post /v1/reseller/users/phones/add/

Додавання контактного номера телефону користувача

                                    {
    "status": "success",
    "id": 98,
    "number": "359000000001",
    "is_proved": true
}

Параметри

user_id - id юзера;
number - номер.

post /v1/reseller/users/phones/update/

Редагування контактного номера телефону користувача

                                    {
    "status": "success",
    "id": 99,
    "number": "359000000002",
    "is_proved": false
}

Параметри

user_id - id юзера;
id - ID номера, 0 - основний номер телефону профіля;
number - номер.

post /v1/reseller/users/phones/prove_by_sms

Запит на підтвердження контактного номера телефону користувача

                                    {
    "number": "359000000002",
    "status": "success",
    "message": "You were sent an SMS message with a code. Code is valid for 1 hour."
}

Параметри

user_id - id юзера;
number - номер;
confirm_number_reuse - підтвердження номеру, який використовується в іншому акаунті (необов'язковий параметр)

post /v1/reseller/users/phones/prove_by_callback

Запит на підтвердження контактного номера телефону користувача (буде здійснено дзвінок і при відповіді, абонент почує код підтвердження)

                                    {
    "number": "359000000002",
    "status": "success",
    "message": "You were sent an SMS message with a code. Code is valid for 1 hour."
}

Параметри:

user_id - обов'язковий параметр, id юзера;
number - обов'язковий параметр, подтверждаемый номер (в международном формате);
caller_id - номер, що відображаєтсья при дзвінку, доступні тільки номери, які підключени в системі;
language - мова начитування
sip_id - необов'язковий параметр, якщо не вказано, бере перший що попався SIP дилера;
confirm_number_reuse - необов'язковий параметр, підтвердження номеру, який використовується в іншому акаунті

post /v1/reseller/users/phones/confirm

Підтвердження контактного номеру кодом з СМС

                                    {
    "status": "success",
    "message": "Your number confirmed!",
    "number": "35900000019"
}

Параметри

user_id - id юзера;
number - номер.
code - код підтвердження.

post /v1/reseller/users/registration/new/

Реєстрація користувача

                                    {
    "status": "success",
    "user_id": 12345,
    "message": "You registered a new user in the system."
},{
    "status": "success",
    "message": "You registered a new user in the system. A registration confirmation link was sent to the email address you provided. To activate the account the user needs to click on that link, after which they can log in on the website."
},{
    "status": "success",
    "message": "You registered a new user in the system. A registration confirmation code was sent to the email address you provided. To activate the account the user needs to send code to you, after which you can confirm registration using API."
}

Параметри

email - электрона пошта клієнта;
first_name - ім'я клієнта ;
last_name - необов'язковий параметр;
middle_name - необов'язковий параметр;
organization - необов'язковий параметр;
country - ISO2 код країни;
city - місто клієнта;
address - необов'язковий параметр;
phone - необов'язковий параметр;
password - необов'язковий параметр;
tariff - ID тарифа (ID можливо отримати методом GET /v1/info/lists/tariffs/) ;
tariff_period - необов'язковий параметр, період тарифа month | year;
language - необов'язковий параметр, код мови, en;
currency - необов'язковий параметр, код валюти, USD;
promocode - необов'язковий параметр, промокод;
gmt - необов'язковий параметр, GMT;
id_card - необов'язковий параметр, номер документа ID card, passport.

post /v1/reseller/users/registration/confirm/

Підтвердження реєстрації користувача

                                    {
    "status": "success",
    "user_id": 12345
}

Параметри

code - код підтвердження реєстрації з листа, відправленого на пошту користувача;
email - email адреса.

get /v1/reseller/users/list/

Список користувачів дилера, що виводяться по-сторінково (50 шт)

                                    {
    "status": "success",
    "total": 205,
    "total_pages": 5,
    "page": 1,
    "users": [
        {
            "id": "1234",
            "email": "test@domain.com",
            "first_name": "Test",
            "last_name": "Test",
            "organization": "",
            "phone": "+44000000001",
            "created": "2021-01-26 14:21:04",
            "last_login": "2021-01-30 09:46:31",
            "balance": "0.4000",
            "currency": "GBP",
            "sips_count": "1",
            "is_active": true,
            "allow_topup": true,
            "allow_api_requests": true
        },
        ...
    ]
}

Параметри

page - номер сторінки.

get /v1/reseller/users/find/

Пошук одного облікового запису користувача за критерієм (одним з id, email, sip)

                                    {
    "status": "success",
    "user": {
        "id": "1234",
        "email": "test@domain.com",
        "first_name": "Test",
        "last_name": "Test",
        "organization": "",
        "phone": "+44000000001",
        "created": "2021-01-26 14:21:04",
        "last_login": "2021-01-30 09:46:31",
        "balance": "0.4000",
        "currency": "GBP",
        "sips_count": "1",
        "is_active": true,
        "allow_topup": true,
        "allow_api_requests": true
    }
}

Параметри

id - optional;
sip - optional;
email - optional.

post /v1/reseller/users/topup/

Переказ з балансу дилера на баланс облікового запису користувача

                                    {
    "status": "success",
    "user_topup": {
        "amount": 10,
        "currency": "GBP"
    },
    "reseller_withdraw": {
        "amount": 10,
        "currency": "GBP"
    }
}

Параметри

user_id - id користувача;
amount - сума;
currency - валюта.

get /v1/reseller/users/api_key/

Отримати поточні ключі доступу користувача до API

                                    {
    "status": "success",
    "user_id": 1234,
    "last_request_datetime": "2021-02-18 10:45:01",
    "allow_reset": true,
    "key": "hidden",
    "secret": "hidden"
},{
    "status": "success",
    "user_id": 1234,
    "last_request_datetime": "2021-02-26 15:59:50",
    "allow_reset": false,
    "key": "abscd",
    "secret": "12345"
}

Параметри

user_id - id користувача.

post /v1/reseller/users/api_key/

Отримати нові ключі доступу користувача до API

                                    {
    "status": "success",
    "user_id": 1234,
    "key": "abscd",
    "secret": "12345"
}

Параметри

user_id - id користувача.

SMS

post /v1/sms/send/

відправка SMS

                                    {
    "status":"success",
    "messages":1,
    "cost":0.24,
    "currency":"USD",
    "sms_detalization":[
        {
            "senderid":"xxxxxxxxxxx",
            "number":"1234567890",
            "cost":0.06
        }
    ],
    "denied_numbers":[
        {
            "number":"1234567890",
            "message":"The reason for the SMS not being sent to the number"
        }
    ]
}

                                    <?xml version="1.0"?>
<answer>
    <status>success</status>
    <value>
        <messages>1</messages>
        <cost>0.24</cost>
        <currency>1</currency>
        <sms_detalization>
            <value>
                <callerid>xxxxxxxxx</callerid>
                <number>1234567890</number>
                <cost>0.06</cost>
            </value>
        </sms_detalization>
        <denied_numbers>
            <value>
                <number>1234567890</number>
                <message>The reason for the SMS not being sent to the number</message>
            </value>
        </denied_numbers>
    </value>
</answer>

Параметри:

number – номер телефону, куди відправляти SMS (можна перерахувати кілька через кому);
message – повідомлення (стандартні обмеження за довжиною SMS, у разі перевищення ліміту - розбивається на кілька SMS);
sender – (опціональний) відправник SMS (віртуальний номер або текстовий) список доступних значень можна отримати методом GET /v1/sms/senderid/
language – (опціонально) мова шаблону SMS. Яущо не вказана, то використовується мова особистого кабінету облікового запису.

get /v1/sms/templates/

Отримання списку шаблонів для SMS

                                    {
"list": [
    {
        "cath_id":"1",
         "title":"The name of the template category",
        "templates": [
            {
                "id":"1",
                "text":"The template text with a variable {$var}"
            },
            {
                "id":"2",
                "text":"Second template text"
            },
        ]
    }
]
}

                                    <answer>
<list>
    <value>
        <cath_id>1</cath_id>
        <title>The name of the template category</title>
        <templates>
            <value>
                <id>1</id>
                <text>The template text with a variable {$var}</text>
            </value>
            <value>
                <id>2</id>
                <text>Second template text</text>
            </value>
        </templates>
    </value>
</list>
</answer>

Параметри

skip – (опціонально) кількість шаблонів, які пропустити перед початком вибірки, за замовчуванням 0;
limit – (опціонально) кількість шаблонів, які вивести (за замовчуванням 25, максимально 1000)
language – (опціонально) мова загальних шаблонів SMS. Якщо не вказана, то використовується мова особистого кабінету облікового запису.

get /v1/sms/senderid/

Отримати список допустимих SMS-відправників на заданий номер

                                    {
    "senders": ["Teamsale", "1234567890"]
}

                                    <answer>
	<senders>
		<value>1234567890</value>
		<value>Teamsale</value>
	</senders>
</answer>

Параметри

phones – номер телефону, для якого потрібно дізнатись список допустимих відправників.

Интеграция WebRTC виджета

get /v1/webrtc/get_key/

отримати ключ для webrtc-віджета. Час життя ключа - 72 години.

                                    {
    "status":"success",
    "key": YOUR_KEY
}

                                    <?xml version="1.0"?>
<answer>
    <status>success</status>
    <key>YOUR_KEY</key>
</answer>

Параметри:

sip – логін SIP'а або внутрішнього номера АТС.

post /v1/webrtc/create/

Створення інтеграції WebRTC віджета

                                    {
    "status": "success"
}

Параметри

user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені;
domain - доменне ім'я.

put /v1/webrtc/

Зміна налаштувань інтеграції WebRTC віджета

                                    {
    "status": "success"
}

Параметри

user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені;
shape - допустимі значення: 'square', 'rounded';
position - допустимі значення: 'top_left', 'top_right', 'bottom_right', 'bottom_left'.

get /v1/webrtc/

Дані інтеграції WebRTC віджета

                                    {
    "status": "success",
    "is_exists": true,
    "domains": [
        "test.domain.com"
    ],
    "settings": {
        "shape": "square",
        "position": "top_right"
    }
}

Параметри

user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені;

post /v1/webrtc/domain/

Додати домен до інтеграції WebRTC віджета

                                    {
   "status": "success"
}

Параметри

user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені;
domain - доменне ім'я.

delete /v1/webrtc/domain/

Видалення домена з інтеграції WebRTC віджета

                                    {
   "status": "success"
}

Параметры

user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені.;
domain - доменне ім'я.

delete /v1/webrtc/

Видалення інтеграції WebRTC віджета

                                    {
   "status": "success"
}

Параметры

user_id - необов'язковий параметр, доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені.

eSIM

get /v1/esim/devices/

Список підтримуваних пристроїв для eSIM

Опис вдалої відповіді (Відповідь 1)

                                    Відповідь 1:
{
    "status": "success",
    "devices": {
        "acer": [
            "ACER Swift 3",
            "ACER Swift 7"
        ],
        "asus": [
            "ASUS Mini Transformer T103HAF",
            "ASUS NovaGo TP370QL",
            "ASUS Vivobook Flip 14 TP401NA"
        ],
        "xiaomi": [
            "Xiaomi 12T Pro",
            "Xiaomi 13 Lite"
        ]
    }
}

devices (оbject[]) — список пристроїв, групованих за брендами

Опис відповіді у випадку внутрішньої помилки (Відповідь 2)

                                    Відповідь 2:
{
  "status": "error",
  "message": "Getting devices internal error"
}

message (string) — містить повідомлення про помилку

get /v1/esim/packages/

Список усіх доступних пакетів

Опис вдалої відповіді (Відповідь 1)

                                    Відповідь 1:
{
  "status": "success",
  "packages": [
    {
      "duration": 7,
      "countries": [
        {
          "iso2": "cn",
          "name": "China",
          "aliases": []
        }
      ],
      "networks": [
        {
          "iso2": "CN",
          "network": "China Unicom",
          "type": "LTE"
        }
      ],
      "region": null,
      "id": "1-cn-7days-1gb",
      "price": 5,
      "data": 1,
      "duration_unit": "days",
      "data_unit": "GB",
      "top_up": true,
      "kyc_verify": false,
      "activation_policy": "first-usage",
      "activation_limit_days": null,
      "price_multi_currency": {
        "eur": 5,
        "usd": 5,
        "gbp": 4,
        "pln": 19,
        "kzt": 2000,
        "uah": 200
      },
    }
  ]
}

packages (object[]) — містить список доступних пакетів
packages.*.duration (integer) — термін дії eSIM. Одиниця виміру значення міститься в параметрі duration_unit
packages.*.countries (object[]) — список країн, де працює зв'язок eSIM
packages.*.networks (object[]) — список країн, де працює мобільний інтернет eSIM
packages.*.region (null|string, europe|america|latin-america|asia|caribbean-islands|africa|south-africa|middle-east|oceania|iberica|scandinavia|eastern-europe) — регіон, в якому працює eSIM
packages.*.id (string) — внутрішній ідентифікатор eSIM
packages.*.price (float) — ціна eSIM
packages.*.data (integer) — доступний об'єм трафіку. Одиниця виміру цього значення міститься в параметрі data_unit
packages.*.duration_unit (string, days) — одиниця виміру терміну дії з параметру duration
packages.*.data_unit (string, GB|KB|MB) — одиниця виміру трафіку з параметру data
packages.*.top_up (boolean) — має значення true, якщо eSIM доступна для поповнення
packages.*.kyc_verify (boolean) — ознака наявності перевірки документів для придбання eSIM
packages.*.activation_policy (null|string, first-usage|installation) — політика активації. Якщо має значення "first-usage", то активується в момент першого використання. Якщо має значення "installation" активується в момент встановлення eSIM в пристрій. Якщо null, то не має політики активності
packages.*.price_multi_currency (object) — об'єкт цін в кожній валюті
packages.*.activation_limit_days (null|integer) — Може містити кількість днів, за які потрібно активувати eSIM після підключення. Якщо null, то не має такого обмеження

Опис відповіді у випадку внутрішньої помилки (Відповідь 2)

                                    Відповідь 2:
{
  "status": "error",
  "message": "Getting packages error"
}

message (string) — містить повідомлення про помилку

get /v1/esim/order/

Список підключених пакетів

Параметри

user_id (integer)
Необов'язкове поле
ID користувача, що запитується. Доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені. За замовчуванням буде використано поточний ID користувача

Опис вдалої відповіді (Відповідь 1)

                                    Відповідь 1:
{
  "status": "success",
  "orders": [
    {
      "iccid": "8937204017175532566",
      "status": "inactive",
      "packages": [
        {
          "iccid": "8937204017175532566",
          "price": 4.5,
          "currency": "USD",
          "countries": [
            {
              "iso2": "al",
              "name": "Albania",
              "aliases": []
            }
          ],
          "duration": 30,
          "data": 1,
          "region": null,
          "id": "3-al-30days-1gb",
          "data_remaining": 1,
          "top_up": true,
          "created_at": 1730978058,
          "auto_prolong": false,
          "activated_at": null,
          "expired_at": null,
          "reference_id": "672ca10a84a28e977c0cfe39"
        }
      ],
      "title": null,
      "msisdn": null,
      "activation_code": "LPA:1$smdp.io$K2-2627GZ-1UM3Z3Y",
      "created_at": 1730978058
    }
  ]
}

orders (оbject[]) — список підключених пакетів. Детальний описданих пакету див. в методі /v1/esim/order/<iccid>/

Опис відповіді у випадку некоректного user_id (Відповідь 2)

                                    Відповідь 2:
{
    "status": "error",
    "message": "You are not a reseller of the requested user"
}

message (string) — містить повідомлення про помилку

get /v1/esim/order/<iccid>/

Інформація про підключений пакет по iccid

Параметри

iccid (string)
Обов'язкове поле
ICCID, що запитується
user_id (integer)
Необов'язкове поле
ID користувача, що запитується. Доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені. За замовчуванням буде використано поточний ID користувача

Опис вдалої відповіді (Відповідь 1)

                                    Відповідь 1:
{
  "status": "success",
  "order": {
    "iccid": "8937204017175532566",
    "status": "inactive",
    "packages": [
      {
        "iccid": "8937204017175532566",
        "price": 4.5,
        "currency": "USD",
        "countries": [
          {
            "iso2": "al",
            "name": "Albania",
            "aliases": []
          }
        ],
        "duration": 30,
        "data": 1,
        "type": "one-off",
        "region": null,
        "id": "3-al-30days-1gb",
        "data_remaining": 1,
        "top_up": true,
        "created_at": 1730978058,
        "auto_prolong": false,
        "activated_at": null,
        "expired_at": null,
        "reference_id": "672ca10a84a28e977c0cfe39"
      }
    ],
    "title": null,
    "msisdn": null,
    "activation_code": "LPA:1$smdp.io$K2-2627GZ-1UM3Z3Y",
    "created_at": 1730978058
  }
}

order.iccid (string) — ICCID пакету eSIM
order.status (string, active|inactive|archived|blocked) — статус пакету — активована, неактивована, архівована та заблокована.
order.packages (object[]) — підключені пакети. Дані для нього описані в методі /v1/esim/esim/packages
order.packages.*.data_remaining (float) — доступний об'єм трафіку. Одиниця виміру цього значення міститься в параметрі order.packages.*.data_unit
order.packages.*.expired_at (null|integer) — timestamp якщо у eSIM скінчився термін дії
order.title (null|string) — ім'я користувача придбаної eSIM
order.msisdn (null|string) — MSISDN якщо він існує
order.activation_code (string) — ключ для генерації QR коду або ручного встановлення
order.created_at (integer) — timestamp підключення eSIM

Опис відповіді з помилкою, якщо надіслати не існуючий ICCID (Відповідь 2)

                                    Відповідь 2:
{
  "status": "error",
  "message": "Not found"
}

message (string) — повідомлення про помилку

post /v1/esim/order/create/

Підключити пакет

Параметри

package_id (string)
Обов'язкове поле
ID пакету для підключення, packages.*.id з методу /v1/esim/packages/
user_id (integer)
Необов'язкове поле
ID користувача для підключення. Доступний для використання тільки дилерами і тільки для тих користувачів, які ними створені. За замовчуванням буде використано поточний ID користувача

Опис вдалої відповіді (Відповідь 1)

                                    Відповідь 1:
{
    "status": "success",
    "order": {
        "iccid": "8937204016150824154",
        "activation_code": "LPA:1$smdp.io$K2-1UYQA7-Z8B3BF",
        "status": "inactive",
        "packages": [
            {
                "iccid": "8937204016150824154",
                "price": 11.01,
                "currency": "EUR",
                "countries": [
                    {
                        "iso2": "us",
                        "name": "США",
                        "aliases": []
                    }
                ],
                "duration": 30,
                "data": 0,
                "data_remaining": 0,
                "top_up": true,
                "type": "one-off",
                "region": "change",
                "created_at": 1720700977,
                "auto_prolong": false,
                "activated_at": null,
                "expired_at": null,
                "reference_id": null,
                "id": "3-change-30days-0gb"
            }
        ],
        "created_at": 1720700977,
        "title": null,
        "msisdn": null
    }
}

order (оbject) — дані про підключений пакет. Детальний опис міститься в методі /v1/esim/order/<iccid>/

Опис відповіді з помилкою у випадку недостатнього балансу (Відповідь 2)

                                    Відповідь 2:
{
  "status": "error",
  "message": "Not enough money on your account"
}

message (string) — містить повідомлення про помилку

Verify

post /v1/verify/

Запит на верифікацію з надсиланням сповіщення користувачу

Тривалість життя запиту на верифікацію складає 10 хвилин.

Загальні параметри (для усіх каналів)

channel (string, sms|call_code|email|call_button)
Обов'язкове поле
Канал для надсилання повідомлення

Опис каналу "sms"

На номер отримувача буде надіслано SMS повідомлення з кодом підтвердження. Надсилання через цей канал може вимагати оплати, тому у користувача API має бути позитивний баланс

Параметри

to (string)
Обов'язкове поле
Номер телефону отримувача у форматі E.164
code (integer)
Необов'язкове поле
Шестизначний код верифікації. Якщо не вказаний, генерується автоматично
language (string, en|es|de|pl|ru|ua|fr)
Необов'язкове поле
Мова повідомлення. Якщо не вказана, використовується мова особистого кабінету.
template_id (integer)
Необов'язкове поле
ID шаблону користувача для SMS. Якщо не вказаний, використовується шаблон за замовчуванням.
caller_id (string)
Необов'язкове поле
Номер відправника. За замовчуванням "Teamsale"

Опис каналу "call_code"

При виборі цього каналу на номер користувача здійснюється дзвінокв, в результаті якого користувачу озвучується код підтвердження. Надсилання через цей канал може вимагати оплати, тому у користувача API має бути позитивний баланс

Вимоги

Для використання цього каналу користувач API мусить мати зареєстрований номер в системі Zadarma

Параметри

to (string)
Обов'язкове поле
Номер телефону отримувача у форматі E.164
from (string)
Необов'язкове поле
Номер телефону в форматі E.164, з якого надходить дзвінок. Вимагається, якщо у користувача більше одного номеру в системі Zadarma
code (integer)
Необов'язкове поле
Шестизначний код верифікації. Якщо не вказаний, генерується автоматично
language (string, en|es|de|pl|ru|ua|fr)
Необов'язкове поле
Мова повідомлення. Якщо не вказана, використовується мова особистого кабінету.

Опис каналу "email"

При використанні цього каналу на вказану email-адресу надсилається лист з кодом підтвердження. Для надсилання через цей канал користувач API мусить мати активовану email-інтеграцію в CRM системі Teamsale

Параметри

to (string)
Обов'язкове поле
email адреса користувача
from (string)
Необов'язкове поле
email адреса відправника. Вказується, якщо у користувача активовано більше однієї email-інтеграції
code (integer)
Необов'язкове поле
Шестизначний код верифікації. Якщо не вказаний, генерується автоматично
language (string, en|es|de|pl|ru|ua|fr)
Необов'язкове поле
Мова повідомлення. Якщо не вказана, використовується мова особистого кабінету.
email_subject (string)
Необов'язкове поле
Тема (subject) листа, що надсилається. Якщо параметр не вказаний, використовується значення за замовчуванням
email_body (string)
Необов'язкове поле
Тіло (body) листа, що надсилається. Має містити строку "{#code#}" для автоматичної підстановки коду підтвердження. Якщо параметр не вказаний, використовується значення за замовчуванням

Опис каналу "call_button"

Цей канал передбачає дзвінок на номер одержувача, під час якого користувач повинен дотримуватися інструкцій зі звукових файлів та натиснути кнопку "1" для підтвердження. Надсилання через цей канал може вимагати оплати, тому у користувача API має бути позитивний баланс

Для використання цього каналу необхідно

Наявність номеру телефона в системі Zadarma.
Увімкнена АТС (віртуальна телефонна станція).
Налаштовані сповіщення про події.

Особливості: результат верифікації через цей канал перевіряється за допомогою NOTIFY_OUT_END webhook, а не методом /v1/verify/check/.

Параметри

to (string)
Обов'язкове поле
Номер телефону отримувача у форматі E.164
from (string)
Необов'язкове поле
Номер телефону у форматі E.164, з якого буде дзвінок. Вимагається, якщо у користувача більше одного номеру телефона в системі АТС
greeting_sound_id (string)
Обов'язкове поле
ID звукового файлу, який користувач почує під час відповіді на дзвінок
button_1_sound_id (string)
Обов'язкове поле
ID звукового файлу, який користувач почує після натискання кнопки "1"
fallback_sound_id (string)
Обов'язкове поле
ID звукового файлу, який буде відтворено, якщо користувач не натисне кнопку "1", натисне іншу кнопку або не виконає жодних дій

Для керування звуковими файлами, що використовуються в параметрах greeting_sound_id, button_1_sound_id та fallback_sound_id, скористайтесь методами API, що доступні у розділі /v1/pbx/ivr/sounds/*.

Приклади

При успішному надсиланні запиту через канали sms, call_code, email (Відповідь 1)

                                    Відповідь 1:
{
    "status": "success",
    "request_id": "NDlLMWlNcW5mR3EvOFkraWVtOWF1Q2c9"
}

request_id (string) — ID запиту, потрібно для подальшої перевірки коду верифікації

При использовании канала call_button успешный ответ не содержит request_id, поскольку проверка результата осуществляется через NOTIFY_OUT_END webhook (Відповідь 2)

                                    Відповідь 2:
{
    "status": "success"
}

У разі невалідного запиту API повертає відповідь зі статусом error та описом помилки у поліmessage (Відповідь 3)

                                    Відповідь 3:
{
    "status": "error",
    "message": "\"to\" param is required"
}

При надсиланні запиту через канал email, якщо параметр from обов'язковий, але не вказаний, система поверне відповідь зі статусом "error" та повідомленням, що вказує на відсутність необхідного параметра (Відповідь 4)

                                    Відповідь 4:
{
    "status": "error",
    "message": "Can't find active email integration for the \"from\" param's email"
}

post /v1/verify/check/

Перевірка коду в запиті на верифікацію для каналів sms, call_code та email

Параметри

code (integer)
Обов'язкове поле
Шестизначний код, який необхідо перевірити.
request_id (string)
Обов'язкове поле
ID запиту, в якому необхідно перевірити код

Опис вдалого запиту, якщо параметр code відповідає тому, що у запиті на верифікацію (Відповідь 1)

                                    Відповідь 1:
{
    "status": "success",
    "message": "Code is correct"
}

status (string) — містить значення "success"
message (string) — містить значення "Code is correct"

Опис відповіді з помилкою, якщо запит застарів або не знайдено запиту за request_id: (Відповідь 2)

                                    Відповідь 2:
{
    "status": "error",
    "message": "No such request id"
}

message (string) — містить повідомлення про помилку

Опис відповіді з помилкою, якщо параметр code не відповідає тому, що у запиті (Відповідь 3)

                                    Відповідь 3:
{
    "status": "error",
    "message": "Invalid verification code"
}

message (string) — містить повідомлення про помилку

Для перевірки каналу call_button потрібно використовувати NOTIFY_OUT_END webhook

Клієнти

get /v1/zcrm/customers

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

Параметри

search (необов'язково) - рядок пошуку. Пошук здійснюється комбіновано за:
- ім'ям клієнта
- номерами телефонів клієнта
- описом клієнта
- адресою і поштовим індексом
- веб-сайтом
- e-mail адресами
- мессенджерами
- іменами співробітників
- номерами телефонів співробітників
- описами співробітників
- e-mail адресами співробітників
- мессенджерами співробітників
filter (необов'язково) - фільтр клієнтів. ФІльтр працює тільки за заданими полями. Структура фільтра:

(Відповідь 1)

                                    Відповідь 1:
{
  "status": "company",
  "type": "client",
  "country": "GB",
  "city": "London",
  "label": 12,
  "utm": 19,
  "employees_count": "50",
  "responsible": 20
}

Де:

status — статус клієнта. Допустимі значення:
- individual — фіз. особа
- company — компанія
type — тип клієнта. Допустимі значення:
- potential — потенційний клієнт
- client — клієнт
- reseller — реселлер
- partner — партнер
country — країна клієнта. Код з двох літер (UA, US і т.і.)
city — місто клієнта (рядок)
label — тег (ідентифікатор)
utm — мітка джерела (ідентифікатор)
employees_count — кількість співробітників. Допустимі значення:
- 50 — менше 50
- 50_250 — 50 – 250
- 250_500 — 250 – 500
responsible — відповідальний (ідентифікатор користувача)

Будь-який з параметрів фільтра може бути опущений, тобто не є обов'язковим.

sort (необов'язково) — сортування клієнтів. Структура параметра:

(Відповідь 2)

                                    Відповідь 2:
{
    "attr": "name",
    "desc": 0
}

Де:

attr — поле сортування. Допустимі значення:
- name — ім'я клієнта
- status — статус клієнта
- type — тип клієнта
desc — напрямок сортування. Допустимі значення:
- 0 — за зростанням
- 1 — за зменшенням

take (для посторінкового виведення) - скільки дзвінків повернути (за замовчуванням 20)
skip (для посторінкового виведення) - скільки клієнтів пропустити (за замовчуванням 0)

Відповідь

(Відповідь 3)

                                    Відповідь 3:
{
  "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"
        }
      ],
      "utms": [
        {
          "id": 19,
          "param": "utm_source",
          "value": "google",
          "display_value": "Google"
        }
      ]
    }
  ]
}

Де:

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 — країна клієнта. Код з двох літер (UA, 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 — значення тега
- utms — масив міток джерела. Кожна мітка містить наступні поля:
  - id — ідентифікатор мітки
  - param — тип мітки. Можливі значення:
    - utm_source
    - utm_medium
    - utm_campaign
    - utm_content
    - phone — телефон
    - custom — довілька
  - value — фактичне значення мітки
  - display_value — значення мітки, що відображається

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"
    }
  ],
  "utms": [
    {
      "id": 19,
      "param": "utm_source",
      "value": "google",
      "display_value": "Google"
    }
  ],
  "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 — країна клієнта. Код з двох літер (UA, 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 — значення тега
utms — масив міток джерела. Кожна мітка містить наступні поля:
- id — ідентифікатор мітки
- param — тип мітки. Можливі значення:
  - utm_source
  - utm_medium
  - utm_campaign
  - utm_content
  - phone — телефон
  - custom — довільна
- value — фактичне значення мітки
- display_value — значення мітки, що відображається
custom_properties — масив додаткових властивостей. Кожна додаткова властивість містить наступні поля:
- id — ідентифікатор додаткової властивості
- key — унікальне ім'я додаткової властивості
- title — назва додаткової властивості, що відображається
- value — значення додаткової властивості

post /v1/zcrm/customers

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

Параметри

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

(Відповідь 1)

                                    Відповідь 1:
{
    "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 }
    ],
    "utms": [
      { "id": 19 },
      { "id": 20 }
    ],
    "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 — країна клієнта. Код з двох літер (UA, 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 — ідентифікатор існуючого тега
- utms — масив міток джерела. Кожен елемент повинен містити:
- id — ідентифікатор існуючої мітки
custom_properties — масив додаткових властивостей. Кожен елемент повинен містити:
- id — ідентифікатор додаткової властивості либо:
- key — унікальне ім'я додаткової властивості
- value — значення додаткової властивості

Відповідь:

(Відповідь 2)

                                    Відповідь 2:
{
  "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 }
    ],
    "utms": [
      { "id": 19 },
      { "id": 20 }
    ],
    "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 — країна клієнта. Код з двох літер (UA, 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 — ідентифікатор існуючого тега
- utms — масив міток джерела. Кожен елемент повинен містити:
  - id — ідентифікатор існуючої мітки
custom_properties — масив додаткових властивостей. Кожен елемент повинен містити:
- id — ідентифікатор додаткової властивості або:
- key — унікальне ім'я додаткової властивості
- value — значення додаткової властивості

delete /v1/zcrm/customers/<c_id>

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

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

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

Мітки джерела

get /v1/zcrm/customers/utms

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

Відповідь

                                    [
  {
    "id": 78,
    "param": "utm_source",
    "value": "google",
    "display_value": "Google",
    "count": 1267
  }
]

Де кожна мітка аналітики містить наступні поля:

id — ідентифікатор мітки джерела
param — тип мітки джерела. Можливі значення:
- utm_source
- utm_medium
- utm_campaign
- utm_content
- phone — телефон
- custom — довільна
value — фактичне значення мітки джерела
display_value — значення мітки джерела що відображається
count — кількість клієнтів та лідів, що використовують цю мітку аналітики

post /v1/zcrm/customers/utms

Створює нову мітку аналітики

Параметри

utm — дані нової мітки джерела. Структура мітки:

(Відповідь 1)

                                    Відповідь 1:
{
  "param": "utm_source",
  "value": "google",
  "display_value": "Google"
}

Де:

param — тип мітки джерела. Допустимі значення:
- utm_source
- utm_medium
- utm_campaign
- utm_content
- phone — телефон
- custom — довільна
value — фактичне значення мітки джерела
display_value (необов'язковий) — значення мітки джерела що відображається

Відповідь

(Відповідь 2)

                                    Відповідь 2:
{
  "id": 78
}

Де:

id — ідентифікатор створеної мітки джерела

put /v1/zcrm/customers/utms/<utm_id>

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

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

utm_id — ідентифікатор мітки джерела

Параметры

utm — нові дані мітки джерела. Структура мітки джерела:

                                    {
  "param": "utm_source",
  "value": "google",
  "display_value": "Google"
}

Де:

param — тип мітки джерела. Допустимі значення:
- utm_source
- utm_medium
- utm_campaign
- utm_content
- phone — телефон
- custom — довільна
value — фактичне значення мітки джерела
display_value — значення мітки джерела що відображається

delete /v1/zcrm/customers/utms/<utm_id>

Видаляє коллтрекінг-мітку з системи за її ID

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

utm_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": "Very 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 the client",
      "time": "2020-06-08 06:55:02",
      "user_id": 20,
      "user_name": "John Beam",
      "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": "document.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 the client",
  "time": "2020-06-08 06:55:02",
  "user_id": 20,
  "user_name": "John Beam",
  "attached_files": [
    {
      "file_id": 576,
      "original_filename": "document.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": "Steven Knight",
      "position": "manager",
      "position_title": "",
      "comment": "",
      "phones": [
        {
          "type": "work",
          "phone": "+44123456789"
        }
      ],
      "contacts": [
        {
          "type": "email_work",
          "value": "s.knight@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": "Steven Knight",
  "position": "manager",
  "position_title": "",
  "comment": "",
  "phones": [
    {
      "type": "work",
      "phone": "+44123456789"
    }
  ],
  "contacts": [
    {
      "type": "email_work",
      "value": "s.knight@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 — дані нового співробітника. Структура співробітника:

(Відповідь 1)

                                    Відповідь 1:
{
    "name": "Steven Knight",
    "position": "manager",
    "position_title": "",
    "comment": "",
    "phones": [
      {
        "type": "work",
        "phone": "+44123456789"
      }
    ],
    "contacts": [
      {
        "type": "email_work",
        "value": "s.knight@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 — значення контакту

Відповідь

(Відповідь 2)

                                    Відповідь 2:
{
  "id": 23
}

де:

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

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

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

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

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

Параметри

employee — нові дані співробітника. Структура:

                                    {
    "name": "Steven Knight",
    "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/leads

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

Параметри

search (необов'язково) — рядок пошуку. Пошук здійснюється комбіновано за:
- ім'ям ліда
- номерами телефонів ліда
- описом ліда
- адресою і поштовому індексу
- веб-сайтом
- адресам e-mail
- мессенджерами
filter (необов'язково) - фільтр лідів. Структура фільтра:

(Відповідь 1)

                                    Відповідь 1:
{
    "source": "call_incoming",
    "responsible": 32,
    "label": 12,
    "utm": 19,
    "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 — тег (ідентифікатор)
utm — мітка джерела (ідентифікатор)
createdAfter — показати тільки ліди, створені після зазначеного часу (формат: YYYY-MM-DD hh:mm:ss)
createdBefore — показати тільки ліди, створені до зазначеного часу (формат: YYYY-MM-DD hh:mm:ss)

Будь-який з параметрів фільтра може бути опущений, тобто не є обов'язковим.

sort (необов'язково) — сортування лідів. Структура параметра:

(Відповідь 2)

                                    Відповідь 2:
{
    "attr": "name",
    "desc": 0
}

Де:

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

Відповідь

(Відповідь 3)

                                    Відповідь 3:
{
  "totalCount": 100,
  "uncategorizedCount": 10,
  "leads": [
    {
      "id": 3486,
      "name": "Good Company",
      "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"
        }
      ],
      "utms": [
        {
          "id": 19,
          "param": "utm_source",
          "value": "google",
          "display_value": "Google"
        }
      ]
    }
  ]
}

Де:

totalCount — загальна кількість знайдених лідів (з урахуванням рядка пошуку і фільтра)
uncategorizedCount — загальна кількість нерозібраних лідів (з урахуванням пошуку і фільтра)
leads — масив лідів (з урахуванням посторінкового виведення). Кожен елемент масиву містить наступні параметри:
- id — ідентифікатор ліда
- name — ім'я ліда
- responsible_user_id — відповідальний (ідентифікатор користувача)
- employees_count — кількість співробітників. Можливі значення:
  - 50 — менше 50
  - 50_250 — 50 – 250
  - 250_500 — 250 – 500
- comment — опис ліда
- country — країна ліда. Код з двох літер (UA, 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 — значення тега
- utms — масив міток джерела. Кожна мітка містить наступні поля:
  - id — ідентифікатор мітки

get /v1/zcrm/leads/<lead_id>

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

Відповідь

                                    {
  "id": 3486,
  "name": "Good Company",
  "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": "Лучшие клиенты"
    }
  ],
  "utms": [
    {
      "id": 19,
      "param": "utm_source",
      "value": "google",
      "display_value": "Google"
    }
  ],
  "custom_properties": [
    {
      "id": 12,
      "key": "loyalty",
      "title": "Лояльность",
      "value": "high"
    }
  ]
}

Де:

id — ідентифікатор ліда
name — ім'я ліда
responsible_user_id — відповідальний (ідентифікатор користувача)
employees_count — кількість співробітників. Можливі значення:
- 50 — менше 50
- 50_250 — 50 – 250
- 250_500 — 250 – 500
comment — описание лида
country — країна ліда. Код з двох літер (UA, 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 — значення тега масив міток джерела. Кожна мітка містить наступні поля:
  - id — ідентифікатор мітки
- param — тип мітки. Можливі значення:
  - utm_source
  - utm_medium
  - utm_campaign
  - utm_content
  - phone — телефон
  - custom — довільна
- value — фактичне значення мітки
- display_value — значення мітки, що відображається

post /v1/zcrm/leads

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

Параметри

convert — конвертувати лід в клієнта. Допустимі значення:
- 0 — не конвертувати, створити лід
- 1 — створити клієнта
- 2 — неякісний (операція буде скасована - ні лід, ні клієнт не будуть створені)
lead — дані нового ліда. Структура ліда:

(Відповідь 1)

                                    Відповідь 1:
{
    "name": "Good Company",
    "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 }
    ],
    "utms": [
      { "id": 19 },
      { "id": 20 }
    ],
    "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 — ідентифікатор існуючого тега
utms — масив міток джерела. Кожен елемент повинен містити:
- id — ідентифікатор існуючої мітки
custom_properties — масив додаткових властивостей. Кожен елемент повинен містити:
- id — ідентифікатор додаткової властивості або:
- key — унікальне ім'я додаткової властивості
- value — значення додаткової властивості

Відповідь

(Відповідь 2)

                                    Відповідь 2:
{
  "id": 123
}

Де:

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

put /v1/zcrm/leads/<lead_id>

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

Параметри

convert — конвертувати лід в клієнта. Допустимі значення:
- 0 — не конвертувати
- 1 — створити клієнта
- 2 — неякісний (видалити лід)
lead — нові дані ліда. Структура ліда:

                                    {
    "name": "Good Company",
    "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 }
    ],
    "utms": [
      { "id": 19 },
      { "id": 20 }
    ],
    "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 — ідентифікатор існуючого тега
- utms — масив міток джерела. Кожен елемент повинен містити:
  - id — ідентифікатор існуючої мітки
custom_properties — масив додаткових властивостей. Кожен елемент повинен містити:
- id — ідентифікатор додаткової властивості або:
- key — унікальне ім'я додаткової властивості
- value — значення додаткової властивості

delete /v1/zcrm/leads/<lead_id>

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

Користувачі

get /v1/zcrm/users

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

Відповідь

                                    {
  "totalCount": 2,
  "users": [
    {
      "id": 234,
      "email": "john@example.com",
      "name": "John Beam",
      "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": "ivanov@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 — колір завдань користувача в інтерфейсі Teamsale CRM (тільки значення hue — від 0 до 359)
- color_hex — колір завдань користувача в інтерфейсі Teamsale CRM (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@example.com",
  "name": "John Beam",
  "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": "simpson@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 — колір завдань користувача в інтерфейсі Teamsale CRM (только значение hue — от 0 до 359)
color_hex — цвет пользователя в интерфейсе Teamsale CRM (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/contacts

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

Параметри

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

Відповідь

(Відповідь 1)

                                    Відповідь 1:
{
  "totalCount": 128,
  "contacts": [
    {
      "contact_type": "customer",
    },
    {
      "contact_type": "employee",
    },
    {
      "contact_type": "lead",
    },
    {
      "contact_type": "user",
    }
  ]
}

де:

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

Клієнт

(Відповідь 2)

                                    Відповідь 2:
{
    "contact_type": "customer",
    "id": 3486,
    "name": "Good Company",
    "status": "company",
    "type": "client",
    "phone": {
      "phone": "+44123456789",
      "type": "work"
    },
    "responsible": {
      "id": 234,
      "name": "John 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 — внутрішній номер АТС користувача

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

(Відповідь 3)

                                    Відповідь 3:
{
    "contact_type": "employee",
    "id": 8,
    "name": "Michael Simpson",
    "phone": {
      "phone": "+44123456789",
      "type": "work"
    },
    "position": {
      "position": "manager",
      "title": ""
    },
    "customer": {
      "id": 3486,
      "name": "Good Company"
    },
    "responsible": {
      "id": 234,
      "name": "John 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 — внутрішній номер АТС користувача

Лід

(Відповідь 4)

                                    Відповідь 4:
{
    "contact_type": "lead",
    "id": 3486,
    "name": "Good Company",
    "phone": {
      "phone": "+44123456789",
      "type": "work"
    },
    "responsible": {
      "id": 234,
      "name": "John Beam",
      "ext_num": "100"
    }
}

де:

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

Користувач

(Відповідь 5)

                                    Відповідь 5:
{
    "contact_type": "user",
    "id": 234,
    "name": "John Beam",
    "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 — номер телефону

Відповідь

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

Клієнт

(Відповідь 1)

                                    Відповідь 1:
{
  "contact_type": "customer",
  "id": 3486,
  "name": "Good Company",
  "status": "company",
  "type": "client",
  "phone": {
    "phone": "+44123456789",
    "type": "work"
  },
  "responsible": {
    "id": 234,
    "name": "John 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 — внутрішній номер АТС користувача

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

(Відповідь 2)

                                    Відповідь 2:
{
  "contact_type": "employee",
  "id": 8,
  "name": "Michael Simpson",
  "phone": {
    "phone": "+44123456789",
    "type": "work"
  },
  "position": {
    "position": "manager",
    "title": ""
  },
  "customer": {
    "id": 3486,
    "name": "Good Company"
  },
  "responsible": {
    "id": 234,
    "name": "John 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 — внутрішній номер АТС користувача

Лід

(Відповідь 3)

                                    Відповідь 3:
{
  "contact_type": "lead",
  "id": 3486,
  "name": "Good Company",
  "phone": {
    "phone": "+44123456789",
    "type": "work"
  },
  "responsible": {
    "id": 234,
    "name": "John Beam",
    "ext_num": "100"
  }
}

де:

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

Користувач

(Відповідь 4)

                                    Відповідь 4:
{
  "contact_type": "user",
  "id": 234,
  "name": "John Beam",
  "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/deals

Повертає список угод

Параметри

search (необов'язковий) — строка пошуку. Пошук угод здійснюється за назвою.
filter (необов'язковий) — фільтр угод. Структура фільтру:

(Відповідь 1)

                                    Відповідь 1:
{
  "currency": "USD",
  "responsible_user": 20,
  "status": "new"
}

Де:

currency — валюта угоди. Трибуквенний код ISO 4217: EUR, USD і т.д.
responsible_user — відповідальний (ідентифікатор користувача)
status — статус угоди. Допустимі значення:
- new — нова угода
- in_progress — в роботі
- decision — приймають рішення
- payment — очікується оплата
- success — угода вдала
- canceled — угоду скасовано
Будь-який з параметрів фільтра може бути пропущеним, тобто не є обов'язковим.

sort (необов'язковий) — сортування угод. Структура параметру:

(Відповідь 2)

                                    Відповідь 2:
{
  "attr": "name",
  "desc": 0
}

Де:

attr — поле сортування. Допустимі значення:
- title — назва угоди
- budget — бюджет угоди
- status — статус угоди
- created_at — дата створення угоди
desc — напрямок сортування. Допустимі значення:
- 0 — за зростанням
- 1 — у порядку спадання

take (для посторінкового виводу) — скільки угод повернути (за замовчуванням 20)
skip (для посторінкового виводу) — скільки угод пропустити (за замовчуванням 0)

Відповідь

(Відповідь 3)

                                    Відповідь 3:
{
  "totalCount": 82,
  "deals": [
    {
      "id": 83,
      "title": "Good deal",
      "budget": 990.00,
      "currency": "USD",
      "status": "new",
      "responsible_user": 20,
      "created_at": "2021-10-05 12:40:10",
      "created_by": 20,
      "customer_id": 65,
      "customer_is_lead": 0,
      "customer_name": "Good company",
      "customer_responsible_user": 20
    }
  ]
}

Де:

totalCount — загальна кількість угод (з урахуванням строки пошуку та фільтру)
deals — масив угод (з урахуванням посторінкового виводу). Кожен елемент масиву містить наступні параметри:
- id — ідентифікатор угоди
- title — назва угоди
- budget — бюджет угоди
- currency — валюта угоди. Трибуквенний код ISO 4217: EUR, USD і т.д.
- status — статус угоди. Можливі значення:
  - new — нова угода
  - in_progress — у роботі
  - decision — приймають рішення
  - payment — очікується оплата
  - success — угода вдала
  - canceled — угоду скасовано
- responsible_user — відповідальний (ідентифікатор користувача)
- created_at — дата та час створення угоди (у форматі YYYY-MM-DD HH:mm:ss)
- created_by — ким була створена (ідентифікатор користувача)
- customer_id — ідентифікатор клієнта, пов'язаного з угодою
- customer_is_lead — флаг, який показує, чи є клієнт лідом
- customer_name — ім'я клієнта, пов'язаного з угодою
- customer_responsible_user — відповідальний за клієнта (ідентифікатор користувача)

get /v1/zcrm/deals/<deal_id>

Повертає угоду за її ID

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

deal_id — ідентифікатор угоди

Відповідь

                                    {
  "id": 83,
  "title": "Good deal",
  "budget": 990.00,
  "currency": "USD",
  "status": "new",
  "responsible_user": 20,
  "created_at": "2021-10-05 12:40:10",
  "created_by": 20,
  "customer_id": 65,
  "customer_is_lead": 0,
  "customer_name": "Good company",
  "customer_responsible_user": 20
}

Де:

id — ідентифікатор угоди
title — назва угоди
budget — бюджет угоди
currency — валюта угоди. Трибуквенний код ISO 4217: EUR, USD і т.д.
status — статус угоди. Можливі значення:
- new — нова угода
- in_progress — у роботі
- decision — приймають рішення
- payment — очікується оплата
- success — угода вдала
- canceled — угоду скасовано
responsible_user — відповідальний (ідентифікатор користувача)
created_at — дата та час створення угоди (у форматі YYYY-MM-DD HH:mm:ss)
created_by — ким була створена (ідентифікатор користувача)
customer_id — ідентифікатор клієнта, пов'язаного з угодою
customer_is_lead — флаг, який показує, чи є клієнт лідом
customer_name — ім'я клієнта, пов'язаного з угодою
customer_responsible_user — відповідальний за клієнта (ідентифікатор користувача)

post /v1/zcrm/deals

Створює нову угоду зі вказаними даними

Параметри

deal — дані нової угоди. Структура угоди:

(Відповідь 1)

                                    Відповідь 1:
{
  "title": "Good deal",
  "budget": 990.00,
  "currency": "USD",
  "status": "new",
  "responsible_user": 20,
  "customer_id": 65
}

Де:

title — назва угоди
budget — бюджет угоди
currency — валюта угоди. Трибуквенний код ISO 4217: EUR, USD і т.д.
status — статус угоди. Можливі значення:
- new — нова угода
- in_progress — у роботі
- decision — приймають рішення
- payment — очікується оплата
- success — угода вдала
- canceled — угоду скасовано
responsible_user — відповідальний (ідентифікатор користувача)
customer_id — ідентифікатор клієнта, пов'язаного з угодою

Відповідь

(Відповідь 2)

                                    Відповідь 2:
{
  "id": 83
}

Де:

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

put /v1/zcrm/deals/<deal_id>

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

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

deal_id — ідентифікатор угоди

Параметри

deal — нові дані угоди. Структура угоди:

                                    {
  "title": "Good deal",
  "budget": 990.00,
  "currency": "USD",
  "status": "new",
  "responsible_user": 20
}

Де:

title — назва угоди
budget — бюджет угоди
currency — валюта угоди. Трибуквенний код ISO 4217: EUR, USD і т.д.
status — статус угоди. Можливі значення:
- new — нова угода
- in_progress — у роботі
- decision — приймають рішення
- payment — очікується оплата
- success — угода вдала
- canceled — угоду скасовано
responsible_user — відповідальний (ідентифікатор користувача)

delete /v1/zcrm/deals/<deal_id>

Видаляє угоду за її ID

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

deal_id — ідентифікатор угоди

Стрічка угоди

get /v1/zcrm/deals/<deal_id>/feed

Повертає записи у стрічці угоди

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

deal_id — ідентифікатор угоди

Відповідь

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

Де:

totalCount — загальна кількість записів
items — масив записів. Кожен запис містить наступні атрибути:
- id — ідентифікатор запису
- type — тип запису. Можливі значення:
  - event — подія
  - note — текстова замітка
- content — вміст запису. Якщо тип запису — замітка, цей атрибут містить текстовий вміст замітки. Якщо тип запису — подія, цей атрибут містить ідентифікатор події, наприклад:
  - DEAL_CREATED — подія створення угоди
  - DEAL_STATUS_CHANGED: success — подія зміни статуса угоди: угода вдала
- time — час запису у форматі YYYY-MM-DD hh:mm:ss
- user_id — ідентифікатор користувача, що створив запис
- user_name — ім'я користувача, що створив запис
- attached_files — масив прикріплених до замітки файлів (якщо тип запису— замітка). Кожен елемент масиву містить наступні атрибути:
  - file_id — ідентифікатор файлу
  - original_filename — оригінальне ім'я файлу

post /v1/zcrm/deals/<deal_id>/feed

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

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

deal_id — ідентифікатор угоди

Параметри

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

Відповідь

                                    {
  "id": 37825,
  "type": "note",
  "content": "Call to the client",
  "time": "2020-06-08 06:55:02",
  "user_id": 20,
  "user_name": "John Beam",
  "attached_files": [
    {
      "file_id": 576,
      "original_filename": "document.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/deals/<deal_id>/feed/<i_id>

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

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

deal_id — ідентифікатор угоди
i_id — ідентифікатор замітки

Параметри

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

delete /v1/zcrm/deals/<deal_id>/feed/<i_id>

Видаляє замітку у стрічці угоди за її ID

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

deal_id — ідентифікатор угоди
i_id — ідентифікатор замітки

Завдання

get /v1/zcrm/events

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

Параметри

search (необов'язково) — рядок пошуку. Пошук здійснюється комбіновано за:
- назвою завдань
- описом завдань
- коментарем до завершених завданнь
filter (необов'язково) — фільтр завдань. Структура фільтра:

(Відповідь 1)

                                    Відповідь 1:
{
    "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 (необов'язково) - сортування завдань. Структура параметра:

(Відповідь 2)

                                    Відповідь 2:
{
    "attr": "start",
    "desc": 0
}

де:

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

Відповідь

(Відповідь 3)

                                    Відповідь 3:
{
  "totalCount": 4,
  "events": [
    {
      "id": 40,
      "type": "task",
      "title": "Create text for Good Company",
      "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": "Good Company",
          "status": "company",
          "type": "client",
          "lead_source": "manual",
          "lead_status": "not_processed",
          "contact_type": "customer"
        }
      ]
    }
  ]
}

де

totalCount — загальна кількість завдань
events — масив завдань. Кожне завдання містить наступні атрибути:
- id — ідентифікатор завдання
- type — тип завдання. Можливі значення:
  - task — завдання
  - call — дзвінок
title — назва завдання
description — опис завдання (в форматі Quill 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": "Create text for Good Company",
  "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": "Good Company",
      "status": "company",
      "type": "client",
      "lead_source": "manual",
      "lead_status": "not_processed",
      "contact_type": "customer"
    }
  ]
}

де:

id — ідентифікатор завдання
type — тип завдання. Можливі значення:
- task — задача
- call — звонок
title — назва завдання
description — опис завдання (в форматі Quill 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 — дані нового завдання. Структура:

(Відповідь 1)

                                    Відповідь 1:
{
    "type": "task",
    "title": "Create text for Good Company",
    "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)
start — дата і час початку завдання (в форматі YYYY-MM-DD hh:mm:ss)
end — дата і час завершення завдання (в форматі YYYY-MM-DD hh:mm:ss)
allDay — завдання на весь день (true або false)
responsible_user — ідентифікатор користувача, відповідального за завдання
phone — номер телефону для дзвінка (якщо тип завдання - дзвінок)
members — масив учасників завдання (тільки ідентифікатори користувачів)
customers — масив прикріплених клієнтів і лідів (тільки ідентифікатори клієнтів і лідів)

Відповідь

(Відповідь 2)

                                    Відповідь 2:
{
  "id": 7216
}

де:

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

put /v1/zcrm/events/<event_id>

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

Параметри

event — нові дані завдання. Структура:

                                    {
    "title": "Create text for Good Company",
    "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)
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/calls

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

Параметри

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

(Відповідь 1)

                                    Відповідь 1:
{
    "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 (необов'язково) — сортування дзвінків. Структура параметра:

(Відповідь 2)

                                    Відповідь 2:
{
    "attr": "time",
    "desc": 0
}

де:

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

Відповідь

(Відповідь 3)

                                    Відповідь 3:
{
  "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": "Good Company",
      "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/files/<file_id>

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

Дзвінки

NOTIFY_START

початок вхідного дзвінка в АТС

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

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

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

(Відповідь 1)

                                    Відповідь 1:
{
    "redirect": ID,
    "return_timeout": TIMEOUT (необязательное)
}

де,

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

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

(Відповідь 2)

                                    Відповідь 2:
{
    "hangup": 1
}

де,

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

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

(Відповідь 3)

                                    Відповідь 3:
{
    "caller_name": NAME
}

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

(Відповідь 4)

                                    Відповідь 4:
{
    "wait_dtmf": {
        "timeout": TIMEOUT,
        "attempts": ATTEMPTS,
        "maxdigits": MAXDIGITS,
        "name": NAME,
        "default": DEFAULT,
    }
}

де,

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

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

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

(Відповідь 5)

                                    Відповідь 5:
{
    "ivr_play": "ID"
}

де,

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

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

(Відповідь 6)

                                    Відповідь 6:
{
    "ivr_saypopular": 1,
    "language": "en"
}

де,

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

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

(Відповідь 7)

                                    Відповідь 7:
{
    "ivr_saydigits": "12",
    "language": "en"
}

де,

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

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

(Відповідь 8)

                                    Відповідь 8:
{
    "ivr_saynumber": "123",
    "language": "en"
}

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

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

(Відповідь 9)

                                    Відповідь 9:
{
    "wait_dtmf": {
        "name": NAME,
        "digits": DIGITS,
        "default_behaviour": "1"
    }
}

де,

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

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

Доброго дня
Добрий день
Переадресація
Дзвінок з сайту
Ласкаво просимо
Тестове повідомлення
Залишайтесь на лінії
Ви подзвонили в неробочий час
Зараз все менеджери зайняті, вам відповість перший звільнившийся оператор
Наберіть внутрішній номер абонента
Наберіть внутрішній номер співробітника
Наберіть додатковий номер
Будь ласка зачекайте
Наберіть внутрішній номер або дочекайтесь відповіді оператора
Будь ласка залиште ваше повідомлення
Залиште ваше повідомлення після сигналу
Передзвоніть будь ласка в робочий час
Дякуємо за звернення до нашої компанії.
Дякуємо за дзвінок.
Чекайте на відповідь оператора
Ваш дзвінок дуже важливий для нас
Розмова записується
В даний момент нас немає в офіс
Ми передзвонимо вам при першій можливості.
Сьогодні у нас вихідний.

NOTIFY_INTERNAL

початок вхідного дзвінка на внутрішній номер АТС

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

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

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

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

NOTIFY_ANSWER

відповідь при дзвінку на внутрішній або зовнішній номер

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

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

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

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

NOTIFY_END

кінець вхідного дзвінка на внутрішній номер АТС

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

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));

NOTIFY_OUT_START

початок вихідного дзвінка з АТС

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

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));

NOTIFY_OUT_END

кінець вихідного дзвінка з АТС

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

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));

NOTIFY_RECORD

запис дзвінка готова для скачування

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

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));

NOTIFY_IVR

відповідь абонента на задану дію

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

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

Інші

NUMBER_LOOKUP

звіт про перевірку номерів

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

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));

CALL_TRACKING

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

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

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

event – подія (CALL_TRACKING);
result - масив
- tracker - ID трекеру (можна дізнатися на сторінці установки коду);
- start - час початку дзвінка;
- duration - тривалість дзвінка в секундах;
- caller_id - номер телефонуючого;
- caller_did - номер, на який подзвонили;
- country - (опціонально) країна, з якої було здійснено дзвінок;
- ga_id - (опціонально, якщо в налаштуваннях вказано Id Google Analytics) id відвідувача в Google Analytics;
- url - адреса сторінки, з якої був дзвінок;
- utm_source, utm_medium, utm_campaign, utm_term, utm_content - (опціонально, якщо при переході на сайт були вказані utm мітки) utm мітки, за якими відвідувач перейшов на сайт востаннє;
- first_utm - (опціонально, якщо при першому переході на сайт були вказані utm мітки, відмінні від тих, за якими був зроблений перехід в останній раз) масив з utm мітками зазначеними вище, за якими відвідувач перейшов на сайт у перший раз;
- pbx_call_id - id дзвінка (окрім Toll Free);

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

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

SMS

інформацію про вхідні SMS

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

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

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

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

SPEECH_RECOGNITION

результат розпiзнання голосу

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

event – подiя (SPEECH_RECOGNITION)
lang – мова;
call_id – унікальний id дзвінка, цей id вказано в назві файлу із записом розмови;
pbx_call_id – постійний ID зовнішнього дзвінка в АТС;
result:
- words - масив:
  - result - список слiв (масив):
    - s - час початку слова
    - e - час скiнчення слова
    - w - слово
  - channel - номер каналу
- phrases - масив:
  - result - фраза
  - channel - номер каналу

Приклад на PHP:

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

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

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

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

Бібліотека

Параметри:

Параметри:

Параметри

Параметри:

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

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

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

Параметри:

Параметри:

Параметри:

Параметри:

Параметри:

Параметры

Параметри

Параметри:

Параметри:

Параметри:

Параметри

Де:

Параметри:

Параметри:

Параметри:

Параметри:

Параметри

Параметри

Параметри:

Параметри:

Параметри:

Параметри:

Параметри:

Параметри:

Параметри:

Параметри:

Параметри:

Параметри:

Параметри:

Параметри:

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

де

Параметри:

Параметри

Параметри:

Параметри:

Параметри:

Параметриы:

Параметри:

Параметри:

Параметри:

Тіло PUT запиту:

Опис:

Параметри:

Параметри:

Параметри:

Параметри:

Параметри

Параметри

Параметри

Параметри:

Параметри:

Параметри

Параметри

Параметри

Параметри:

Параметри:

Параметри: