Общая информация

Атрибуты клиентов в Sailplay — это дополнительные данные, которые можно хранить для описания и персонализации клиентов. Они расширяют стандартный профиль пользователя и позволяют:

• Использовать значения для фильтрации и сегментации клиентов (например, выделять всех пользователей с определённым городом или интересом).
• Настраивать персонализированные коммуникации и триггерные сценарии.
• Подставлять данные в шаблоны сообщений. Атрибуты можно использовать как переменные в email, SMS и push-уведомлениях.
• Хранить дополнительный идентификатор клиента (например, внешний ID из CRM или ID устройства с мобильным приложением).
• Запускать акции на основе конкретных значений (например, уникальное предложение товара, выбранного клиентом).

Каждый атрибут имеет три ключевых характеристики: тип, кардинальность и уникальность.

---

Типы атрибутов

Тип определяет формат и допустимые значения атрибута.

Тип	Подтип	Значение	Примеры значений
string	value	Текстовая строка	"Moscow"
date	value	Дата в формате YYYY‑MM‑DD	"1995‑04‑23"
integer	value	Целое число	42
sku	reference	Ссылка на товар (SKU)	{ "ref_type": "sku", "ref_id": "171850" }
product	reference	Ссылка на товар (id товара в системе Sailplay)	{"ref_type":"product", "ref_id":"875435"}
department	reference	Ссылка на департамент (id департамента в системе Sailplay)	{"ref_type":"department", "ref_id":"4552"}
user	reference	Ссылка на клиента (user_id в системе Sailplay)	{"ref_type":"user", "ref_id":"114765948"}

Атрибуты подтипа reference используются для связи клиента со сторонними сущностями. Например, тип sku позволяет создавать связь клиента с товаром. Эта функциональность даёт возможность задавать персонализированную скидку на конкретный товар для клиента.

---

Кардинальность атрибутов

Кардинальность определяет, может ли у клиента быть несколько значений одного атрибута.

• Одиночное значение (is_array = false)
  Атрибут хранит только одно значение у клиента.
  Примеры:

  • Место рождения — "Denpasar"
  • Любимый фрукт — "Apple"

• Множественные значения (is_array = true)
  Атрибут хранит список значений у клиента.
  Примеры:

  • Имена детей — ["Annet", "Jhon"]
  • Любимые категории товаров — ["electronics", "toys", "books"]

---

Уникальность атрибутов

Уникальность (is_unique = true) определяет, может ли значение атрибута использоваться как идентификатор клиента. Если уникальность включена, значение должно быть уникальным среди всех клиентов. Такой атрибут может использоваться для поиска, идентификации и интеграции клиентов (примеры: card_number, crm_id, session_id).

Атрибуты без уникальности (is_unique = false) могут повторяться у разных клиентов (например, «город проживания» или «интересы»).

Как создать атрибут

Напишите в техподдержку: support@sailplay.ru и сообщите:

1. partner_id — идентификатор кабинета.
2. name — техническое название (латиницей, без пробелов и спецсимволов).
   Минимальная длина: 4 символа. Максимальная: 32 символа. Пример: city_name.
3. title — пользовательское название для отображения в личном кабинете. Пример: Город проживания.
4. description — краткое описание назначения атрибута.
   Пример: Город проживания клиента для исключения Москвичей из коммуникации по Санкт-Петербургу.
5. attribute_type — тип атрибута.
6. is_array — кардинальность атрибута (укажите, если для одного атрибута у одного клиента может быть список значений).
7. is_unique — уникальность атрибута (укажите, если атрибут будет использован в качестве идентификатора клиента).

Предварительно заданные свойства атрибутов не имеют возможности изменения в процессе их использования.

---

Карта методов API

Ниже — список методов, которые используются для работы с атрибутами клиентов. При переносе документации на ваш портал замените ссылки на соответствующие страницы в вашем разделе API.

Группа	Назначение	URL метода
Атрибуты клиентов	Получить атрибуты	/api/v2/users/attributes/get-partner-attributes-list/
	Получить значения атрибута	/api/v2/users/attributes/get-values-by-attribute/
	Получить значения атрибутов клиента	/api/v2/users/attributes/get-values-by-user/
	Добавить значение атрибута	/api/v2/users/attributes/set-values-for-user/
	Добавить значение в атрибут-массив	/api/v2/users/attributes/push-values-to-array/
	Удалить значение из атрибута-массива	/api/v2/users/attributes/pop-values-from-array/

---

Получить список всех атрибутов

Для получения атрибутов, которые ранее были добавлены в личный кабинет, используйте метод /api/v2/users/attributes/get-partner-attributes-list/. Метод поддерживает пагинацию по номеру страницы с указанием количества элементов на страницу.

Request

curl --request GET \
  --url https://api.sailplay.ru/api/v2/users/attributes/get-partner-attributes-list/ \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data token=*** \
  --data store_department_id=*** \
  --data page=1 \
  --data per_page=50

Response

{
  "status": "ok",
  "result": {
    "Region": [
      {
        "description": "регион клиента, выбранный клиентом вручную в личном кабинете",
        "title": "Регион клиента",
        "is_array": false,
        "is_unique": false,
        "type": {
          "name": "string",
          "parameters": {}
        }
      }
    ],
    "City": [
      {
        "description": "Автоматически определенные города клиента",
        "title": "Город клиента",
        "is_array": true,
        "is_unique": false,
        "type": {
          "name": "string",
          "parameters": {}
        }
      }
    ]
  }
}

