# Руководство по вызову Mefree.NET API на Node.js

Данное руководство описывает процесс взаимодействия с API платформы **Mefree.NET** с использованием Node.js. Оно включает создание подписи, отправку запросов и обработку ответов от API.

***

#### **1. Общая информация о правилах подписи**

Для аутентификации Mefree.NET API требует подпись, которая создаётся следующим образом:

**1.1 Формирование строки для подписи**

Строка для подписи формируется по следующему шаблону:

```plaintext
sign = timestamp + method + requestPath
```

* **timestamp**: Метка времени в формате UTC (ISO 8601), например: `2024-11-26T12:34:56.789Z`.
* **method**: HTTP-метод, например, `GET` или `POST`.
* **requestPath**: Путь запроса (включая параметры), например:
  * `/api/config`
  * `/api/order?quantity=65000&target_address=TRON_ADDRESS&period=1`

**1.2 Процесс генерации подписи**

1. Объедините `timestamp`, `method` и `requestPath` в строку.
2. Используйте алгоритм **HMAC-SHA256**, чтобы зашифровать строку с использованием вашего **секретного ключа API (Secret Key)**.
3. Закодируйте результат с помощью **Base64**, чтобы получить финальную подпись.

**1.3 Заголовки HTTP-запроса**

Каждый запрос к API должен содержать следующие заголовки:

* `Content-Type`: `application/json`
* `MF-ACCESS-KEY`: Ваш API-ключ.
* `MF-ACCESS-SIGN`: Сгенерированная подпись.
* `MF-ACCESS-TIMESTAMP`: Метка времени в формате UTC.

***

#### **2. Реализация подписи на Node.js**

**2.1 Установка необходимых библиотек**

Перед началом убедитесь, что у вас установлены следующие библиотеки:

```bash
npm install axios crypto
```

* **axios**: Для отправки HTTP-запросов.
* **crypto**: Встроенная библиотека Node.js для создания подписи.

***

**2.2 Функция для генерации подписи**

Ниже приведён пример функции для генерации подписи:

```javascript
const crypto = require('crypto');

/**
 * Генерация подписи для Mefree API.
 *
 * @param {string} timestamp Метка времени (UTC в формате ISO 8601)
 * @param {string} method HTTP-метод (GET/POST)
 * @param {string} requestPath Путь запроса (включая параметры)
 * @param {string} secretKey Секретный ключ API
 * @returns {string} Подпись в формате Base64
 */
function generateSignature(timestamp, method, requestPath, secretKey) {
    // Формируем строку для подписи
    const stringToSign = `${timestamp}${method}${requestPath}`;

    // Используем HMAC-SHA256 для шифрования строки
    const hmac = crypto.createHmac('sha256', secretKey);
    hmac.update(stringToSign);

    // Возвращаем подпись в формате Base64
    return hmac.digest('base64');
}
```

***

#### **3. Создание запросов к API**

**3.1 Конфигурация**

Задайте базовые параметры для подключения к API:

```javascript
const axios = require('axios');

// Конфигурация API
const BASE_URL = "https://api.mefree.net";       // Базовый URL Mefree API
const API_KEY = "your_api_key";             // Ваш API-ключ
const SECRET_KEY = "your_secret_key";       // Ваш секретный ключ
```

**3.2 Универсальная функция для отправки запросов**

Используйте следующую функцию для отправки запросов:

```javascript
/**
 * Отправка запроса к Mefree API.
 *
 * @param {string} method HTTP-метод (GET/POST)
 * @param {string} requestPath Путь запроса (включая параметры)
 * @returns {Promise<Object>} Ответ API
 */
async function sendRequest(method, requestPath) {
    // Генерируем метку времени (UTC)
    const timestamp = new Date().toISOString();

    // Генерируем подпись
    const signature = generateSignature(timestamp, method, requestPath, SECRET_KEY);

    // Заголовки запроса
    const headers = {
        'Content-Type': 'application/json',
        'MF-ACCESS-KEY': API_KEY,
        'MF-ACCESS-SIGN': signature,
        'MF-ACCESS-TIMESTAMP': timestamp,
    };

    // Полный URL
    const url = `${BASE_URL}${requestPath}`;

    try {
        // Выполняем запрос
        const response = await axios({
            method,
            url,
            headers,
        });

        // Возвращаем ответ API
        return {
            statusCode: response.status,
            data: response.data,
        };
    } catch (error) {
        // Обработка ошибок
        return {
            statusCode: error.response?.status || 500,
            error: error.response?.data || error.message,
        };
    }
}
```

***

#### **4. Примеры вызовов API**

**4.1 Получение информации об аккаунте**

* **Endpoint**: `/api/config`
* **HTTP-метод**: `GET`

**Пример:**

```javascript
(async () => {
    const response = await sendRequest('GET', '/api/config');

    if (response.statusCode === 200) {
        console.log("Информация об аккаунте:", response.data);
    } else {
        console.error("Ошибка:", response);
    }
})();
```

***

**4.2 Создание заказа**

* **Endpoint**: `/api/order?quantity=65000&target_address=TRON_ADDRESS&period=1`
* **HTTP-метод**: `POST`

**Пример:**

```javascript
(async () => {
    const requestPath = '/api/order?quantity=65000&target_address=TRON_ADDRESS&period=1';
    const response = await sendRequest('POST', requestPath);

    if (response.statusCode === 200) {
        console.log("Заказ успешно создан:", response.data);
    } else {
        console.error("Ошибка:", response);
    }
})();
```

***

**4.3 Проверка статуса заказа**

* **Endpoint**: `/api/order/{pay_hash}`
* **HTTP-метод**: `GET`

**Пример:**

```javascript
(async () => {
    const payHash = 'abcd1234'; // Замените на реальный pay_hash
    const requestPath = `/api/order/${payHash}`;
    const response = await sendRequest('GET', requestPath);

    if (response.statusCode === 200) {
        console.log("Статус заказа:", response.data);
    } else {
        console.error("Ошибка:", response);
    }
})();
```

***

#### **5. Часто встречающиеся ошибки**

**5.1 Неверная подпись (401 Unauthorized)**

* Убедитесь, что заголовок `MF-ACCESS-KEY` содержит правильный API-ключ.
* Проверьте, что строка для подписи сформирована в правильной последовательности: `timestamp + method + requestPath`.
* Используйте правильный **SECRET\_KEY**.
* Метка времени должна быть в формате UTC.

**5.2 Ошибки параметров (400 Bad Request)**

* Проверьте правильность пути и параметров в запросе.
* Убедитесь, что заголовок `Content-Type` установлен как `application/json`.

**5.3 Ограничение частоты запросов (429 Too Many Requests)**

* Mefree API имеет ограничения на частоту запросов. Избегайте частых вызовов в короткий промежуток времени.
* Рекомендуется не превышать 2 запроса в секунду.

***

#### **6. Заключение**

С помощью этого руководства вы сможете успешно взаимодействовать с Mefree.NET API на Node.js. Вы научитесь создавать запросы, обрабатывать ответы и управлять действиями через API. Для важнейших операций (например, создание заказа) рекомендуется реализовать повторные попытки для повышения надежности. При возникновении вопросов обратитесь в службу поддержки Mefree.