API de conversão de moeda: taxas de câmbio em tempo real sobre REST

Sua loja de comércio eletrônico vende para clientes em 30 países. Você exibe os preços na lista do comprador moeda local. Isso significa que você precisa de taxas de câmbio em tempo real e que elas sejam gratuitas durante o desenvolvimento e barato na produção.

A maioria das APIs forex cobra por solicitação, exige fluxos OAuth ou retorna XML do início dos anos 2000. A API de moeda botoi oferece dois endpoints POST que retornam JSON, suportam mais de 170 moedas, e trabalhe anonimamente no nível gratuito. Nenhuma chave de API é necessária para começar.

Converta entre quaisquer duas moedas

O /v1/currency/convert endpoint usa uma moeda de origem, uma moeda de destino e quantia. Retorna o resultado convertido e a taxa de câmbio utilizada.

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

Resposta:

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

O rate campo é a taxa de câmbio bruta. O result campo é o valor convertido, arredondado para duas casas decimais. Você obtém os dois para poder exibir a taxa aos usuários ou verifique a matemática em seu próprio código.

Obtenha todas as taxas de câmbio de uma só vez

Se você precisar de tarifas para diversas moedas, ligue para /v1/currency/convert para cada par é um desperdício. O /v1/currency/rates endpoint retorna todos os disponíveis taxa para uma determinada moeda base em uma única resposta.

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

Resposta (truncada para 9 moedas):

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

Uma solicitação, mais de 170 tarifas. Armazene esta resposta em cache por uma hora e você poderá converter qualquer valor localmente sem fazer chamadas de API adicionais. Esta é a abordagem a ser adotada para fluxos de checkout e páginas de preços onde você precisa de várias moedas ao mesmo tempo.

Componente de exibição de preço que converte instantaneamente

Uma página de preços onde os usuários escolhem sua moeda em um menu suspenso. Este componente Preact chama o ponto final de conversão quando a seleção muda e exibe o 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>
  );
}

O padrão do componente é USD e só chama a API quando o usuário seleciona um valor diferente. moeda. Para produção, envolva isso em uma camada de cache (abordada abaixo), voltando e entre moedas não repete chamadas de API.

Middleware Node.js para checkout em várias moedas

Os checkouts de comércio eletrônico precisam converter todo o carrinho da moeda base para a do comprador moeda local. Este middleware busca taxas uma vez, armazena-as em cache por uma hora e converte cada item de linha sem chamadas extras de 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);

O convertAmount função lida com dois cenários: conversão direta quando a origem corresponde à moeda base e conversão de taxa cruzada quando isso não acontece. O cache na memória significa que a API é chamada uma vez por hora, não uma vez por checkout.

Para armazenamentos de alto tráfego, mova o cache para Redis ou seu armazenamento KV de borda para que todos os servidores as instâncias compartilham as mesmas taxas em cache.

Armazenando taxas de câmbio em cache para reduzir chamadas de API

As taxas de câmbio não mudam a cada segundo. Para a maioria dos aplicativos, taxas de armazenamento em cache de 1 a 4 horas é o suficiente. Este padrão usa um mapa na memória com expiração baseada em TTL e aquece o cache na inicialização para seus pares de moedas mais comuns.

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

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

O warmCache função é executada na inicialização e pré-busca seus cinco mais comuns pares. Depois disso, cada par é atualizado de acordo com sua própria programação quando o TTL expirar. Você fica bem dentro do limite de 100 solicitações por dia do nível gratuito, mesmo com dezenas de pares de moedas.

Escolhendo um TTL de cache

• 1 hora: Bom para fluxos de checkout onde você deseja que as taxas permaneçam atualizadas durante uma sessão de usuário.
• 4 horas: Bom para páginas de preços, painéis e ferramentas de relatórios. As tarifas são atualizadas uma vez por dia útil, portanto, o cache de 4 horas captura as alterações no mesmo dia.
• 24 horas: Ótimo para análises, faturamento e relatórios financeiros onde a taxa de ontem é aceitável.

Pontos-chave

• /v1/currency/convert converte um valor específico entre quaisquer dois de 170+ moedas suportadas. Retorna o resultado convertido e a taxa utilizada.
• /v1/currency/rates retorna todas as taxas de câmbio disponíveis para uma moeda base em uma resposta. Armazene-o em cache localmente para evitar chamadas de API por conversão.
• Ambos os endpoints funcionam anonimamente com 5 solicitações por minuto e 100 por dia. Passe um X-Api-Key cabeçalho para limites mais altos.
• Taxas de cache por 1 a 4 horas, dependendo de seus requisitos de precisão. Taxas de câmbio atualizar uma vez por dia útil.
• A API é executada na rede de ponta da Cloudflare. Os tempos de resposta são de 20 a 50 ms. Combine com o cache local e a conversão de moeda adicionam latência zero às solicitações voltadas ao usuário.