API de conversión de moneda: tipos de cambio en tiempo real sobre REST

Su tienda de comercio electrónico vende a clientes en 30 países. Muestras los precios en la página del comprador. moneda local. Eso significa que necesita tipos de cambio en tiempo real y que sean gratuitos. durante el desarrollo y barato en producción.

La mayoría de las API de Forex cobran por solicitud, requieren flujos OAuth o devuelven XML de principios de la década de 2000. La API de moneda botoi le brinda dos puntos finales POST que devuelven JSON, admiten más de 170 monedas, y trabajar de forma anónima en el nivel gratuito. No se necesita clave API para comenzar.

Convertir entre dos monedas cualesquiera

La /v1/currency/convert El punto final toma una moneda de origen, una moneda de destino y cantidad. Devuelve el resultado convertido y el tipo de cambio utilizado.

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

Respuesta:

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

La rate El campo es el tipo de cambio bruto. El result campo es el Importe convertido, redondeado a dos decimales. Obtienes ambos para que puedas mostrar la tarifa. a los usuarios o verificar las matemáticas en su propio código.

Obtenga todos los tipos de cambio a la vez

Si necesita tarifas para varias monedas, llame /v1/currency/convert para cada par es un desperdicio. El /v1/currency/rates El punto final devuelve todos los disponibles. tipo de cambio para una moneda base determinada en una sola respuesta.

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

Respuesta (truncada a 9 monedas):

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

Una solicitud, más de 170 tarifas. Guarde en caché esta respuesta durante una hora y podrá convertir cualquier cantidad localmente sin realizar llamadas API adicionales. Este es el enfoque a seguir para los flujos de pago y páginas de precios donde necesita varias monedas a la vez.

Componente de visualización de precios que convierte sobre la marcha

Una página de precios donde los usuarios eligen su moneda en un menú desplegable. Este componente de Preact llama el punto final de conversión cuando la selección cambia y muestra el resultado.

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

El componente por defecto es USD y solo llama a la API cuando el usuario selecciona un valor diferente. moneda. Para producción, envuelva esto en una capa de caché (que se describe a continuación) para cambiar de un lado a otro. El intercambio entre monedas no repite las llamadas API.

Middleware Node.js para pago en múltiples monedas

Las cajas de comercio electrónico deben convertir todo el carrito de su moneda base a la del comprador. moneda local. Este middleware obtiene tasas una vez, las almacena en caché durante una hora y las convierte cada línea de pedido sin llamadas API adicionales.

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 función maneja dos escenarios: conversión directa cuando la fuente coincide con la moneda base y la conversión de tipos cruzados cuando no es así. el La caché en memoria significa que se llama a la API una vez por hora, no una vez por pago.

Para tiendas con mucho tráfico, mueva el caché a Redis o a su tienda Edge KV para que todos los servidores Las instancias comparten las mismas tasas de caché.

Almacenamiento en caché de tipos de cambio para reducir las llamadas API

Los tipos de cambio no cambian por segundo. Para la mayoría de las aplicaciones, el almacenamiento en caché dura entre 1 y 4 horas. es suficiente. Este patrón utiliza un mapa en memoria con caducidad basada en TTL y calienta el caché al inicio para sus pares de divisas más comunes.

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 función se ejecuta al inicio y busca previamente los cinco más comunes. pares. Después de eso, cada par se actualiza según su propio cronograma cuando expira el TTL. tu te quedas dentro del límite de 100 solicitudes por día del nivel gratuito, incluso con docenas de pares de divisas.

Elegir un TTL de caché

• 1 hora: Bueno para flujos de pago en los que desea que las tarifas se mantengan actualizadas durante una sesión de usuario.
• 4 horas: Bueno para páginas de precios, paneles y herramientas de informes. Las tarifas se actualizan una vez por día hábil, por lo que el almacenamiento en caché de 4 horas captura los cambios dentro del mismo día.
• 24 horas: Multa para análisis, facturación e informes financieros donde El ritmo de ayer es aceptable.

Puntos clave

• /v1/currency/convert convierte una cantidad específica entre dos cualesquiera de 170+ monedas admitidas. Devuelve el resultado convertido y la tasa utilizada.
• /v1/currency/rates devuelve todos los tipos de cambio disponibles para una moneda base en una sola respuesta. Almacénelo en caché localmente para evitar llamadas API por conversión.
• Ambos puntos finales funcionan de forma anónima a 5 solicitudes por minuto y 100 por día. pasar un X-Api-Key encabezado para límites más altos.
• Tasas de caché de 1 a 4 horas, según sus requisitos de precisión. Tipos de cambio actualizar una vez por día hábil.
• La API se ejecuta en la red perimetral de Cloudflare. Los tiempos de respuesta son de 20 a 50 ms. Combínalo con el almacenamiento en caché local y la conversión de moneda agregan latencia cero a las solicitudes de los usuarios.