调试示例

以下示例代码演示如何调用 Legend Gateway API,以获取平台支持的国家列表为例。

Python 示例

import requests

# 1. 配置认证信息
API_TOKEN = "替换为您的实际访问令牌"  # 沙箱:请在 DevTools 中自助生成(系统设置 -> REST API Token)
BASE_URL = "https://sandboxapi.legendtrading.com"  # 沙箱环境地址

# 2. 设置请求头部
headers = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Accept": "application/json",
    "User-Ip": "123.45.67.89"  # 替换为终端用户的真实公网IP
}

# 3. 发起API请求
try:
    # 调用"获取国家列表"接口
    response = requests.get(
        f"{BASE_URL}/v2/app/countries",
        headers=headers,
        timeout=10  # 设置10秒超时
    )
    
    # 4. 处理响应
    response.raise_for_status()  # 检查HTTP错误
    result = response.json()
    
    # 打印完整响应
    print("请求成功!")
    print("响应数据:", result)
    
except requests.exceptions.RequestException as e:
    print(f"请求失败: {e}")
    if hasattr(e.response, 'text'):
        print(f"错误详情: {e.response.text}")

cURL 示例

curl --http1.1  -X GET \
  -H "Authorization: Bearer 替换为您的实际访问令牌" \
  -H "Accept: application/json" \
  -H "User-Ip: 123.45.67.89" \
  "https://sandboxapi.legendtrading.com/v2/app/countries"

关键步骤说明

  1. 获取访问令牌:沙箱环境下,你在 DevTools 中自助生成有效的 API_TOKEN(系统设置 → REST API Token → +生成新 Token);生产环境请联系 Legend 技术团队。详见概述与认证。

  2. 设置请求头:调用 API 时,所有请求必须在 HTTP 头部中至少包含以下两个字段:

    • Authorization:用于身份认证,格式为 Bearer {您的API_TOKEN}。
    • User-Ip:必须传递终端用户的真实公网 IP 地址,用于风控和审计。切勿使用服务器IP或代理IP。
  3. 选择环境:请根据您的开发阶段使用正确的接口地址。

    • 沙箱环境:https://sandboxapi.legendtrading.com
    • 生产环境:https://api.legendtrading.com

    注意:两个环境的凭证相互独立,严禁混用。

  4. 配置服务器IP白名单:为了保障接口安全,请将所有发起API请求的服务器出口IP地址加入访问白名单。沙箱环境下由你自行在 DevTools 中添加(系统设置 → IP 白名单);生产环境请提供给我们,由我们添加。两个环境均需完成此配置。

  5. 实施错误处理:请务必在您的代码中检查并处理所有可能的 HTTP 响应状态码(特别是 4xx 和 5xx 错误),实现适当的重试、降级或告警逻辑,以确保集成的稳定性和可靠性。

预期成功响应

{
  "request_id": "0578ac927c446fedd16a32e2846028a9",
  "status": "success",
  "code": "100000",
  "message": "success",
  "data": [
    {
      "country_iso2_code": "US",
      "country_name": "United States"
    },
    {
      "country_iso2_code": "GB", 
      "country_name": "United Kingdom"
    }
  ],
  "metadata": {}
}

常见问题排查

问题可能原因解决方案
401 UnauthorizedToken无效或过期检查 Token 是否正确。沙箱环境请在 DevTools 中重新生成;生产环境请联系 Legend 更换
无响应/超时网络问题检查网络连接,确认URL可访问
400 Bad Request缺少必要头部确认已包含 User-Ip 头部