# HugeProfit API Handler - Документация

## Описание

Модуль `api-handler.php` предоставляет REST API endpoints для двусторонней синхронизации товаров между WooCommerce и HugeProfit CRM.

## Endpoints

Все endpoints доступны по базовому пути: `https://ваш-сайт.com/wp-json/hugeprofit/v1/`

### 1. Проверка статуса

**GET** `/status`

Получение информации о состоянии плагина и подключении к HugeProfit.

**Заголовки:**
```
Authorization: ваш_api_токен
```

**Ответ:**
```json
{
  "success": true,
  "connected": true,
  "woocommerce_active": true,
  "products_count": 150,
  "crm_url": "https://crm.hugeprofit.com",
  "plugin_version": "1.0.9",
  "wordpress_version": "6.4",
  "woocommerce_version": "8.5.0"
}
```

### 2. Выгрузка товаров на HugeProfit

**POST** `/export-products`

Экспортирует товары из WooCommerce в HugeProfit CRM.

**Заголовки:**
```
Authorization: ваш_api_токен
Content-Type: application/json
```

**Параметры (опциональные):**
```json
{
  "limit": 100,
  "offset": 0,
  "product_ids": [1, 2, 3, 4, 5]
}
```

- `limit` - максимальное количество товаров для выгрузки (по умолчанию: все)
- `offset` - смещение для пагинации
- `product_ids` - массив конкретных ID товаров WooCommerce для выгрузки

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

**Пример использования:**

```bash
# Выгрузить все товары
curl -X POST https://ваш-сайт.com/wp-json/hugeprofit/v1/export-products \
  -H "Authorization: your_api_token_here" \
  -H "Content-Type: application/json"

# Выгрузить конкретные товары
curl -X POST https://ваш-сайт.com/wp-json/hugeprofit/v1/export-products \
  -H "Authorization: your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{"product_ids": [10, 20, 30]}'

# Выгрузить с пагинацией
curl -X POST https://ваш-сайт.com/wp-json/hugeprofit/v1/export-products \
  -H "Authorization: your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{"limit": 50, "offset": 0}'
```

### 3. Загрузка товаров с HugeProfit

**POST** `/import-products`

Импортирует товары из HugeProfit CRM в WooCommerce.

**Заголовки:**
```
Authorization: ваш_api_токен
Content-Type: application/json
```

**Параметры (опциональные):**
```json
{
  "pids": ["hp_product_id_1", "hp_product_id_2", "hp_product_id_3"]
}
```

- `pids` - массив product_id из системы HugeProfit. Если не указан - загружаются все товары.

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

**Пример использования:**

```bash
# Загрузить все товары из HugeProfit
curl -X POST https://ваш-сайт.com/wp-json/hugeprofit/v1/import-products \
  -H "Authorization: your_api_token_here" \
  -H "Content-Type: application/json"

# Загрузить конкретные товары по их ID в HugeProfit
curl -X POST https://ваш-сайт.com/wp-json/hugeprofit/v1/import-products \
  -H "Authorization: your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{"pids": ["hp_123", "hp_456", "hp_789"]}'
```

## Аутентификация

Все запросы должны содержать заголовок `Authorization` с API токеном, который настраивается в плагине HugeProfit.

Токен можно получить из настроек плагина WordPress после подключения к HugeProfit CRM.

## Коды ошибок

| Код | Описание |
|-----|----------|
| 401 | Отсутствует токен авторизации |
| 403 | Неверный токен авторизации |
| 500 | Внутренняя ошибка сервера |
| 503 | Плагин не настроен или WooCommerce не установлен |

**Пример ошибки:**
```json
{
  "code": "unauthorized",
  "message": "Отсутствует токен авторизации",
  "data": {
    "status": 401
  }
}
```

## Формат данных товара

### При выгрузке в HugeProfit отправляются:

```json
{
  "woo_id": 123,
  "sku": "PRODUCT-001",
  "name": "Название товара",
  "description": "Полное описание",
  "short_description": "Краткое описание",
  "price": "999.99",
  "sale_price": "799.99",
  "stock_quantity": 50,
  "stock_status": "instock",
  "manage_stock": true,
  "status": "publish",
  "type": "simple",
  "categories": [
    {
      "id": 10,
      "name": "Электроника",
      "slug": "electronics"
    }
  ],
  "images": [
    {
      "id": 456,
      "url": "https://site.com/image.jpg",
      "alt": "Alt текст",
      "position": 0
    }
  ],
  "weight": "0.5",
  "length": "10",
  "width": "5",
  "height": "3",
  "permalink": "https://site.com/product/product-001",
  "date_created": "2024-01-15 10:30:00",
  "date_modified": "2024-01-20 14:45:00"
}
```

