Currency Exchange Rate

能力概述

调用汇率转换 API，根据指定源货币代码查询该货币对其他所有货币的实时汇率信息。

• Endpoint: POST https://app-bo4w33bsdqm9-api-ELbWz8OmBW5Y-gateway.appmiaoda.com/exchange-rate-v2/single
• Content-Type: application/x-www-form-urlencoded
• 认证: platform_managed（密钥由平台注入）
• 支持货币: 200 多种，含 CNY、USD、EUR、JPY、GBP、HKD、SGD 等主流货币及各国小币种
• 支持平台: Web / MiniProgram / App
• 响应: JSON，data.list 为以目标货币代码为键的对象，每项含汇率 rate、货币名称 name、更新时间 updatetime

响应示例：

{
  "code": 200,
  "msg": "成功",
  "taskNo": "825091389158520001104287",
  "data": {
    "name": "英镑",
    "currency": "GBP",
    "list": {
      "FJD": {
        "rate": "2.946800",
        "name": "斐济元",
        "updatetime": "2024-10-29 04:37:55"
      },
      "MXN": {
        "rate": "25.949600",
        "name": "墨西哥比索",
        "updatetime": "2024-10-29 13:54:37"
      }
    }
  }
}

返回码说明：

生成期用法（Agent 直接调用）

const apiKey = process.env["INTEGRATIONS_API_KEY"]!; // platform_managed，密钥由平台注入

interface ExchangeRateItem {
  rate: string;
  name: string;
  updatetime: string;
}

interface ExchangeRateData {
  name: string;
  currency: string;
  list: Record<string, ExchangeRateItem>;
}

/**
 * 查询指定源货币对所有其他货币的实时汇率列表。
 * @param fromCode - 源货币代码，如 CNY、USD、EUR、JPY、GBP 等
 * @returns 汇率数据对象，含源货币名称、代码及目标货币汇率列表
 */
async function getExchangeRates(fromCode: string): Promise<ExchangeRateData> {
  const response = await fetch(
    "https://app-bo4w33bsdqm9-api-ELbWz8OmBW5Y-gateway.appmiaoda.com/exchange-rate-v2/single",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
        "X-Gateway-Authorization": `Bearer ${apiKey}`,
      },
      body: new URLSearchParams({ fromCode }).toString(),
    }
  );

  if (!response.ok) throw new Error(`HTTP error: ${response.status}`);

  const json = await response.json();
  if (json.code !== 200) throw new Error(`API error ${json.code}: ${json.msg}`);

  return json.data as ExchangeRateData;
}

// 示例：查询英镑对所有货币的汇率
const data = await getExchangeRates("GBP");
console.log(`${data.name}（${data.currency}）汇率列表：`);
for (const [code, info] of Object.entries(data.list)) {
  console.log(`  ${code} ${info.name}: ${info.rate}（更新于 ${info.updatetime}）`);
}

生成后用法（应用内通过 Edge Function 调用）

Edge Function

// edge-functions/currency-exchange-rate.ts
import { serve } from "https://deno.land/std/http/server.ts";

serve(async (req: Request): Promise<Response> => {
  if (req.method !== "POST") {
    return new Response("Method Not Allowed", { status: 405 });
  }

  // --- 解析客户端请求 ---
  let fromCode: string;
  try {
    const body = await req.json();
    fromCode = body.fromCode;
    if (!fromCode) throw new Error("Missing fromCode");
  } catch {
    return new Response(JSON.stringify({ error: "Invalid request body" }), {
      status: 400,
      headers: { "Content-Type": "application/json" },
    });
  }

  // --- 注入平台密钥（严禁暴露到前端） ---
  const apiKey = Deno.env.get("INTEGRATIONS_API_KEY");
  if (!apiKey) {
    return new Response(JSON.stringify({ error: "Server configuration error" }), {
      status: 500,
      headers: { "Content-Type": "application/json" },
    });
  }

  // --- 调用上游 API ---
  const upstream = await fetch(
    "https://app-bo4w33bsdqm9-api-ELbWz8OmBW5Y-gateway.appmiaoda.com/exchange-rate-v2/single",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
        "X-Gateway-Authorization": `Bearer ${apiKey}`,
      },
      body: new URLSearchParams({ fromCode }).toString(),
    }
  );

  // 转发配额/余额错误
  if (upstream.status === 429 || upstream.status === 402) {
    const errText = await upstream.text();
    return new Response(errText, {
      status: upstream.status,
      headers: { "Content-Type": "application/json" },
    });
  }

  if (!upstream.ok) {
    return new Response(
      JSON.stringify({ error: `Upstream error: ${upstream.status}` }),
      { status: 502, headers: { "Content-Type": "application/json" } }
    );
  }

  const data = await upstream.json();
  return new Response(JSON.stringify(data), {
    status: 200,
    headers: { "Content-Type": "application/json" },
  });
});

前端调用

推荐方式（supabase client 可用时）：

/**
 * 通过 Edge Function 查询指定源货币的实时汇率列表。
 * @param fromCode - 源货币代码，如 CNY、USD、EUR、JPY、GBP 等
 * @returns 汇率数据对象
 */
async function fetchExchangeRates(fromCode: string) {
  const { data, error } = await supabase.functions.invoke("currency-exchange-rate", {
    body: { fromCode },
  });
  if (error) throw error;
  if (data.code !== 200) throw new Error(`API 错误 ${data.code}：${data.msg}`);
  return data.data;
}

备用方式（无法使用 supabase client 时）：

/**
 * 通过原生 fetch 调用 Edge Function 查询汇率。
 * @param fromCode - 源货币代码，如 CNY、USD、EUR 等
 * @returns 汇率数据对象
 */
async function fetchExchangeRates(fromCode: string) {
  const res = await fetch(
    `${import.meta.env.VITE_SUPABASE_URL}/functions/v1/currency-exchange-rate`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ fromCode }),
    }
  );

  if (res.status === 429) {
    const err = await res.json();
    throw new Error(`配额已用尽：${err.message ?? res.statusText}`);
  }
  if (res.status === 402) {
    const err = await res.json();
    throw new Error(`余额不足：${err.message ?? res.statusText}`);
  }
  if (!res.ok) throw new Error(`请求失败：${res.status}`);

  const json = await res.json();
  if (json.code !== 200) throw new Error(`API 错误 ${json.code}：${json.msg}`);

  return json.data;
}

参数说明

请求参数

常用货币代码

完整货币代码列表请参阅官方文档，共支持 200 多种货币。

返回字段说明

成功响应（code = 200）：

失败响应：

注意事项

• 密钥安全: INTEGRATIONS_API_KEY 仅可在 Edge Function 服务端读取，严禁暴露到前端代码或客户端日志中。
• 错误处理: 务必处理 429（配额超限）和 402（余额不足）两类错误，建议展示友好提示而非原始错误码。
• 计费: 该接口启用计费，折扣单价 ¥0.02 / 次（原价 ¥0.10 / 次），每次调用均计费，请避免不必要的重复调用（如轮询或频繁刷新）。
• 数据时效: 汇率数据为实时行情，但更新时间由上游决定，updatetime 字段反映各货币对的最新同步时间，非 tick 级精度，不适用于高频交易场景。
• fromCode 为空: 传入空字符串或不传 fromCode 时，上游返回 code: 400，msg 为"源货币类型不能为空"。
• 查无数据: 若货币代码不在支持范围内，上游返回 code: 201，msg 为"查无数据"。