API konversi mata uang: nilai tukar real-time dibandingkan REST

Toko e-niaga Anda menjual ke pelanggan di 30 negara. Anda menampilkan harga di pembeli mata uang lokal. Itu berarti Anda memerlukan nilai tukar real-time, dan Anda memerlukannya gratis selama pengembangan dan murah dalam produksi.

Sebagian besar API forex mengenakan biaya per permintaan, memerlukan aliran OAuth, atau mengembalikan XML dari awal tahun 2000-an. API mata uang botoi memberi Anda dua titik akhir POST yang mengembalikan JSON, mendukung 170+ mata uang, dan bekerja secara anonim di tingkat gratis. Tidak diperlukan kunci API untuk memulai.

Konversi antara dua mata uang apa pun

Itu /v1/currency/convert titik akhir mengambil mata uang sumber, mata uang target, dan jumlah. Ini mengembalikan hasil yang dikonversi dan nilai tukar yang digunakan.

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

Tanggapan:

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

Itu rate lapangan adalah nilai tukar mentah. Itu result bidang adalah jumlah yang dikonversi, dibulatkan menjadi dua tempat desimal. Anda mendapatkan keduanya sehingga Anda dapat menampilkan tarifnya kepada pengguna atau verifikasi matematika dalam kode Anda sendiri.

Ambil semua nilai tukar sekaligus

Jika Anda memerlukan tarif untuk berbagai mata uang, hubungi /v1/currency/convert untuk setiap pasangan boros. Itu /v1/currency/rates titik akhir mengembalikan setiap tersedia kurs untuk mata uang dasar tertentu dalam satu respons.

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

Respon (dipotong menjadi 9 mata uang):

{
  "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
    }
  }
}

Satu permintaan, 170+ tarif. Simpan respons ini dalam cache selama satu jam dan Anda dapat mengonversi jumlah berapa pun secara lokal tanpa membuat panggilan API tambahan. Ini adalah pendekatan yang harus diambil untuk alur pembayaran dan halaman harga di mana Anda memerlukan banyak mata uang sekaligus.

Komponen tampilan harga yang dikonversi dengan cepat

Halaman harga tempat pengguna memilih mata uang mereka dari dropdown. Komponen Preact ini memanggil titik akhir konversi ketika pilihan berubah dan menampilkan hasilnya.

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>
  );
}

Komponen defaultnya adalah USD dan hanya memanggil API ketika pengguna memilih yang lain mata uang. Untuk produksi, bungkus ini dalam lapisan cache (dibahas di bawah) sehingga beralih kembali dan maju antar mata uang tidak mengulangi panggilan API.

Middleware Node.js untuk checkout multi-mata uang

Pembayaran e-niaga perlu mengonversi seluruh keranjang dari mata uang dasar Anda ke mata uang pembeli mata uang lokal. Middleware ini mengambil tarif satu kali, menyimpannya dalam cache selama satu jam, dan mengonversinya setiap item baris tanpa panggilan API tambahan.

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);

Itu convertAmount fungsi menangani dua skenario: konversi langsung kapan sumbernya cocok dengan mata uang dasar, dan konversi lintas kurs jika tidak. Itu cache dalam memori berarti API dipanggil sekali per jam, bukan sekali per checkout.

Untuk penyimpanan dengan lalu lintas tinggi, pindahkan cache ke Redis atau penyimpanan edge KV Anda jadi semua server instance berbagi tingkat cache yang sama.

Menyimpan nilai tukar dalam cache untuk mengurangi panggilan API

Nilai tukar tidak berubah setiap detiknya. Untuk sebagian besar aplikasi, kecepatan caching adalah 1-4 jam sudah cukup. Pola ini menggunakan Peta dalam memori dengan kedaluwarsa berbasis TTL dan menghangatkan cache saat startup untuk pasangan mata uang Anda yang paling umum.

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

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

Itu warmCache fungsi berjalan saat startup dan mengambil lima fungsi yang paling umum berpasangan. Setelah itu, setiap pasangan disegarkan pada jadwalnya masing-masing ketika TTL berakhir. Anda tinggal berada dalam batas 100 permintaan per hari tingkat gratis, bahkan dengan lusinan pasangan mata uang.

Memilih cache TTL

• 1 jam: Cocok untuk alur pembayaran di mana Anda ingin harga tetap segar selama sesi pengguna.
• 4 jam: Cocok untuk halaman harga, dasbor, dan alat pelaporan. Tarif diperbarui sekali per hari kerja, sehingga cache 4 jam mencatat perubahan dalam hari yang sama.
• 24 jam: Baik untuk analitik, pembuatan faktur, dan laporan keuangan tarif kemarin dapat diterima.

Poin-poin penting

• /v1/currency/convert mengonversi jumlah tertentu antara dua dari 170+ mata uang yang didukung. Mengembalikan hasil konversi dan tarif yang digunakan.
• /v1/currency/rates mengembalikan semua nilai tukar yang tersedia untuk mata uang dasar dalam satu tanggapan. Simpan dalam cache secara lokal untuk menghindari panggilan API per konversi.
• Kedua titik akhir bekerja secara anonim dengan 5 permintaan per menit dan 100 permintaan per hari. Lulus sebuah X-Api-Key header untuk batas yang lebih tinggi.
• Tarif cache selama 1-4 jam tergantung pada kebutuhan akurasi Anda. Nilai tukar perbarui sekali per hari kerja.
• API berjalan di jaringan edge Cloudflare. Waktu respons adalah 20-50 ms. Pasangkan dengan caching lokal dan konversi mata uang Anda tidak menambah latensi pada permintaan yang dihadapi pengguna.