### При импорте из HugeProfit ожидаются:

```json
{
  "id": "hp_product_123",
  "sku": "PRODUCT-001",
  "name": "Название товара",
  "description": "Полное описание",
  "short_description": "Краткое описание",
  "price": "999.99",
  "sale_price": "799.99",
  "stock_quantity": 50,
  "stock_status": "instock",
  "manage_stock": true,
  "status": "publish",
  "categories": [
    {
      "name": "Электроника",
      "slug": "electronics"
    }
  ],
  "images": [
    {
      "url": "https://hugeprofit.com/images/product.jpg"
    }
  ],
  "weight": "0.5",
  "length": "10",
  "width": "5",
  "height": "3"
}
```

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

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

- `hugeprofit_update_price` - обновлять ли цены (по умолчанию: да)
- `hugeprofit_update_stock` - обновлять ли остатки (по умолчанию: да)
- `hugeprofit_is_description` - обновлять ли описания (по умолчанию: да)

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

Все ошибки API записываются в лог WordPress через функцию `error_log()`.

Для просмотра логов можно использовать:
- Файл `wp-content/debug.log` (если включен WP_DEBUG_LOG)
- Плагины для просмотра логов WordPress

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

1. Все входные данные проходят санитизацию
2. Используется авторизация по токену
3. Запросы логируются для аудита
4. Поддерживается SSL/TLS для безопасной передачи данных

## Примеры интеграции со стороны HugeProfit

### PHP пример

```php
<?php
function hugeprofit_trigger_export($site_url, $api_token) {
    $url = $site_url . '/wp-json/hugeprofit/v1/export-products';
    
    $response = wp_remote_post($url, array(
        'headers' => array(
            'Authorization' => $api_token,
            'Content-Type' => 'application/json',
        ),
        'timeout' => 60,
    ));
    
    if (is_wp_error($response)) {
        return $response;
    }
    
    return json_decode(wp_remote_retrieve_body($response), true);
}

function hugeprofit_trigger_import($site_url, $api_token, $product_ids = array()) {
    $url = $site_url . '/wp-json/hugeprofit/v1/import-products';
    
    $body = empty($product_ids) ? array() : array('pids' => $product_ids);
    
    $response = wp_remote_post($url, array(
        'headers' => array(
            'Authorization' => $api_token,
            'Content-Type' => 'application/json',
        ),
        'body' => json_encode($body),
        'timeout' => 60,
    ));
    
    if (is_wp_error($response)) {
        return $response;
    }
    
    return json_decode(wp_remote_retrieve_body($response), true);
}
```

### JavaScript пример

```javascript
async function exportProducts(siteUrl, apiToken) {
    const response = await fetch(`${siteUrl}/wp-json/hugeprofit/v1/export-products`, {
        method: 'POST',
        headers: {
            'Authorization': apiToken,
            'Content-Type': 'application/json',
        },
    });
    
    return await response.json();
}

async function importProducts(siteUrl, apiToken, productIds = []) {
    const body = productIds.length > 0 ? { pids: productIds } : {};
    
    const response = await fetch(`${siteUrl}/wp-json/hugeprofit/v1/import-products`, {
        method: 'POST',
        headers: {
            'Authorization': apiToken,
            'Content-Type': 'application/json',
        },
        body: JSON.stringify(body),
    });
    
    return await response.json();
}
```

## Дополнительная информация

### Мета-поля

Плагин использует следующие мета-поля для связи товаров:

- `_hugeprofit_product_id` - ID товара в системе HugeProfit
- `_hugeprofit_source_url` - URL исходного изображения из HugeProfit

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

- Рекомендуется использовать пагинацию при выгрузке большого количества товаров
- При импорте изображения кэшируются для предотвращения повторной загрузки
- Таймаут запросов установлен на 60 секунд

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

При возникновении проблем проверьте:
1. Корректность API токена
2. Доступность endpoint'ов (REST API включен в WordPress)
3. Логи ошибок в `wp-content/debug.log`
4. Настройки прав доступа к файлам и директориям