Настройка интеграции с 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. Предусловия

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

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

Если Настройки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.

Заполните:

Поле	Что указать
Адрес интеграции	Уникальное значение, например `smsru_prod`, `smsru_test`, `smsru_crm4dev_1472_test`
Подключено	Включить
api_id	API-ключ из личного кабинета sms.ru или тестовый ключ из Jira CRM4DEV-1472
Логин	Не обязателен, если заполнен `api_id`
Пароль	Не обязателен, если заполнен `api_id`
Имя отправителя	Заполнить, если имя согласовано в sms.ru
Тестовый режим (test=1)	Включить для безопасной проверки без реальной отправки
Переводить кириллицу в транслит	Включать только если нужен транслит

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Проверка:

Создайте документ СообщениеSMS.
Заполните адресата и текст.
Проведите документ.
Запустите или дождитесь выполнения регламента Отправка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 или изменение не попало в базу.

Что сделать:

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

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

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

Что сделать:

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

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

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

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

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

Проверьте:

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

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

Проверьте:

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

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

Проверка	Ожидаемый результат
Базовая интеграция SMS.RU записана	`Вид = SMS.RU`, JSON заполнены
Актуальная интеграция записана	Ошибки уникальности адреса нет
`Проверить подключение`	Подключение успешно
`Узнать баланс`	Показан баланс sms.ru
Отправка с `test=1`	Ошибки нет, деньги не списаны
Реальная отправка без `test=1`	SMS доставлена на телефон
Документ `СообщениеSMS`	Сохраняет результат отправки
Регламент `ОтправкаSMS`	Обрабатывает исходящие SMS
Статусы доставки	Обновляются webhook или fallback-регламентом

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

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

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

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

НастройкиJSON

КомандыJSON

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

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

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

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

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

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

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

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

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

Webhook

Fallback-регламент

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

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

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

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

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

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

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

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