Настройка интеграции с SMS.RU

Инструкция описывает настройку отправки SMS через SMS.RU в CRM 4DEV через механизм базовых интеграций.

Связанная задача: CRM4DEV-1472.

1. Что делает интеграция

Интеграция позволяет отправлять SMS из CRM через SMS.RU:

• из карточки партнера/контрагента через действие «Отправить SMS»;
• из документа СообщениеSMS;
• через регламентное задание ОтправкаSMS;
• программно через типовой механизм ОтправкаSMS.

При активной настройке SMS.RU типовой механизм отправки SMS перенаправляется в новый модуль Дев_ОтправкаSMSЧерезSMSRU, который работает с API sms.ru по HTTPS и JSON.

2. Предусловия

Перед настройкой проверьте:

1. В базе есть элемент SMS.RU в справочнике Дев_БазовыеИнтеграции.
2. У элемента SMS.RU заполнен Вид = SMS.RU.
3. У элемента заполнены реквизиты НастройкиJSON и КомандыJSON.
4. В конфигурации присутствует общий модуль Дев_ОтправкаSMSЧерезSMSRU.
5. Пользователь имеет права на настройку сторонних сервисов и актуальных интеграций.

Если НастройкиJSON и КомандыJSON пустые, значит обработчик обновления 0.9.37.42 не отработал или не попал в базу. В этом случае заполните шаблоны вручную по разделу ниже.

3. Шаблон базовой интеграции

Откройте:

Сервис → Сторонние сервисы → Базовые интеграции → SMS.RU

Проверьте:

• Код: 000000048;
• Наименование: SMS.RU;
• Тип: Внешние приложения и сервисы;
• Вид: SMS.RU.

НастройкиJSON

В реквизит НастройкиJSON вставьте:

[
  {
    "Ключ": "ApiId",
    "Представление": "api_id",
    "Тип": "Строка",
    "ЗначениеПоУмолчанию": "",
    "Отображение": ""
  },
  {
    "Ключ": "Login",
    "Представление": "Логин (номер телефона)",
    "Тип": "Строка",
    "ЗначениеПоУмолчанию": "",
    "Отображение": ""
  },
  {
    "Ключ": "Password",
    "Представление": "Пароль",
    "Тип": "Строка",
    "ЗначениеПоУмолчанию": "",
    "Отображение": ""
  },
  {
    "Ключ": "ИмяОтправителя",
    "Представление": "Имя отправителя",
    "Тип": "Строка",
    "ЗначениеПоУмолчанию": "",
    "Отображение": ""
  },
  {
    "Ключ": "ТестовыйРежим",
    "Представление": "Тестовый режим (test=1)",
    "Тип": "Булево",
    "ЗначениеПоУмолчанию": false,
    "Отображение": ""
  },
  {
    "Ключ": "ПереводитьВТранслит",
    "Представление": "Переводить кириллицу в транслит",
    "Тип": "Булево",
    "ЗначениеПоУмолчанию": false,
    "Отображение": ""
  }
]

КомандыJSON

В реквизит КомандыJSON вставьте актуальный шаблон без кнопки тестовой SMS:

[
  {
    "Ключ": "ПроверитьПодключение",
    "Представление": "Проверить подключение",
    "Подсказка": "Запрос auth/check к sms.ru.",
    "АлгоритмКлиент": "Результат = Дев_ОтправкаSMSЧерезSMSRU.ПроверитьАвторизациюПоСсылкеИнтеграции(Объект.Ссылка); Сообщить(Результат.Описание);",
    "СопоставлениеПользователей": false,
    "НоваяСтрока": false
  },
  {
    "Ключ": "УзнатьБаланс",
    "Представление": "Узнать баланс",
    "Подсказка": "Запрос my/balance к sms.ru.",
    "АлгоритмКлиент": "Результат = Дев_ОтправкаSMSЧерезSMSRU.ПроверитьБалансПоСсылкеИнтеграции(Объект.Ссылка); Сообщить(Результат.Описание);",
    "СопоставлениеПользователей": false,
    "НоваяСтрока": false
  },
  {
    "Ключ": "ЗарегистрироватьWebhook",
    "Представление": "Зарегистрировать webhook",
    "Подсказка": "callback/add — регистрирует URL приема статусов sms.ru.",
    "АлгоритмКлиент": "Результат = Дев_ОтправкаSMSЧерезSMSRU.ЗарегистрироватьWebhookПоСсылкеИнтеграции(Объект.Ссылка); Сообщить(Результат.Описание);",
    "СопоставлениеПользователей": false,
    "НоваяСтрока": true
  }
]

Нажмите Записать.

Важно: если метод ЗарегистрироватьWebhookПоСсылкеИнтеграции отсутствует в текущей версии базы, кнопка webhook может не работать. Для первичной проверки интеграции достаточно кнопок Проверить подключение и Узнать баланс.

4. Создание актуальной интеграции

Откройте:

Сервис → Сторонние сервисы → карточка SMS.RU

