# Квэлп: Поделиться корзиной

Полное руководство из встроенной справки qwelp.sharedcart. Версия 1.0.0, сверка 11.10.2026.

## Начало

Модуль «Квэлп: Поделиться корзиной» сохраняет состав корзины и создаёт ссылку для просмотра. Покупатель может скопировать её, отправить через социальную сеть или показать QR-код.

1. **Установите модуль.** В разделе «Установленные решения» найдите «Квэлп: Поделиться корзиной» и нажмите «Установить».
2. **Подключите кнопку.** Передайте разработчику примеры из раздела «Подключение». Установщик не добавляет кнопку в произвольный шаблон корзины автоматически.
3. **Проверьте результат.** Добавьте товар в корзину, нажмите «Поделиться корзиной» и откройте полученную ссылку в другом браузере. Должны появиться товары, количества и сохранённая сумма.

### Как работает ссылка

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

Ссылка действует 30 дней по умолчанию. Состав, количества и сохранённые в корзине цены содержатся в самой подписанной ссылке; новая запись в базе данных не создаётся. Последующие изменения корзины не меняют ссылку. Для больших корзин ссылка длиннее: если QR-код недоступен, скопируйте её целиком. Социальная сеть может ограничивать длину ссылки.

Перейти к проверке и решению частых проблем

## Установка

### Перед установкой

Нужны права администратора, PHP 8.2 и модуль «Главный модуль» версии 23.0.0 или новее. В Битриксе должны быть установлены модули «Интернет-магазин» (`sale`), «Торговый каталог» (`catalog`), «Информационные блоки» (`iblock`) и «Валюты» (`currency`).

1. Создайте резервную копию сайта и базы данных.
2. Загрузите решение средствами Marketplace. Откройте Marketplace → Установленные решения, найдите «Квэлп: Поделиться корзиной» и выполните установку.
3. Дождитесь сообщения об успешной установке. В разделе «Квэлп» откройте «Квэлп: Поделиться корзиной → Документация».
4. Перейдите к подключению кнопки и проверьте ссылку с непустой корзиной.

:::details Что создаёт установщик

Установщик создаёт таблицу снимков корзины, регистрирует ежедневную очистку просроченных снимков, размещает собственные административные файлы, компоненты `qwelp:sharedcart.page` и `qwelp:sharedcart.share`, расширение `qwelp.sharedcart` и страницу `personal/shared-cart/index.php` в папке каждого настроенного сайта.

Общие ресурсы устанавливаются в `/bitrix/js/qwelp/sharedcart/` и `/bitrix/components/qwelp/sharedcart.page/`. Пользовательские копии в `/local/` не перезаписываются и имеют приоритет. Полная поставка Marketplace размещается в `/bitrix/modules/qwelp.sharedcart/`, административная страница — в `/bitrix/admin/`. Разработческая или пользовательская копия модуля в `/local/modules/` имеет приоритет: при обновлении проверяйте, какая копия фактически загружается.

Перед установкой проверяются локальные каталоги расширения и обоих компонентов на всех настроенных сайтах. Пустые остаточные деревья каталогов удаляются автоматически. Неполная копия с файлами, но без config.php для расширения либо class.php/component.php для компонента, останавливает установку с указанием пути. Символические ссылки в этих путях не изменяются и также требуют проверки. Полноценные пользовательские копии сохраняются и продолжают иметь приоритет; их совместимость проверяет разработчик сайта. При удалении модуля пустые каталоги его файлов также очищаются, а пользовательские файлы и общие каталоги сохраняются.

Существующая пользовательская страница общей корзины не мешает установке: её каталог сохраняется без изменений и не присваивается модулю. Если страница ещё не подключена к модулю, добавьте вызов `qwelp:sharedcart.page` по примеру ниже. Конфликты общих файлов компонентов и JS, повреждённый файл учёта и небезопасные пути по-прежнему останавливают установку: сохраните указанный файл и передайте разработчику путь из сообщения.

:::

:::details Удаление и повторная установка

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

Откройте «Установленные решения», выберите удаление модуля и оставьте флажок сохранения данных, если снимки и настройки понадобятся после повторной установки. Удаление без сохранения данных уничтожает снимки и ключ подписи: старые ссылки восстановить нельзя без резервной копии.

