API

Клиенты

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

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

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

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

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

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

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

3. Телефон (phone)

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

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

4. Email клиента (email)

Уникальный адрес электронной почты клиента. Допускается один email на клиента. При передаче выполняется валидация формата email.

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

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

📘

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

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

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

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

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

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

ГруппаНазначениеURL метода
КлиентыПолучить информацию о клиенте/api/v2/users/info/
Создать нового клиента/api/v2/users/add/
Обновить существующего клиента/api/v2/users/update/
Объединить клиентские записи/api/v2/users/merge/

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

Для создания клиента с помощью метода /api/v2/users/add/ необходимо указать хотя бы один из идентификаторов: origin_user_id, phone или email.

Пример запроса (cURL):

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=d21a23d5ff695377ca99a3a6cf9b4a1ec6452b00 \
     --data store_department_id=14864 \
     --data user_phone=79653215476 \
     --data [email protected] \
     --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/ с параметрами, аналогичными методу создания. В запросе нужно передать один существующий идентификатор, указывающий на запись клиента: user_id, origin_user_id, user_phone или email.

Метод обновления поддерживает специальные параметры для смены идентификаторов:

  • new_phone
  • new_email
  • new_origin_user_id

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

Пример запроса (cURL):

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=d21a23d5ff695377ca99a3a6cf9b4a1ec6452b00 \
     --data store_department_id=2444 \
     --data user_phone=79538889977 \
     --data new_phone=79994443322 \
     --data new_origin_user_id=null \
     --data [email protected]

Ошибки при конфликте идентификаторов:

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

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

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

Если клиент не найден:

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

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

Метод /api/v2/users/info/ возвращает:

  • Основные сведения (ФИО, дата регистрации, дата рождения).
  • Статусы подписок на каналы коммуникаций (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
  }
}
  • Историю покупок и историю по бонусам (начисления, списания, сгорания).
    Для включения истории передайте параметр hystory=1. Дополнительно можно ограничить период параметрами from_date и to_date (формат, '2024-06-30 00:00').

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

{
	"history": [
		{
			"action": "expiration",
			"action_date": "2025-07-31T05:05:29.239",
			"is_completed": true,
			"points_delta": -250,
			"name": "Списание неиспользованных бонусов от \"Начисление баллов (Сгораемые 250 для В зоне риска)\""
		},
		{
			"name": "Сгораемые 250 для \"В зоне риска\" ",
			"is_completed": true,
			"expiry_info": [],
			"order_num": null,
			"action_date": "2025-07-23T04:58:44.423",
			"action": "extra",
			"points_delta": 250
		},
		{
			"is_completed": true,
			"store_department_id": 7849,
			"order_num": "20250611_120611_89_1_258_37",
			"id": 1176711344,
			"debited_points_delta": 0,
			"name": "Покупка",
			"action_date": "2025-06-11T12:06:45.301",
			"points_delta": 0,
			"action": "purchase",
			"attributes": [],
			"price": 799
    }
	]
}

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

Чтобы проверить наличие нескольких идентификаторов клиента за один запрос, передайте multi=1 и укажите в запросе несколько идентификаторов разных типов (например, phone и email).
Если передать несколько идентификаторов одного типа (например, два email), проверка будет выполнена только по одному из них.

Пример ответа при multi=1:

{  
	"status": "ok",  
	"origin_user_id": {},  
	"user_id": {},  
	"phone": {  
		"category": null,  
		"first_name": null,  
		"last_name": null,  
		"middle_name": null,  
		"referral_promocode": "684GLMРР",  
		"origin_user_id": "12345",  
		"sex": 1,  
		"phone": "79534311111",  
		"points": {  
			"spent_extra": 1000,  
			"confirmed": 2,  
			"total": 2,  
			"spent": 0,  
			"unconfirmed": 0  
		},  
		"avatar": null,  
		"email": null,  
		"birth_date": null,  
		"id": 376442122  
	},  
	"identification": {},  
	"email": {  
		"category": null,  
		"first_name": null,  
		"last_name": null,  
		"middle_name": null,  
		"referral_promocode": "4FFVHF",  
		"origin_user_id": "12345555666",  
		"sex": 1,  
		"phone": "79534334455",  
		"points": {  
			"spent_extra": 10000,  
			"confirmed": 200,  
			"total": 220,  
			"spent": 0,  
			"unconfirmed":20  
		},  
		"avatar": null,  
		"email": "[email protected]",  
		"birth_date": null,  
		"id": 376443577  
	}  
}

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

Метод /api/v2/users/merge/ объединяет два клиентских профиля в один. История событий двух профилей (покупки, начисления баллов, теги и другое) будет доступна в одной карточке.

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

Набор параметров:

ПараметрЗначение
from_uiduser_id клиента from
to_uiduser_id клиента to
from_phonephone клиента from
to_phonephone клиента to
from_emailemail клиента from
to_emailemail клиента to
from_oidorigin_user_id клиента from
to_oidorigin_user_id клиента to

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

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

Если одно и то же поле заполнено в обоих профилях, Sailplay берёт значение по таблице:

ПараметрыИтоговое значение из профиля
user_id,phone, emailto
origin_user_id,first_name, middle_name, last_name,birth_date,sexfrom

Если заполнено только в одном месте — берёт это заполненное значение, независимо от того, from это или to.