Создайте или откройте актуальную интеграцию SMS.RU.

Заполните:

Нажмите OK или Записать.

Если появляется ошибка Адрес интеграции должен быть уникальным, измените адрес интеграции на заведомо уникальный или найдите существующую карточку с таким адресом и редактируйте ее.

5. Проверка подключения

После записи карточки откройте ее заново и выполните проверки.

Проверить подключение

Нажмите Проверить подключение.

Ожидаемый результат:

Подключение к sms.ru установлено.

Если появляется ошибка авторизации, проверьте api_id. Если api_id заполнен, логин и пароль не используются.

Узнать баланс

Нажмите Узнать баланс.

Ожидаемый результат:

Баланс sms.ru: <число> руб.

Если баланс получен, значит:

• настройки читаются из Дев_АктуальныеИтеграции;
• api_id применяется корректно;
• HTTPS-доступ до sms.ru работает;
• ответ API парсится корректно.

6. Проверка отправки SMS

Безопасная проверка без реальной отправки

1. В карточке SMS.RU включите Тестовый режим (test=1).
2. Откройте партнера или контрагента с телефоном.
3. Нажмите Отправить SMS.
4. Введите текст, например Проверка CRM4DEV-1472.
5. Выполните отправку.

Ожидаемый результат:

• ошибка отправки не возникает;
• запрос проходит через Дев_ОтправкаSMSЧерезSMSRU;
• деньги не списываются;
• реальная SMS может не прийти, потому что test=1 только проверяет запрос у sms.ru.

Реальная отправка

1. Снимите флаг Тестовый режим (test=1).
2. Убедитесь, что баланс положительный.
3. Проверьте номер телефона получателя.
4. Если используется Имя отправителя, убедитесь, что оно согласовано в sms.ru.
5. Отправьте SMS через карточку партнера/контрагента или через документ СообщениеSMS.

Ожидаемый результат:

• SMS уходит через sms.ru;
• получатель получает сообщение;
• в документе СообщениеSMS сохраняется результат отправки и идентификатор сообщения.

7. Регламентная отправка

Для отправки документов СообщениеSMS через очередь должен быть включен регламент:

Администрирование → Регламентные задания → ОтправкаSMS

Проверка:

1. Создайте документ СообщениеSMS.
2. Заполните адресата и текст.
3. Проведите документ.
4. Запустите или дождитесь выполнения регламента ОтправкаSMS.

Ожидаемый результат:

• документ обрабатывается регламентом;
• отправка идет через активную SMS.RU-интеграцию;
• состояние строки адресата меняется на отправленное провайдером или ошибочное с причиной.

8. Статусы доставки

Статусы могут обновляться двумя способами.

Webhook

Если реализован и зарегистрирован webhook, sms.ru сам присылает статус на endpoint CRM.

Ожидаемый URL имеет вид:

<АдресВнешнегоСервераWebhook>/hs/restapi_v1/smsru/callback

Проверка webhook выполняется кнопкой Зарегистрировать webhook, если метод доступен в текущей версии базы.

Fallback-регламент

Если webhook не используется или callback был пропущен, статусы обновляет регламент:

ОбновлениеСтатусовДоставкиSMS

Он опрашивает sms.ru через sms/status.

9. Частые проблемы

В базовой интеграции пустые НастройкиJSON и КомандыJSON

Причина: не отработал обработчик обновления 0.9.37.42 или изменение не попало в базу.

Что сделать:

1. Проверить версию ИБ.
2. Проверить наличие обработчика УПДК_ОбновлениеИнформационнойБазы.ПерейтиНаВерсию_0_9_37_42.
3. Временно заполнить JSON вручную из этой инструкции.
4. Зафиксировать дефект миграции, если автозаполнение должно было выполниться.

Ошибка Адрес интеграции должен быть уникальным

Причина: в Дев_АктуальныеИтеграции уже есть запись с таким адресом.

Что сделать:

• найти существующую запись и редактировать ее;
• либо указать уникальный адрес, например smsru_prod или smsru_test_0603.

Кнопки не появились

Что проверить:

1. Заполнен ли КомандыJSON в базовой интеграции.
2. Записана ли базовая интеграция после вставки JSON.
3. Открыта ли актуальная интеграция именно по шаблону SMS.RU.
4. Закрыта и открыта ли форма заново после изменения шаблона.

Проверить подключение работает, но SMS не приходит

Проверьте:

• не включен ли Тестовый режим (test=1);
• положительный ли баланс;
• корректный ли номер телефона;
• согласовано ли имя отправителя в sms.ru;
• нет ли ошибки провайдера в журнале регистрации.

Реальная отправка уходит не через SMS.RU

Проверьте:

1. В актуальной интеграции включен флаг Подключено.
2. Активна именно SMS.RU-интеграция.
3. В журнале регистрации есть событие Отправка SMS (Дев_ОтправкаSMSЧерезSMSRU).
4. Нет старой активной настройки SMS4B, которая перехватывает сценарий.

10. Минимальный чек-лист после настройки