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

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

---

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

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

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 Заголовки запроса

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

• Content-Type: application/json

• MF-ACCESS-KEY: Ваш API-ключ.

• MF-ACCESS-SIGN: Сгенерированная подпись.

• MF-ACCESS-TIMESTAMP: Метка времени в формате UTC.

---

2. Реализация подписи на PHP

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

Пример функции для создания подписи:

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

    // Создаём HMAC-SHA256 подпись
    $hash = hash_hmac('sha256', $string_to_sign, $secret_key, true);

    // Кодируем подпись в Base64
    return base64_encode($hash);
}

---

3. Отправка запросов к API

3.1 Базовая конфигурация

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

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

3.2 Функция отправки запросов

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

/**
 * Отправка запроса к Mefree API.
 *
 * @param string $method HTTP-метод (GET/POST)
 * @param string $request_path Путь запроса (включая параметры)
 * @param string $base_url Базовый URL API
 * @param string $api_key API-ключ
 * @param string $secret_key Секретный ключ API
 * @return array Ответ API
 */
function send_request($method, $request_path, $base_url, $api_key, $secret_key) {
    // Генерируем текущую метку времени в UTC
    $timestamp = gmdate("Y-m-d\TH:i:s.v\Z");

    // Создаём подпись
    $signature = generate_signature($timestamp, $method, $request_path, $secret_key);

    // Устанавливаем заголовки запроса
    $headers = [
        "Content-Type: application/json",
        "MF-ACCESS-KEY: {$api_key}",
        "MF-ACCESS-SIGN: {$signature}",
        "MF-ACCESS-TIMESTAMP: {$timestamp}",
    ];

    // Инициализация CURL
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $base_url . $request_path); // Устанавливаем URL
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);        // Устанавливаем HTTP-метод
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);          // Устанавливаем заголовки
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);          // Возвращаем ответ

    // Выполняем запрос
    $response = curl_exec($ch);
    $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);      // Получаем HTTP-код ответа
    curl_close($ch);

    // Возвращаем результат
    return [
        "status_code" => $http_code,
        "response" => $response
    ];
}

---

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

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

• Endpoint: /api/config

• HTTP-метод: GET

Пример кода:

// Получение информации об аккаунте
$request_path = "/api/config"; // Путь запроса
$response = send_request("GET", $request_path, $base_url, $api_key, $secret_key);

// Обработка ответа
if ($response['status_code'] == 200) {
    echo "Информация об аккаунте:\n";
    echo $response['response'];
} else {
    echo "Ошибка: HTTP статус " . $response['status_code'] . "\n";
    echo "Ответ API: " . $response['response'];
}

---

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

• Endpoint: /api/order?quantity=65000&target_address=TRON_ADDRESS&period=1

• HTTP-метод: POST

Пример кода:

// Создание заказа
$request_path = "/api/order?quantity=65000&target_address=TRON_ADDRESS&period=1"; // Путь запроса
$response = send_request("POST", $request_path, $base_url, $api_key, $secret_key);

// Обработка ответа
if ($response['status_code'] == 200) {
    echo "Заказ успешно создан:\n";
    echo $response['response'];
} else {
    echo "Ошибка: HTTP статус " . $response['status_code'] . "\n";
    echo "Ответ API: " . $response['response'];
}

---

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

• Endpoint: /api/order/{pay_hash}

• HTTP-метод: GET

Пример кода:

// Проверка статуса заказа
$pay_hash = "abcd1234"; // Замените на реальный pay_hash
$request_path = "/api/order/" . $pay_hash; // Путь запроса
$response = send_request("GET", $request_path, $base_url, $api_key, $secret_key);

// Обработка ответа
if ($response['status_code'] == 200) {
    echo "Статус заказа:\n";
    echo $response['response'];
} else {
    echo "Ошибка: HTTP статус " . $response['status_code'] . "\n";
    echo "Ответ API: " . $response['response'];
}

---

5. Частые ошибки

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

• Проверьте правильность MF-ACCESS-KEY.

• Убедитесь, что строка для подписи создана по шаблону: 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, используя PHP. Включены примеры создания запросов, обработки ответов и управления операциями через API. Для критически важных действий (например, создание заказа) рекомендуется добавлять механизм повторных попыток. Если у вас возникнут вопросы, обратитесь в службу поддержки Mefree.