Обновлено: 24.08.2026

Пользователи

Единый профиль болельщика, ученика школы или участника мероприятия — общее ядро для всех продуктов экосистемы «Вираж». Один ID работает в CRM, ДЮСШ, билетах и лояльности одновременно.

Обзор методов

Метод	Путь	Описание
`GET`	`/users`	Список пользователей
`GET`	`/users/{id}`	Получить профиль пользователя
`POST`	`/users`	Создать пользователя
`PATCH`	`/users/{id}`	Обновить профиль
`DELETE`	`/users/{id}`	Удалить пользователя
`GET`	`/users/{id}/activity`	Лента активности
`POST`	`/users/merge`	Объединить дубли

Список пользователей

Эндпоинт

GET /users

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

Параметры

Параметр	Где	Тип	Обязателен	Описание
`limit`	`query`	integer	нет	Размер страницы, от 1 до 100. По умолчанию — 20.
`cursor`	`query`	string	нет	Значение next_cursor из предыдущего ответа.
`loyalty_status`	`query`	string	нет	Фильтр по уровню лояльности: silver, gold, platinum.
`created_after`	`query`	string (ISO 8601)	нет	Только пользователи, зарегистрированные после указанной даты.

Запрос

curl "https://api.virazh.io/v1/users?limit=20&loyalty_status=gold" \
  -H "Authorization: Bearer sk_test_51H..."

Ответ

{
  "data": [
    { "id": "usr_8f21c", "name": "Иван Петров", "loyalty_status": "gold" },
    { "id": "usr_71bd0", "name": "Мария Орлова", "loyalty_status": "gold" }
  ],
  "has_more": true,
  "next_cursor": "usr_71bd0"
}

Поля ответа

Поле	Тип	Описание
`data`	`array<User>`	Список карточек пользователей на текущей странице.
`has_more`	`boolean`	Есть ли следующая страница.
`next_cursor`	`string \| null`	Курсор для запроса следующей страницы, если has_more = true.

Получить профиль пользователя

Эндпоинт

GET /users/{id}

Возвращает карточку пользователя с базовыми полями и ссылками на связанные сущности — программу лояльности, покупки, посещаемость.

Параметры

Параметр	Где	Тип	Обязателен	Описание
`id`	`путь`	string	да	Идентификатор пользователя, например usr_8f21c.

Запрос

curl https://api.virazh.io/v1/users/usr_8f21c \
  -H "Authorization: Bearer sk_test_51H..."

Ответ

{
  "id": "usr_8f21c",
  "name": "Иван Петров",
  "phone": "+7 900 123-45-67",
  "email": "ivan@example.com",
  "created_at": "2026-03-14T09:02:00Z",
  "loyalty": {
    "status": "silver",
    "points": 1240
  }
}

Поля ответа

Поле	Тип	Описание
`id`	`string`	Идентификатор пользователя.
`name`	`string`	Полное имя.
`phone`	`string`	Телефон в формате +7 900 123-45-67.
`email`	`string \| null`	Электронная почта, если указана.
`created_at`	`string (ISO 8601)`	Дата и время регистрации.
`loyalty.status`	`string`	Текущий уровень программы лояльности.
`loyalty.points`	`integer`	Баланс баллов.

Создать пользователя

Эндпоинт

POST /users

Регистрирует нового пользователя в системе. Если пользователь с таким телефоном уже есть — вернёт существующую карточку без дубликата.

Параметры

Параметр	Где	Тип	Обязателен	Описание
`name`	`тело`	string	да	Полное имя пользователя.
`phone`	`тело`	string	да	Телефон в формате +7XXXXXXXXXX — основной идентификатор для поиска дублей.
`email`	`тело`	string	нет	Электронная почта.
`source`	`тело`	string	нет	Источник регистрации: сайт, приложение, стойка на стадионе. Для аналитики.

Запрос

curl https://api.virazh.io/v1/users \
  -X POST \
  -H "Authorization: Bearer sk_test_51H..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Иван Петров",
    "phone": "+79001234567"
  }'

Ответ

{
  "id": "usr_8f21c",
  "name": "Иван Петров",
  "phone": "+7 900 123-45-67",
  "created_at": "2026-08-25T11:40:12Z"
}

Поля ответа

Поле	Тип	Описание
`id`	`string`	Идентификатор созданного (или найденного существующего) пользователя.
`name`	`string`	Полное имя.
`phone`	`string`	Телефон в нормализованном формате.
`created_at`	`string (ISO 8601)`	Дата создания карточки.

Обновить профиль

Эндпоинт

PATCH /users/{id}

Частичное обновление — передавайте только изменившиеся поля. Телефон и email проходят повторную проверку на уникальность.

Параметры

Параметр	Где	Тип	Обязателен	Описание
`id`	`путь`	string	да	Идентификатор пользователя.
`name`	`тело`	string	нет	Новое имя.
`phone`	`тело`	string	нет	Новый телефон.
`email`	`тело`	string	нет	Новый email.

