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

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

***

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

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

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

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

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

***

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

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

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

```php
/**
 * Генерация подписи для Mefree API.
 *
 * @param string $timestamp Метка времени (UTC в формате ISO 8601)
 * @param string $method HTTP-метод (GET/POST)
 * @param string $request_path Путь запроса (включая параметры)
 * @param string $secret_key Секретный ключ API
 * @return string Подпись в формате Base64
 */
function generate_signature($timestamp, $method, $request_path, $secret_key) {
    // Формируем строку для подписи
    $string_to_sign = $timestamp . $method . $request_path;

    // Создаём HMAC-SHA256 подпись
    $hash = hash_hmac('sha256', $string_to_sign, $secret_key, true);

    // Кодируем подпись в Base64
    return base64_encode($hash);
}
```

***

#### **3. Отправка запросов к API**

**3.1 Базовая конфигурация**

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

```php
// Конфигурация API
$base_url = "https://api.mefree.net";        // Базовый URL Mefree API
$api_key = "your_api_key";              // Ваш API-ключ
$secret_key = "your_secret_key";        // Ваш секретный ключ
```

**3.2 Функция отправки запросов**

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

```php
/**
 * Отправка запроса к Mefree API.
 *
 * @param string $method HTTP-метод (GET/POST)
 * @param string $request_path Путь запроса (включая параметры)
 * @param string $base_url Базовый URL API
 * @param string $api_key API-ключ
 * @param string $secret_key Секретный ключ API
 * @return array Ответ API
 */
function send_request($method, $request_path, $base_url, $api_key, $secret_key) {
    // Генерируем текущую метку времени в UTC
    $timestamp = gmdate("Y-m-d\TH:i:s.v\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}",
    ];

    // Инициализация CURL
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $base_url . $request_path); // Устанавливаем URL
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);        // Устанавливаем HTTP-метод
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);          // Устанавливаем заголовки
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);          // Возвращаем ответ

    // Выполняем запрос
    $response = curl_exec($ch);
    $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);      // Получаем HTTP-код ответа
    curl_close($ch);

    // Возвращаем результат
    return [
        "status_code" => $http_code,
        "response" => $response
    ];
}
```

***

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

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

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

**Пример кода:**

```php
// Получение информации об аккаунте
$request_path = "/api/config"; // Путь запроса
$response = send_request("GET", $request_path, $base_url, $api_key, $secret_key);

// Обработка ответа
if ($response['status_code'] == 200) {
    echo "Информация об аккаунте:\n";
    echo $response['response'];
} else {
    echo "Ошибка: HTTP статус " . $response['status_code'] . "\n";
    echo "Ответ API: " . $response['response'];
}
```

***

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

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

**Пример кода:**

```php
// Создание заказа
$request_path = "/api/order?quantity=65000&target_address=TRON_ADDRESS&period=1"; // Путь запроса
$response = send_request("POST", $request_path, $base_url, $api_key, $secret_key);

// Обработка ответа
if ($response['status_code'] == 200) {
    echo "Заказ успешно создан:\n";
    echo $response['response'];
} else {
    echo "Ошибка: HTTP статус " . $response['status_code'] . "\n";
    echo "Ответ API: " . $response['response'];
}
```

***

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

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

**Пример кода:**

```php
// Проверка статуса заказа
$pay_hash = "abcd1234"; // Замените на реальный pay_hash
$request_path = "/api/order/" . $pay_hash; // Путь запроса
$response = send_request("GET", $request_path, $base_url, $api_key, $secret_key);

// Обработка ответа
if ($response['status_code'] == 200) {
    echo "Статус заказа:\n";
    echo $response['response'];
} else {
    echo "Ошибка: HTTP статус " . $response['status_code'] . "\n";
    echo "Ответ API: " . $response['response'];
}
```

***

#### **5. Частые ошибки**

**5.1 Неверная подпись (401 Unauthorized)**

* Проверьте правильность `MF-ACCESS-KEY`.
* Убедитесь, что строка для подписи создана по шаблону: `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. Заключение**

С помощью данного руководства вы сможете эффективно взаимодействовать с Mefree.NET API, используя PHP. Включены примеры создания запросов, обработки ответов и управления операциями через API. Для критически важных действий (например, создание заказа) рекомендуется добавлять механизм повторных попыток. Если у вас возникнут вопросы, обратитесь в службу поддержки 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/php.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.