通貨換算 API: REST を介したリアルタイム為替レート

あなたの e コマース ストアは 30 か国の顧客に販売しています。 購入者のサイトに価格を表示します 現地通貨。 つまり、リアルタイムの為替レートが必要であり、それが無料である必要があります。 開発中および製造中は安価です。

ほとんどの外国為替 API はリクエストごとに料金を請求し、OAuth フローを必要とするか、2000 年代初頭から XML を返します。 Botoi 通貨 API は、JSON を返し、170 以上の通貨をサポートする 2 つの POST エンドポイントを提供します。 無料枠で匿名で作業できます。 開始するために API キーは必要ありません。

任意の 2 つの通貨間で変換する

の /v1/currency/convert エンドポイントはソース通貨、ターゲット通貨、および 金額。 変換結果と使用された為替レートを返します。

curl -X POST https://api.botoi.com/v1/currency/convert \\
  -H "Content-Type: application/json" \\
  -d '{"from": "USD", "to": "EUR", "amount": 99.99}'

応答：

{
  "success": true,
  "data": {
    "from": "USD",
    "to": "EUR",
    "amount": 99.99,
    "result": 91.79,
    "rate": 0.9180
  }
}

の rate フィールドは生の為替レートです。 の result フィールドは 換算金額、小数点第2位を四捨五入。 両方取得できるのでレートを表示できます ユーザーに伝えるか、独自のコードで計算を検証してください。

すべての為替レートを一度に取得する

複数の通貨のレートが必要な場合は、電話してください。 /v1/currency/convert のために 各ペアは無駄です。 の /v1/currency/rates エンドポイントは利用可能なものをすべて返します 単一の応答で特定の基本通貨のレートを返します。

curl -X POST https://api.botoi.com/v1/currency/rates \\
  -H "Content-Type: application/json" \\
  -d '{"base": "USD"}'

応答 (9 通貨に切り捨て):

{
  "success": true,
  "data": {
    "base": "USD",
    "rates": {
      "EUR": 0.9180,
      "GBP": 0.7891,
      "JPY": 149.52,
      "CAD": 1.3612,
      "AUD": 1.5340,
      "CHF": 0.8821,
      "INR": 83.4150,
      "BRL": 4.9720,
      "MXN": 17.1340
    }
  }
}

1 つのリクエストで 170 以上のレート。 この応答を 1 時間キャッシュすると、任意の金額に変換できます 追加の API 呼び出しを行わずにローカルで実行できます。 これはチェックアウトフローで採用されるアプローチです 一度に複数の通貨が必要な価格設定ページ。

オンザフライで変換する価格表示コンポーネント

ユーザーがドロップダウンから通貨を選択する価格設定ページ。 この Preact コンポーネントは 選択が変更され、結果が表示されるときの変換エンドポイント。

import { useState, useEffect } from "preact/hooks";

const SUPPORTED_CURRENCIES = ["USD", "EUR", "GBP", "JPY", "CAD"];

