Магазин тема 9 из 27

Корзина

Корзина покупателя живёт в сессии: гость и вошедший пользователь работают с ней одинаково, но витрине нужен X-Session-Id (Сессия и авторизация). Без заголовка корзина пустая. Методы корзины — в группе /api/sale; оформление заказа — тема Заказ.

в этой теме 5
  1. Методы корзины
  2. Корзина на витрине по шагам
  3. Где настраивается корзина
  4. Известные ограничения
  5. Что почитать после корзины

Методы корзины

Все методы вызывает гость или вошедший.

МетодАдресНачинает сессию
Корзина покупателя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).

Корзина на витрине по шагам

  1. Кнопка «В корзину»: POST /api/sale/basket с productId и quantity. Если сессии ещё нет, она создаётся, ID приходит в заголовке X-Session-Id — витрина сохраняет его.
  2. Мини-корзина в шапке и страница корзины: GET /api/sale/basket с X-Session-Id.
  3. Счётчик «- / +»: POST /api/sale/setBasketQuantity (id строки корзины, quantity).
  4. Кнопка «Удалить» — POST /api/sale/clearBasket с id; «Очистить корзину» — тот же метод без id.
  5. Поле «Промокод»: POST /api/sale/basketCoupon с coupon; убрать — DELETE /api/sale/basketCoupon.
  6. Оформление: Заказ.

Добавление товара

bash
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
json
{
    "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 нет в корзине.

Чтение корзины

bash
curl "https://example.ru/api/sale/basket" -H "X-Session-Id: JLfAjGOFZ3qb2elyU2VIxlhvt1kYjQMZ"
json
{
    "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.

Пустая корзина (и запрос без сессии) отдаёт только итоги:

json
{
    "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:

json
{
    "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, остальные поля строки сохраняются.

Что почитать после корзины

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

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

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