Интеграция с телефонией Zadarma.com

Вводная 

Задарма позволяет внедрить телефонию на сайт. 

Руководство по интеграции от Zadarma - https://zadarma.com/ru/support/instructions/crm-zadarma/#

Базовая интеграция с телефонией Zadarma

Для выполнения интеграции с Zadarma.com необходимо сделать следующее: 

1. Зарегистрироваться на zadarma.com и получить ключ и секретный пароль (key,secret).  Ключи находятся на странице https://my.zadarma.com/api/

2. Для размещения виджета звона на странице сайта настраиваем виджет Позвонить нам на странице https://my.zadarma.com/callmebutton/ и ставим код на свою страницу: 

3. Для приема звонков необходимо на внутренней странице сайта поставить JS виджет  https://my.zadarma.com/api/ в разделе "Интеграция WebRTC виджета"

Здесь мы должны прописать вместо YOUR_SIP  наш номер SIP (его можно взять на странице https://my.zadarma.com/mysip/), а также YOUR_KEY - его необходимо получить через авторизацию через АПИ (об этом ниже).

В итоге на указанной внутренней странице будет расположен виджет телефонии, через который мы можем принимать звонки и звонить на телефонные номера. 

Как работать с API Zadarma

Описание методов API можно найти здесь - https://zadarma.com/ru/support/api/

В методах где требуется авторизация должен передаваться специальный header Authorization со специальным значением (алгоритм его вычисления показан здесь https://zadarma.com/ru/support/api/#intro_authorization)

Используйте следующую функцию, которая вычисляет нужное значение заголовка Authorization: 

create or alter FUNCTION [dbo].[zadarma_authHeader]
(
    @method varchar(120) =  '',  -- /v1/info/balance/
	@params varchar(max) = '',
    @key varchar(max) = '',
	@secret varchar(max) = ''
)
RETURNS varchar(max)
AS
BEGIN
	declare @data varchar(max) = @method +@params + lower(dbo.as_md5(@params))  -- ! важно - varchar(max) 
	declare @sh1 varbinary(max) = dbo.as_hmac('SHA1', convert(varbinary(max), @secret), 
		 convert(varbinary(max), @data ))
	declare @b64 nvarchar(max) =  dbo.as_strToBase64(lower(convert(nvarchar(max), @sh1, 2)))

	
	declare @res varchar(max) =   @key + ':'+ @b64   --'Authorization=' 
	return @res
END

Пример для метода balance: 

select [dbo].[zadarma_authHeader]( '/v1/info/balance/', '','KEY', 'SECRET')

Запускаем через RequestAPI форму (или можно через Postman): 

Как получить ключ для виджета через API

Описание метода авторизации находится здесь - https://zadarma.com/ru/support/api/#intro_authorization

Запускаем метод getKey 

select [dbo].[zadarma_authHeader]( '/v1/webrtc/get_key/', 'sip=__SIP___','KEY', 'SECRET')

В итоге получаем секретный сессионный ключ (он действует 72 часа).

В итоге полученный ключ вставляем в виджет на внутренней странице сайта (т.е. страница доступна только внутреннему пользователю телефонии). 

Получив вручную ключ, можно настроить периодическое обновление сессионного ключа:

1. В sync day процедуре вызываем внешнее действие по вызову API. 

2. Получив ключ, сохраняем его в некоторой настройке в as_settings. 

3. На странице с виджетом вставляем через sp параметры ключ через функцию as_setting(code, defaultValue).

Примечание. В случае проблем с авторизацией по API (выдается 403 ошибка) сделайте следующее: 

• Проверьте что в HMAC функцию передаются varchar параметры, а не nvarchar (в функции специально используeтся varchar).
• Попробуйте строку переводить в tolower. 
• Также параметры в строке адреса должны идти по алфавиту. 
• Проверьте пошагово каждую операцию взятия хеша и перекодировки в base64. Для этого можно использовать онлайн сервисы: 

  • HMAC Service https://www.freeformatter.com/hmac-generator.html#ad-output

  • MD5 Online https://decodeit.ru/md5/

  • Base64 Online - https://decodeit.ru/base64/