• Услуги
  • Тарифы
  • Решения
  • Поддержка
Показать все результаты
Навигация по API
Вернуться наверх

Введение


Интерфейс API абсолютно бесплатен и доступен на всех учетных записях Zadarma

Ссылка на API
https://api.zadarma.com
Версия
v1
Ссылка на метод
https://api.zadarma.com/v1/METHOD/

Библиотеки

Скачайте готовые классы для работы с API
PHP С# Python Zadarma на GitHub

Примеры работы с API

В API доступны все основные функции для работы

  • Телефония и виртуальные номера
  • АТС и ZCRM
  • SMS и HLR-запросы
  • Коллтрекинг
  • Распознавание речи

Авторизация

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

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

Подпись составляется по следующему алгоритму:

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

Форматы ответа: json (по умолчанию) и xml.

Чтобы получить ответ от АПИ в формате xml, в строку запроса добавляется параметр "format=xml".

Ограничения 

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

В ответе также содержится информация о лимитах и текущем запросе, например:

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 и получайте информацию о каждом звонке в момент его начала и окончания.

Методы

get /v1/info/balance/

баланс пользователя

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

get /v1/info/price/

стоимость звонка с учетом текущего тарифа пользователя

                                    {
    "status":"success",
    "info": {
        "prefix":"4420",
        "description":"United Kingdom, London",
        "price":"0.009",
        "currency":"USD",
    }
}

Параметры

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


get /v1/info/timezone/

часовой пояс пользователя

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

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

Где:

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

обратный звонок

                                    {
    "status":"success", 
    "from":442037691880, 
    "to":442037691881, 
    "time":1435573082
}

Параметры

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

  • predicted (опционально) – если указан этот флаг, то запрос является предикативным (система изначально звонит на номер "to" и только если ему дозванивается, соединяет с вашим SIP либо телефонным номером);

post /v1/sms/send/

отправка SMS

                                    {
    "status":"success",
    "messages":1,
    "cost":0.24,
    "currency":"USD"
}

Параметры

  • number – номер телефона, куда отправлять SMS (можно перечислить несколько через запятую);
  • message – сообщение (стандартные ограничения по длине SMS, в случае превышения лимита – разбивается на несколько SMS);
  • caller_id – (опциональный) номер телефона, от кого будет отправлена SMS (можно отправлять только из списка подтвержденных номеров пользователя).

get /v1/request/checknumber/

подтверждение номера

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

Параметры

  • caller_id - номер, отображаемый при звонке, доступны только номера, подключенные в Zadarma;
  • to - номер телефона или SIP, которому звонят;
  • code - код, который будет воспроизводиться. Только цифры и длина не более 20 символов;
  • lang - язык начитки. При отсутствии - берется из ЛК клиента, проверяется на наличие в языках системы.

post /v1/info/number_lookup/

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

Параметры

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

Если numbers содержит 1 номер, результат будет возвращен сразу, если указан список номеров, результат будет отправлен по адресу, указанному на странице актуализации контактов, либо отправлен на email, если адрес не задан.

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

Пример ответа для 1 номера:

(Пример 1) 

                                    Пример 1:
{
    "status":"success",
    "info":{
        "mcc":"250",
        "mnc":"01",
        "mccName":"Russia",
        "mncName":"Mobile TeleSystems",
        "ported":false,
        "roaming":false,
        "errorDescription":"No Error"
    }
}

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

(Пример 2) 

                                    Пример 2:
{
    "status":"success"
}

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

(Пример 3) 

                                    Пример 3:
{
    "success":true,
    "description":"Success",
    "result": [
        {
            "mcc":"250",
            "mnc":"01",
            "ported":false,
            "roaming":false,
            "errorDescription":"No Error",
            "mccName":"Russia",
            "mncName":"Mobile TeleSystems",
            "number":"791234567890",
        }, ...
    ]
}

get /v1/info/lists/currencies/

Список валют

                                    {
    "status": "success",
    "currencies": [
        "USD",
        "EUR",
        "RUB",
        "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
}

Где:

  • id – SIP-id;
  • display_name – отображаемое имя;
  • lines – количество линий;
  • left – количество оставшихся SIP, которые можно создать (зависит от баланса пользователя и общего количества уже созданных SIP).

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

online-статус SIP-номера пользователя

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

put /v1/sip/callerid/

изменение CallerID

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

Параметры

  • 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"
        },
    ...
    ]
}

Параметры

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

Параметры

  • id – SIP id;
  • status – выставляемый статус переадресации на выбранный SIP-номер.

