API SYNERGY CRM
API — это интерфейс программирования, который позволяет создавать, редактировать и управлять данными в Syenrgy CRM через ваше приложение. Интеграция СRМ по API помогает «связать» с нашей системой любой софт: программа будет сама синхронизироваться с приложениями и корпоративным ПО. Больше никакой рутины и переноса информации вручную!
Например, бухгалтерия оформит закрывающие документы по сделке в 1С, и это сразу отобразится в CRM, с которой работает отдел продаж. Вы избавитесь от ошибок, связанных с ручным копированием информации, и улучшите взаимодействие между подразделениями компании.
API Synergy CRM реализован на основе спецификации JSON API. Документация для разработчиков расположена по адресу api.synergycrm.ru.
Получение API ключа в Synergy CRM
Для получения API ключа перейдите в раздел настроек. Выберите пункт API и нажмите кнопку добавить "+".
В созданном поле введите название, указывающее на цель использования ключа, чек-бокс "Активный" должен быть поставлен.
Примеры интеграции с CRM-системой по API
Synergy CRM.Подключение телефонии через механизм
«Synergy telephony engine»
В настройках системы, в подразделе "Интеграции" выбираем интеграцию, "Synergy API", далее в появившемся окне указываем:
адрес заказа звонка (например https://my_telephony_host.ru/order/call)
После сохранения формы, в блоке с телефониями появится ваша интеграция. Кликнув вашей телефонии, отобразится модальное окно, в котором будет указан URL уведомлений (вида https://telephony.app.syncrm.ru/telephony_external...), на который необходимо будет отправлять POST запросом информацию о звонках. Так же в этом окне необходимо будет указать каким сотрудникам какие внутренние номера соответствуют.
2. Заказ звонка из Synergy CRM
После того, как пользователям будут присвоены внут. номера, то любое нажатие на номер контакта/компании будет вызывать popover-окно, где можно будет инициировать заказ звонка. Технически в этот момент произойдет отправка POST-запроса на URL который указан в первом пункте, в теле POST-запроса будут указаны:
{
src_phone: '200',
dst_phone: '79876543211',
signature*: 'dac5f5967202b4cf6a0e075f4b9db3ce'
}
curl "https://telephony.app.syncrm.ru/telephony_external/6693d051-1111-2222-3333-000000000000" \
-X POST \ -H "Content-Type: application/x-www-form-urlencoded" \
-d @- << EOF src_number=200&started_at=2022-02-22T12:22:22+03:00&answered_at=2022-02-22T12:22:22+03:00&completed_at=2022-02-22T12:22:22+03:00&direction=outgoing&dst_number=79876543211&duration=20&status=answered&call_id=123456789
Расчет поля signature был выполнен методом MD5 от строки: dst_phone79876543211src_phone200TOKEN В качестве ответа на запрос, ожидается получение 200 серверного статуса. При многократном (5 попыток) получении статуса отличного от 200, интеграция клиента в Synergy CRM переводится из активного, в неактивный режим и указывается причина. Signature поле заполняется только в случае, когда в настройках интеграции выставлен флаг "Проверка данных".
3. Уведомления о звонках из АТС в Synergy CRM
Для доставки информации о звонках в Synergy CRM необходимо на выданный URL (см 1 пункт) отправлять POST запросом следующие атрибуты звонка:
* Обязательные поля Уточнение по обязательным полям, в зависимости от направления звонка
Сценарий доставки уведомлений может быть двух видов
Например, как только поступил входящий звонок, то формируется запрос в котором указаны: src_phone=79876543211, dst_phone=200 и started_at=2022-02-22T12:22:22.222+03:00, call_id=MasOIEqwe1aq
Далее, как только была поднята трубка, то отправляется ещё один запрос с дополненными атрибутами:
src_phone=79876543211, dst_phone=200, started_at=2022-02-22T12:22:22.222+03:00, call_id=MasOIEqwe1aq, status=answered, answered_at=2022-02-22T12:22:22.222+03:00.
Далее, звонок был завершен, повторяем отправку с новой информацией:
src_phone=79876543211, dst_phone=200, started_at=2022-02-22T12:22:22.222+03:00, call_id=MasOIEqwe1aq, status=answered, answered_at=2022-02-22T12:22:22.222+03:00, completed_at=2022-02-22T12:22:22.222+03:00, duration=2000, recording=https://host/audio.mp3.
Не забываем, что каждый запрос должен содержать рассчитанный хэш в поле signature (только если опция проверки данных включена в настройках интеграции).
По окончанию звонка или по таймауту сервер телефонии делает отправку истории звонков. В момент обработки уведомлений на стороне Synergy CRM происходит следующее:
Дополнение: Синхронный ответ с телом объекта, в ближайшее время будет заменен на ID звонка в очереди обработки звонков, узнать о статусе обработки можно будет воспользовавшись методами https://api.syncrm.ru/#telephony_calls.
Правило расчета подписи (signature)
Целостность запросов как в случае с заказом звонка, так и в случае с уведомлениями можно проверить по хэшу в поле signature. Для этого необходимо сгенерировать хэш алгоритмом md5 от строки параметров и значений, отсортированной в алфавитном порядке по имени ключа и добавленным токеном в конец этой строки.
{
dst_phone: '222',
src_phone: '200',
direction: 'internal',
duration: '2000',
started_at: '2022-02-22T12:22:22.222+03:00'
}
{
dst_phone: '222',
src_phone: '200',
direction: 'internal',
duration: '2000',
started_at: '2022-02-22T12:22:22.222+03:00'
}
directioninternaldst_phone222duration2000src_phone200started_at2022-02-22T12:22:22 .222+03:00TOKEN
Генерируем от полученной строки хэш: 4655a2c26466969e1c73f5ed4a8df503