Методы корзины
Все методы вызывает гость или вошедший.
| Метод | Адрес | Начинает сессию |
|---|---|---|
| Корзина покупателя | GET /api/sale/basket | нет |
| Отложенные товары | GET /api/sale/delayProducts | нет |
| Добавить товар или изменить позицию | POST /api/sale/basket | да |
| Добавить несколько товаров | POST /api/sale/basket/batch | да |
| Заменить товар другим | POST /api/sale/basket/replace | нет |
| Изменить количество | POST /api/sale/setBasketQuantity | нет |
| Удалить позиции | POST /api/sale/clearBasket | нет |
| Очистить отложенные | POST /api/sale/clearDelayProducts | нет |
| Применить купон | POST /api/sale/basketCoupon | да |
| Убрать купон | DELETE /api/sale/basketCoupon | да |
| Расчёт цен набора без корзины | POST /api/sale/basket/calculate | нет |
Методы, которые не начинают сессию, работают с корзиной сессии из X-Session-Id, но сами сессию не создают: первым вызовом гостя должен быть метод, начинающий сессию (обычно POST /api/sale/basket).
Корзина на витрине по шагам
- Кнопка «В корзину»:
POST /api/sale/basketсproductIdиquantity. Если сессии ещё нет, она создаётся, ID приходит в заголовкеX-Session-Id— витрина сохраняет его. - Мини-корзина в шапке и страница корзины:
GET /api/sale/basketсX-Session-Id. - Счётчик «- / +»:
POST /api/sale/setBasketQuantity(idстроки корзины,quantity). - Кнопка «Удалить» —
POST /api/sale/clearBasketсid; «Очистить корзину» — тот же метод безid. - Поле «Промокод»:
POST /api/sale/basketCouponсcoupon; убрать —DELETE /api/sale/basketCoupon. - Оформление: Заказ.
Добавление товара
curl -i -X POST "https://example.ru/api/sale/basket" \
-H "Content-Type: application/json" \
-d '{"productId": 105, "quantity": 2}' HTTP/1.1 200 OK
X-Session-Id: JLfAjGOFZ3qb2elyU2VIxlhvt1kYjQMZ {
"success": true,
"basketItemId": 15
} Какая строка меняется: если передан basketId (ID строки, поле id позиции корзины) — именно она, новая не создаётся; иначе строка с тем же productId и теми же productPropsVar, а если такой нет — добавляется новая. quantity — итоговое число, quantity = 0 удаляет позицию. delay = Y кладёт товар в отложенные (N — в основную корзину); fastBuy = Y оставляет к оформлению только эту строку, остальные откладывает («Купить в один клик»). productPropsVar — свойства строки, JSON-массив {NAME, CODE, VALUE, SORT}: по ним различаются строки одного товара.
Логические параметры принимают только Y / N: delay=true — ошибка 400, корзина не меняется.
Если товар не найден или корзину не удалось сохранить, ответ приходит со статусом 200 и success = false, тексты — в errors[]. Статус 400: не переданы ни productId, ни basketId; 404: строки с таким basketId нет в корзине.
Чтение корзины
curl "https://example.ru/api/sale/basket" -H "X-Session-Id: JLfAjGOFZ3qb2elyU2VIxlhvt1kYjQMZ" {
"numProducts": 1,
"totalPrice": 4000,
"quantity": 2,
"data": [
{
"id": 15,
"productId": 105,
"name": "Футболка базовая",
"quantity": 2,
"price": 2000,
"basePrice": 2500,
"discountPrice": 500,
"currency": "RUB",
"weight": 300,
"canBuy": "Y",
"delay": "N",
"measureName": "шт",
"sumValue": 4000,
"sum": "4 000 руб.",
"priceFmt": "2 000 руб.",
"fullPrice": "2 500 руб.",
"discountPricePercent": 20,
"element": { "id": 105, "name": "Футболка базовая" },
"props": [],
"previewPicture": "/upload/iblock/abc/futbolka.jpg"
}
],
"coupons": []
} В ответе — позиции текущего покупателя (в том числе отложенные, у них delay = "Y") с пересчитанными ценами и скидками; итоги считаются по доступным к заказу позициям. id позиции — то, что принимают setBasketQuantity, clearBasket и basketId. Ответ сокращён: полный список полей позиции — в документации API.
Пустая корзина (и запрос без сессии) отдаёт только итоги:
{
"numProducts": 0,
"totalPrice": 0,
"quantity": 0,
"coupons": []
} Состав карточки товара в element задаётся набором «Корзина и заказ» инфоблока. Проект может изменить ответ событием OnAfterSaleGetBasket (Контроллеры). Если подключён модуль Loymax (вкладка «Модули»), в ответе есть блок loymax (бонусы).
Несколько товаров
POST /api/sale/basket/batch принимает три JSON-массива, выровненных по индексу: productId, basketId, quantity. Для неиспользуемого значения позиции ставят 0. Каждая позиция обрабатывается как POST /api/sale/basket; delay действует на все позиции.
Пример: productId=[122,0]&basketId=[0,55]&quantity=[1,3] — товар 122 добавить или обновить, у строки корзины 55 поставить количество 3.
Ответ всегда со статусом 200: success = true, если прошли все позиции, items[] — итог по каждой (productId, basketId, success, basketItemId, errors).
Купоны
POST /api/sale/basketCoupon привязывает купон к корзине и возвращает все купоны корзины со статусом. Неверный или неподходящий купон тоже попадает в список со своим статусом, витрина показывает statusText:
{
"data": [
{ "coupon": "SALE10", "discountName": "Скидка по купону", "status": 4, "statusText": "Применён" }
]
} Если у корзины нет купонов, тело ответа {"errors": null}.
Расчёт цены набора без корзины
POST /api/sale/basket/calculate считает цены со скидками по позициям items (productId, quantity, необязательный comment; до 100 позиций), не трогая корзину: цена комплекта, подарочной корзины, предрасчёт. coupon учитывается только на время расчёта, asGuest = Y — считать как для гостя, withCards = N — без карточек товаров. Недоступный товар остаётся в data[] с available = false и в итоги не входит. Сессию метод не начинает.
Где настраивается корзина
- Состав карточки товара в корзине: Настройки модуля -> вкладка «Инфоблоки» -> инфоблок -> таб «Элементы» -> набор «Корзина и заказ» (Состав ответа). Свойства попадают в набор по штатному флагу «Добавлять в корзину».
- Цены, скидки, купоны, правила корзины — штатные настройки магазина Битрикса.
- Корзина не кешируется: это данные покупателя.
Известные ограничения
| Метод | Проблема | Как обойти |
|---|---|---|
POST /api/sale/basket/batch | у productId и quantity остались отладочные умолчания [122,143,125] и [1,1,1]: вызов без них (например, только с basketId) добавит в корзину ещё и товары 122, 143, 125 | всегда передавать productId и quantity явно |
POST /api/sale/basket/replace | если заменяемого товара нет в корзине, ответ 500 «Внутренняя ошибка» вместо 404 | вызывать только для позиции, которая есть в текущей корзине |
| ошибки методов | часть приходит телом {errors: [текст]}, часть — {success: false, error: текст} | читать текст из error или errors[0] |
POST /api/sale/basket/replace (смена размера или цвета товара в корзине) принимает oldProductId и newProductId, меняет ID товара у первой позиции со старым ID, остальные поля строки сохраняются.
Что почитать после корзины
- Заказ
- Доставка и местоположение: город и склад влияют на цены и остатки
- Сессия и авторизация