> For the complete documentation index, see [llms.txt](https://docs.mefree.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mefree.net/ru/getting-started/how-to-buy-energy/java.md). # Инструкция по вызову 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.