# Shopify

## Что это

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

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

- Магазин на Shopify и доступ владельца или сотрудника с правом создавать приложения.
- Приложение в [Shopify Dev Dashboard](https://dev.shopify.com/dashboard), созданное в той же организации, что и магазин, и установленное в магазин. Нужны доступы (scopes):
  - `read_products` — каталог и товары;
  - `read_inventory` — остатки;
  - `write_orders` — создание заказов и их чтение;
  - `read_customers` — поиск клиента для истории заказов.
- Домен магазина вида `your-store.myshopify.com`. Собственный домен магазина для API не подходит.

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

1. Откройте Shopify Dev Dashboard и создайте приложение.
2. В настройках версии приложения выдайте доступы `read_products`, `read_inventory`, `write_orders`, `read_customers`, выпустите версию и установите приложение в свой магазин.
3. Скопируйте **Client ID** и **Client Secret** приложения.
4. В конструкторе откройте **Интеграции** → найдите карточку **Shopify** → **Подключить**.
5. Укажите **домен магазина**, **Client ID** и **Client Secret**. Если у магазина уже есть старое приложение, созданное в админке, вместо Client ID и Secret можно вставить его **Admin API token** (`shpat_…`).
6. Сохраните подключение и нажмите **Проверить соединение**. В ответе будут название магазина и его валюта.

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

| Операция | Что делает |
|---|---|
| Выгрузить каталог | Страница товаров (до 250): ID, название, цена от, валюта, фото, ссылка, наличие, остаток, ID первого варианта. Поддерживает поиск Shopify и постраничную выгрузку через `next_cursor` |
| Товар и его варианты | Описание товара и все его варианты: ID, название, SKU, цена, наличие, остаток |
| Проверить наличие | По ID варианта или SKU и нужному количеству отвечает `available` = 1/0 и показывает остаток и цену |
| Создать заказ | Передаёт заказ в Shopify: позиции `ID_варианта:количество`, email/телефон, имя, адрес доставки, комментарий, теги, статус оплаты. Возвращает номер заказа (`#1001`) и ссылку на страницу статуса |
| Информация о заказе | По номеру `#1001` или ID показывает статус оплаты и выполнения, состав, сумму и трек-номер |
| Заказы клиента | Находит клиента по email или телефону и возвращает его последние заказы, новые первыми |

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

- Магазин и приложение должны быть в одной организации Shopify. Токен приложения живёт 24 часа, Botconsole обновляет его сам.
- Создавать приложения прямо в админке Shopify (с токеном `shpat_…`) больше нельзя. Уже созданные работают, поэтому поле для такого токена оставлено.
- Email, телефон и адрес клиента относятся к защищённым данным Shopify. Если доступ к ним не одобрен для приложения, операции с данными клиента вернут ошибку Shopify.
- Доступ `write_orders` без `read_all_orders` видит заказы только за последние 60 дней. Для более старой истории запросите `read_all_orders`.
- На dev- и trial-магазинах Shopify разрешает создавать не больше 5 заказов в минуту.
- Shopify ограничивает частоту запросов к API. Не выгружайте каталог в цикле без нужды — сохраняйте результат в переменные.

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

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

> Заказ создаётся со списанием остатков по правилам магазина. Если товара не хватает и продажа «под заказ» выключена, Shopify откажет, и в ответе будет текст ошибки.

> По умолчанию заказ получает статус «Ожидает оплаты» и тег `botconsole`, чтобы заказы из бота было легко найти в админке. Статус «Оплачен» ставьте, только если оплата уже прошла в боте.

> Номер заказа для клиента — поле `name` (`#1001`). Его же можно передать в «Информацию о заказе».