put /v1/sip/redirection/

изменение параметров переадресации

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

Параметры

  • 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 - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы.

Статистика

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"
        },
        …
    ]
}

Параметры

  • start - дата начала просмотра статистики (формат - YYYY-MM-DD HH:MM:SS);
  • end - дата окончания просмотра статистики (формат - YYYY-MM-DD HH:MM:SS);
  • sip (опционально) - фильтр по определенному SIP-номеру;
  • cost_only (опционально) - просмотр только потраченных средств за период;
  • type (опционально - только на общей статистики) - тип запроса: общий (не указывается в запросе), toll и ru495. (для статистики номеров 800 и бесплатных номеров 495);
  • skip (опционально - не учитывается при заданном параметре cost_only) - количество строк, которое необходимо пропустить в выборке, вывод начнется со строки skip + 1 (используется для пагинации совместно с параметром limit, по умолчанию равняется 0);
  • limit (опционально - не учитывается при заданном параметре 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
        }
    ]
}

Где:

  • 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"
        },
        …
    ]
}

Параметры

  • 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"
                }
            ]
        },
        ...
    ]
}

Параметры

  • 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"
        },
        …
    ]
}

Параметры

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

Параметры

Для включения и настройки переадресации:

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

Пример ответа когда указан только 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"
}

Параметры:

  • 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 - ссылка на ваш скрипт, с проверочным кодом <?php if (isset($_GET['zd_echo'])) exit($_GET['zd_echo']); ?> в начале скрипта;
  • 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,
        ...
    ]
}

Где:

  • pbx_id – id ATC пользователя;
  • numbers – список внутренних номеров.

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

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

                                    {
    "status":"success",
    "pbx_id":1234,
    "number":100,
    "is_online":"false"
}

Где:

  • 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": "74990000000",
    "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"
}

где:

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

Параметры

  • 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 - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы.

АТС (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 - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы.

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 - уникальный id звонка, этот id указан в названии файла с записью разговора (уникален для каждой записи в статистике);
  • lang - язык распознавания (не обязательный);
  • return - возвращаемый результат. Варианты: words - слова, phrases - фразы. (не обязательный. по умолчанию phrases);
  • alternatives - возвращать ли альтернативные варианты. Варианты: 0 - нет, 1 - да. (не обязательный. по умолчанию 0).

Параметры ответа:

  • lang – язык;
  • recognitionStatus: - статус распознавания. Варианты:
    • in progress - в процессе распознавания,
    • error - при распознавании возникла ошибка,
    • recognized - распознано
    • ready for recognize - запись готова для распознавания,
    • not available for recognize - запись не доступна для распознавания.
  • result:
    • words - массив:
      • result - список слов (массив):
        • s - время начала слова
        • e - время окончания слова
        • 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"
        },
    ...
    ]
}

Параметры

В зависимости от типа номера набор полей может отличаться! Описание полей:

  • number – купленный виртуальный номер пользователя;
  • status – статус номера;
  • country – страна (для common и revenue);
  • description – описание: город или тип (для common и revenue);
  • number_name – "имя" виртуального номера (задается пользователем);
  • sip – SIP, привязанный к номеру;
  • sip_name – "имя" SIP, привязанного к номеру;
  • start_date – дата покупки номера пользователем;
  • stop_date – дата окончания срока оплаты номера пользователем;
  • monthly_fee – стоимость номера (для common);
  • currency – валюта стоимости номера (для common);
  • channels – количество линий на номере (для common);
  • minutes – общая длительность входящих звонков за текущий месяц (для revenue);
  • autorenew – включено ли автопродление номера (для common, revenue, rufree);
  • is_on_test – находится ли номер на тесте;
  • type – тип номера: common (виртуальный номер), rufree (бесплатный московский номер), revenue (бесплатный московский номер 495).

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

Параметры

  • type - может иметь одно из 3-х значений:
    • 'revenue' - Бесплатный московский номер 495;
    • 'common' - Обычный номер, все остальные;
  • number - номер.

get /v1/direct_numbers/autoprolongation/

статус автопродления

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

Параметры

  • type - может иметь одно из 2-х значений:
    • 'revenue' - Бесплатный московский номер 495;
    • 'common' - Обычный номер, все остальные;
  • number - номер.

put /v1/direct_numbers/autoprolongation/

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

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

