Интерфейс API абсолютно бесплатен и доступен на всех учетных записях Zadarma
Каждый запрос, который нуждается в авторизации, сопровождается дополнительным заголовком, вида:
"Authorization: ключ_пользователя:подпись"
Ключи для авторизации необходимо получить в личном кабинете.
Подпись составляется по следующему алгоритму:
Звонки
Телефонные номера
eSIM для путешествий
SMS
Виртуальная АТС
CRM
Речевая аналитика
Коллтрекинг
Виджет обратного звонка
Видеоконференция
Кнопка “Позвонить нам”
Корпоративное подключение
Партнерская программа
Интеграции
Для кого
Инструкции по настройке
Вопросы и ответы
Онлайн чат
Заявка в поддержку
Блог
ksort($params);
$paramsStr = http_build_query($params, null, '&', PHP_QUERY_RFC1738);
$sign = base64_encode(hash_hmac('sha1', $method . $paramsStr . md5($paramsStr), $secret));
$header = 'Authorization: ' . $userKey . ':' . $sign;
Готовый класс PHP для работы с API, можете скачать на GitHub.
Заголовок Content-Type для POST запросов должен быть равным application/x-www-form-urlencoded либо multipart/form-data.
Форматы ответа: json (по умолчанию) и xml.
Чтобы получить ответ от АПИ в формате xml, в строку запроса добавляется параметр "format=xml".
{
"status":"error",
"message":"Check phone's number"
}
В ответе также содержится информация о лимитах и текущем запросе, например:
X-Zadarma-Method: /v1/ X-RateLimit-Reset: 1434371160 X-RateLimit-Limit: 100 X-RateLimit-Remaining: 99
где,
Общие ограничения - 100 запросов в минуту, на методы статистики - 3 запроса в минуту.
В случае блокировки, метод отдает ответ с 429 заголовком "You exceeded the rate limit".
Ответ состоит из обязательного ключа "status" (success или error). Далее, в зависимости от метода, отдаются свои ключи с запрашиваемой информацией.
В случае ошибки, отдается дополнительный ключ "message" с описанием ошибки.
Также, все ответы сопровождаются соответствующими HTTP-заголовками.
Внимание: если нужна постоянно актуальная статистика АТС, не нужно запрашивать каждую минуту метод statistics/pbx/. Включите уведомления webhooks и получайте информацию о каждом звонке в момент его начала и окончания.
баланс пользователя
{
"status":"success",
"balance":10.34,
"currency":"USD"
}
стоимость звонка с учетом текущего тарифа пользователя
{
"status":"success",
"info": {
"prefix":"4420",
"description":"United Kingdom, London",
"price":"0.009",
"currency":"USD",
}
}
часовой пояс пользователя
{
"status":"success",
"unixtime":1483228800,
"datetime":"2017-01-01 00:00:00",
"timezone":"UTC+0"
}
информация о текущем тарифе пользователя
{
"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
}
}
Где:
обратный звонок
{
"status":"success",
"from":442037691880,
"to":442037691881,
"time":1435573082
}
отправка SMS
{
"status":"success",
"messages":1,
"cost":0.24,
"currency":"USD",
"sms_detalization":[
{
"senderid":"xxxxxxxxxxx",
"number":"1234567890",
"cost":0.06
}
],
"denied_numbers":[
{
"number":"1234567890",
"message":"The reason for the SMS not being sent to the number"
}
]
}
Получение списка шаблонов для SMS
{
"list": [
{
"cath_id":"1",
"title":"The name of the template category",
"templates": [
{
"id":"1",
"text":"The template text with a variable {$var}"
},
{
"id":"2",
"text":"Second template text"
},
]
}
]
}
Получить список допустимых отправителей SMS на заданный номер
{
"senders": ["Teamsale", "1234567890"]
}
подтверждение номера
{
"status":"success",
"from":442037691880,
"to":442037691881,
"lang":"fr",
"time":1612779278
}
актуализация контактов
Если numbers содержит 1 номер, результат будет возвращен сразу, если указан список номеров, результат будет отправлен по адресу, указанному на странице актуализации контактов, либо отправлен на email, если адрес не задан.
Обратите внимание: настройки данного метода проводятся на странице актуализации номеров в личном кабинете.
(Пример 1)
Пример 1:
{
"status":"success",
"info":{
"mcc":"24702",
"mnc":"02",
"mccName":"Latvia",
"mncName":"Tele2",
"ported":false,
"roaming":false,
"errorDescription":"No Error"
}
}
(Пример 2)
Пример 2:
{
"status":"success"
}
(Пример 3)
Пример 3:
{
"success":true,
"description":"Success",
"result": [
{
"mcc":"24702",
"mnc":"02",
"ported":false,
"roaming":false,
"errorDescription":"No Error",
"mccName":"Latvia",
"mncName":"Tele2",
"number":"3712812858",
}, ...
]
} Список валют
{
"status": "success",
"currencies": [
"USD",
"EUR",
"GBP",
"PLN"
]
} Список доступных языков в ЛК
{
"status": "success",
"languages": [
"en",
"es",
"de",
"pl",
"ru",
"ua",
"fr"
]
} Список тарифов
{
"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
},
...
]
},
...
]
}
список SIP-номеров пользователя
{
"status":"success",
"sips":[
{"id":"00001", "display_name":"SIP 1", "lines":3},
{"id":"00002", "display_name":"SIP 2", "lines":3}
],
"left":3
}
Где:
online-статус SIP-номера пользователя
{
"status":"success",
"sip":"00001",
"is_online":"false"
}
изменение CallerID
{
"status":"success",
"sip":"00001",
"new_caller_id":"442037691880"
}
отображение текущих переадресаций по SIP-номерам пользователя
{
"status":"success",
"info": [
{
"sip_id":"00001",
"status":"on",
"condition":"always",
"destination":"phone",
"destination_value":"442037691880"
},
...
]
}
Где:
включение/выключение переадресации по номеру SIP
{
"status":"success",
"sip":"00001",
"current_status":"on"
}
изменение параметров переадресации
{
"status":"success",
"sip":"00001",
"destination":"442037691880"
}
Создание SIP номера
{
"status": "success",
"sip": "123456"
}
Смена пароля на SIP
{
"status":"success",
"sip":$sip,
}
получение общей статистики
(Пример 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"
},
…
]
}
Максимальный период получения статистики - месяц. В случае превышения лимита в запросе - период автоматически сокращается до 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
}
]
}
Где:
статистика по АТС
Внимание: если нужна постоянно актуальная статистика АТС, не нужно запрашивать каждую минуту метод 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"
},
…
]
}
Где:
статистика по Виджету обратного звонка
{
"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"
}
]
},
...
]
}
Максимальный период получения статистики - месяц. В случае превышения лимита в запросе - период автоматически сокращается до 30 дней. Если не указана дата начала выборки, выбирается начало текущего месяца. Если не указана дата конца выборки – выборка ограничивается текущей датой и временем.
Максимальное количество выводимых строк для одного запроса - 1000. Для пагинации используйте параметры skip и limit.
Где:
получение общей статистики входящих вызовов
{
"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"
},
…
]
}
Максимальный период получения статистики - месяц. В случае превышения лимита в запросе - период автоматически сокращается до 30 дней. Если не указана дата начала выборки, выбирается начало текущего месяца. Если не указана дата конца выборки – выборка ограничивается текущей датой и временем.
Максимальное количество выводимых строк для одного запроса - 1000. Для пагинации используйте параметры skip и limit.
изменение параметров переадресации на внутреннем номере АТС
{
"status":"success",
"current_status":"on",
"pbx_id":"1234",
"pbx_name":"100",
"type":"phone",
"destination":"79123456789",
"condition":"noanswer"
}
Для включения и настройки переадресации:
Для выключения переадресации:
получение параметров переадресации на внутреннем номере АТС
{
"status":"success",
"current_status":"on",
"pbx_id":"1234",
"pbx_name":"100",
"type":"phone",
"destination":"79123456789",
"condition":"noanswer",
}
запрос на файл записи разговора
Примечание: достаточно указать один из двух параметров идентификации (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"
}
загрузка мелодии
вкл/выкл мелодию для АТС
удаление мелодии
получить настройки 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"
}
}
изменение url для pbx call info
{
"status": "success",
"url": ""
}
изменение реакции на события 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"
}
}
удаление url для pbx call info
{
"status": "success",
"url": ""
}
создание АТС
{
"status": "success",
"stop_datetime": "2021-12-31 23:59:59"
}
получить настройки pbx webhooks
{
"status": "success",
"url": "",
"hooks": {
"number_lookup": "true",
"call_tracking": "false",
"sms": "true",
"speech_recognition": "true"
}
}
изменение url для pbx webhooks
{
"status": "success",
"url": ""
}
изменение реакции на события для других уведомлений (Актуализация контактов, Коллтрекинг, СМС и Речевая аналитика)
{
"status": "success",
"hooks": {
"number_lookup": "true",
"call_tracking": "false",
"sms": "true",
"speech_recognition": "true"
}
}
удаление url для других уведомлений (Актуализация контактов, Коллтрекинг, СМС и Речевая аналитика)
{
"status": "success",
"url": ""
}
отображение внутренних номеров АТС
{
"status":"success",
"pbx_id":1234,
"numbers": [
100,
101,
...
]
}
Где:
online-статус внутреннего номера АТС
{
"status":"success",
"pbx_id":1234,
"number":100,
"is_online":"false"
}
Где:
информация о внутреннем номере АТС
{
"status": "success",
"pbx_id": 12345,
"number": 100,
"name": "Extension 100",
"caller_id": "+44000000000",
"caller_id_app_change": "true",
"caller_id_by_direction": "false",
"lines": "3",
"ip_restriction": "1.1.1.1",
"record_store": "For automatic speech recognition",
"record_email": "email@server.com",
"supervisor_status": 1
}
где:
включение записи разговоров на внутреннем номере АТС
{
"status":"success",
"internal_number":100,
"recording":"on",
"email":"test@test.com",
"speech_recognition":"all"
}
создание номера АТС
{
"status": "success",
"numbers": [
{
"number": 200,
"password": "PASSWORD"
},
{
"number": 201,
"password": "PASSWORD"
}
]
}
запрос пароля внутреннего номера АТС, пароль доступен для просмотра ограниченное время
{
"status": "success",
"pbx_id": 114,
"number": 200,
"password": "PASSWORD"
}
смена пароля на внутреннем номере
{
"status": "success",
"pbx_id": 114,
"number": 200
}
изменение внутреннего номера АТС
список файлов в хранилище АТС
загрузка файла
удаление файла по айди
список 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
}
},
...
]
}
создать IVR
{
"status": "success",
"menu_id": 2
}
удаление IVR
{
"status": "success"
}
список сценариев 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
},
...
]
}
создание сценария IVR
{
"status": "success",
"menu_id": 0,
"scenario_id": 2
}
изменение сценария IVR
(Пример 1)
Пример 1:
[
"id": "630cb6b3dc666e947503a77a",
"title": "Scenario 1",
"queue_strategy": "off",
"queue_announce_position": 0,
"numbers": [
[
"number": 100,
"delay": 0,
"duration": 20
],
[
"number": 101,
"delay": 20,
"duration": 20
],
[
"number": 102,
"delay": 40,
"duration": 20
],
]
]
Описание стратегий распределения вызовов по внутренним номерам в очереди:
Параметры задержки и длительности обзвона внутренних номеров используются только с выключенной очередью (queue_strategy : "off").
Ответ: (Пример 2)
Пример 2:
{"status": "success"}
Ошибка: (Пример 3)
Пример 3:
{"status": "error","message": "Wrong parameters!"} удаление сценария IVR
{
"status": "success"
}
получение результатов распознавания
{
"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
}
]
}
запуск распознавания звонка в статистике АТС, предварительно должно быть включено выборочное распознавание в настройках внутреннего номера
{
"status":"success"
}
информация о прямых номерах пользователя
{
"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"
},
...
]
}
В зависимости от типа номера набор полей может отличаться! Описание полей:
информация о купленном номере
{
"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"
}
}
статус автопродления
{
"status": "success",
"number": "35924913550",
"autoprolongation": "on"
}
получение информации об ошибках проверки документов или адреса
{
"status":"success",
"info":{
"wrong_document":{
"document_type":"contract",
"message":"The passport has expired. It is considered invalid."
},
"wrong_address":{
"message":"Invalid address"
}
}
}
изменить статус автопродления
{
"status": "success",
"number": "35924913550",
"autoprolongation": "off"
}
список стран в которых можно заказать номер
{
"status": "success",
"info": [
{
"countryCode": "61",
"countryCodeIso": "AU",
"name": "Australia"
},
...
]
}
список направлений в стране, в которых можно заказать номер
{
"status": "success",
"info": [
{
"id": "3753",
"countryCode": "49",
"areaCode": "800",
"name": "800 number (Toll-free)",
"connect_fee": 0,
"monthly_fee": 15,
"currency": "USD",
"restrictions": {
"upload": [
"Certificate of registration copy or passport or ID copy (both sides)",
"Proof of address (a copy of utility bill no older than of 6 months) -
your current address (city, street, number and postal code).
The address must be located in the country of ordered phone number"
]
},
"receive_sms": "false",
"is_toll": "true",
"feature": "Available from all networks"
"connect_time": "0"
},
{
"id": "3766",
"countryCode": "49",
"areaCode": "821",
"name": "Augsburg",
"connect_fee": 3,
"monthly_fee": 3,
"currency": "USD",
"restrictions": {
"upload": [
"Passport or ID copy (both sides)"
],
"specify": [
"You current address (city, street, number and postal code).
The address must be located in the region of the city
where you ordered the phone number"
]
},
"receive_sms": "false",
"is_toll": "false",
"feature": null,
"connect_time": "0"
},
...
]
}
установка Имя Номера (латиница и цифры, до 30 знаков)
{
"status": "success",
"number": "+44000000000",
"caller_name": "test"
}
привязка номера к sip или включение тестового режима
{
"status": "success",
"number": "+44000000000",
"sip_id": "00001"
}
номера, доступные для заказа
{
'status': 'success',
'numbers': [
{
'id': 1712p0D1643D0t42r198658,
'direction_id': 13755,
'number': '+44000000001'
},
{
'id': 184bdf85006c3f1676be200,
'direction_id': 13755,
'number': '+44000000000'
},
...
]
}
заказ/покупка номера
{
'status': 'success',
'number': '+44000000000',
'is_reserved': 'false',
'is_activated': 'true'
}
продление номера на произвольное кол-во месяцев
{
'status': 'success',
'number': '+44000000000',
'stop_date': '2021-05-01 12:00:00',
'total_paid': {
'amount': 2,
'currency': 'USD'
}
}
включение приема SMS (только если номер поддерживает прием SMS)
{
"status": "success",
"number": "",
"receive_sms": "on"
}
список файлов/документов в группе документов
{
"status": "success",
"documents": [
{
"type": "passport",
"is_verified": "true",
"source": "upload",
"name": "file1.jpg"
},
{
"type": "receipt",
"is_verified": "false",
"source": "upload",
"name": "file2.jpg"
}
]
}
список групп документов
{
"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
}
]
}
данные по конкретной группе
{
"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
}
}
проверка: подходит ли группа документов для конкретного города/направления
{
"status": "success",
"is_information_match": "true",
"is_documents_uploaded": "true",
"is_documents_verified": "true",
"is_address_match": "true"
}
создание новой группы документов
{
"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
}
}
обновление данных группы документов
{
"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
}
}
загрузка файла документа для группы документов
$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"
} информация о учетной записи дилера
{
"status": "success",
"balance": 123,
"credit": 0,
"currency": "USD",
"reseller_fee": 10,
"user_fee": 10
} Перевод с баланса дилера на баланс связанной учетной записи и обратно
{
"status": "success",
"user": {
"balance": "62.0000",
"currency": "EUR"
},
"reseller": {
"balance": "94.825",
"currency": "USD"
}
}
Список номеров контактных телефонов пользователя
{
"status": "success",
"list": [
{
"id": 0,
"number": "49025000897",
"is_proved": false
}
]
}
Добавление контактного номера телефона пользователя
{
"status": "success",
"id": 98,
"number": "359000000001",
"is_proved": true
}
Редактирование контактного номера телефона пользователя
{
"status": "success",
"id": 99,
"number": "359000000002",
"is_proved": false
}
Запрос подтверждения контактного номера телефона пользователя
{
"number": "359000000002",
"status": "success",
"message": "You were sent an SMS message with a code. Code is valid for 1 hour."
}
Запрос подтверждения контактного номера телефона пользователя (будет осуществлен звонок и при ответе, абонент услышит код подтверждения)
{
"number": "359000000002",
"status": "success",
"message": "You were sent an SMS message with a code. Code is valid for 1 hour."
}
Подтверждения контактного номера кодом из СМС
{
"status": "success",
"message": "Your number confirmed!",
"number": "35900000019"
}
Регистрация пользователя
{
"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."
}
Подтверждение регистрации пользователя
{
"status": "success",
"user_id": 12345
}
Список пользователей дилера выводимых постранично (50 шт.)
{
"status": "success",
"total": 205,
"total_pages": 5,
"page": 1,
"users": [
{
"id": "1234",
"email": "test@domain.com",
"first_name": "Test",
"last_name": "Test",
"organization": "",
"phone": "+44000000001",
"created": "2021-01-26 14:21:04",
"last_login": "2021-01-30 09:46:31",
"balance": "0.4000",
"currency": "GBP",
"sips_count": "1",
"is_active": true,
"allow_topup": true,
"allow_api_requests": true
},
...
]
}
Поиск одной пользовательской учетной записи по критерию (одному из id, email, sip)
{
"status": "success",
"user": {
"id": "1234",
"email": "test@domain.com",
"first_name": "Test",
"last_name": "Test",
"organization": "",
"phone": "+44000000001",
"created": "2021-01-26 14:21:04",
"last_login": "2021-01-30 09:46:31",
"balance": "0.4000",
"currency": "GBP",
"sips_count": "1",
"is_active": true,
"allow_topup": true,
"allow_api_requests": true
}
}
Перевод с баланса дилера на баланс пользовательской учетной записи
{
"status": "success",
"user_topup": {
"amount": 10,
"currency": "GBP"
},
"reseller_withdraw": {
"amount": 10,
"currency": "GBP"
}
}
Получить текущие ключи доступа пользователя к 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"
}
Получить новые ключи доступа пользователя к API
{
"status": "success",
"user_id": 1234,
"key": "abscd",
"secret": "12345"
}
получить ключ для webrtc-виджета. Время жизни ключа - 72 часа.
{
"status":"success",
"key": YOUR_KEY
}
Параметры:
Создание интеграции WebRTC виджета
{
"status": "success"
}
Изменение настроек интеграции WebRTC виджета
{
"status": "success"
}
Данные интеграции WebRTC виджета
{
"status": "success",
"is_exists": true,
"domains": [
"test.domain.com"
],
"settings": {
"shape": "square",
"position": "top_right"
}
}
Добавить домен к интеграции WebRTC виджета
{
"status": "success"
}
Удаление домена из интеграции WebRTC виджета
{
"status": "success"
}
Удаление интеграции WebRTC виджета
{
"status": "success"
}
Список поддерживаемых устройств для eSIM
Описание успешного ответа (Пример 1)
Пример 1:
{
"status": "success",
"devices": {
"acer": [
"ACER Swift 3",
"ACER Swift 7"
],
"asus": [
"ASUS Mini Transformer T103HAF",
"ASUS NovaGo TP370QL",
"ASUS Vivobook Flip 14 TP401NA"
],
"xiaomi": [
"Xiaomi 12T Pro",
"Xiaomi 13 Lite"
]
}
}
Описание ответа в случае внутренней ошибки (Пример 2)
Пример 2:
{
"status": "error",
"message": "Getting devices internal error"
}
Список всех доступных пакетов
Описание успешного ответа (Пример 1)
Пример 1:
{
"status": "success",
"packages": [
{
"duration": 7,
"countries": [
{
"iso2": "cn",
"name": "China",
"aliases": []
}
],
"networks": [
{
"iso2": "CN",
"network": "China Unicom",
"type": "LTE"
}
],
"region": null,
"id": "1-cn-7days-1gb",
"price": 5,
"data": 1,
"duration_unit": "days",
"data_unit": "GB",
"top_up": true,
"kyc_verify": false,
"activation_policy": "first-usage",
"activation_limit_days": null,
"price_multi_currency": {
"eur": 5,
"usd": 5,
"gbp": 4,
"pln": 19,
"kzt": 2000,
"uah": 200
},
}
]
}
Описание ответа в случае внутренней ошибки (Пример 2)
Пример 2:
{
"status": "error",
"message": "Getting packages error"
}
Список подключенных пакетов
Параметры
Описание успешного ответа (Пример 1)
Пример 1:
{
"status": "success",
"orders": [
{
"iccid": "8937204017175532566",
"status": "inactive",
"packages": [
{
"iccid": "8937204017175532566",
"price": 4.5,
"currency": "USD",
"countries": [
{
"iso2": "al",
"name": "Albania",
"aliases": []
}
],
"duration": 30,
"data": 1,
"region": null,
"id": "3-al-30days-1gb",
"data_remaining": 1,
"top_up": true,
"created_at": 1730978058,
"auto_prolong": false,
"activated_at": null,
"expired_at": null,
"reference_id": "672ca10a84a28e977c0cfe39"
}
],
"title": null,
"msisdn": null,
"activation_code": "LPA:1$smdp.io$K2-2627GZ-1UM3Z3Y",
"created_at": 1730978058
}
]
}
Описание ответа в случае некорректного user_id (Пример 2)
Пример 2:
{
"status": "error",
"message": "You are not a reseller of the requested user"
}
Информация про подключенный пакет по ICCID
Параметры
Описание успешного ответа (Пример 1)
Пример 1:
{
"status": "success",
"order": {
"iccid": "8937204017175532566",
"status": "inactive",
"packages": [
{
"iccid": "8937204017175532566",
"price": 4.5,
"currency": "USD",
"countries": [
{
"iso2": "al",
"name": "Albania",
"aliases": []
}
],
"duration": 30,
"data": 1,
"type": "one-off",
"region": null,
"id": "3-al-30days-1gb",
"data_remaining": 1,
"top_up": true,
"created_at": 1730978058,
"auto_prolong": false,
"activated_at": null,
"expired_at": null,
"reference_id": "672ca10a84a28e977c0cfe39"
}
],
"title": null,
"msisdn": null,
"activation_code": "LPA:1$smdp.io$K2-2627GZ-1UM3Z3Y",
"created_at": 1730978058
}
}
Описание ответа с ошибкой если послать не сущетвующий ICCID (Пример 2)
Пример 2:
{
"status": "error",
"message": "Not found"
}
Подключить пакет
Описание успешного ответа (Пример 1)
Пример 1:
{
"status": "success",
"order": {
"iccid": "8937204016150824154",
"activation_code": "LPA:1$smdp.io$K2-1UYQA7-Z8B3BF",
"status": "inactive",
"packages": [
{
"iccid": "8937204016150824154",
"price": 11.01,
"currency": "EUR",
"countries": [
{
"iso2": "us",
"name": "США",
"aliases": []
}
],
"duration": 30,
"data": 0,
"data_remaining": 0,
"top_up": true,
"type": "one-off",
"region": "change",
"created_at": 1720700977,
"auto_prolong": false,
"activated_at": null,
"expired_at": null,
"reference_id": null,
"id": "3-change-30days-0gb"
}
],
"created_at": 1720700977,
"title": null,
"msisdn": null
}
}
Описание ответа с ошибкой в случае недостатка баланса (Пример 2)
Пример 2:
{
"status": "error",
"message": "Not enough money on your account"
}
Запрос на верификацию с отправкой уведомления пользователю
Время жизни запроса на верификацию составляет 10 минут.
На номер получателя будет отправлено SMS сообщение с кодом подтверждения. Отправка через этот канал может требовать оплаты, поэтому у пользователя API должен быть положительный баланс
Параметры
При выборе данного канала на номер получателя совершается звонок, в ходе которого пользователю озвучивается код подтверждения. Отправка через этот канал может требовать оплаты, поэтому у пользователя API должен быть положительный баланс
Для использования этого канала пользователь API должен иметь зарегистрированный номер в системе Zadarma
Параметры
При использовании данного канала на указанный email-адрес отправляется письмо с кодом подтверждения. Для отправки через этот канал пользователь API должен иметь активированную email-интеграцию в CRM системе Teamsale
Параметры
Данный канал предусматривает звонок на номер получателя, во время которого пользователь должен следовать инструкциям из звуковых файлов и нажать кнопку "1" для подтверждения. Отправка через этот канал может требовать оплаты, поэтому у пользователя API должен быть положительный баланс
Для использования этого канала требуется
Особенности: результат верификации через этот канал проверяется с помощью NOTIFY_OUT_END webhook, а не методом /v1/verify/check/.
Параметры
Для управления звуковыми файлами, используемыми в параметрах greeting_sound_id, button_1_sound_id и fallback_sound_id, воспользуйтесь методами API, доступными в разделе /v1/pbx/ivr/sounds/*.
При успешной отправке запроса через каналы sms, call_code, email (Пример 1)
Пример 1:
{
"status": "success",
"request_id": "NDlLMWlNcW5mR3EvOFkraWVtOWF1Q2c9"
}
При использовании канала call_button успешный ответ не содержит request_id, поскольку проверка результата осуществляется через NOTIFY_OUT_END webhook (Пример 2)
Пример 2:
{
"status": "success"
}
В случае невалидного запроса API возвращает ответ со статусом error и описанием ошибки в поле message (Пример 3)
Пример 3:
{
"status": "error",
"message": "\"to\" param is required"
}
При отправке запроса через канал email, если параметр from обязателен, но не указан, система вернет ответ со статусом "error" и сообщением, указывающим на отсутствие необходимого параметра (Пример 4)
Пример 4:
{
"status": "error",
"message": "Can't find active email integration for the \"from\" param's email"
} Проверка кода в запросе на верификацию для каналов sms, call_code и email
Описание успешного ответа, если параметр code соответствует тому что в запросе на верификацию (Пример 1)
Пример 1:
{
"status": "success",
"message": "Code is correct"
}
Описание ответа с ошибкой, если запрос устарел или не найдено запроса по request_id: (Пример 2)
Пример 2:
{
"status": "error",
"message": "No such request id"
}
Описание ответа с ошибкой, если параметр code не соответствует тому что в запросе (Пример 3)
Пример 3:
{
"status": "error",
"message": "Invalid verification code"
}
Для проверки канала call_button нужно использовать NOTIFY_OUT_END webhook
Возвращает список клиентов
(Пример 1)
Пример 1:
{
"status": "company",
"type": "client",
"country": "GB",
"city": "London",
"label": 12,
"utm": 19,
"employees_count": "50",
"responsible": 20
}
Где:
responsible — ответственный (идентификатор пользователя)
Любой из параметров фильтра может быть опущен, т.е. не является обязательным.
(Пример 2)
Пример 2:
{
"attr": "name",
"desc": 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"
}
]
}
]
}
Где:
YYYY-MM-DD HH:mm:ss)YYYY-MM-DD HH:mm:ss)Возвращает клиента по его 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"
}
]
}
Где:
YYYY-MM-DD HH:mm:ss)YYYY-MM-DD HH:mm:ss)Создаёт нового клиента с указанными данными
(Пример 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"
}
]
}
Где:
(Пример 2)
Пример 2:
{
"id": 65
}
Где:
Обновляет существующего клиента с указанным ID
{
"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"
}
]
}
Где:
Удаляет клиента по его ID
Возвращает массив всех меток источника и статистику по ним
[
{
"id": 78,
"param": "utm_source",
"value": "google",
"display_value": "Google",
"count": 1267
}
]
Где каждая метка источника содержит следующие поля:
Создаёт новую метку источника
(Пример 1)
Пример 1:
{
"param": "utm_source",
"value": "google",
"display_value": "Google"
}
Где:
(Пример 2)
Пример 2:
{
"id": 78
}
Где:
Обновляет существующую метку источника с указанным ID
{
"param": "utm_source",
"value": "google",
"display_value": "Google"
}
Где:
Удаляет метку источника из системы по её ID
Возвращает список всех тегов и статистику по ним
{
"totalCount": 5,
"labels": [
{
"id": 12,
"label": "Best clients",
"count": 14
}
]
}
Где:
Создаёт новый тег
{
"id": 13,
"label": "Very best clients",
"count": 0
}
Где:
Удаляет тег из системы по его ID
Возвращает все дополнительные свойства
{
"totalCount": 8,
"customProperties": [
{
"id": 18,
"key": "loyalty",
"title": "Loyalty"
}
]
}
Где:
Возвращает записи в ленте клиента
{
"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"
}
]
}
]
}
Где:
YYYY-MM-DD hh:mm:ssДобавляет текстовую заметку в ленту клиента с возможностью прикрепления файлов
{
"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"
}
]
}
Где:
YYYY-MM-DD hh:mm:ssОбновляет содержимое существующей текстовой заметки по её ID
Удаляет заметку в ленте клиента по её ID
Возвращает список сотрудников клиента по его 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"
}
]
}
]
}
Где:
Возвращает сотрудника клиента по его 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"
}
]
}
Где:
Создаёт и сохраняет нового сотрудника для заданного клиента
(Пример 1)
Пример 1:
{
"name": "Steven Knight",
"position": "manager",
"position_title": "",
"comment": "",
"phones": [
{
"type": "work",
"phone": "+44123456789"
}
],
"contacts": [
{
"type": "email_work",
"value": "s.knight@example.com"
}
]
}
Где:
(Пример 2)
Пример 2:
{
"id": 23
}
Где:
Обновляет существующего сотрудника с указанным ID
{
"name": "Steven Knight",
"position": "manager",
"position_title": "",
"comment": "",
"phones": [
{
"type": "work",
"phone": "+44123456789"
}
],
"contacts": [
{
"type": "email_work",
"value": "john@example.com"
}
]
}
Где:
Удаляет сотрудника по его ID
Возвращает список лидов
(Пример 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"
}
Где:
YYYY-MM-DD hh:mm:ss)createdBefore — показать только лиды, созданные до указанного времени (формат: YYYY-MM-DD hh:mm:ss)
Любой из параметров фильтра может быть опущен, т.е. не является обязательным.
(Пример 2)
Пример 2:
{
"attr": "name",
"desc": 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"
}
]
}
]
}
Где:
YYYY-MM-DD HH:mm:ss)Возвращает лид по его 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"
}
]
}
Где:
YYYY-MM-DD HH:mm:ss)Создаёт новый лид с указанными данными
(Пример 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"
}
]
}
Где:
(Пример 2)
Пример 2:
{
"id": 123
}
Где:
Обновляет существующий лид с указанным ID
{
"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"
}
]
}
Где:
Удаляет лид по его ID
Возвращает список пользователей
{
"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"
}
]
}
]
}
Где:
YYYY-MM-DD hh:mm:ss)Возвращает пользователя по его 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
}
Где:
YYYY-MM-DD hh:mm:ss)Возвращает рабочие часы пользователя
{
"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"
}
]
}
Где:
YYYY-MM-DD hh:mm:ssYYYY-MM-DD hh:mm:ssYYYY-MM-DD hh:mm:ssYYYY-MM-DD hh:mm:ssYYYY-MM-DD hh:mm:ssYYYY-MM-DD hh:mm:ssВозвращает группы и права пользователей каждой из них
{
"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
}
}
]
}
Где:
true или false):
Возвращает список всех контактов (клиенты, сотрудники, лиды, пользователи) с номерами телефонов
(Пример 1)
Пример 1:
{
"totalCount": 128,
"contacts": [
{
"contact_type": "customer",
},
{
"contact_type": "employee",
},
{
"contact_type": "lead",
},
{
"contact_type": "user",
}
]
}
Где:
(Пример 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"
}
}
Где:
(Пример 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"
}
}
Где:
(Пример 4)
Пример 4:
{
"contact_type": "lead",
"id": 3486,
"name": "Good Company",
"phone": {
"phone": "+44123456789",
"type": "work"
},
"responsible": {
"id": 234,
"name": "John Beam",
"ext_num": "100"
}
}
Где:
(Пример 5)
Пример 5:
{
"contact_type": "user",
"id": 234,
"name": "John Beam",
"avatar": 2457,
"role": "",
"status": "",
"phone": {
"phone": "100",
"type": "internal"
},
"group": {
"type": "admin",
"title": ""
}
}
Где:
Идентифицирует контакт (клиента, сотрудника, лида, пользователя) по номеру телефона
Ответ будет зависеть от типа найденного контакта (клиент, сотрудник, лид, пользователь).
(Пример 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"
}
}
Где:
(Пример 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"
}
}
Где:
(Пример 3)
Пример 3:
{
"contact_type": "lead",
"id": 3486,
"name": "Good Company",
"phone": {
"phone": "+44123456789",
"type": "work"
},
"responsible": {
"id": 234,
"name": "John Beam",
"ext_num": "100"
}
}
Где:
(Пример 4)
Пример 4:
{
"contact_type": "user",
"id": 234,
"name": "John Beam",
"avatar": 2457,
"role": "",
"status": "",
"phone": {
"phone": "100",
"type": "internal"
},
"group": {
"type": "admin",
"title": ""
}
}
Где:
Возвращает список сделок
search (необязательный) — строка поиска. Поиск сделок осуществляется по названию.
filter (необязательный) — фильтр сделок. Структура фильтра:
(Пример 1)
Пример 1:
{
"currency": "USD",
"responsible_user": 20,
"status": "new"
}
Где:
status — статус сделки. Допустимые значения:
Любой из параметров фильтра может быть опущен, т.е. не является обязательным.
(Пример 2)
Пример 2:
{
"attr": "name",
"desc": 0
}
Где:
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
}
]
}
Где:
YYYY-MM-DD HH:mm:ss)Возвращает сделку по её 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
}
Где:
YYYY-MM-DD HH:mm:ss)Создаёт новую сделку с указанными данными
(Пример 1)
Пример 1:
{
"title": "Good deal",
"budget": 990.00,
"currency": "USD",
"status": "new",
"responsible_user": 20,
"customer_id": 65
}
Где:
(Пример 2)
Пример 2:
{
"id": 83
}
Где:
Обновляет существующую сделку с указанным ID
{
"title": "Good deal",
"budget": 990.00,
"currency": "USD",
"status": "new",
"responsible_user": 20
}
Где:
Удаляет сделку по её 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"
}
]
}
]
}
Где:
YYYY-MM-DD hh:mm:ssДобавляет текстовую заметку в ленту сделки с возможностью прикрепления файлов
{
"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"
}
]
}
Где:
YYYY-MM-DD hh:mm:ssОбновляет содержимое существующей текстовой заметки по её ID
Удаляет заметку в ленте сделки по её ID
Возвращает список задач
(Пример 1)
Пример 1:
{
"responsible": 456,
"createdBy": 456,
"start": "2020-06-03 02:56:00",
"end": "2020-06-12 02:56:00",
"completed": 1
}
Где:
YYYY-MM-DD hh:mm:ss)YYYY-MM-DD hh:mm:ss)(Пример 2)
Пример 2:
{
"attr": "start",
"desc": 0
}
Где:
(Пример 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"
}
]
}
]
}
Где:
YYYY-MM-DD hh:mm:ss)YYYY-MM-DD hh:mm:ss)true или false) — дата определяется параметром startВозвращает задачу по её 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"
}
]
}
Где:
YYYY-MM-DD hh:mm:ss)YYYY-MM-DD hh:mm:ss)true или false)Создаёт новую задачу с указанными данными
(Пример 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]
}
Где:
YYYY-MM-DD hh:mm:ss)YYYY-MM-DD hh:mm:ss)true или false)(Пример 2)
Пример 2:
{
"id": 7216
}
Где:
Обновляет существующую задачу с указанным ID
{
"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]
}
Где:
YYYY-MM-DD hh:mm:ss)YYYY-MM-DD hh:mm:ss)true или false)Завершает (закрывает) задачу
Удаляет задачу по её ID
Возвращает список звонков
(Пример 1)
Пример 1:
{
"user": 23,
"type": "incoming",
"status": "answer",
"dateFrom": "2020-06-03 14:56:00",
"dateTo": "2020-06-26 14:56:00"
}
Где:
YYYY-MM-DD hh:mm:ss)dateTo — показать только звонки, совершённые до указанного времени (формат: YYYY-MM-DD hh:mm:ss)
Любой из параметров фильтра может быть опущен, т.е. не является обязательным.
(Пример 2)
Пример 2:
{
"attr": "time",
"desc": 0
}
Где:
(Пример 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"
}
]
}
]
}
Где:
YYYY-MM-DD hh:mm:ssОтдаёт файл по его ID
Система Zadarma может отправлять информацию о каждом звонке в виртуальной АТС и направлять звонок на нужный внутренний номер в зависимости от ответа. Для этого необходимо создать открытую для всеобщего доступа ссылку, которая будет принимать POST-запросы с информацией из системы Zadarma.
Шаг 1. Добавьте код в начале скрипта
<?php if (isset($_GET['zd_echo'])) exit($_GET['zd_echo']); ?>
Шаг 2. Добавьте URL для webhook
Перейдите в "Настройки" → "Интеграции и API", в блоке Notifications введите ваш URL в поле для уведомлений о звонках в АТС, затем нажмите "Включить"
начало входящего звонка в АТС
Параметры, которые отправляются на ссылку для уведомлений:
Составление проверочной подписи для уведомления о входящих звонках, пример на 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 (необязательное)
}
Где:
2. Завершить звонок:
(Пример 2)
Пример 2:
{
"hangup": 1
}
3. Задать имя входящего номера
Вы можете задать имя звонящего номера (SIP поле CallerName) и оно отразится в приложении. Таким образом удобно передать имя звонящего, если его номер есть в вашей системе.
(Пример 3)
Пример 3:
{
"caller_name": NAME
}
Где:
В каждом из следующих вариантов ниже (номера 4-7) может присутствовать ответ от абонента в виде цифр. Параметры ввода цифр:
(Пример 4)
Пример 4:
{
"wait_dtmf": {
"timeout": TIMEOUT,
"attempts": ATTEMPTS,
"maxdigits": MAXDIGITS,
"name": NAME,
"default": DEFAULT,
}
}
Где:
4. Воспроизвести файл:
(Пример 5)
Пример 5:
{
"ivr_play": "ID"
}
Где:
5. Воспроизвести популярную фразу:
(Пример 6)
Пример 6:
{
"ivr_saypopular": 1,
"language": "en"
}
Где:
Списки популярных фраз:
6. Воспроизвести цифры:
(Пример 7)
Пример 7:
{
"ivr_saydigits": "12",
"language": "en"
}
7. Воспроизвести число (в соответствии с правилами сложных числительных):
(Пример 8)
Пример 8:
{
"ivr_saynumber": "123",
"language": "en"
}
Где:
Если были указаны 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"
}
}
Где:
начало входящего звонка на внутренний номер АТС
Параметры, которые отправляются на ссылку для уведомлений:
Составление проверочной подписи для уведомления о входящих звонках, пример на PHP:
$signatureTest = base64_encode(hash_hmac('sha1',
$_POST['caller_id'] . $_POST['called_did'] .
$_POST['call_start'], API_SECRET)); ответ при звонке на внутренний или на внешний номер
Параметры, которые отправляются на ссылку для уведомлений:
Составление проверочной подписи для уведомления о входящих звонках, пример на PHP:
$signatureTest = base64_encode(hash_hmac('sha1',
$_POST['caller_id'] . $_POST['destination'] .
$_POST['call_start'], API_SECRET)); конец входящего звонка на внутренний номер АТС
Параметры, которые отправляются на ссылку для уведомлений:
Составление проверочной подписи для уведомления о входящих звонках, пример на PHP:
$signatureTest = base64_encode(hash_hmac('sha1',
$_POST['caller_id'] . $_POST['called_did'] .
$_POST['call_start'], API_SECRET)); начало исходящего звонка с АТС
Параметры, которые отправляются на ссылку для уведомлений:
Составление проверочной подписи для уведомления о входящих звонках, пример на PHP:
$signatureTest = base64_encode(hash_hmac('sha1',
$_POST['internal'] . $_POST['destination'] .
$_POST['call_start'], API_SECRET)); конец исходящего звонка с АТС
Параметры, которые отправляются на ссылку для уведомлений:
Составление проверочной подписи для уведомления о входящих звонках, пример на PHP:
$signatureTest = base64_encode(hash_hmac('sha1',
$_POST['internal'] . $_POST['destination'] .
$_POST['call_start'], API_SECRET)); запись звонка готова для скачивания
Параметры, которые отправляются на ссылку для уведомлений:
Составление проверочной подписи для уведомления о входящих звонках, пример на PHP:
$signatureTest = base64_encode(hash_hmac('sha1',
$_POST['pbx_call_id'] . $_POST['call_id_with_rec'], API_SECRET)); ответ абонента на заданное действие
Параметры, которые отправляются на ссылку для уведомлений:
Составление проверочной подписи для уведомления о входящих звонках, пример на PHP:
$signatureTest = base64_encode(hash_hmac('sha1',
$_POST['caller_id'] . $_POST['called_did'] .
$_POST['call_start'], API_SECRET));
Возможные отправляемые ответы аналогичны ответам запросов NOTIFY_START
<?php if (isset($_GET['zd_echo'])) exit($_GET['zd_echo']); ?>
Для увеличения безопасности, рекомендуем разрешить доступ к вашей ссылке только с IP 185.45.152.42.
Также, если Вы выпустили ключи для доступа к API, в каждом запросе на Вашу ссылку будет приходить дополнительный заголовок "Signature", по которому также сможете сверять целостность, а также подлинность данных.
Пример скрипта можете посмотреть на нашем репозитории на GitHub.
Параметр "result" в этих уведомлениях задан в JSON формате. Вы можете получить его в XML формате, указав в ссылке параметр format=xml.
отчет о проверке номеров
$signatureTest = base64_encode(hash_hmac('sha1', $_POST['result'], API_SECRET));
информацию о звонках на номера, подключенные к коллтрекингу
Параметры, которые отправляются на ссылку для уведомлений:
$signatureTest = base64_encode(hash_hmac('sha1', $_POST['result'], API_SECRET));
информацию о входящих SMS
$signatureTest = base64_encode(hash_hmac('sha1', $_POST['result'], API_SECRET));
результат распознавания голоса
Параметры, которые отправляются на ссылку для уведомлений:
Задать ссылку по которой уведомлять, а также включить/выключить каждый вид уведомлений вы можете в разделе API личного кабинета.
Для того, чтобы система приняла ссылку, необходимо добавить проверочный код вначале скрипта.