Сессия и пользователи тема 7 из 27

Профили покупателя, счёт и подписки

Группа /api/profile — раздел личного кабинета магазина (модуль sale): сохранённые профили плательщика, внутренний счёт, купоны, накопительные скидки и подписки на поступление товара. Профиль учётной записи (имя, e-mail, пароль) — отдельная группа, см. Профиль пользователя.

в этой теме 7
  1. Методы профилей покупателя
  2. Сценарий: профили плательщика
  3. Счёт, купоны, скидки
  4. Подписки на поступление товара
  5. Где настраиваются профили, счёт и подписки
  6. Ограничения профилей покупателя
  7. Что почитать после профилей покупателя

Все методы, кроме GET /api/profile/fields, только для вошедших: гость получает 401 и {"success": false, "error": "Требуется авторизация"}. Сессию методы группы не начинают: витрина передаёт X-Session-Id, полученный при входе (Сессия и авторизация).

Методы профилей покупателя

МетодАдресКто вызываетНачинает сессию
Список профилей покупателяGET /api/profileвошедшийнет
Добавление профиляPOST /api/profileвошедшийнет
Изменение профиляPUT /api/profileвошедшийнет
Удаление профиляDELETE /api/profileвошедшийнет
Поля профиля по типу плательщикаGET /api/profile/fieldsгость и вошедшийнет
Счёт пользователяGET /api/profile/accountвошедшийнет
История операций по счётуGET /api/profile/account/historyвошедшийнет
Персональные купоныGET /api/profile/personalCouponвошедшийнет
Накопительные скидкиGET /api/profile/cumulativeDiscountвошедшийнет
Подписки на поступление товараGET /api/profile/subscriptionвошедшийнет
Подписаться на поступлениеPOST /api/profile/subscriptionвошедшийнет
Отменить подпискуDELETE /api/profile/subscription/{subscriptionID}вошедшийнет

Постраничные методы принимают limit (по умолчанию 10) и offset и отдают pagen (total, limit, offset).

Сценарий: профили плательщика

Профиль нужен, чтобы покупатель не вводил данные заказа заново: на оформлении заказа он выбирает готовый профиль (profileID в POST /api/sale/order/refresh, см. Заказ).

  1. GET /api/profile/fields?personTypeId=1 — свойства заказа типа плательщика: по ним витрина строит форму. Типы плательщиков — GET /api/sale/personTypes.
  2. POST /api/profile — сохранить профиль: name, personTypeID и fields (массив {id, name, value}, id — ID свойства из шага 1).
  3. GET /api/profile — список профилей пользователя.
  4. PUT /api/profile — изменить: saleProfileID, name, fields (массив {id, value} или {code, value}).
  5. DELETE /api/profile — удалить: параметр userProfileID.

Чужой или несуществующий профиль в PUT и DELETE не вызывает ошибку: метод ничего не меняет.

Поля профиля

GET /api/profile/fields открыт гостю. Состав полей — штатные свойства заказа Битрикса (Магазин -> Настройки -> Свойства заказа). Ответ стенда, сокращён:

json
{
    "data": [
        {
            "id": 1,
            "personTypeId": 1,
            "name": "Ф.И.О.",
            "type": "TEXT",
            "requied": "Y",
            "sort": 100,
            "userProps": "Y",
            "isLocation": "N",
            "code": "fio",
            "active": "Y",
            "multiple": "N"
        }
    ]
}

Ключ обязательности называется requied (так он назван в самом Битриксе), значения — "Y" / "N".

Добавление профиля

bash
curl -X POST "https://example.ru/api/profile" \
  -H "X-Session-Id: JLfAjGOFZ3qb2elyU2VIxlhvt1kYjQMZ" \
  -H "Content-Type: application/json" \
  -d '{"name": "Домашний адрес", "personTypeID": 1, "fields": [{"id": 12, "name": "Имя", "value": "Сергей"}]}'

Ответ:

json
{
    "data": {
        "id": 5,
        "name": "Домашний адрес",
        "userId": 12,
        "personTypeId": 1,
        "dateUpdate": "01.01.2026 12:00:00",
        "fields": [
            { "id": 101, "name": "Имя", "code": "NAME", "value": "Иван", "type": "TEXT", "sort": 100 }
        ]
    }
}

Счёт, купоны, скидки

МетодЧто отдаёт
GET /api/profile/accountвнутренний счёт в рублях (если счёта нет, он создаётся): id, userId, currentBudget, currency, locked
GET /api/profile/account/historyтранзакции счёта (order, filter по transactDate, currency): amount, debit, orderId, description
GET /api/profile/personalCouponкупоны пользователя: coupon, active, activeFrom, activeTo, maxUse, useCount, discount
GET /api/profile/cumulativeDiscountнакопительные скидки: userTotalBuy и пороги ranges (sum, value, type)

У пользователя может быть несколько счетов в разных валютах; история отдаёт операции одного, по умолчанию рублёвого.

Подписки на поступление товара

Кнопка «Сообщить о поступлении» на карточке товара, которого нет в наличии: POST /api/profile/subscription с itemID (ID товара или торгового предложения) и необязательным email (если не передан, берётся из профиля; в профиль не сохраняется). Метод идемпотентен: при уже активной подписке вернётся её ID и result = ALREADY. Письмо о поступлении отправляет штатный агент модуля catalog.

json
{
    "data": { "subscriptionId": 15, "result": "CREATED" }
}

GET /api/profile/subscription отдаёт активные подписки (новые первыми), DELETE /api/profile/subscription/15 отменяет подписку. Ошибки подписки: 400 — itemID не положительный, подписка запрещена настройками каталога, e-mail не прошёл проверку или не передан и не заполнен в профиле; 404 — товара нет в каталоге; при отмене 404 — подписки нет или она чужая.

Где настраиваются профили, счёт и подписки

  • Поля профиля, типы плательщиков, счета, купоны и скидки — штатные настройки магазина Битрикса (модуль sale).
  • Подписка на поступление включается настройками каталога Битрикса.
  • Вкладка «Магазин» в настройках модуля относится к заказу (лимиты, оформление), на эти методы напрямую не влияет — см. Заказ.

Ограничения профилей покупателя

  • Часть ошибок приходит телом {errors: [...]}, часть — {success: false, error: текст}: читайте текст из error или errors[0].

Что почитать после профилей покупателя

Подключим BIK.REST-API к вашему сайту

Оставьте заявку — установим и настроим модуль, ответим на вопросы по API.

c заботой о вас, мы используем cookie на своем сайте, чтобы интернет был чистым и прекрасным