Если вы добавили кнопку вручную, уберите её из шаблона корзины при отключении модуля. Пользовательские шаблоны и изменённые файлы проверяйте отдельно.

:::

## Подключение

Регистрация не нужна. Кнопка вызывает `qwelp:sharedcart.CartLink.get`: сервер читает существующую корзину текущей сессии и подписывает её состав без записи снимка. Для открытия новой ссылки требуется JavaScript. Сохраняйте весь адрес, включая часть после `#qsc=`. Ранее созданные ссылки `?code=…` продолжают работать.

Этот раздел для разработчика сайта. Если кнопка уже есть и открывает окно со ссылкой, повторное подключение не требуется.

### 1. Подключите компонент

Добавьте вызов в пользовательский шаблон корзины или на страницу после подключения ядра. Компонент `qwelp:sharedcart.share` выводит кнопку и подготавливает окно отправки. Его шаблон сам подключает стили и скрипт; отдельно загружать расширение не нужно.

```php
<?php
if (\Bitrix\Main\Loader::includeModule('qwelp.sharedcart'))
{
    $APPLICATION->IncludeComponent('qwelp:sharedcart.share', '', ['SHOW_BUTTON' => 'Y'], false);
}
?>
```

### 2. Если кнопка уже есть

Вызовите этот же компонент один раз с `SHOW_BUTTON => N` вне обновляемого фрагмента корзины. Добавьте существующей кнопке атрибут `data-qsc-share-button`. Оформление кнопки останется в шаблоне сайта.

```
<button type="button" class="qsc-cart-share" data-qsc-share-button>Поделиться корзиной</button>
```

Компонент берёт текущую корзину сам: идентификатор пользователя передавать не нужно. Значение `SHOW_BUTTON` можно менять в параметрах компонента; по умолчанию кнопка включена.

:::details Страница просмотра и её параметры

Установщик создаёт страницу `personal/shared-cart/index.php` относительно папки сайта. Для сайта в корне адрес имеет вид `/personal/shared-cart/?code=…`, для сайта в подпапке перед ним добавляется папка сайта. Код берётся из созданной модулем ссылки.

Если вы интегрируете модуль в уже существующую пользовательскую страницу, сохраните её и добавьте вызов компонента. Полный минимальный пример страницы:

```php
<?php
declare(strict_types=1);

require $_SERVER['DOCUMENT_ROOT'] . '/bitrix/header.php';
$APPLICATION->IncludeComponent('qwelp:sharedcart.page', '', ['SET_TITLE' => 'Y'], false);
require $_SERVER['DOCUMENT_ROOT'] . '/bitrix/footer.php';
```

При копировании шаблона страницы сохраните `data-qsc-page`, `data-qsc-loading`, `data-qsc-error` и файл `script.js`: они загружают подписанный состав через POST и используют этот же шаблон для вывода. Для ключа на прежней установке используется уже существующий ключ подписи ядра; если ни одного ключа нет, выполните повторную установку с сохранением данных.

| Параметр | Значение | Назначение |
| --- | --- | --- |
| `SET_TITLE` | `Y` по умолчанию | Устанавливает заголовок страницы. Передайте `N`, если заголовком управляет сама страница. |

Компонент получает снимок по коду и отключает Композит для страницы просмотра. Не помещайте его результат в общий кеш или кеширующий родительский компонент.

:::

:::details Свой дизайн

Оба компонента используют обычные шаблоны Битрикса. Скопируйте нужную папку `.default` целиком:

- страница: `/bitrix/components/qwelp/sharedcart.page/templates/.default/` → `/local/templates/ИМЯ_ШАБЛОНА/components/qwelp/sharedcart.page/ИМЯ_КОПИИ/`;
- кнопка и окно: `/bitrix/components/qwelp/sharedcart.share/templates/.default/` → `/local/templates/ИМЯ_ШАБЛОНА/components/qwelp/sharedcart.share/ИМЯ_КОПИИ/`.

Выберите имя копии в параметрах компонента или передайте его вторым аргументом `IncludeComponent`. Меняйте `template.php`, `style.css`, `script.js` и языковые файлы в своей копии. Для страницы достаточно разметки и CSS; общий CSS модуля к ней не подключается.

