API de conversion de devises : taux de change en temps réel sur REST

Votre boutique e-commerce vend à des clients dans 30 pays. Vous affichez les prix dans la fenêtre de l'acheteur monnaie locale. Cela signifie que vous avez besoin de taux de change en temps réel et qu’ils soient gratuits. pendant le développement et bon marché en production.

La plupart des API Forex facturent par requête, nécessitent des flux OAuth ou renvoient du XML du début des années 2000. L'API de devise botoi vous offre deux points de terminaison POST qui renvoient JSON, prennent en charge plus de 170 devises, et travaillez de manière anonyme sur le niveau gratuit. Aucune clé API n'est nécessaire pour commencer.

Convertir entre deux devises

La /v1/currency/convert le point de terminaison prend une devise source, une devise cible et montant. Il renvoie le résultat converti et le taux de change utilisé.

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

Réponse:

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

La rate Le champ est le taux de change brut. Le result le champ est le montant converti, arrondi à deux décimales. Vous obtenez les deux pour pouvoir afficher le tarif aux utilisateurs ou vérifiez les calculs dans votre propre code.

Récupérez tous les taux de change en même temps

Si vous avez besoin de tarifs pour plusieurs devises, appelez /v1/currency/convert pour chaque paire est un gaspillage. Le /v1/currency/rates le point de terminaison renvoie tous les disponibles taux pour une devise de base donnée en une seule réponse.

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

Réponse (tronquée à 9 devises) :

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

Une demande, plus de 170 tarifs. Mettez en cache cette réponse pendant une heure et vous pourrez convertir n'importe quel montant localement sans effectuer d’appels API supplémentaires. C’est l’approche à adopter pour les flux de caisse et des pages de tarification où vous avez besoin de plusieurs devises à la fois.

Composant d'affichage des prix qui convertit à la volée

Une page de tarification où les utilisateurs choisissent leur devise dans une liste déroulante. Ce composant Preact appelle le point final de conversion lorsque la sélection change et affiche le résultat.

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

Le composant est par défaut USD et appelle l'API uniquement lorsque l'utilisateur sélectionne un autre monnaie. Pour la production, enveloppez-le dans une couche de cache (couverte ci-dessous) afin de revenir en arrière et entre les devises ne répète pas les appels API.

Middleware Node.js pour le paiement multi-devises

Les caisses de commerce électronique doivent convertir l'intégralité du panier de votre devise de base vers celle de l'acheteur. monnaie locale. Ce middleware récupère les tarifs une fois, les met en cache pendant une heure et les convertit chaque élément de campagne sans appels d'API supplémentaires.

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

La convertAmount la fonction gère deux scénarios : conversion directe lorsque la source correspond à la devise de base et la conversion à taux croisés dans le cas contraire. Le Le cache en mémoire signifie que l'API est appelée une fois par heure, et non une fois par paiement.

Pour les magasins à fort trafic, déplacez le cache vers Redis ou votre magasin Edge KV afin que tous les serveurs les instances partagent les mêmes tarifs mis en cache.

Mise en cache des taux de change pour réduire les appels d'API

Les taux de change ne changent pas à la seconde près. Pour la plupart des applications, mise en cache des taux pendant 1 à 4 heures c'est suffisant. Ce modèle utilise une carte en mémoire avec une expiration basée sur TTL et réchauffe le cache au démarrage pour vos paires de devises les plus courantes.

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

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

La warmCache La fonction s'exécute au démarrage et pré-récupère vos cinq applications les plus courantes. paires. Après cela, chaque paire est actualisée selon son propre calendrier lorsque la durée de vie expire. Tu restes bien dans la limite de 100 requêtes par jour du niveau gratuit, même avec des dizaines de paires de devises.

Choisir un cache TTL

• 1 heure : Idéal pour les flux de paiement où vous souhaitez que les tarifs restent actualisés lors d'une session utilisateur.
• 4 heures : Idéal pour les pages de tarification, les tableaux de bord et les outils de reporting. Les tarifs sont mis à jour une fois par jour ouvrable, de sorte que la mise en cache de 4 heures capture les modifications au cours de la même journée.
• 24 heures : Amende pour les analyses, la facturation et les rapports financiers où le taux d'hier est acceptable.

Points clés

• /v1/currency/convert convertit un montant spécifique entre deux de 170+ devises prises en charge. Renvoie le résultat converti et le taux utilisé.
• /v1/currency/rates renvoie tous les taux de change disponibles pour une devise de base en une seule réponse. Mettez-le en cache localement pour éviter les appels d'API par conversion.
• Les deux points de terminaison fonctionnent de manière anonyme à 5 requêtes par minute et 100 par jour. Passer un X-Api-Key en-tête pour des limites plus élevées.
• Taux de cache pendant 1 à 4 heures en fonction de vos exigences de précision. Taux de change mettre à jour une fois par jour ouvrable.
• L'API s'exécute sur le réseau périphérique de Cloudflare. Les temps de réponse sont de 20 à 50 ms. Associez-le à la mise en cache locale et la conversion de devises n'ajoutent aucune latence aux requêtes adressées aux utilisateurs.