واجهة برمجة تطبيقات تحويل العملات: أسعار الصرف في الوقت الفعلي عبر REST

يبيع متجر التجارة الإلكترونية الخاص بك للعملاء في 30 دولة. تقوم بعرض الأسعار في المشتري العملة المحلية. وهذا يعني أنك بحاجة إلى أسعار صرف في الوقت الحقيقي، وتحتاج إلى أن تكون مجانية أثناء التطوير ورخيصة في الإنتاج.

تتقاضى معظم واجهات برمجة تطبيقات الفوركس رسومًا لكل طلب، أو تتطلب تدفقات OAuth، أو ترجع XML من أوائل العقد الأول من القرن الحادي والعشرين. تمنحك واجهة برمجة تطبيقات عملة botoi نقطتي نهاية POST تُرجع JSON، وتدعم أكثر من 170 عملة، والعمل بشكل مجهول على الطبقة المجانية. لا حاجة إلى مفتاح API للبدء.

التحويل بين أي عملتين

ال /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
  }
}

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

يتم تعيين المكون افتراضيًا على USD ولا يستدعي واجهة برمجة التطبيقات (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);

ال convertAmount تتعامل الوظيفة مع سيناريوهين: التحويل المباشر متى يتطابق المصدر مع العملة الأساسية، ويتم تحويل السعر المتقاطع عندما لا يكون كذلك. ال تعني ذاكرة التخزين المؤقت في الذاكرة أن واجهة برمجة التطبيقات (API) يتم استدعاؤها مرة واحدة كل ساعة، وليس مرة واحدة لكل عملية دفع.

بالنسبة إلى المتاجر ذات حركة المرور العالية، انقل ذاكرة التخزين المؤقت إلى Redis أو متجر edge 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}\

ال warmCache تعمل الوظيفة عند بدء التشغيل وتقوم بجلب العناصر الخمسة الأكثر شيوعًا مسبقًا أزواج. بعد ذلك، يتم تحديث كل زوج وفقًا لجدوله الخاص عند انتهاء مدة البقاء (TTL). يمكنك البقاء ضمن حد الطبقة المجانية البالغ 100 طلب يوميًا، حتى مع عشرات أزواج العملات.

اختيار ذاكرة التخزين المؤقت TTL

• 1 ساعة: جيد لتدفقات الخروج حيث تريد أن تظل الأسعار جديدة أثناء جلسة المستخدم.
• 4 ساعات: مناسب لصفحات التسعير ولوحات المعلومات وأدوات إعداد التقارير. يتم تحديث الأسعار مرة واحدة في كل يوم عمل، لذا فإن التخزين المؤقت لمدة 4 ساعات يلتقط التغييرات خلال نفس اليوم.
• 24 ساعة: جيد للتحليلات والفواتير والتقارير المالية حيث سعر الأمس مقبول.

النقاط الرئيسية

• /v1/currency/convert يحول مبلغًا محددًا بين أي اثنين من 170+ العملات المدعومة. إرجاع النتيجة المحولة والمعدل المستخدم.
• /v1/currency/rates إرجاع جميع أسعار الصرف المتاحة للعملة الأساسية في رد واحد. قم بتخزينه مؤقتًا محليًا لتجنب استدعاءات واجهة برمجة التطبيقات لكل تحويل.
• تعمل كلا نقطتي النهاية بشكل مجهول عند 5 طلبات في الدقيقة و100 في اليوم. تمرير ان X-Api-Key رأس للحدود الأعلى.
• معدلات ذاكرة التخزين المؤقت لمدة 1-4 ساعات حسب متطلبات الدقة الخاصة بك. أسعار الصرف التحديث مرة واحدة في يوم العمل.
• تعمل واجهة برمجة التطبيقات (API) على شبكة Cloudflare الطرفية. أوقات الاستجابة هي 20-50 مللي ثانية. إقرانها مع يضيف التخزين المؤقت المحلي وتحويل العملة أي زمن استجابة للطلبات التي يواجهها المستخدم.