Если меняете только оформление окна, сохраните служебные атрибуты `data-qsc-*`, `data-qr`, `data-network` и классы элементов, используемые в `script.js`. Сохраните экранирование данных и обработку отсутствующей корзины. Установщик не записывает файлы в пользовательские папки шаблонов.

:::

## Настройки

Настройки кнопки, социальных сетей и ссылок открываются внутри меню «Квэлп → Квэлп: Поделиться корзиной → Настройки». В стандартных настройках модулей остаётся только «Доступ». Справа от каждого шаблона ссылки кнопка ⋯ открывает переменные с пояснениями. Выбор вставляет переменную на место курсора; «Вставить пример» заполняет пустое поле готовым шаблоном.

Откройте «Квэлп → Квэлп: Поделиться корзиной → Настройки». Пункт доступен пользователям с правом W на модуль. Во вкладке «Кнопка и социальные сети» выберите сайт в выпадающем списке «Сайт». При переключении открываются настройки выбранного сайта; несохранённые изменения не применяются. Ссылки на товары настраиваются на соседней вкладке.

### Оформление кнопки и социальные сети

В настройках модуля откройте вкладку «Кнопка и социальные сети» и выберите сайт. Доступны акцентная, светлая и тёмная кнопки, а также свои цвета фона, текста, рамки и наведения. Можно задать скругление, выравнивание кнопки, значок и его размер и положение слева или справа от текста.

Для своей картинки загрузите PNG, JPEG или WebP до 1 МБ и 1024 × 1024 px. На сервере нужен GD; файл сохраняется как PNG. Новая картинка заменяет старую. Флажок «Удалить изображение» удаляет файл после сохранения. При удалении модуля с сохранением данных картинки сохраняются; при полном удалении удаляются только его собственные картинки.

Выберите нужные VK, Одноклассники и X. Если отключены все сети, раздел исчезает, а копирование ссылки и QR-код остаются. Нажмите «Сохранить кнопку и сети этого сайта»: настройки других сайтов, ссылок и прав не меняются. Предпросмотр показывает оформление до сохранения.

Оформление применяется к стандартному шаблону компонента с SHOW_BUTTON=Y. Для пользовательских шаблонов и вручную созданных внешних кнопок оформление задаётся в их собственном коде. Компонент не кеширует настройки; стандартный шаблон выводится в динамической области Композита.

### Права доступа

Откройте «Настройки → Настройки продукта → Настройки модулей» и выберите «Квэлп: Поделиться корзиной». На вкладке «Доступ» назначьте права группам пользователей и нажмите «Сохранить».

| Право | Что доступно |
| --- | --- |
| `D` — доступ закрыт | Административные страницы модуля недоступны. |
| `R` — чтение | Просмотр документации. |
| `W` — полный доступ | Документация, настройка ссылок на товары и управление правами. |

Это права административного раздела. Они не делают публичную ссылку закрытой: снимок просматривает любой получатель ссылки до окончания её срока.

### Ссылки на товары

Откройте «Квэлп → Квэлп: Поделиться корзиной → Настройки», вкладку «Ссылки на товары». Для каждой пары сайт/каталог доступно поле шаблона. Пустое поле оставляет автоматический адрес из корзины; заполненное имеет приоритет. Пример для каталога с ЧПУ: `/catalog/#SECTION_CODE#/#ELEMENT_CODE#/`. Скопируйте структуру ЧПУ из настроек компонента каталога, а не адрес одного товара.

Доступны `#SITE_DIR#`, `#ELEMENT_ID#`, `#ELEMENT_CODE#`, `#IBLOCK_ID#`, `#SECTION_ID#`, `#SECTION_CODE#` и `#SECTION_CODE_PATH#`. Последняя подстановка содержит путь кодов разделов, а `#SECTION_CODE#` — код основного раздела. Указывайте путь от корня сайта без домена, обязательно с ID или кодом товара. Для торговых предложений подставляются поля основного товара. При отсутствии товара или нужного кода остаётся сохранённая ссылка.

Настройка действует и на уже отправленные ссылки при следующем открытии страницы, не меняя цены, количества и остальные данные снимка. Настройки разных сайтов и каталогов независимы. После сохранения проверьте несколько карточек. Очистите поле, чтобы вернуть автоматический режим. Если корзина уже открыта, обновите её страницу.

