# Документация API для обратной связи с HugeProfit

## 📋 Обзор

Создан новый модуль `api-handler.php`, который предоставляет REST API для взаимодействия сервиса HugeProfit с вашим сайтом WooCommerce.

## 🎯 Основные возможности

### 1. **Выгрузка товаров на HugeProfit**
Сервис HugeProfit может запросить выгрузку товаров из WooCommerce в свою систему.

### 2. **Загрузка товаров с HugeProfit**
Сервис HugeProfit может отправить товары на ваш сайт WooCommerce с двумя режимами:
- Загрузить все товары
- Загрузить конкретный список товаров по их ID в системе HugeProfit

## 🔗 Endpoints

Базовый URL: `https://ваш-сайт.com/wp-json/hugeprofit/v1/`

### 1. Статус подключения
```
GET /status
```

### 2. Выгрузка товаров
```
POST /export-products
```

### 3. Загрузка товаров
```
POST /import-products
```

## 🔐 Авторизация

Все запросы требуют токен в заголовке:
```
Authorization: ваш_api_токен_из_настроек_плагина
```

## 📤 Примеры запросов от HugeProfit

### Выгрузить все товары на HugeProfit

```bash
curl -X POST https://example.com/wp-json/hugeprofit/v1/export-products \
  -H "Authorization: YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
```

### Выгрузить конкретные товары по их ID в WooCommerce

```bash
curl -X POST https://example.com/wp-json/hugeprofit/v1/export-products \
  -H "Authorization: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_ids": [10, 20, 30, 40, 50]
  }'
```

### Загрузить ВСЕ товары с HugeProfit

```bash
curl -X POST https://example.com/wp-json/hugeprofit/v1/import-products \
  -H "Authorization: YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
```

### Загрузить КОНКРЕТНЫЕ товары по их ID в HugeProfit

```bash
curl -X POST https://example.com/wp-json/hugeprofit/v1/import-products \
  -H "Authorization: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pids": ["hp_product_123", "hp_product_456", "hp_product_789"]
  }'
```

**Важно:** Параметр `pids` - это массив ID товаров в системе HugeProfit!

## 📊 Примеры ответов

### Успешная выгрузка товаров

```json
{
  "success": true,
  "message": "Успешно выгружено товаров: 45",
  "products_count": 45,
  "result": {
    "imported": 40,
    "updated": 5,
    "errors": []
  }
}
```

### Успешная загрузка товаров

```json
{
  "success": true,
  "message": "Обработано товаров: 50 (создано: 30, обновлено: 18, пропущено: 2)",
  "products_count": 50,
  "imported": 30,
  "updated": 18,
  "skipped": 2,
  "total": 50,
  "errors": []
}
```

### Ошибка авторизации

```json
{
  "code": "forbidden",
  "message": "Неверный токен авторизации",
  "data": {
    "status": 403
  }
}
```

## 🔄 Логика работы

### При выгрузке товаров (Export)

1. HugeProfit отправляет POST запрос на `/export-products`
2. Плагин проверяет токен авторизации
3. Плагин получает товары из WooCommerce
4. Формирует данные товаров (название, цена, остатки, изображения и т.д.)
5. Отправляет данные в HugeProfit API на endpoint `/bapi/woo-products`
6. Возвращает результат операции

### При загрузке товаров (Import)

1. HugeProfit отправляет POST запрос на `/import-products`
   - Без параметров = загрузить все товары
   - С параметром `pids` = загрузить конкретные товары
2. Плагин проверяет токен авторизации
3. Плагин делает запрос к HugeProfit API на endpoint `/bapi/products`
   - Если указаны `pids`, они передаются как параметр `?pids=id1,id2,id3`
4. Получает данные товаров из HugeProfit
5. Для каждого товара:
   - Ищет существующий товар по `_hugeprofit_product_id` или SKU
   - Если найден - **обновляет** его
   - Если не найден - **создает** новый
6. Обрабатывает категории и изображения
7. Возвращает статистику операции

## ⚙️ Настройки синхронизации

При импорте учитываются настройки плагина:

- ✅ **Обновлять цены** - если включено в настройках
- ✅ **Обновлять остатки** - если включено в настройках  
- ✅ **Обновлять описания** - если включено в настройках

## 🔍 Поиск и связь товаров

Плагин использует специальное мета-поле `_hugeprofit_product_id` для связи товаров между системами:

1. При первой загрузке товара из HugeProfit сохраняется его ID
2. При последующих обновлениях товар находится по этому ID
3. Если товар не найден по HP ID, поиск идет по SKU
4. Если найден по SKU, сохраняется HP ID для будущих обновлений

## 📁 Структура файлов

```
wp-content/plugins/hugeprofit/
├── hugeprofit.php          # Основной файл плагина
├── settings.php            # Настройки плагина
├── api-handler.php         # НОВЫЙ! Обработчик API запросов
├── API-README.md           # Полная документация API (EN)
└── API-DOCS-RU.md          # Краткое руководство (RU)
```

## 🛡️ Безопасность

- ✅ Авторизация по токену
- ✅ Санитизация всех входных данных
- ✅ Проверка прав доступа
- ✅ Логирование попыток несанкционированного доступа
- ✅ Поддержка SSL/TLS

## 📝 Логирование

Все ошибки записываются в лог:
```
wp-content/debug.log
```

Для включения логирования добавьте в `wp-config.php`:
```php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
```

## 🧪 Тестирование

Проверить доступность API:
```bash
curl -X GET https://ваш-сайт.com/wp-json/hugeprofit/v1/status \
  -H "Authorization: YOUR_API_TOKEN"
```

Ожидаемый ответ:
```json
{
  "success": true,
  "connected": true,
  "woocommerce_active": true,
  "products_count": 150,
  "crm_url": "https://crm.hugeprofit.com",
  "plugin_version": "1.0.9"
}
```

## ⚡ Производительность

- Таймаут запросов: 60 секунд
- Изображения кэшируются (не загружаются повторно)
- Поддержка пагинации для больших объемов данных
- Использование WordPress REST API для оптимальной производительности

## 🔧 Что делать при ошибках

1. **401 / 403 ошибки** - проверьте токен авторизации
2. **503 ошибка** - убедитесь, что плагин настроен и WooCommerce активен
3. **500 ошибка** - проверьте логи в `wp-content/debug.log`
4. **Товары не импортируются** - убедитесь, что формат данных соответствует документации

## 💡 Примеры использования со стороны HugeProfit

### PHP
```php
// Запросить выгрузку товаров
$response = wp_remote_post($woo_site . '/wp-json/hugeprofit/v1/export-products', [
    'headers' => ['Authorization' => $api_token],
]);

// Загрузить конкретные товары
$response = wp_remote_post($woo_site . '/wp-json/hugeprofit/v1/import-products', [
    'headers' => [
        'Authorization' => $api_token,
        'Content-Type' => 'application/json'
    ],
    'body' => json_encode(['pids' => ['hp_123', 'hp_456']])
]);
```

### JavaScript
```javascript
// Запросить выгрузку товаров
const response = await fetch(`${wooSite}/wp-json/hugeprofit/v1/export-products`, {
    method: 'POST',
    headers: { 'Authorization': apiToken }
});

// Загрузить конкретные товары
const response = await fetch(`${wooSite}/wp-json/hugeprofit/v1/import-products`, {
    method: 'POST',
    headers: {
        'Authorization': apiToken,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({ pids: ['hp_123', 'hp_456'] })
});
```

## 📮 Поддержка

При возникновении вопросов или проблем обращайтесь к полной документации в файле `API-README.md`.