Список позиций корзины

GET /v1/basket-items

Возвращает список позиций корзины с поддержкой фильтрации и автоматической пагинации.

Параметры

Параметр Тип По умолч. Описание
limit number 50 Количество записей (до 5000). При limit > 50 Вайбкод автоматически запрашивает несколько страниц у Битрикс24
offset number 0 Пропустить N записей. При offset ≥ 2500 рекомендуется limit ≤ 500
select string — Выборка полей: ?select=id,orderId,name,quantity,price
order object — Сортировка: ?order[id]=desc
filter object — Фильтрация по ключевым полям позиции.
Синтаксис фильтрации. Пример: ?filter[orderId]=33

Примеры

curl — личный ключ

Terminal 
curl "https://vibecode.bitrix24.tech/v1/basket-items?limit=10&filter[orderId]=33" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

Terminal 
curl "https://vibecode.bitrix24.tech/v1/basket-items?limit=10&filter[orderId]=33" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/basket-items?limit=10&filter[orderId]=33', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`Позиций в заказе: ${meta.total}`)

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/basket-items?limit=10&filter[orderId]=33', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data, meta } = await res.json()

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data array Массив позиций корзины
meta.total number Общее количество записей, соответствующих фильтру
meta.hasMore boolean Есть ли ещё записи за пределами limit

Пример ответа

JSON 
{
  "success": true,
  "data": [
    {
      "id": 9,
      "orderId": 33,
      "productId": 119,
      "name": "Домашние Тапочки Любимый Спорт",
      "price": 470,
      "basePrice": 470,
      "discountPrice": 0,
      "currency": "RUB",
      "quantity": 1,
      "weight": 0,
      "vatRate": 0,
      "vatIncluded": true,
      "measureCode": 796,
      "measureName": "шт",
      "xmlId": "bx_5fc9f8c57fe6c",
      "productXmlId": "1000000475",
      "catalogXmlId": "FUTURE-1C-CATALOG",
      "canBuy": true,
      "dateInsert": "2020-12-04T07:52:21.000Z",
      "dateUpdate": "2022-11-02T05:10:13.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "hasMore": false
  }
}

Показаны основные поля. Полный ответ позиции — см. `GET /v1/basket-items/:id`.

Пример ответа при ошибке

400 — фильтр по несуществующему полю:

JSON 
{
  "success": false,
  "error": {
    "code": "UNKNOWN_FILTER_FIELD",
    "message": "Unknown filter field 'foo' for entity 'basket-items'. Available: …"
  }
}

Ошибки

HTTP Код Описание
400 UNKNOWN_FILTER_FIELD Фильтр по полю, которого нет в схеме
403 SCOPE_DENIED API-ключ не имеет скоупа sale
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

Полный список общих ошибок API — Ошибки.

Известные особенности

Автоматическая пагинация: при limit > 50 Вайбкод автоматически запрашивает несколько страниц у Битрикс24 и возвращает все записи в одном ответе.

Свободные позиции без заказа. Часть позиций в data[] может иметь orderId: null — это позиции в незавершённых корзинах покупателей, ещё не оформленных в заказ. Чтобы исключить их, добавьте filter[orderId][!]=null или фильтр по конкретному orderId.

Смотрите также