# OpenCart

## Что это

**OpenCart** — бесплатная платформа интернет-магазина (на ней же построен ocStore). Интеграция работает через **встроенный API OpenCart** версий 3.x и 4.x — ничего дополнительно ставить в магазин не нужно. Бот проверяет наличие и стоимость товаров, оформляет заказ с доставкой и оплатой и меняет статус заказа. В OpenCart 3.x бот также получает информацию о заказе. Заказ из бота появляется в админке OpenCart как обычный.

Встроенный API OpenCart создан для оформления заказов из админки, поэтому в нём **нет выгрузки каталога, поиска товаров и истории заказов клиента**. Чтобы бот показывал товары, подключите каталог магазина в разделе **Товары → Синхронизация** через YML- или CSV-фид. ID товаров из каталога OpenCart подходят для заказа.

## Требования

- Магазин на OpenCart 3.x (включая ocStore 3) или 4.x, доступный из интернета по **HTTPS**.
- Доступ администратора к админке OpenCart.
- API-пользователь OpenCart, в белый список IP которого добавлен **IP сервера Botconsole**.

## Как подключить

1. В админке OpenCart откройте **Система → Пользователи → API** и нажмите **Добавить**.
2. Задайте **имя API-пользователя**, нажмите **Сгенерировать** и скопируйте ключ — позже его не посмотреть. Включите **статус**.
3. На вкладке **IP-адреса** добавьте IP сервера Botconsole и сохраните. Этот IP показан в инструкции в форме подключения OpenCart в конструкторе.
4. В конструкторе откройте **Интеграции** → найдите карточку **OpenCart** → **Подключить**.
5. Укажите **адрес магазина** с `https://`, **имя API-пользователя** (в точности как в OpenCart) и **API-ключ**.
6. Нажмите **Проверить соединение**. Botconsole сам определит версию OpenCart. Если магазин отклонит запрос, в тексте ошибки будет IP, который нужно внести в список.

## Доступные операции

| Операция | Что делает |
|---|---|
| Проверить наличие и стоимость | Кладёт товары во временную корзину и возвращает `available` = 1/0, цены, итог и текст ошибки магазина: нет на складе, не выбрана обязательная опция, меньше минимального количества |
| Создать заказ | Клиент, позиции, адрес, способы доставки и оплаты, комментарий, статус. Возвращает номер заказа и выбранные способы |
| Информация о заказе | Статус, сумма, валюта, дата, контакты и способы доставки/оплаты. **Только OpenCart 3.x** |
| Изменить статус заказа | Добавляет запись в историю заказа с новым статусом и комментарием, может уведомить клиента письмом |

Позиции задаются строками `ID_товара:количество`. Для товаров с обязательными опциями (размер, цвет) используйте JSON: `[{"product_id": 42, "quantity": 1, "option": {"225": "17"}}]`. Здесь `225` — ID опции товара, `17` — ID значения; их видно в карточке товара в админке.

## Настройка блока «Создать заказ»

- **ID страны** и **ID региона** — из **Система → Локализация → Страны / Регионы**, число в адресе страницы редактирования. В стандартной установке США — `223`, Россия — `176`. Регион обязателен, если у страны есть регионы.
- **Код способа доставки** — например `flat.flat`, `free.free`, `pickup.pickup`. Пусто — первый способ, который магазин предложит для адреса.
- **Код способа оплаты** — например `cod`, `bank_transfer`. Пусто — первый доступный.
- **ID статуса заказа** — из **Система → Локализация → Статусы заказов**. По умолчанию `1` («Ожидание»).

## Ограничения

- Только **HTTPS**: ключ API передаётся магазину, по HTTP он ушёл бы открытым текстом. Адрес должен быть публичным сайтом. Botconsole не следует за редиректами, поэтому указывайте итоговый адрес магазина.
- Без IP сервера Botconsole в белом списке API-пользователя магазин отклоняет все запросы. При смене серверов Botconsole список нужно обновить.
- В OpenCart 4.x запросы подписываются ключом, и в подпись входят домен и путь магазина. Если магазин стоит за прокси, который меняет заголовок `Host`, подпись не сойдётся и магазин ответит «доступ запрещён».
- Имя API-пользователя вводите в точности как в OpenCart, с учётом регистра.
- Каталога, поиска товаров и заказов клиента во встроенном API нет. Информации о заказе нет в OpenCart 4.x.
- Модули, меняющие стандартное оформление заказа (например, быстрый или упрощённый заказ), могут менять поведение API.

## Особенности и примечания

> Типичный сценарий: каталог из синхронизации Botconsole → «Проверить наличие и стоимость» → «Создать заказ» → бот отправляет клиенту номер заказа.

> OpenCart требует email, имя, фамилию и адрес. Если клиент не назвал фамилию, бот подставит имя.

> Стоимость доставки всегда берётся из расчёта самого магазина для адреса клиента, а не из параметров бота.