PHP调用Mefree.NET API

本指南将详细介绍如何通过PHP实现对Mefree.NET的API调用，包括生成签名的方法、请求的构建以及接口调用的完整流程。

---

1. 签名规则概述

Mefree.NET API 的身份验证通过签名机制进行，签名的生成逻辑如下：

1.1 签名字符串规则

签名使用以下格式的字符串：

sign = timestamp + method + requestPath

• timestamp：UTC 时间，格式为 ISO 8601（例如：2024-11-26T12:34:56.789Z）。

• method：HTTP 方法，如 GET 或 POST。

• requestPath：API 请求路径（包括查询参数），例如：

  • /api/config

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

1.2 签名生成流程

1. 使用 HMAC-SHA256 算法，用 API 的 Secret Key 对拼接的字符串进行加密。

2. 将加密结果用 Base64 编码，得到签名值。

1.3 请求头参数

每次请求需要添加以下 HTTP 头：

• Content-Type: application/json

• MF-ACCESS-KEY: 您的 API Key。

• MF-ACCESS-SIGN: 生成的签名值。

• MF-ACCESS-TIMESTAMP: 当前的 UTC 时间戳。

---

2. PHP实现签名方法

2.1 签名生成函数

/**
 * 生成 Mefree API 的签名
 * @param string $timestamp UTC 时间戳 (ISO 8601 格式)
 * @param string $method HTTP 方法 (GET/POST)
 * @param string $request_path API 请求路径（含参数）
 * @param string $secret_key API 的 Secret Key
 * @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 的基础信息：

// API 配置信息
$base_url = "https://api.mefree.net";        // Mefree API 基础地址
$api_key = "your_api_key";              // 替换为实际的 API Key
$secret_key = "your_secret_key";        // 替换为实际的 Secret Key

3.2 发起请求的函数

使用 CURL 构建通用的 HTTP 请求函数：

/**
 * 发起 Mefree API 请求
 * @param string $method HTTP 方法 (GET/POST)
 * @param string $request_path API 请求路径（含查询参数）
 * @param string $base_url API 基础 URL
 * @param string $api_key API Key
 * @param string $secret_key API Secret Key
 * @return mixed 返回 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);        // 设置请求方法
    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. 示例接口调用

4.1 获取账户信息

接口描述：

• 请求路径：/api/config

• HTTP 方法：GET

调用代码：

// 获取账户信息
$request_path = "/api/config"; // API 请求路径
$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 "响应内容：" . $response['response'];
}

---

4.2 创建订单

接口描述：

• 请求路径：/api/order?quantity=65000&target_address=TRON_ADDRESS&period=1

• HTTP 方法：POST

调用代码：

// 创建订单
$request_path = "/api/order?quantity=65000&target_address=TRON_ADDRESS&period=1"; // API 请求路径
$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 "响应内容：" . $response['response'];
}

---

4.3 查询订单状态

接口描述：

• 请求路径：/api/order/{pay_hash}

• HTTP 方法：GET

调用代码：

// 查询订单状态
$pay_hash = "abcd1234"; // 替换为实际订单的 pay_hash
$request_path = "/api/order/" . $pay_hash; // API 请求路径
$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 "响应内容：" . $response['response'];
}

---

5. 常见问题

5.1 签名无效 (401 Unauthorized)

• 确认 MF-ACCESS-KEY 是否正确。

• 确保签名按照规则生成：

  • 拼接顺序为：timestamp + method + requestPath。

  • 时间戳需为 UTC 格式，格式示例：2024-11-26T12:34:56.789Z。

  • 使用正确的 SECRET_KEY 生成签名。

5.2 请求参数错误 (400 Bad Request)

• 检查请求路径是否正确，尤其是查询参数是否完整。

• 确认 Content-Type 是否为 application/json。

5.3 请求速率限制 (429 Too Many Requests)

• Mefree API 对请求频率有限制，需避免在短时间内发起大量请求。

• 添加合理的请求间隔（例如每秒最多 2 次请求）。

---

6. 总结

通过以上文档，您可以使用 PHP 高效实现对 Mefree.NET API 的调用，包括生成签名、发送请求以及解析响应数据。对重要操作（如下单）时，建议加上重试机制以提高稳定性。如有疑问，请联系 Mefree 官方支持团队。