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

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