Follow

SendSingle2: Отправка писем с передачей параметров

Новый API метод SendSingle2 поддерживает новую опцию персонализации сообщений. Теперь есть возможность передавать составные иерархические данные и использовать их в сообщениях.

С документацией API данного метода можно ознакомиться здесь.

https://ofsys.com/webservices/en-US/#tab=doc&section=services&application=OFC4&service=Sendings&method=SendSingle2

Иногда требуется отправить т.н. одноразовые данные (промо-код, пароль или пин-код на восстановление пароля и т.п.), которые не требуется хранить. Преимущества нового метода очевидны: нет необходимости сохранять данные в таблице для передачи их в сообщения.

ВАЖНО: Новый метод нельзя использовать для массовых рассылок и запускать в циклах. В противном случае, доступ к вызовам API будет заблокирован без уведомления до выяснения обстоятельств.

Подготовка сообщения

Для отправки сообщения с помощью метода SendSingle2, сообщение требуется определённым образом настроить. Необходимо добавить в сообщение все параметры, которые будут передаваться в этом методе и использоваться в коде сообщения.

Для добавления параметров следует в редакторе сообщения нажать на кнопку "Additional options" в правом верхнем углу окна.

2017-03-28_15-53-10.png

 

Затем, в левом меню выбрать раздел "Parameters"

2017-03-28_15-59-29.png

 

Далее, вы можете добавить простой параметр текстового или числового типа

2017-03-28_16-01-32.png

Или создать новый тип, который будет состоять из переменных и/или массивов других типов.

02.png

03.png

 04.png

05.png

 

Обращение к параметрам в коде письма.

Текстовый или числовой тип параметра с условным именем Promocode:

[[=Message.Parameters.Promocode;]]

 

Параметр составного типа с условным названием Address, который содержит три поля: City, Street, House

[[=Message.Parameters.Address.City;]]

[[=Message.Parameters.Address.Street;]]

[[=Message.Parameters.Address.House;]]

 

Параметр-массив с условным названием Products, который содержит поля: Name, Price, Image

[[
foreach (Product_array_index => Product in Message.Parameters.Products) {
]]
    [[=Product.Name;]]
    [[=Product.Price;]]
    [[=Product.Image;]]
[[
}
]]

или непосредственно по индексу элемента в массиве. Например:

[[=Message.Parameters.Products[0].Name;]]

выведет наименование первого продукта из массива.

 

Передача параметров в API запросе

Пример передачи данных:

"MessageParameterValues": {

    "Promocode": "MN09P",

    "Address": {
        "City": "Москва",
        "Street": "Покровка",
        "House": "31c2"
    },

    "Products": [
      {
          "Name": "Утюг",
          "Price": 2900,
          "Image": "http://..."
      },
      {
          "Name": "Чайник",
          "Price": 3200,
          "Image": "http://..."
      },
      {
          "Name": "Телевизор",
          "Price": 43000,
          "Image": "http://..."
      }
  ]
}

Вы можете указать в опциях свойство

DiscardParametersAfterSending: true

сразу после передачи свойства MessageParameterValues, т.е.

"SendSingleOptions": {

    "MessageParameterValues": {
        .......
    },

    "DiscardParametersAfterSending": true

}

В этом случае, значения всех переданных параметров будут удалены из хранилища в Ofsys, но это позволит вам передавать в качестве значения параметра HTML-код.

Если передать "DiscardParametersAfterSending": false, то значения параметров будут храниться в Ofsys некоторое время для того, чтобы эти значения были доступны в веб-версии писем. При этом передавать HTML-код в качестве значений параметров нельзя ни в коем случае.

Важные уточнения для передачи значений параметров:

  1. ВСЕ передаваемые параметры в MessageParameterValues должны быть описаны в шаблоне во вкладке Parameters 
  2. Если в запросе будет лишний параметр (например его название mainInfo), то API вернет ошибку типа "Unexpected parameter: mainInfo" 
  3. Если в шаблоне параметр описан, как необязательный, то в JSON структуре запроса он может отсутствовать. 
  4. Если в шаблоне параметр описан, как обязательный, и для него в шаблоне не указано умолчательное значение (Default value), то при отсутствии данного параметра в запросе API вернет ошибку типа "The parameters: Missing value for parameter 'cardNo'". При тех же настройках, но передаче пустой строки (например, "cardNo": ""), ошибка не возникнет. Т.е. пустое значение для строк допускается. 
  5. Если в шаблоне параметр описан, как обязательный, и для него в шаблоне указано значение по умолчанию (Default value), то при отсутствии данного параметра в запросе API ошибка не возникнет. При формировании письма будет подставлено значение по умолчанию.
  6. Для составных типов можно настроить обязательность того или иного поля, но значений по умолчанию для полей не предусмотрено. При запросе через API обязательность поля контролируется. Т.е. если поле обязательно, то при отсутствии поля в запросе будет ошибка типа "The parameters: InvalidType error for value (NULL) of property Products[0].cost. The expected type is System.Decimal."

 

Также, с документацией API данного метода можно ознакомиться здесь.

https://ofsys.com/webservices/en-US/#tab=doc&section=services&application=OFC4&service=Sendings&method=SendSingle2

0 Comments

Please sign in to leave a comment.