function PriceDisplay({ priceUsd }) {
  const [currency, setCurrency] = useState("USD");
  const [converted, setConverted] = useState(priceUsd);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    if (currency === "USD") {
      setConverted(priceUsd);
      return;
    }

    setLoading(true);
    fetch("https://api.botoi.com/v1/currency/convert", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        from: "USD",
        to: currency,
        amount: priceUsd,
      }),
    })
      .then((res) => res.json())
      .then(({ data }) => {
        setConverted(data.result);
        setLoading(false);
      });
  }, [currency, priceUsd]);

  return (
    <div>
      <select
        value={currency}
        onChange={(e) => setCurrency(e.target.value)}
      >
        {SUPPORTED_CURRENCIES.map((c) => (
          <option key={c} value={c}>{c}</option>
        ))}
      </select>
      <span>
        {loading ? "..." : \`\\\${converted.toFixed(2)} \\\${currency}\`}
      </span>
    </div>
  );
}

このコンポーネントのデフォルトは USD であり、ユーザーが別のドルを選択した場合にのみ API を呼び出します。 通貨。 運用環境では、これをキャッシュ層 (以下で説明) にラップして、スイッチバックして、 通貨間で API 呼び出しを繰り返すことはありません。

複数通貨チェックアウト用の Node.js ミドルウェア

電子商取引チェックアウトでは、カート全体を基本通貨から購入者の通貨に変換する必要があります 現地通貨。 このミドルウェアはレートを 1 回フェッチし、1 時間キャッシュして変換します。 追加の API 呼び出しを行わずにすべての項目を実行できます。

import express from "express";

const app = express();
app.use(express.json());

// Cache rates in memory with a 1-hour TTL
let ratesCache = null;
let cacheTimestamp = 0;
const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour

async function getRates(base) {
  const now = Date.now();

  if (ratesCache && ratesCache.base === base && now - cacheTimestamp < CACHE_TTL_MS) {
    return ratesCache;
  }

  const res = await fetch("https://api.botoi.com/v1/currency/rates", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Key": process.env.BOTOI_API_KEY,
    },
    body: JSON.stringify({ base }),
  });
  const { data } = await res.json();

  ratesCache = data;
  cacheTimestamp = now;
  return data;
}

function convertAmount(rates, from, to, amount) {
  if (from === to) return amount;

  // If "from" is the base currency, multiply by the target rate
  if (from === rates.base) {
    return Math.round(amount * rates.rates[to] * 100) / 100;
  }

  // Otherwise, convert to base first, then to target
  const inBase = amount / rates.rates[from];
  return Math.round(inBase * rates.rates[to] * 100) / 100;
}

app.post("/checkout", async (req, res) => {
  const { items, currency } = req.body;

  // Calculate total in USD (your base currency)
  const totalUsd = items.reduce((sum, item) => sum + item.price * item.qty, 0);

  // Convert to the buyer's currency
  const rates = await getRates("USD");
  const totalLocal = convertAmount(rates, "USD", currency, totalUsd);

  res.json({
    currency,
    total: totalLocal,
    rate: rates.rates[currency],
    items: items.map((item) => ({
      ...item,
      localPrice: convertAmount(rates, "USD", currency, item.price),
    })),
  });
});

app.listen(3000);

の convertAmount 関数は 2 つのシナリオを処理します: 直接変換 ソースは基本通貨と一致し、一致しない場合はクロスレート変換が行われます。 の メモリ内キャッシュとは、API がチェックアウトごとに 1 回ではなく、1 時間に 1 回呼び出されることを意味します。

トラフィックの多いストアの場合は、キャッシュを Redis またはエッジ KV ストアに移動して、すべてのサーバーが インスタンスは同じキャッシュされたレートを共有します。

為替レートをキャッシュして API 呼び出しを削減する

為替レートは秒単位で変わりません。 ほとんどのアプリケーションでは、キャッシュ速度は 1 ～ 4 時間です 十分です。 このパターンは、TTL ベースの有効期限を持つメモリ内マップを使用し、キャッシュをウォームします。 最も一般的な通貨ペアの起動時に。

const RATES_CACHE = new Map();
const CACHE_TTL_MS = 4 * 60 * 60 * 1000; // 4 hours

async function getCachedRate(from, to) {
  const key = \`\\\${from}:\\\${to}\

の warmCache 関数は起動時に実行され、最も一般的な 5 つをプリフェッチします ペア。 その後、TTL の有効期限が切れると、各ペアが独自のスケジュールで更新されます。 あなたは滞在します たとえ数十の通貨ペアであっても、無料利用枠の 1 日あたり 100 リクエストの制限内に十分収まります。

キャッシュTTLの選択

• 1時間: 料金を最新の状態に保ちたいチェックアウト フローに適しています ユーザーセッション中。
• 4時間: 価格設定ページ、ダッシュボード、レポート ツールに適しています。 料金は営業日ごとに 1 回更新されるため、4 時間のキャッシュにより同じ日内の変更がキャプチャされます。
• 24時間： 分析、請求書発行、財務レポートには最適です。 昨日のレートは許容範囲内です。

重要なポイント

• /v1/currency/convert 170 以上の任意の 2 つの金額の間で特定の金額を変換します サポートされている通貨。 変換結果と使用レートを返します。
• /v1/currency/rates 基本通貨に対して利用可能なすべての為替レートを返します 一つの返答で。 変換ごとの API 呼び出しを避けるためにローカルにキャッシュします。
• どちらのエンドポイントも匿名で 1 分あたり 5 リクエスト、1 日あたり 100 リクエストで動作します。 渡す X-Api-Key より高い制限のヘッダー。
• 精度要件に応じて、1 ～ 4 時間のキャッシュ速度。 為替レート 営業日ごとに 1 回更新します。
• APIはCloudflareのエッジネットワーク上で実行されます。 応答時間は 20 ～ 50 ミリ秒です。 と組み合わせてください ローカル キャッシュと通貨換算により、ユーザー向けのリクエストに待ち時間が追加されません。