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

В этом руководстве подробно описано, как работать с API платформы Mefree.NET на языке Go. Приведены инструкции по генерации подписи, отправке запросов и обработке ответов.

---

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/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. Реализация подписи на Go

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

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

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/base64"
	"fmt"
)

// GenerateSignature создаёт подпись для Mefree API
func GenerateSignature(timestamp, method, requestPath, secretKey string) (string, error) {
	// Формируем строку для подписи
	stringToSign := timestamp + method + requestPath

	// Создаём HMAC-SHA256 хэш
	h := hmac.New(sha256.New, []byte(secretKey))
	_, err := h.Write([]byte(stringToSign))
	if err != nil {
		return "", err
	}

	// Кодируем хэш в Base64
	signature := base64.StdEncoding.EncodeToString(h.Sum(nil))
	return signature, nil
}

---

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

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

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

const (
	BaseURL   = "https://api.mefree.net"  // Базовый URL Mefree API
	APIKey    = "your_api_key"        // Ваш API-ключ
	SecretKey = "your_secret_key"     // Ваш секретный ключ
)

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

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

package main

import (
	"bytes"
	"fmt"
	"io/ioutil"
	"net/http"
	"time"
)

// SendRequest отправляет запрос к Mefree API
func SendRequest(method, requestPath string) (int, string, error) {
	// Генерируем текущую метку времени в формате UTC
	timestamp := time.Now().UTC().Format("2006-01-02T15:04:05.000Z")

	// Создаём подпись
	signature, err := GenerateSignature(timestamp, method, requestPath, SecretKey)
	if err != nil {
		return 0, "", fmt.Errorf("error generating signature: %v", err)
	}

	// Устанавливаем заголовки
	headers := map[string]string{
		"Content-Type":           "application/json",
		"MF-ACCESS-KEY":          APIKey,
		"MF-ACCESS-SIGN":         signature,
		"MF-ACCESS-TIMESTAMP":    timestamp,
	}

	// Формируем запрос
	url := BaseURL + requestPath
	req, err := http.NewRequest(method, url, nil)
	if err != nil {
		return 0, "", fmt.Errorf("error creating request: %v", err)
	}

	// Добавляем заголовки к запросу
	for key, value := range headers {
		req.Header.Set(key, value)
	}

	// Отправляем запрос
	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		return 0, "", fmt.Errorf("error sending request: %v", err)
	}
	defer resp.Body.Close()

	// Читаем тело ответа
	body, err := ioutil.ReadAll(resp.Body)
	if err != nil {
		return resp.StatusCode, "", fmt.Errorf("error reading response: %v", err)
	}

	return resp.StatusCode, string(body), nil
}

---

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

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

• Endpoint: /api/config

• HTTP-метод: GET

Пример кода:

func main() {
	// Путь запроса
	requestPath := "/api/config"

	// Отправляем запрос
	statusCode, response, err := SendRequest("GET", requestPath)
	if err != nil {
		fmt.Printf("Ошибка: %v\n", err)
		return
	}

	// Обрабатываем ответ
	if statusCode == 200 {
		fmt.Println("Информация об аккаунте:")
		fmt.Println(response)
	} else {
		fmt.Printf("Ошибка: HTTP статус %d\nОтвет: %s\n", statusCode, response)
	}
}

---

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

• Endpoint: /api/order?quantity=65000&target_address=TRON_ADDRESS&period=1

• HTTP-метод: POST

Пример кода:

func main() {
	// Путь запроса
	requestPath := "/api/order?quantity=65000&target_address=TRON_ADDRESS&period=1"

	// Отправляем запрос
	statusCode, response, err := SendRequest("POST", requestPath)
	if err != nil {
		fmt.Printf("Ошибка: %v\n", err)
		return
	}

	// Обрабатываем ответ
	if statusCode == 200 {
		fmt.Println("Заказ успешно создан:")
		fmt.Println(response)
	} else {
		fmt.Printf("Ошибка: HTTP статус %d\nОтвет: %s\n", statusCode, response)
	}
}

---

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

• Endpoint: /api/order/{pay_hash}

• HTTP-метод: GET

Пример кода:

func main() {
	// Путь запроса
	payHash := "abcd1234" // Замените на реальный pay_hash
	requestPath := "/api/order/" + payHash

	// Отправляем запрос
	statusCode, response, err := SendRequest("GET", requestPath)
	if err != nil {
		fmt.Printf("Ошибка: %v\n", err)
		return
	}

	// Обрабатываем ответ
	if statusCode == 200 {
		fmt.Println("Статус заказа:")
		fmt.Println(response)
	} else {
		fmt.Printf("Ошибка: HTTP статус %d\nОтвет: %s\n", statusCode, 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. Заключение

С помощью данного руководства вы сможете эффективно взаимодействовать с API платформы Mefree.NET на языке Go. Включены примеры создания запросов, обработки ответов и управления операциями через API. Для критически важных операций (например, создание заказа) рекомендуется реализовать повторные попытки. Если у вас возникнут вопросы, обращайтесь в службу поддержки Mefree.NET.