# WooCommerce

## Что это

**WooCommerce** — плагин интернет-магазина для WordPress. Интеграция подключает бота к REST API вашего магазина. Бот выгружает каталог с ценами и остатками, проверяет наличие товара или вариации и создаёт заказ со ссылкой на оплату. Ещё он сообщает статус заказа, отменяет его, добавляет заметки и показывает клиенту историю покупок. Заказ из бота появляется в админке WooCommerce как обычный.

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

- Сайт на WordPress с установленным WooCommerce, доступный из интернета по **HTTPS**.
- Доступ администратора к админке WordPress.
- Ключ REST API WooCommerce с правами **Чтение/Запись**.

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

1. В админке WordPress откройте **WooCommerce → Настройки → Дополнительно → REST API**.
2. Нажмите **Добавить ключ**, выберите пользователя-администратора и права **Чтение/Запись**, затем **Создать API-ключ**.
3. Скопируйте **Consumer Key** (`ck_…`) и **Consumer Secret** (`cs_…`). Secret показывается один раз.
4. В конструкторе откройте **Интеграции** → найдите карточку **WooCommerce** → **Подключить**.
5. Укажите **адрес магазина** с `https://`, **Consumer Key** и **Consumer Secret**.
6. Сохраните подключение и нажмите **Проверить соединение**. В ответе будут название магазина и версия WooCommerce.

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

| Операция | Что делает |
|---|---|
| Выгрузить каталог | Страница опубликованных товаров (до 100): ID, название, тип, цены, фото, ссылка, наличие, остаток, число вариаций. Поиск по слову, фильтр по категории, постраничная выгрузка через `next_page` |
| Товар и его вариации | Описание товара и все вариации: ID, атрибуты («Размер: M, Цвет: Red»), SKU, цена, наличие, остаток |
| Проверить наличие | По ID товара/вариации или SKU и нужному количеству отвечает `available` = 1/0, показывает остаток и цену |
| Создать заказ | Позиции `ID:количество`, контакты, адрес, комментарий, статус и отметка об оплате. Возвращает номер заказа и `payment_url` — ссылку на оплату |
| Информация о заказе | По ID или номеру: статус, состав, сумма, ссылка на оплату, комментарий покупателя |
| Заказы клиента | Последние заказы по email или телефону покупателя, включая гостевые, или по ID покупателя |
| Отменить заказ | Переводит заказ в «Отменён», причину сохраняет заметкой. Остатки WooCommerce возвращает сам |
| Добавить заметку к заказу | Внутренняя заметка к заказу или заметка, которая уйдёт клиенту письмом |

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

- Только **HTTPS**: по HTTP WooCommerce требует другую схему подписи, и ключи ушли бы открытым текстом. Адрес должен быть публичным сайтом — локальные и внутренние адреса не принимаются.
- Botconsole не следует за редиректами. Указывайте итоговый адрес магазина: с `www` или без — как открывается сайт.
- Если хостинг вырезает заголовок `Authorization` (бывает на Apache в режиме CGI), WooCommerce ответит 401, хотя ключи верные. Это решается настройкой сервера — см. [документацию WooCommerce](https://woocommerce.com/document/woocommerce-rest-api/).
- Остатки списываются, когда заказ переходит в статус «Обработка» или «На удержании». Заказ «Ожидает оплаты» остатки не резервирует — перед созданием проверьте наличие.
- Поиск по SKU находит товары. Для вариации надёжнее передавать её ID из операции «Товар и его вариации».
- Каталог и заказы выгружаются страницами до 100 записей.

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

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

> Заказы из бота получают скрытую метку `_botconsole` в метаданных — по ней их можно отличить от заказов с сайта.

> «Отметить как оплаченный» ставьте, только если оплата уже прошла в боте. Иначе оставьте статус «Ожидает оплаты» и отправьте клиенту `payment_url`.

> Поиск заказов по телефону сравнивает только цифры, поэтому `+7 (900) 123-45-67` и `79001234567` считаются одним номером.