---

Получить значения атрибута

Для получения значений атрибута выполните запрос /api/v2/users/attributes/get-values-by-attribute/ с указанием списка атрибутов.

• attr_names — list — список технических названий атрибутов.

Ниже пример запроса для получения значений двух атрибутов: Region (is_array = false) и City (is_array = true). В ответе возвращаются массивы по двум атрибутам:

• В рамках атрибута Region возвращается массив, состоящий из словарей.
• В рамках атрибута City возвращается массив, состоящий из словарей с вложенным массивом значений.

Request

curl --request GET \
  --url https://api.sailplay.ru/api/v2/users/attributes/get-values-by-attribute/ \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data token=*** \
  --data store_department_id=*** \
  --data page=1 \
  --data per_page=50 \
  --data 'attr_names=["Region","City"]'

Response

{
  "status": "ok",
  "result": {
    "City": [
      {
        "value": [
          "Moscow"
        ]
      },
      {
        "value": [
          "Kiyv",
          "Minsk",
          "Odessa"
        ]
      }
    ],
    "Region": [
      {
        "value": "Europe"
      },
      {
        "value": "North America"
      },
      {
        "value": "Russia"
      }
    ]
  }
}

---

Получить значения атрибутов клиента

Для получения списка значений атрибутов клиента выполните запрос /api/v2/users/attributes/get-values-by-user/ с перечислением атрибутов.

• attributes — string — список технических названий атрибутов, разделённых запятыми. Пробелы вокруг разделителя не допускаются.

Request

curl --request GET \
  --url https://api.sailplay.ru/api/v2/users/attributes/get-values-by-user/ \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data token=*** \
  --data store_department_id=*** \
  --data user_phone=79998880011 \
  --data 'attributes=Region,City'

Response

{
  "status": "ok",
  "result": {
    "City": [
      {
        "title": "Город клиента",
        "description": "Автоматически определенные города клиента",
        "value": [
          "Almaty",
          "Minsk",
          "Boston"
        ],
        "value_id": [
          948618149,
          948618150,
          948618151
        ]
      }
    ],
    "Region": [
      {
        "title": "Регион клиента",
        "description": "регион клиента, выбранный клиентом вручную в личном кабинете",
        "value": "Russia",
        "value_id": 262833408
      }
    ]
  }
}

Если атрибут не найден или название было передано неверно — система вернёт пустой result:

Response

{
  "status": "ok",
  "result": {}
}

Параметр attributes не является обязательным. При отсутствии параметра attributes система вернёт все атрибуты, которые закреплены за клиентом.

---

Добавить значение атрибута

Метод /api/v2/users/attributes/set-values-for-user/ используется для присвоения атрибутам новых и перезаписи уже заданных значений.

Request

curl --request POST \
  --url https://api.sailplay.ru/api/v2/users/attributes/set-values-for-user/ \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data token=*** \
  --data store_department_id=*** \
  --data user_phone=79998880011 \
  --data 'attributes=[{"name":"country","value":"USA"},{"name":"region","value":"Boston"}]'

Response

{
  "status": "ok"
}

Параметр:

• attributes — array — массив словарей с атрибутами и их значениями.

Пример структуры attributes:

attributes

[
  {
    "name": "country",
    "value": "USA"
  }
]

• name — string — техническое название атрибута.
• value — тип элемента должен соответствовать типу атрибута.

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

attributes

[
  {
    "name": "country",
    "value": "USA"
  },
  {
    "name": "region",
    "value": "Boston"
  }
]

Если атрибут is_array = true, то value обязательно нужно заключать в квадратные скобки — вне зависимости от того, передаёте вы одно значение или несколько:

attributes

[
  {
    "name": "child_names",
    "value": [
      "Sam",
      "John"
    ]
  }
]

---

Добавить массив значений

Метод /api/v2/users/attributes/push-values-to-array/ предназначен для добавления новых элементов к атрибуту клиента с кардинальностью is_array = true.

Request

curl --request POST \
  --url https://api.sailplay.ru/api/v2/users/attributes/push-values-to-array/ \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data token=*** \
  --data store_department_id=*** \
  --data user_phone=79998880011 \
  --data 'attributes={"name":"City","value":["Moscow","Astana"]}'

Response

{
  "status": "ok"
}

Параметр:

• attributes — object — словарь атрибутов и значений. За один вызов метод обрабатывает только один атрибут.
  • value — array — список добавляемых значений (минимум один элемент). Тип элементов массива должен соответствовать типу атрибута.

Пример структуры attributes:

attributes

{
  "name": "City",
  "value": [
    "Moscow",
    "Astana"
  ]
}

---

Удалить значение из атрибут-массива

Метод /api/v2/users/attributes/pop-values-from-array/ удаляет значения атрибутов с кардинальностью is_array = true. Типы параметра attributes соответствуют типам в методе добавления массива значений.

Request

curl --request POST \
  --url https://api.sailplay.ru/api/v2/users/attributes/pop-values-from-array/ \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data token=*** \
  --data store_department_id=*** \
  --data user_phone=79998880011 \
  --data 'attributes={"name":"City","value":["Moscow"]}'

Response

{
  "status": "ok"
}