API конвертации валюты: обменные курсы в реальном времени через REST

Ваш интернет-магазин продает товары клиентам в 30 странах. Вы отображаете цены в магазине покупателя местная валюта. Это означает, что вам нужны обменные курсы в реальном времени, и они должны быть бесплатными. во время разработки и дешев в производстве.

Большинство API-интерфейсов форекс взимают плату за запрос, требуют потоков OAuth или возвращают XML с начала 2000-х годов. API валюты botoi предоставляет вам две конечные точки POST, которые возвращают JSON, поддерживают более 170 валют, и работайте анонимно на бесплатном уровне. Для начала работы не требуется ключ API.

Конвертируйте между любыми двумя валютами

The /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
  }
}

The rate Поле — это исходный обменный курс. result поле – это конвертированная сумма, округленная до двух десятичных знаков. Вы получаете оба, чтобы вы могли отображать курс пользователям или проверьте математику в своем собственном коде.

Получить все обменные курсы одновременно

Если вам нужны курсы для нескольких валют, позвоните по телефону /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
    }
  }
}

Один запрос, 170+ ставок. Кэшируйте этот ответ на час и сможете конвертировать любую сумму локально без дополнительных вызовов 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>
  );
}

По умолчанию компонент использует доллары США и вызывает API только тогда, когда пользователь выбирает другой вариант. валюта. Для производства оберните это в уровень кэша (описанный ниже), поэтому переключитесь обратно и переход между валютами не повторяет вызовы API.

Промежуточное ПО Node.js для мультивалютной оплаты

Кассы электронной коммерции должны конвертировать всю корзину из вашей базовой валюты в валюту покупателя. местная валюта. Это промежуточное программное обеспечение один раз извлекает тарифы, кэширует их в течение часа и конвертирует каждую позицию без дополнительных вызовов 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);

The convertAmount функция обрабатывает два сценария: прямое преобразование, когда источник соответствует базовой валюте и конвертации кросс-курсов, если это не так. Кэш в памяти означает, что API вызывается один раз в час, а не один раз при оформлении заказа.

Для магазинов с высоким трафиком переместите кеш в 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}\

The warmCache функция запускается при запуске и предварительно выбирает пять наиболее распространенных пары. После этого каждая пара обновляется по собственному расписанию по истечении срока TTL. Ты остаешься вполне в пределах лимита бесплатного уровня в 100 запросов в день, даже с десятками валютных пар.

Выбор TTL кэша

• 1 час: Подходит для процессов оформления заказов, когда вы хотите, чтобы цены оставались актуальными. во время сеанса пользователя.
• 4 часа: Подходит для страниц цен, информационных панелей и инструментов отчетности. Тарифы обновляются один раз в рабочий день, поэтому 4-часовое кэширование фиксирует изменения в течение одного и того же дня.
• 24 часа: Штраф за аналитику, выставление счетов и финансовые отчеты, где вчерашний курс приемлем.

Ключевые моменты

• /v1/currency/convert конвертирует определенную сумму между любыми двумя из 170+ поддерживаемые валюты. Возвращает преобразованный результат и использованную ставку.
• /v1/currency/rates возвращает все доступные обменные курсы для базовой валюты в одном ответе. Кэшируйте его локально, чтобы избежать вызовов API для каждой конверсии.
• Обе конечные точки работают анонимно со скоростью 5 запросов в минуту и ​​100 в день. Передайте X-Api-Key заголовок для более высоких лимитов.
• Скорость кэширования составляет 1–4 часа в зависимости от ваших требований к точности. Курсы валют обновляется один раз в рабочий день.
• API работает в периферийной сети Cloudflare. Время отклика составляет 20-50 мс. Соедините его с локальное кэширование и конвертация валюты обеспечивают нулевую задержку для запросов пользователя.