Инструкция по вызову API Mefree.NET на языке Java

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

---

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 (включая параметры), например:

  • /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. Реализация генерации подписи в Java

2.1 Метод для генерации подписи

Пример реализации метода для генерации подписи:

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;

public class MefreeSignatureUtil {
    /**
     * Генерация подписи для Mefree API.
     *
     * @param timestamp     Временная метка (UTC в формате ISO 8601)
     * @param method        HTTP-метод (GET/POST)
     * @param requestPath   Путь запроса (с параметрами)
     * @param secretKey     Секретный ключ API
     * @return Подпись в формате Base64
     */
    public static String generateSignature(String timestamp, String method, String requestPath, String secretKey) {
        try {
            // Формируем строку для подписи
            String stringToSign = timestamp + method + requestPath;

            // Инициализируем HMAC-SHA256
            Mac mac = Mac.getInstance("HmacSHA256");
            SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
            mac.init(secretKeySpec);

            // Вычисляем хэш и кодируем его в Base64
            byte[] hmacBytes = mac.doFinal(stringToSign.getBytes());
            return Base64.getEncoder().encodeToString(hmacBytes);
        } catch (Exception e) {
            throw new RuntimeException("Ошибка при генерации подписи", e);
        }
    }
}

---

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

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

Создайте конфигурацию с основными параметрами:

public class MefreeConfig {
    public static final String BASE_URL = "https://api.mefree.net"; // Базовый URL Mefree API
    public static final String API_KEY = "your_api_key";       // Ваш API-ключ
    public static final String SECRET_KEY = "your_secret_key"; // Ваш секретный ключ
}

3.2 Универсальный метод для отправки запросов

Используйте следующий метод для отправки HTTP-запросов:

import java.net.HttpURLConnection;
import java.net.URL;
import java.io.OutputStream;
import java.io.InputStream;
import java.util.Scanner;

public class MefreeApiRequest {
    /**
     * Отправка запроса к API Mefree.
     *
     * @param method      HTTP-метод (GET/POST)
     * @param requestPath Путь запроса (с параметрами)
     * @return Ответ API в виде строки
     * @throws Exception В случае ошибки
     */
    public static String sendRequest(String method, String requestPath) throws Exception {
        // Генерация временной метки (UTC)
        String timestamp = java.time.Instant.now().toString();

        // Генерация подписи
        String signature = MefreeSignatureUtil.generateSignature(timestamp, method, requestPath, MefreeConfig.SECRET_KEY);

        // Формируем полный URL
        URL url = new URL(MefreeConfig.BASE_URL + requestPath);

        // Настраиваем соединение
        HttpURLConnection connection = (HttpURLConnection) url.openConnection();
        connection.setRequestMethod(method);
        connection.setRequestProperty("Content-Type", "application/json");
        connection.setRequestProperty("MF-ACCESS-KEY", MefreeConfig.API_KEY);
        connection.setRequestProperty("MF-ACCESS-SIGN", signature);
        connection.setRequestProperty("MF-ACCESS-TIMESTAMP", timestamp);

        // Отправляем запрос и читаем ответ
        InputStream responseStream = connection.getInputStream();
        Scanner scanner = new Scanner(responseStream).useDelimiter("\\A");
        return scanner.hasNext() ? scanner.next() : "";
    }
}

---

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

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

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

Пример кода:

public class MefreeExample {
    public static void main(String[] args) {
        try {
            // Вызов API для получения информации об аккаунте
            String response = MefreeApiRequest.sendRequest("GET", "/api/config");
            System.out.println("Информация об аккаунте:");
            System.out.println(response);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

---

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

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

Пример кода:

public class MefreeExample {
    public static void main(String[] args) {
        try {
            // Вызов API для создания заказа
            String response = MefreeApiRequest.sendRequest("POST", "/api/order?quantity=65000&target_address=TRON_ADDRESS&period=1");
            System.out.println("Заказ успешно создан:");
            System.out.println(response);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

---

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

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

Пример кода:

public class MefreeExample {
    public static void main(String[] args) {
        try {
            // Проверка статуса заказа
            String payHash = "abcd1234"; // Замените на реальный pay_hash
            String response = MefreeApiRequest.sendRequest("GET", "/api/order/" + payHash);
            System.out.println("Статус заказа:");
            System.out.println(response);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

---

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)

• API Mefree имеет ограничение на частоту запросов. Избегайте отправки слишком большого количества запросов за короткое время.

• Рекомендуется не превышать 2 запроса в секунду.

---

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

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