调试示例

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

Python 示例

import requests

# 1. 配置认证信息
API_TOKEN = "替换为您的实际访问令牌"  # 请替换为从Legend获取的有效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. 获取访问令牌:在开始集成前,请联系 Legend 技术团队获取有效的 API_TOKEN

  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地址提供给我们,以便我们将其加入访问白名单。此配置在测试和生产环境中均需要完成。

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

预期成功响应

{
  "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是否正确,联系Legend更新
无响应/超时网络问题检查网络连接,确认URL可访问
400 Bad Request缺少必要头部确认已包含 User-Ip 头部