Все методы, кроме 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, см. Заказ).
GET /api/profile/fields?personTypeId=1— свойства заказа типа плательщика: по ним витрина строит форму. Типы плательщиков —GET /api/sale/personTypes.POST /api/profile— сохранить профиль:name,personTypeIDиfields(массив{id, name, value},id— ID свойства из шага 1).GET /api/profile— список профилей пользователя.PUT /api/profile— изменить:saleProfileID,name,fields(массив{id, value}или{code, value}).DELETE /api/profile— удалить: параметрuserProfileID.
Чужой или несуществующий профиль в PUT и DELETE не вызывает ошибку: метод ничего не меняет.
Поля профиля
GET /api/profile/fields открыт гостю. Состав полей — штатные свойства заказа Битрикса (Магазин -> Настройки -> Свойства заказа). Ответ стенда, сокращён:
{
"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".
Добавление профиля
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": "Сергей"}]}' Ответ:
{
"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.
{
"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].
Что почитать после профилей покупателя
- Заказ:
profileIDпри оформлении. - Профиль пользователя
- Сессия и авторизация