# API Contract: ai-assistant-for-woocommerce (WP plugin) ⇄ woo-ai-backend

Версия контракта: 1.1
Этот файл — единый источник правды. Копия лежит в `docs/` обоих репо.
Любое изменение формата = новая версия + обновление обоих репо.

## Общее

- Base URL: `https://<backend>.vercel.app` (dev: `http://localhost:3000`)
- Все запросы: `Content-Type: application/json`
- Аутентификация: заголовок `X-License-Key: <key>` (кроме /license/activate)
- Ошибки: HTTP-код + тело `{"error": {"code": "string", "message": "string"}}`
  Коды: `invalid_license` (401), `quota_exceeded` (402),
  `rate_limited` (429), `internal` (500)

---

## POST /api/license/activate

Активация при сохранении ключа в настройках плагина.

Запрос:
```json
{
  "license_key": "WAI-XXXX-XXXX-XXXX",
  "site_url": "https://shop.example.com",
  "settings": {
    "language": "uk",
    "currency": "UAH",
    "telegram_chat_id": "123456789",
    "welcome_message": "Привіт! Чим допомогти?",
    "store_info": "Доставка: Нова Пошта 1-3 дні. Оплата: картка, накладений платіж. Повернення: 14 днів."
  }
}
```

Ответ 200:
```json
{
  "store_id": "uuid",
  "plan": "free",
  "limits": { "monthly_messages": 50 }
}
```
`plan`: `free` | `pro`. Плагин кэширует ответ в опции на 12 часов.
Плагин повторно вызывает activate при изменении любой из настроек
(language, telegram_chat_id, welcome_message, store_info) — бэкенд
обновляет их upsert-ом.
`settings.store_info` (с v1.1): свободный текст про доставку/оплату/
возврат/график — подставляется в системный промпт чата.

---

## POST /api/sync

Батч товаров (1–50 шт). Плагин шлёт при изменении товара и по крону.

Запрос:
```json
{
  "products": [
    {
      "wc_id": 123,
      "action": "upsert",
      "title": "Кросівки Nike Air",
      "description": "Текст описания без HTML...",
      "short_description": "...",
      "sku": "NK-AIR-42",
      "price": "3200",
      "regular_price": "3500",
      "currency": "UAH",
      "stock_status": "instock",
      "categories": ["Взуття", "Чоловіче"],
      "attributes": { "Розмір": ["41", "42", "43"], "Колір": ["чорний"] },
      "url": "https://shop.example.com/product/nike-air",
      "image_url": "https://shop.example.com/wp-content/.../nike.jpg",
      "content_hash": "md5-от-title+description+price+attributes"
    },
    { "wc_id": 124, "action": "delete" }
  ]
}
```
Правила для плагина:
- `description` — plain text, `wp_strip_all_tags`, максимум 4000 символов
- `action`: `upsert` | `delete`
- `content_hash` обязателен при upsert — бэкенд пропускает эмбеддинг,
  если hash не изменился

Ответ 200:
```json
{ "synced": 49, "deleted": 1, "skipped_unchanged": 30 }
```

---

## POST /api/chat

Сообщение покупателя. Плагин проксирует со своего REST-эндпоинта.

Запрос:
```json
{
  "conversation_id": "uuid-или-null-для-нового",
  "message": "Какие у вас есть кроссовки до 3000 грн?",
  "page_url": "https://shop.example.com/shop/"
}
```

Ответ 200 (обычный):
```json
{
  "conversation_id": "uuid",
  "action": "answer",
  "reply": "Ось що підійде: [Nike Air](https://...) за 3200 грн...",
  "products": [
    { "wc_id": 123, "title": "Nike Air", "price": "3200",
      "url": "https://...", "image_url": "https://..." }
  ]
}
```

Ответ 200 (нужен лид — нет ответа в каталоге):
```json
{
  "conversation_id": "uuid",
  "action": "collect_lead",
  "reply": "Не маю точної відповіді. Залиште контакт — менеджер відповість."
}
```
Виджет при `collect_lead` показывает форму: имя + телефон/email.

Ответ 402 quota_exceeded: виджет показывает
"Чат тимчасово недоступний" и кнопку лид-формы.

---

## POST /api/lead

Запрос:
```json
{
  "conversation_id": "uuid",
  "name": "Иван",
  "contact": "+380501234567",
  "question": "Есть ли доставка в Польшу?",
  "page_url": "https://shop.example.com/product/nike-air"
}
```

Ответ 200: `{ "ok": true }`
Бэкенд: записывает лид в БД + отправляет в Telegram chat_id магазина:
```
🔥 Новий лід з чату
Магазин: shop.example.com
Ім'я: Иван
Контакт: +380501234567
Питання: Есть ли доставка в Польшу?
Сторінка: /product/nike-air
```

---

## Curl-примеры для теста бэкенда без плагина

```bash
# активация
curl -X POST http://localhost:3000/api/license/activate \
  -H 'Content-Type: application/json' \
  -d '{"license_key":"WAI-TEST-0000-0000","site_url":"http://test.local","settings":{"language":"uk","currency":"UAH"}}'

# чат
curl -X POST http://localhost:3000/api/chat \
  -H 'Content-Type: application/json' \
  -H 'X-License-Key: WAI-TEST-0000-0000' \
  -d '{"conversation_id":null,"message":"Що порадите до 3000 грн?","page_url":"http://test.local/shop"}'
```
