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

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

---

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

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

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

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

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 Установка необходимых библиотек

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

npm install axios crypto

• axios: Для отправки HTTP-запросов.

• crypto: Встроенная библиотека Node.js для создания подписи.

---

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

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

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:

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 Универсальная функция для отправки запросов

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

/**
 * Отправка запроса к 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

Пример:

(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

Пример:

(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

Пример:

(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.