Параметры

  • type - может иметь одно из 2-х значений:
    • 'revenue' - Бесплатный московский номер 495;
    • 'common' - Обычный номер, все остальные;
  • 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 (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": "Аугсбург",
            "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);
  • direction_id - необязательный параметр, получение данных по конкретному направлению в стране.

put /v1/direct_numbers/set_caller_name/

установка Имя Номера (латиница и цифры, до 30 знаков)

                                    {
    "status": "success",
    "number": "74990000000",
    "caller_name": "test"
}

Параметры

  • type - может иметь одно из 2-х значений:
    • 'revenue' - Бесплатный московский номер 495;
    • 'common' - Обычный номер, все остальные;
  • number - номер;
  • caller_name - для того чтобы убрать - просто передать пустое поле.

put /v1/direct_numbers/set_sip_id/

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

                                    {
    "status": "success",
    "number": "74990000000",
    "sip_id": "00001"
}

Параметры

  • type - может иметь одно из 3-х значений:
    • 'revenue' - Бесплатный московский номер 495;
    • 'common' - Обычный номер, все остальные;
  • 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': '74990000001'
        },
        {
            'id': 184bdf85006c3f1676be200,
            'direction_id': 13755,
            'number': '74990000000'
        },
        ...
    ]
}

Параметры:

  • DIRECTION_ID - ID направления или ru495;
  • mask - необязательный параметр, для поиска совпадений по номерам.

post /v1/direct_numbers/order/

