Основная информация

Клиентская запись в Sailplay — это унифицированная карточка покупателя, в которой агрегируются его основная информация, идентификаторы, контактные данные, статусы в программе лояльности, теги и любые другие произвольные атрибуты.
Эта сущность лежит в основе персонализированных коммуникаций, сегментации, расчёта бонусов и скидок, а также сценариев автоматизации маркетинга.

---

Идентификаторы клиентов

Для обращения к клиенту в API и процессах автоматизации используются следующие ключевые идентификаторы.

Основной идентификатор клиента (user_id)

Уникальный внутренний идентификатор, автоматически присваиваемый Sailplay при создании записи.
Является основным идентификатором в системе. Может быть изменён только при объединении клиентских профилей.

---

Внешний идентификатор (origin_user_id)

Дополнительный идентификатор клиента, обычно используемый для связи с внешними источниками данных
(например, номер карты лояльности или идентификатор из CRM-системы).

• может содержать произвольные строковые значения
• допускает изменение и обновление при необходимости

---

Телефон (user_phone)

Уникальный номер телефона клиента. Используется в первую очередь для SMS-коммуникаций,
но может применяться и как идентификатор во внешних интеграциях.

Требования к формату:

• международный формат без символа +, например 79998887766
• у одного клиента может быть только один номер телефона
• создание записи с городским номером недопустимо

---

Email (email)

Уникальный адрес электронной почты клиента.

• допускается один email на клиента
• выполняется валидация формата email

---

Дополнительный идентификатор (атрибут)

Произвольный атрибут с уникальным значением
(например, идентификатор из сторонней системы).

Для такой интеграции требуется специальный подход к работе с сущностями
(см. соответствующую документацию).

к сведению

Любые операции с клиентом в Sailplay
(создание заказов, начисление бонусов, назначение тегов и т. п.)
могут выполняться по любому из идентификаторов:

user_id, origin_user_id, phone, email
или по значению дополнительного атрибута.

---

Основные параметры API для создания и обновления клиентов

Эти параметры используются в бизнес-логике Sailplay
для сегментации, персонализации и настройки акций.

• first_name — имя (например, Иван)
• middle_name — отчество (например, Иванович)
• last_name — фамилия (например, Иванов)
• birth_date — дата рождения в формате YYYY-MM-DD
• sex — пол:
  • 1 — мужской
  • 2 — женский
  • 3 — другой
• register_date — дата регистрации
  минимально допустимая дата — 1971-01-01

примечание

Параметры данного раздела не являются обязательными.

---

Карта методов API для клиентов

Назначение	Метод
Получить информацию о клиенте	/api/v2/users/info/
Создать клиента	/api/v2/users/add/
Обновить клиента	/api/v2/users/update/
Объединить клиентов	/api/v2/users/merge/

---

Создание клиента

Для создания клиента необходимо указать хотя бы один идентификатор:

• origin_user_id
• phone
• email

Пример запроса

curl --request POST \
  --url https://api.sailplay.ru/api/v2/users/add/ \
  --header 'accept: application/json' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data token=TOKEN \
  --data store_department_id=14864 \
  --data user_phone=79653215476 \
  --data email=ivanovivan@mail.ru \
  --data origin_user_id=12345 \
  --data first_name=Иван \
  --data middle_name=Иванович \
  --data last_name=Абрамов \
  --data birth_date=1983-11-07 \
  --data sex=1 \
  --data register_date=2012-04-24

Если клиент уже существует:

{
  "status": "error",
  "status_code": -5100,
  "message": "User already exist"
}

---

Обновление клиента

Метод: /api/v2/users/update/

Поддерживает смену идентификаторов:

• new_phone
• new_email
• new_origin_user_id

Для удаления значения идентификатора передайте null.

Пример запроса

curl --request POST \
  --url https://api.sailplay.ru/api/v2/users/update/ \
  --header 'accept: application/json' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data token=TOKEN \
  --data store_department_id=2444 \
  --data user_phone=79538889977 \
  --data new_phone=79994443322 \
  --data new_origin_user_id=null \
  --data new_email=myname@gmail.com

Ошибки

{ "status_code": -5102, "message": "Phone is used" }

{ "status_code": -5103, "message": "Email is used" }

{ "status_code": -5122, "message": "User ID принадлежит другому пользователю" }

{ "status_code": -4000, "message": "User not found" }

---

Получение информации о клиенте

Метод получения информации о клиенте возвращает:

• Основные сведения о клиенте
  (ФИО, дата регистрации, дата рождения).

• Статусы подписок на каналы коммуникаций (email, SMS, push).
  Для получения статусов необходимо передать параметр subscriptions=1.
  В ответе будет массив subscriptions. Наличие значения в массиве означает активную подписку на соответствующий канал.

Примеры ответов со статусами подписок

{
  "subscriptions": [
    "email_all",
    "sms_all",
    "push_all"
  ]
}

{
  "subscriptions": [
    "email_all"
  ]
}

{
  "subscriptions": [
    "push_all"
  ]
}

{
  "subscriptions": [
    "sms_all"
  ]
}

---

Бонусный баланс клиента

Метод возвращает текущий бонусный баланс клиента:

• confirmed — подтверждённые баллы, доступны к использованию
• unconfirmed — баллы, ожидающие подтверждения покупки
• total — общее количество баллов (confirmed + unconfirmed)
• spent — потраченные баллы на подарки
• spent_extra — прочие списания

{
  "points": {
    "spent_extra": 1000,
    "confirmed": 255,
    "total": 355,
    "spent": 10,
    "unconfirmed": 100
  }
}

---

История покупок и бонусных операций

Метод позволяет получить историю:

• покупок,
• начислений баллов,
• списаний,
• сгорания бонусов.

Для включения истории необходимо передать параметр history=1.
Дополнительно можно ограничить период параметрами from_date и to_date
(формат: YYYY-MM-DD HH:MM:SS).

Пример фрагмента ответа с историей:

{
  "history": [
    {
      "action": "expiration",
      "action_date": "2025-07-31T05:05:29.239",
      "is_completed": true,
      "points_delta": -250,
      "name": "Списание неиспользованных бонусов"
    },
    {
      "action": "extra",
      "action_date": "2025-07-23T04:58:44.423",
      "is_completed": true,
      "points_delta": 250,
      "name": "Начисление бонусов"
    },
    {
      "action": "purchase",
      "action_date": "2025-06-11T12:06:45.301",
      "is_completed": true,
      "order_num": "20250611_120611_89_1_258_37",
      "points_delta": 0,
      "price": 799
    }
  ]
}

---

Проверка нескольких идентификаторов (multi)

Для проверки нескольких идентификаторов передайте multi=1.

Если указано несколько идентификаторов одного типа, будет использован только один.

---

Объединение клиентских записей

Метод /api/v2/users/merge/

В запросе можно указывать пару идентификаторов как одного, так и разного типа
(например, from_email → to_oid).

Набор параметров для объединения

Параметр	Значение
from_uid	user_id клиента from
to_uid	user_id клиента to
from_phone	phone клиента from
to_phone	phone клиента to
from_email	email клиента from
to_email	email клиента to
from_oid	origin_user_id клиента from
to_oid	origin_user_id клиента to

Важно

В одном запросе допускается указать только одну пару идентификаторов.

Правила объединения

Поле	Итог
user_id, phone, email	из to
origin_user_id, ФИО, дата рождения, пол	из from

Если поле заполнено только в одном профиле — оно сохраняется.