> 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/python.md).

# Руководство по вызову 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.