ENS: настройка сендера

Описание

Сервис ENS является внешним клиентским сервисом, доступ к которому напрямую отсутствует. Взаимодействие платформы с ENS осуществляется исключительно через системные очереди RabbitMQ. Интеграция с сервисом позволяет осуществлять отправку сообщений через Email и SMS-каналы.

Платформа не выполняет вызовы напрямую к ENS. Клиент должен самостоятельно настроить ENS-сервис на чтение из очередей платформы и запись в них, согласно соглашениям по структуре и маршрутам сообщений.

Сценарии интеграции

Интеграция предусматривает два направления взаимодействия:

• Отправка сообщений — платформа публикует события в очереди, откуда ENS забирает сообщения.

• Приём статусов/ошибок — ENS публикует в ответ статусные события и ошибки в другую очередь, откуда их читает платформа.

Отправка сообщений (Email/SMS)

ENS-сервис должен подписаться на соответствующие exchanger'ы RMQ и забирать сообщения по следующим параметрам:

Тип	Exchange	Routing key
Email	fintechiq.ens.send	fintechiq.ens.email.send
SMS	fintechiq.ens.send	fintechiq.ens.sms.send

Параметры Exchange и Routing Key задаются в Сендере платформы. При необходимости их можно изменить без изменения кода или повторной интеграции.

Email: пример структуры сообщения

{
  "legal_entity_id": "GUID",
  "template": {
    "template_name": "string",
    "brand_name": "string",
    "strictly": true
  },
  "email_from": {
    "name": "string",
    "address": "email@example.com"
  },
  "client": {
    "external_data": "FSMID",
    "template_variable_values": {
      "content": "Email body text here"
    },
    "email_to": [
      {
        "name": "Recipient Name",
        "address": "recipient@example.com",
        "isBcc": false
      }
    ]
  }
}

Email: параметры запроса

Имя параметра	Тип	Обязательность	Описание	Ограничения
legal_entity_id	GUID	Да	Идентификатор юридического лица. Указывается в настройках сендера в панели администрирования.	-
template	object	Да	Объект с данными для генерации шаблона.	-
template.template_name	string	Да	Наименование шаблона. Используется один шаблон для всех отправок. Указывается в настройках сендера.	-
template.brand_name	string	Да	Наименование бренда. Указывается в настройках объекта сендера.	-
template.strictly	boolean	Нет	Если true — происходит строгая проверка всех переменных в template_variable_values. Всегда true.	-
email_from	object	Да	Информация об отправителе.	-
email_from.name	string	Нет	Имя отправителя (From Name).	-
email_from.address	string	Да	Адрес отправителя (From Email).	Максимальная длина 256 символов. Адрес должен содержать символ '@' с символами до и после него.
client	object	Да	Информация о клиенте для отправки сообщения.	-
client.external_data	string	Нет	Любые данные, которые вызывающий сервис передаёт в ENS и которые возвращаются в callback-уведомлениях.	Максимальная длина 192 символа. Используется, например, для FSMID идентификатора.
client.template_variable_values	Словарь <string,string>	Да	Значения переменных шаблона. При отсутствии переменных передаётся пустой объект { }.	-
client.email_to	array[object]	Да	Массив с данными о получателях. Допустим только один получатель.	-
client.email_to.name	string	Нет	Имя получателя (To Name).	-
client.email_to.address	string	Да	Адрес получателя (To Email).	Максимальная длина 256 символов. Адрес должен содержать символ '@' с символами до и после него.
client.email_to.isBcc	boolean	Нет	Признак скрытой копии (BCC). По умолчанию значение — false.	-

SMS: пример структуры сообщения

{
  "legal_entity_id": "GUID",
  "template": {
    "template_name": "string",
    "brand_name": "string",
    "strictly": true
  },
  "client": {
    "external_data": "FSMID",
    "template_variable_values": {
      "content": "SMS text here"
    },
    "phone": "9191234567"
  }
}

SMS: параметры запроса

