# Инструкция по вызову 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 Метод для генерации подписи** Пример реализации метода для генерации подписи: ```java 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 Конфигурация** Создайте конфигурацию с основными параметрами: ```java 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-запросов: ```java 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` **Пример кода**: ```java 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` **Пример кода**: ```java 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` **Пример кода**: ```java 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.mefree.net/ru/getting-started/how-to-buy-energy/java.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.