Заголовок страницы задаётся компонентом через `SET_TITLE` и выводится шаблоном сайта. Внутри списка товаров он повторно не выводится.

### Срок действия

### Размер и хранение

Состав корзины ограничен 60000 байтами. Новые ссылки содержат подписанные данные и не расходуют квоту базы данных. Короткие снимки через прежний API `SharedBasket.createSnapshot` требуют авторизации; для них сохранены общие квоты 30/мин, 300/час, 3000/сутки и 10000 действующих снимков. Ключ подписи создаётся при установке и сохраняется при обновлении и удалении с сохранением данных. Не меняйте ключ: это сделает выданные ссылки недействительными.

По умолчанию ссылки действуют 30 дней. В текущем экране настроек отдельного поля срока нет. Изменение выполняет разработчик через штатную настройку Битрикса.

:::details Изменить срок через API

Добавьте этот код в контролируемую одноразовую миграцию сайта с подключённым ядром Битрикса. Замените `30` числом дней от 1 до 365. Не размещайте код на общедоступной странице или в обработчике каждого запроса.

```
if (\Bitrix\Main\Loader::includeModule('qwelp.sharedcart'))
{
    \Bitrix\Main\Config\Option::set('qwelp.sharedcart', 'SHARE_BASKET_LIFETIME', '30');
}
```

Настройка общая для установки. Она применяется только к новым снимкам; дата окончания старых ссылок не пересчитывается. Чтобы вернуть срок по умолчанию, установите значение `30`.

:::

### Несколько сайтов

В настройках каждого сайта Битрикса проверьте доменное имя и папку сайта. Модуль использует их для адреса ссылки и открывает снимок только на том сайте, где он создан. Проверьте кнопку и страницу просмотра отдельно на каждом домене. Общая папка `/bitrix/` сама по себе не подтверждает доступность локальных компонентов и расширений второго сайта.

## Проверка

### Проверка после подключения

1. Добавьте несколько товаров в корзину и нажмите «Поделиться корзиной». Должно открыться окно со ссылкой и QR-кодом.
2. Скопируйте ссылку и откройте её в другом браузере без авторизации. Сверьте товары, количества и сумму со снимком.
3. Измените корзину, создайте новую ссылку. Старая должна показывать прежний состав.
4. Проверьте пустую корзину и неверный код ссылки: должно появляться понятное сообщение, без ошибок PHP.
5. Повторите проверку на телефоне, после обновления страницы и после AJAX-обновления корзины. При включённом Композите проверьте повторное открытие страницы корзины из кеша.
6. Для многосайтовой установки повторите шаги на каждом сайте; ссылка должна вести на правильный домен.

| Проблема | Что проверить |
| --- | --- |
| Кнопки нет | Установщик не меняет шаблон корзины. Добавьте кнопку по разделу «Подключение» и проверьте пользовательский шаблон. |
| Кнопка не реагирует | Проверьте атрибут `data-qsc-share-button` и подключение компонента `qwelp:sharedcart.share` и ошибки JavaScript. Подключение ресурсов должно выполняться вне кешируемого фрагмента. |
| Ссылка показывает прежние товары | Снимок не обновляется. Создайте новую ссылку. |
| Корзина не найдена | Проверьте полный код, срок действия и домен: снимок привязан к сайту создания. Создайте новую ссылку. |
| По ссылке ошибка 404 или не найден компонент | Проверьте созданную страницу в папке нужного сайта, доступность компонента и его шаблона. При наличии локальной копии проверьте, не перекрывает ли она установленную. |
| Неправильный домен | Проверьте доменное имя сайта в Битриксе и основное имя сервера в настройках главного модуля. Затем создайте ссылку заново. |
| Где найти настройки | Откройте «Квэлп → Квэлп: Поделиться корзиной → Настройки». Для изменения нужны права `W`; при `R` доступна документация. |

:::details Что передать разработчику при ошибке

Укажите версию модуля и Битрикса, версию PHP, сайт и последовательность действий. Приложите снимок экрана, текст ошибки из консоли браузера и результат сетевого запроса без cookies, токенов и персональных данных.

:::