Запрос

curl https://api.virazh.io/v1/users/usr_8f21c \
  -X PATCH \
  -H "Authorization: Bearer sk_test_51H..." \
  -H "Content-Type: application/json" \
  -d '{ "email": "ivan.petrov@example.com" }'

Ответ

{
  "id": "usr_8f21c",
  "email": "ivan.petrov@example.com",
  "updated_at": "2026-08-25T11:44:02Z"
}

Поля ответа

Поле	Тип	Описание
`id`	`string`	Идентификатор пользователя.
`updated_at`	`string (ISO 8601)`	Дата последнего обновления профиля.

Удалить пользователя

Эндпоинт

DELETE /users/{id}

Мягкое удаление — профиль скрывается из выборок и рассылок, но история покупок и посещений сохраняется для отчётности. Восстановление возможно только через поддержку.

Параметры

Параметр	Где	Тип	Обязателен	Описание
`id`	`путь`	string	да	Идентификатор пользователя.

Запрос

curl https://api.virazh.io/v1/users/usr_8f21c \
  -X DELETE \
  -H "Authorization: Bearer sk_test_51H..."

Ответ

{
  "id": "usr_8f21c",
  "status": "deleted",
  "deleted_at": "2026-08-25T12:10:00Z"
}

Поля ответа

Поле	Тип	Описание
`id`	`string`	Идентификатор удалённого пользователя.
`status`	`string`	Всегда deleted при успешном ответе.
`deleted_at`	`string (ISO 8601)`	Дата и время удаления.

Лента активности

Эндпоинт

GET /users/{id}/activity

Хронологический журнал действий пользователя — покупки, посещения тренировок, начисления баллов, участие в рассылках. Полезно для карточки клиента в вашей CRM.

Параметры

Параметр	Где	Тип	Обязателен	Описание
`id`	`путь`	string	да	Идентификатор пользователя.
`limit`	`query`	integer	нет	Количество записей, до 50. По умолчанию — 10.
`type`	`query`	string	нет	Фильтр по типу события: ticket_purchase, loyalty_accrued, training_attended и др.

Запрос

curl "https://api.virazh.io/v1/users/usr_8f21c/activity?limit=10" \
  -H "Authorization: Bearer sk_test_51H..."

Ответ

{
  "user_id": "usr_8f21c",
  "data": [
    { "type": "ticket_purchase", "at": "2026-08-20T18:02:00Z", "amount": 800 },
    { "type": "loyalty_accrued", "at": "2026-08-20T18:03:00Z", "amount": 40 },
    { "type": "training_attended", "at": "2026-08-19T16:00:00Z" }
  ]
}

Поля ответа

Поле	Тип	Описание
`user_id`	`string`	Идентификатор пользователя.
`data`	`array<ActivityEvent>`	Список событий с полями type, at и параметрами события.

Объединить дубли

Эндпоинт

POST /users/merge

Склеивает две карточки одного человека (например, заведённые по телефону и по email) в одну — баллы, история и билеты переносятся на primary_id, вторая карточка помечается как объединённая.

Параметры

Параметр	Где	Тип	Обязателен	Описание
`primary_id`	`тело`	string	да	Карточка, которая останется активной.
`duplicate_id`	`тело`	string	да	Карточка-дубль, которая будет объединена с primary_id.

Запрос

curl https://api.virazh.io/v1/users/merge \
  -X POST \
  -H "Authorization: Bearer sk_test_51H..." \
  -H "Content-Type: application/json" \
  -d '{ "primary_id": "usr_8f21c", "duplicate_id": "usr_11a90" }'

Ответ

{
  "primary_id": "usr_8f21c",
  "merged_from": "usr_11a90",
  "points_merged": 210
}

Поля ответа

Поле	Тип	Описание
`primary_id`	`string`	Идентификатор итоговой карточки.
`merged_from`	`string`	Идентификатор объединённой (закрытой) карточки.
`points_merged`	`integer`	Сколько баллов перенесено на primary_id.

Полезно знать

Поле phone — основной идентификатор при создании: повторная регистрация с тем же номером вернёт существующего пользователя, а не создаст дубликат.
Для списков используйте limit до 100 записей за раз и next_cursor из ответа — офсетная пагинация (page=) не поддерживается.
Мягкое удаление (DELETE /users/{id}) скрывает профиль из выборок и рассылок, но сохраняет историю для отчётности — это не то же самое, что обращение по праву на забвение, которое обрабатывается вручную через поддержку клуба.
При объединении дублей (/users/merge) необратимо: вторая карточка помечается объединённой и теряет самостоятельный доступ, все баллы и билеты переходят на primary_id.

Документация «Вираж»

Пользователи

Обзор методов

Список пользователей

Получить профиль пользователя

Создать пользователя

Обновить профиль

Удалить пользователя

Лента активности

Объединить дубли

Полезно знать