заказ/покупка номера

                                    {
    'status': 'success',
    'number': '74990000000',
    '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 месяца);
  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы.

post /v1/direct_numbers/prolong/

продление номера на произвольное кол-во месяцев

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

Параметры:

  • number - продлеваемый номер;
  • months - кол-во месяцев;
  • 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 - номер.

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": "74990000001",
            "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": "74990000001",
        "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 пользователя.

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

get /v1/webrtc/get_key/

получить ключ для webrtc-виджета. Время жизни ключа - 72 часа.

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

Параметры:

  • 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 - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы.

Методы ZCRM

Клиенты

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 — страна клиента. Двухбуквенный код (RU, 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 — страна клиента. Двухбуквенный код (RU, US и т.д.)
    • city — город клиента
    • address — адрес клиента
    • zip — почтовый индекс
    • website — веб-сайт клиента
    • created_at — дата и время создания клиента (в формате YYYY-MM-DD HH:mm:ss)
    • created_by — кем был создан (идентификатор пользователя)
    • lead_source — источник. Возможные значения:
      • manual — вручную
      • call_incoming — входящий звонок
      • call_outgoing — исходящий звонок
      • form — форма
    • lead_created_at — дата и время создания лида, если клиент был создан из лида (в формате YYYY-MM-DD HH:mm:ss)
    • lead_created_by — кем был создан лид, если клиент был создан из лида (идентификатор пользователя)
    • phones — массив телефонных номеров клиента. Каждый номер содержит следующие поля:
      • type — тип номера. Возможные значения:
        • work — рабочий
        • personal — личный
      • phone — значение номера
    • contacts — массив контактов клиента. Каждый контакт содержит следующие поля:
      • type — тип контакта. Возможные значения:
        • email_work — рабочий e-mail
        • email_personal — личный e-mail
        • skype
        • telegram
        • viber
        • whatsapp
      • value — значение контакта
    • labels — массив тегов, назначенных клиенту. Каждый тег содержит следующие поля:
      • id — идентификатор тега
      • label — значение тега
    • 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 — страна клиента. Двухбуквенный код (RU, US и т.д.)
  • city — город клиента
  • address — адрес клиента
  • zip — почтовый индекс
  • website — веб-сайт клиента
  • created_at — дата и время создания клиента (в формате YYYY-MM-DD HH:mm:ss)
  • created_by — кем был создан (идентификатор пользователя)
  • lead_source — источник. Возможные значения:
    • manual — вручную
    • call_incoming — входящий звонок
    • call_outgoing — исходящий звонок
    • form — форма
  • lead_created_at — дата и время создания лида, если клиент был создан из лида (в формате YYYY-MM-DD HH:mm:ss)
  • lead_created_by — кем был создан лид, если клиент был создан из лида (идентификатор пользователя)
  • phones — массив телефонных номеров клиента. Каждый номер содержит следующие поля:
    • type — тип номера. Возможные значения:
      • work — рабочий
      • personal — личный
    • phone — значение номера
  • contacts — массив контактов клиента. Каждый контакт содержит следующие поля:
    • type — тип контакта. Возможные значения:
      • email_work — рабочий e-mail
      • email_personal — личный e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — значение контакта
  • labels — массив тегов, назначенных клиенту. Каждый тег содержит следующие поля:
    • id — идентификатор тега
    • label — значение тега
  • 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 — страна клиента. Двухбуквенный код (RU, US и т.д.)
  • city — город клиента
  • address — адрес клиента
  • zip — почтовый индекс
  • website — веб-сайт клиента
  • lead_source — источник. Допустимые значения:
    • manual — вручную
    • call_incoming — входящий звонок
    • call_outgoing — исходящий звонок
    • form — форма
  • phones — массив телефонных номеров. Каждый номер должен содержать следующие поля:
    • type — тип номера. Возможные значения:
      • work — рабочий
      • personal — личный
    • phone — значение номера
  • contacts — массив контактов клиента. Каждый контакт должен содержать следующие поля:
    • type — тип контакта. Возможные значения:
      • email_work — рабочий e-mail
      • email_personal — личный e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — значение контакта
  • labels — массив тегов, добавляемых к клиенту. Каждый элемент должен содержать:
    • id — идентификатор существующего тега
  • 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 — страна клиента. Двухбуквенный код (RU, US и т.д.)
  • city — город клиента
  • address — адрес клиента
  • zip — почтовый индекс
  • website — веб-сайт клиента
  • lead_source — источник. Допустимые значения:
    • manual — вручную
    • call_incoming — входящий звонок
    • call_outgoing — исходящий звонок
    • form — форма
  • phones — массив телефонных номеров. Каждый номер должен содержать следующие поля:
    • type — тип номера. Возможные значения:
      • work — рабочий
      • personal — личный
    • phone — значение номера
  • contacts — массив контактов клиента. Каждый контакт должен содержать следующие поля:
    • type — тип контакта. Возможные значения:
      • email_work — рабочий e-mail
      • email_personal — личный e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — значение контакта
  • labels — массив тегов, добавляемых к клиенту. Каждый элемент должен содержать:
    • id — идентификатор существующего тега
  • 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 — страна лида. Двухбуквенный код (RU, US и т.д.)
    • city — город лида
    • address — адрес лида
    • zip — почтовый индекс
    • website — веб-сайт лида
    • lead_status — статус лида. Возможные значения:
      • not_processed — не обработан
      • in_progress — в обработке
      • finished — завершён
    • lead_source — источник лида. Возможные значения:
      • manual — вручную
      • call_incoming — входящий звонок
      • call_outgoing — исходящий звонок
      • form — форма
    • lead_created_at — дата и время создания лида (в формате YYYY-MM-DD HH:mm:ss)
    • lead_created_by — кем был создан лид (идентификатор пользователя)
    • phones — массив телефонных номеров лида. Каждый номер содержит следующие поля:
      • type — тип номера. Возможные значения:
        • work — рабочий
        • personal — личный
      • phone — значение номера
    • contacts — массив контактов лида. Каждый контакт содержит следующие поля:
      • type — тип контакта. Возможные значения:
        • email_work — рабочий e-mail
        • email_personal — личный e-mail
        • skype
        • telegram
        • viber
        • whatsapp
      • value — значение контакта
    • labels — массив тегов, назначенных лиду. Каждый тег содержит следующие поля:
      • id — идентификатор тега
      • label — значение тега
    • utms — массив меток источника. Каждая метка содержит следующие поля:
      • id — идентификатор метки
      • param — тип метки. Возможные значения:
        • utm_source
        • utm_medium
        • utm_campaign
        • utm_content
        • phone — телефон
        • custom — произвольная
      • value — фактическое значение метки
      • display_value — отображаемое значение метки

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 — страна лида. Двухбуквенный код (RU, US и т.д.)
  • city — город лида
  • address — адрес лида
  • zip — почтовый индекс
  • website — веб-сайт лида
  • lead_status — статус лида. Возможные значения:
    • not_processed — не обработан
    • in_progress — в обработке
    • finished — завершён
  • lead_source — источник лида. Возможные значения:
    • manual — вручную
    • call_incoming — входящий звонок
    • call_outgoing — исходящий звонок
    • form — форма
  • lead_created_at — дата и время создания лида (в формате YYYY-MM-DD HH:mm:ss)
  • lead_created_by — кем был создан лид (идентификатор пользователя)
  • phones — массив телефонных номеров лида. Каждый номер содержит следующие поля:
    • type — тип номера. Возможные значения:
      • work — рабочий
      • personal — личный
    • phone — значение номера
  • contacts — массив контактов лида. Каждый контакт содержит следующие поля:
    • type — тип контакта. Возможные значения:
      • email_work — рабочий e-mail
      • email_personal — личный e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — значение контакта
  • labels — массив тегов, назначенных лиду. Каждый тег содержит следующие поля:
    • id — идентификатор тега
    • label — значение тега
  • utms — массив меток источника. Каждая метка содержит следующие поля:
    • 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 — цвет пользователя в интерфейсе ZCRM (только значение hue — от 0 до 359)
    • color_hex — цвет пользователя в интерфейсе ZCRM (hex-представление)
    • internal_number — внутренний номер АТС пользователя
    • timezone — временная зона пользователя
    • first_day — определяет, какой день недели является началом недели:
      • 0 — воскресенье
      • 1 — понедельник
    • device — что используется для звонков. Возможные значения:
      • webphone — веб-телефон
      • softphone — сторонний софтфон
    • phone_widget_location — расположение виджета веб-телефона. Возмодные значения:
      • left — располагать виджет телефона слева
      • right — располагать виджет телефона справа
    • phones — массив телефонных номеров пользователя. Каждый номер содержит следующие поля:
      • phone — значение номера
      • type — тип номера. Возможные значения:
        • work — рабочий
        • personal — личный
    • contacts — массив контактов пользователя. Каждый контакт содержит следующие поля:
      • type — тип контакта. Возможные значения:
        • email_work — рабочий контактный e-mail
        • email_personal — личный контактный e-mail
        • skype
        • telegram
        • viber
        • whatsapp
      • value — значение контакта

get /v1/zcrm/users/<user_id>

Возвращает пользователя по его ID

Ответ

                                    {
  "id": 234,
  "email": "john@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 — цвет пользователя в интерфейсе ZCRM (только значение hue — от 0 до 359)
  • color_hex — цвет пользователя в интерфейсе ZCRM (hex-представление)
  • internal_number — внутренний номер АТС пользователя
  • timezone — временная зона пользователя
  • first_day — определяет, какой день недели является началом недели:
    • 0 — воскресенье
    • 1 — понедельник
  • device — что используется для звонков. Возможные значения:
    • webphone — веб-телефон
    • softphone — сторонний софтфон
  • phone_widget_location — расположение виджета веб-телефона. Возмодные значения:
    • left — располагать виджет телефона слева
    • right — располагать виджет телефона справа
  • phones — массив телефонных номеров пользователя. Каждый номер содержит следующие поля:
    • phone — значение номера
    • type — тип номера. Возможные значения:
      • work — рабочий
      • personal — личный
  • contacts — массив контактов пользователя. Каждый контакт содержит следующие поля:
    • type — тип контакта. Возможные значения:
      • email_work — рабочий контактный e-mail
      • email_personal — личный контактный e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — значение контакта
  • pending_email_change_request — если был отправлен запрос на изменение e-mail аккаунта, но запрос пока не подтверждён, этот параметр будет установлен в true

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

Возвращает рабочие часы пользователя

Ответ

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

Где:

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

get /v1/zcrm/users/groups

Возвращает группы и права пользователей каждой из них

Ответ

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

Где:

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

Обобщенные контакты

get /v1/zcrm/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: RUB, 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: RUB, 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: RUB, 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: RUB, 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: RUB, 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 — занято
    • call 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

Система уведомлений о звонках - webhook


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

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) 

                                    Пример 1:
{
    "redirect": ID,
    "return_timeout": TIMEOUT (необязательное)
}

Где:

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

2. Завершить звонок:

(Пример 2) 

                                    Пример 2:
{
    "hangup": 1
}

3. Задать имя входящего номера

Вы можете задать имя звонящего номера (SIP поле CallerName) и оно отразится в приложении. Таким образом удобно передать имя звонящего, если его номер есть в вашей системе.

(Пример 3) 

                                    Пример 3:
{
    "caller_name": NAME
}

Где:

  • caller_name - имя номера.

В каждом из следующих вариантов ниже (номера 4-7) может присутствовать ответ от абонента в виде цифр. Параметры ввода цифр:

(Пример 4) 

                                    Пример 4:
{
    "wait_dtmf": {
        "timeout": TIMEOUT,
        "attempts": ATTEMPTS,
        "maxdigits": MAXDIGITS,
        "name": NAME,
        "default": DEFAULT,
    }
}

Где:

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

4. Воспроизвести файл:

(Пример 5) 

                                    Пример 5:
{
    "ivr_play": "ID"
}

Где:

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

5. Воспроизвести популярную фразу:

(Пример 6) 

                                    Пример 6:
{
    "ivr_saypopular": 1,
    "language": "en"
}

Где:

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

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

  • Здравствуйте
  • Добрый день
  • Переадресация
  • Звонок с сайта
  • Добро пожаловать
  • Тестовое сообщение
  • Оставайтесь на линии
  • Вы позвонили в нерабочее время
  • Сейчас все менеджеры заняты, вам ответит первый освободившийся оператор.
  • Наберите внутренний номер абонента
  • Наберите внутренний номер сотрудника
  • Наберите добавочный номер
  • Пожалуйста ожидайте
  • Наберите внутренний номер или дождитесь ответа оператора
  • Пожалуйста оставьте сообщение
  • Оставьте ваше сообщение после сигнала
  • Перезвоните пожалуйста в рабочее время
  • Благодарим за обращение в нашу компанию.
  • Спасибо за звонок.
  • Ожидайте ответа оператора
  • Ваш звонок очень важен для нас
  • Разговор записывается
  • В данный момент нас нет в офисе
  • Мы перезвоним вам при первой возможности
  • Сегодня у нас выходной.

6. Воспроизвести цифры:

(Пример 7) 

                                    Пример 7:
{
    "ivr_saydigits": "12",
    "language": "en"
}

7. Воспроизвести число (в соответствии с правилами сложных числительных):

(Пример 8) 

                                    Пример 8:
{
    "ivr_saynumber": "123",
    "language": "en"
}

Где:

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

Если были указаны ivr_saydigits или ivr_saynumber, в следующем событии NOTIFY_IVR будет добавлен параметр: "ivr_saydigits": "COMPLETE" или "ivr_saynumber": "COMPLETE"

В следующем событии NOTIFY_IVR будет дополнительно указан параметр:

(Пример 9) 

                                    Пример 9:
{
    "wait_dtmf": {
        "name": NAME,
        "digits": DIGITS,
        "default_behaviour": "1"
    }
}

Где:

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

NOTIFY_INTERNAL

начало входящего звонка на внутренний номер АТС

Параметры, которые отправляются на ссылку для уведомлений:

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

Составление проверочной подписи для уведомления о входящих звонках, пример на PHP:

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

NOTIFY_ANSWER

ответ при звонке на внутренний или на внешний номер

Параметры, которые отправляются на ссылку для уведомлений:

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

Составление проверочной подписи для уведомления о входящих звонках, пример на PHP:

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

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 - превышен лимит;
  • last_internal – внутренний номер, последний участник звонка (после трансфера или перехвата);
  • 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;
  • destination – номер, на который позвонили;
  • internal – (опциональный) внутренний номер;
  • duration – длительность в секундах;
  • disposition – состояние звонка:
    • answered – разговор,
    • busy – занято,
    • cancel - отменен,
    • no answer - без ответа,
    • failed - не удался,
    • no money - нет средств, превышен лимит,
    • unallocated number - номер не существует,
    • no limit - превышен лимит,
    • no day limit - превышен дневной лимит,
    • line limit - превышен лимит линий,
    • no money, no limit - превышен лимит;
  • status_code – код статуса звонка Q.931;
  • is_recorded – 1 - есть запись звонка, 0 - нет записи;
  • call_id_with_rec – id звонка с записью (рекомендуем загружать файл записи не ранее чем через 40 секунд после уведомления т.к. для сохранения файла записи нужно время).

Составление проверочной подписи для уведомления о входящих звонках, пример на PHP:

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

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

Пример на PHP: 

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

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

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

Пример скрипта можете посмотреть на нашем репозитории на GitHub.

Другие уведомления


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

NUMBER_LOOKUP

отчет о проверке номеров

Параметры, которые отправляются на ссылку для уведомлений:

  • 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 - номер, на который позвонили;
    • source - название источника посетителя;
    • country - (опционально) страна, из которой был совершен звонок;
    • ga_id - (опционально, если в настройках указан Id Google Analytics) id посетителя в Google Analytics;
    • metrika_id - (опционально, еcли в настройках указан Id Yandex.Metrika) id посетителя в Yandex.Metrika;
    • 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

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

Параметры, которые отправляются на ссылку для уведомлений:

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

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

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

Продолжая использовать наш сайт, Вы даете согласие на обработку файлов Cookies и пользовательских данных, подробнее в нашей Политике Cookie. Если Вы не хотите, чтобы Ваши данные обрабатывались, пожалуйста, покиньте сайт.