Данное руководство подробно описывает, как с помощью 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 (включая параметры), например:
Объедините timestamp, method и requestPath в одну строку.
Используйте алгоритм HMAC-SHA256, чтобы зашифровать строку с использованием вашего секретного ключа API (Secret Key).
Закодируйте результат с помощью 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/configHTTP-метод: 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=1HTTP-метод: 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.