Имя параметра	Тип	Обязательный	Описание	Ограничения
legal_entity_id	GUID	Да	Идентификатор юридического лица. Указывается в настройках объекта сендера в панели администрирования.	-
template	object	Да	Объект с данными для генерации шаблона.	-
template.template_name	string	Да	Наименование шаблона. Используется один шаблон для всех отправок. Указывается в настройках сендера.	-
template.brand_name	string	Да	Наименование бренда. Используется один шаблон для всех отправок. Указывается в настройках сендера.	-
template.strictly	boolean	Нет	Если true — выполняется строгая проверка всех переменных в template_variable_values. Всегда установлено значение true.	-
client	object	Да	Информация о клиенте для отправки сообщения.	-
client.external_data	string	Нет	Дополнительные данные, передаваемые в ENS, возвращаются в callback-уведомлениях и при получении данных о сообщении через API.	Максимальная длина — 192 символа. Используется, например, для передачи FSMID идентификатора.
client.template_variable_values	Словарь <string,string>	Да	Значения переменных шаблона. Для передачи всего тела сообщения используется переменная content. При отсутствии переменных передаётся {}.	-
client.phone	string	Да	Номер телефона получателя. Только номера РФ (+7), передаются без кода страны.	Формат — 10 цифр (например, "9191234567"). При передаче номера не из РФ отправка будет отклонена.

Получение статусов и ошибок

ENS должен публиковать сообщения о статусах и ошибках в следующую очередь:

• Exchange: fintechiq.ens.status
• Тип: headers
• Заголовки:
  • type — email или sms
  • publisher-id — значение AppId из исходного события
  • result-type — status

Структура успешного статус-события (Email/SMS)

{
  "AppId": "GUID",
  "MessageId": "GUID",
  "ContentType": "application/json",
  "Timestamp": 1713774123000,
  "status": 64,
  "external_data": "FSMID"
}

Структура статус-события с ошибкой (Email/SMS)

{
  "AppId": "GUID",
  "MessageId": "GUID",
  "ContentType": "application/json",
  "Timestamp": 1713774123000,
  "status": 512,
  "external_data": "FSMID",
  "error_details": {
    "error_code": 2,
    "error_message": "Неправильный шаблон"
  }
}

Коды статусов Email/SMS

Код	Описание	Описание
64	Доставлено до получателя	SMS-провайдер подтвердил успешную доставку сообщения клиенту. Считается событием доставки.
128	Дубликат	Сообщение не отправлялось из-за срабатывания проверки дедупликации. Считается событием недоставки.
512	Не доставлено	При отправке произошла ошибка. Детали доступны в полях error_message и error_details. Считается событием недоставки.

Создание и настройка сендера в Altcraft

Для отправки сообщений необходимо настроить Email и SMS сендер, а затем подклчючить их к виртуальному сендеру аккаунта.

Email сендер

В панели администратора перейдите в раздел Сендеры → Email:

Создайте новый сендер с помощью кнопки в правом верхнем углу. Укажите произвольное название сендера и выберите тип — Email: ENS. Далее привяжите аккаунты, в которых будет использоваться этот сендер.

Заполните поля:

• Ключ маршрутизации
• Название RMQ exchange для сообщений (используется для отправки Email-сообщений)
• Название RMQ exchange для статусов (используется для получения статусов Email-сообщений)
• Publisher ID (идентификатор сервиса (App ID))
• Идентификатор юридического лица
• Название шаблона
• Наименование бренда

SMS сендер

В панели администратора перейдите в раздел Сендеры → SMS:

Создайте новый сендер с помощью кнопки в правом верхнем углу. Укажите произвольное название сендера и выберите тип — SMS: ENS. Далее привяжите аккаунты, в которых будет использоваться этот сендер.

Заполните поля:

• Ключ маршрутизации
• Название RMQ exchange для сообщений (используется для отправки SMS-сообщений)
• Название RMQ exchange для статусов (используется для получения статусов SMS-сообщений)
• Publisher ID (идентификатор сервиса (App ID))
• Идентификатор юридического лица
• Название шаблона
• Наименование бренда

Настройка виртуального сендера

В панели администратора откройте раздел Управление аккаунтами → Аккаунты. В списке найдите нужный аккаунт и откройте список виртуальных сендеров:

Создайте новый виртуальный сендер с помощью кнопки в правом верхнем углу:

Укажите произвольное название виртуального сендера, при необходимости добавьте описание и задайте группы доступа:

Далее добавьте правило для Email-сендера:

Выберите ваш Email: ENS сендер и настройте правила. Настройка правил подробно описана в [этой статье]( Выберите ваш Email: ENS сендер и настройте правила:).

Таким же образом надо добавить правило для SMS-сендера:

Сохраните виртуальный сендер с помощью кнопки внизу. Теперь пользователи аккаунта могут использовать его для отправки Email и SMS сообщений.

tip

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