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

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

***

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

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

**1.1 Формирование строки для подписи**

Строка для подписи формируется по следующему шаблону:

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

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

* `Content-Type`: `application/json`
* `MF-ACCESS-KEY`: Ваш API-ключ.
* `MF-ACCESS-SIGN`: Сгенерированная подпись.
* `MF-ACCESS-TIMESTAMP`: Метка времени в формате UTC.

***

#### **2. Реализация подписи в Python**

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

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

```python
import hmac
import hashlib
import base64

def generate_signature(timestamp, method, request_path, secret_key):
    """
    Генерация подписи для Mefree API.

    :param timestamp: Метка времени (UTC в формате ISO 8601)
    :param method: HTTP-метод (GET/POST)
    :param request_path: Путь запроса (включая параметры)
    :param secret_key: Секретный ключ API
    :return: Подпись в формате Base64
    """
    # Формируем строку для подписи
    string_to_sign = f"{timestamp}{method}{request_path}"
    
    # Используем HMAC-SHA256 для шифрования строки
    hmac_obj = hmac.new(secret_key.encode('utf-8'), string_to_sign.encode('utf-8'), hashlib.sha256)
    
    # Возвращаем подпись в формате Base64
    return base64.b64encode(hmac_obj.digest()).decode('utf-8')
```

***

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

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

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

```python
# Конфигурация API
BASE_URL = "https://api.mefree.net"       # Базовый URL Mefree API
API_KEY = "your_api_key"             # Ваш API-ключ
SECRET_KEY = "your_secret_key"       # Ваш секретный ключ
```

**3.2 Универсальная функция для отправки запросов**

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

```python
import requests
from datetime import datetime, timezone

def send_request(method, request_path):
    """
    Отправка запроса к Mefree API.

    :param method: HTTP-метод (GET/POST)
    :param request_path: Путь запроса (включая параметры)
    :return: Ответ API в формате JSON
    """
    # Генерируем метку времени (UTC)
    timestamp = datetime.now(timezone.utc).isoformat(timespec='milliseconds').replace('+00:00', '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
    }

    # Полный URL
    url = BASE_URL + request_path

    # Выполняем запрос
    response = requests.request(method, url, headers=headers)

    # Возвращаем JSON-ответ или текст ошибки
    return {
        "status_code": response.status_code,
        "response": response.json() if response.headers.get('Content-Type') == 'application/json' else response.text
    }
```

***

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

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

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

**Пример:**

```python
if __name__ == "__main__":
    # Вызов API для получения информации об аккаунте
    result = send_request("GET", "/api/config")

    # Обработка ответа
    if result['status_code'] == 200:
        print("Информация об аккаунте:")
        print(result['response'])
    else:
        print(f"Ошибка: {result['status_code']}")
        print(result['response'])
```

***

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

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

**Пример:**

```python
if __name__ == "__main__":
    # Вызов API для создания заказа
    result = send_request("POST", "/api/order?quantity=65000&target_address=TRON_ADDRESS&period=1")

    # Обработка ответа
    if result['status_code'] == 200:
        print("Заказ успешно создан:")
        print(result['response'])
    else:
        print(f"Ошибка: {result['status_code']}")
        print(result['response'])
```

***

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

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

**Пример:**

```python
if __name__ == "__main__":
    # ID заказа для проверки
    pay_hash = "abcd1234"  # Замените на реальный pay_hash

    # Вызов API для проверки статуса заказа
    result = send_request("GET", f"/api/order/{pay_hash}")

    # Обработка ответа
    if result['status_code'] == 200:
        print("Статус заказа:")
        print(result['response'])
    else:
        print(f"Ошибка: {result['status_code']}")
        print(result['response'])
```

***

#### **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)**

* Mefree API имеет ограничения на частоту запросов. Избегайте частых вызовов в короткий промежуток времени.
* Рекомендуется не превышать 2 запроса в секунду.

***

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

Это руководство поможет вам эффективно взаимодействовать с API Mefree.NET на Python. Вы можете создавать запросы, обрабатывать ответы и получать доступ к функционалу платформы. Для критически важных операций (например, создание заказа) рекомендуется реализовать повторные попытки для повышения надежности. При возникновении вопросов обратитесь в службу поддержки 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/python.md?ask=<question>
```

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.