کاربردهای عملی

به‌روزرسانی خودکار قیمت محصولات فروشگاه با API قیمت دلار

قیمت تومانی کالاهای وارداتی را با API قیمت دلار کارینا خودکار و زمان‌بندی‌شده به‌روز کنید؛ همراه با حاشیه سود، گرد کردن قیمت و محافظت در برابر نوسان شدید نرخ دلار.

  • ۱۳ دقیقه مطالعه

سلام به همهٔ همراهان عزیز کارینا، با یک آموزش بسیار کاربردی دیگر در خدمت شما هستیم. اگر در پروژه‌های خود با فروش کالای وارداتی سروکار داشته باشید، حتماً می‌دانید که قیمت تومانی این کالاها مستقیماً به نرخ دلار وابسته است. در این مطلب قصد داریم API قیمت دلار را به زبان ساده و به صورت کاملاً عملی بررسی کنیم و با آن، قیمت محصولات فروشگاه را خودکار به‌روز نگه داریم.

در واقع هدف ما فقط خواندن یک عدد از API قیمت دلار نیست. بلکه می‌خواهیم یک فرایند کامل و قابل‌اعتماد بسازیم؛ فرایندی که حاشیه سود را اعمال کند، قیمت را گرد کند و در برابر نوسان شدید نرخ دلار نیز محتاط رفتار کند.

سناریوی واقعی: فروشگاهی با قیمت پایهٔ دلاری

یک مثال می‌زنم تا موضوع را بهتر متوجه شوید: فرض کنید فروشگاهی آنلاین قطعات و لوازم جانبی وارداتی می‌فروشد. قیمت خرید هر کالا از تأمین‌کنندهٔ خارجی به دلار مشخص است. بنابراین منطقی‌ترین کار این است که قیمت پایهٔ هر محصول را به دلار ذخیره کنیم و قیمت تومانی را از روی آن بسازیم.

با این حال، اگر مدیر فروشگاه بخواهد با هر تغییر نرخ دلار صدها محصول را دستی ویرایش کند، هم زمان زیادی از دست می‌رود و هم احتمال خطای انسانی بالا می‌رود. در نتیجه یا قیمت‌ها از بازار عقب می‌مانند و فروشگاه ضرر می‌کند، یا بیش از حد بالا می‌روند و مشتری را از دست می‌دهد.

حالا راه‌حل این مشکل چیست؟ ما یک اسکریپت زمان‌بندی‌شده می‌نویسیم که این کارها را انجام دهد:

  1. نرخ لحظه‌ای دلار را از API قیمت دلار کارینا دریافت می‌کند.
  2. تغییر نرخ را با آخرین نرخ اعمال‌شده مقایسه می‌کند تا نوسان‌های غیرعادی را تشخیص دهد.
  3. قیمت تومانی هر محصول را با احتساب حاشیه سود همان محصول محاسبه می‌کند.
  4. قیمت نهایی را به یک عدد رند و خوانا گرد می‌کند.
  5. همهٔ محصولات را در یک تراکنش دیتابیس به‌روز می‌کند.

به عبارت دیگر، صفحات سایت هیچ‌گاه مستقیماً به API متصل نمی‌شوند. فقط اسکریپت زمان‌بندی‌شده نرخ را از API قیمت دلار می‌گیرد و صفحات محصول، قیمت آماده را از دیتابیس می‌خوانند. لذا سرعت سایت به سرعت شبکه وابسته نمی‌شود و سهمیهٔ (Quota) API نیز بی‌جهت مصرف نمی‌شود.

دریافت نرخ لحظه‌ای با API قیمت دلار کارینا

اولین قدم، دریافت نرخ دلار به صورت مطمئن است. در اینجاست که API قیمت دلار کارینا به کمک ما می‌آید. این سرویس آخرین نرخ دلار را به تومان برمی‌گرداند و آدرس آن به شکل GET https://karinaco.net/api/v1/dollar/price است. توکن نیز در هدر Authorization و به شکل Bearer ارسال می‌شود.

جالب است بدانید که ریسپانس API قیمت دلار ساختار ساده‌ای دارد و به صورت زیر خواهد بود:

{
    "success": true,
    "data": {
        "type": "dollar",
        "price": 189700,
        "currency": "IRT",
        "unit": "usd",
        "is_stale": false,
        "updated_at": "1405/05/04 00:50:03"
    },
    "quota": {
        "unlimited": false,
        "remaining": 245
    }
}

همان‌طور که مشاهده می‌کنید، کلید price نرخ دلار به تومان است و updated_at زمان آخرین به‌روزرسانی را با تاریخ شمسی نشان می‌دهد. علاوه بر این، فیلد is_stale مشخص می‌کند که داده تازه است یا خیر. بخش quota نیز تعداد درخواست‌های باقی‌ماندهٔ شما را گزارش می‌دهد.

حالا تابعی می‌نویسیم که نرخ را از API قیمت دلار با رعایت نکات امنیتی و مدیریت خطا دریافت کند. به مثال زیر توجه کنید:

<?php
// فایل pricing.php

function fetchDollarRate(): int
{
    // توکن API را همیشه از متغیر محیطی بخوانید، نه از داخل کد
    $token = getenv('KARINA_API_TOKEN');
    if ($token === false || $token === '') {
        throw new RuntimeException('KARINA_API_TOKEN is not set');
    }

    $ch = curl_init('https://karinaco.net/api/v1/dollar/price');
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 5, // حداکثر ۵ ثانیه برای برقراری اتصال
        CURLOPT_TIMEOUT => 10,       // حداکثر ۱۰ ثانیه منتظر پاسخ می‌مانیم
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $token,
            'Accept: application/json',
        ],
    ]);

    $body   = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    $error  = curl_error($ch);

    // خطای شبکه یا پایان مهلت انتظار
    if ($body === false) {
        throw new RuntimeException('Connection error: ' . $error);
    }

    // هر کد وضعیتی غیر از ۲۰۰ را خطا در نظر می‌گیریم
    if ($status !== 200) {
        throw new RuntimeException('Unexpected HTTP status: ' . $status);
    }

    $json = json_decode($body, true);
    if (!is_array($json) || ($json['success'] ?? false) !== true) {
        throw new RuntimeException('Invalid API response');
    }

    // اگر داده تازه نباشد، قیمت‌ها را بر اساس آن تغییر نمی‌دهیم
    if (!empty($json['data']['is_stale'])) {
        throw new RuntimeException('Dollar rate is stale');
    }

    $rate = (int) ($json['data']['price'] ?? 0);
    if ($rate <= 0) {
        throw new RuntimeException('Invalid dollar rate');
    }

    return $rate;
}

در این تابع، هر حالتی که داده قابل‌اعتماد نباشد به یک Exception ختم می‌شود. بنابراین اسکریپت اصلی می‌تواند با خیال آسوده تصمیم بگیرد که در صورت بروز خطا، قیمت‌های فعلی را دست‌نخورده باقی بگذارد. این رفتار برای یک فروشگاه بسیار مهم است؛ زیرا قیمت صفر یا نامعتبر به هیچ وجه نباید روی سایت نمایش داده شود.

نکته: توکن API را در داشبورد کارینا (https://karinaco.net/dashboard/tokens) بسازید و آن را فقط در متغیر محیطی سرور قرار دهید. هرگز توکن را داخل مخزن Git یا فایل‌های قابل‌دسترس عمومی ذخیره نکنید.

فرمول به‌روزرسانی قیمت محصولات: حاشیه سود و گرد کردن

پس از دریافت نرخ از API قیمت دلار، نوبت به محاسبهٔ قیمت تومانی می‌رسد. فرمول پایه ساده است: قیمت دلاری کالا ضرب در نرخ دلار. با این حال، در دنیای واقعی دو عامل دیگر نیز اهمیت دارند: حاشیه سود و گرد کردن قیمت.

اعمال حاشیه سود برای هر محصول

حاشیهٔ سود همهٔ کالاها یکسان نیست. برای مثال، حاشیهٔ سود یک قطعهٔ پرفروش ممکن است کمتر از یک کالای خاص و کم‌یاب باشد. به همین دلیل بهتر است درصد سود را برای هر محصول جداگانه نگه داریم و در محاسبه از آن استفاده کنیم.

گرد کردن قیمت به عددی خوانا

از طرفی، قیمتی مثل ۲۶٬۸۶۱٬۵۲۰ تومان برای مشتری نامأنوس است و ظاهر حرفه‌ای ندارد. لذا قیمت را رو به بالا گرد می‌کنیم تا هم عدد خوانا شود و هم حاشیهٔ سود کاهش پیدا نکند. به مثال زیر توجه کنید:

<?php
// ادامهٔ فایل pricing.php

function calculateTomanPrice(
    float $priceUsd,
    int $dollarRate,
    float $marginPercent,
    int $roundTo = 10000
): int {
    // قیمت خام = قیمت دلاری × نرخ دلار × (۱ + درصد سود)
    $raw = $priceUsd * $dollarRate * (1 + $marginPercent / 100);

    // برای جلوگیری از خطای اعشاری، ابتدا تا دو رقم اعشار گرد می‌کنیم
    $raw = round($raw, 2);

    // گرد کردن رو به بالا تا حاشیهٔ سود کم نشود
    return (int) (ceil($raw / $roundTo) * $roundTo);
}

echo number_format(calculateTomanPrice(120, 189700, 18));

در این مثال، کالایی با قیمت ۱۲۰ دلار، نرخ دلار ۱۸۹٬۷۰۰ تومان و حاشیهٔ سود ۱۸ درصد را در نظر گرفته‌ایم. قیمت خام برابر ۲۶٬۸۶۱٬۵۲۰ تومان می‌شود. جالب است بدانید که خروجی کد بالا به صورت زیر خواهد بود:

26,870,000

پارامتر $roundTo دقت گرد کردن را تعیین می‌کند. در جدول زیر، اثر مقادیر مختلف این پارامتر روی همان قیمت خام را مشاهده می‌کنید:

مقدار $roundToقیمت نهایی (تومان)کاربرد پیشنهادی
۱٬۰۰۰۲۶٬۸۶۲٬۰۰۰کالاهای ارزان و لوازم مصرفی
۱۰٬۰۰۰۲۶٬۸۷۰٬۰۰۰بیشتر کالاهای فروشگاه
۱۰۰٬۰۰۰۲۶٬۹۰۰٬۰۰۰کالاهای گران‌قیمت

به طور کلی، هرچه قیمت کالا بالاتر باشد، می‌توانید دقت گرد کردن را کمتر کنید؛ زیرا اختلاف ایجادشده در مقایسه با قیمت کل ناچیز است.

جلوگیری از نوسان شدید نرخ دلار در قیمت‌ها

یکی از خطاهای رایج در پیاده‌سازی به‌روزرسانی خودکار این است که هر عددی که از API قیمت دلار رسید، بی‌درنگ روی همهٔ محصولات اعمال شود. در واقع دو مشکل در این روش وجود دارد. نخست اینکه تغییرات بسیار کوچک باعث می‌شوند قیمت‌ها مدام جابه‌جا شوند و مشتری احساس بی‌ثباتی کند. دوم اینکه یک جهش ناگهانی و بزرگ ممکن است بدون بازبینی مدیر، کل فروشگاه را تحت تأثیر قرار دهد.

بنابراین یک «محافظ» در نظر می‌گیریم که دو آستانه دارد: حداقل تغییر لازم برای به‌روزرسانی و حداکثر تغییر مجاز برای اعمال خودکار. به مثال زیر توجه کنید:

<?php
// ادامهٔ فایل pricing.php

function decideRate(
    int $newRate,
    ?int $lastRate,
    float $minChange = 0.5, // تغییرات کمتر از نیم درصد نادیده گرفته می‌شوند
    float $maxChange = 5.0  // تغییرات بیشتر از ۵ درصد نیاز به تأیید مدیر دارند
): array {
    // اولین اجرا: هنوز نرخی اعمال نشده است
    if ($lastRate === null) {
        return ['status' => 'apply', 'rate' => $newRate];
    }

    $changePercent = abs($newRate - $lastRate) / $lastRate * 100;

    if ($changePercent < $minChange) {
        return ['status' => 'skip', 'rate' => $lastRate];
    }

    if ($changePercent > $maxChange) {
        return ['status' => 'hold', 'rate' => $lastRate];
    }

    return ['status' => 'apply', 'rate' => $newRate];
}

اکنون فرض کنید آخرین نرخ اعمال‌شده ۱۸۹٬۷۰۰ تومان باشد. در جدول زیر رفتار این تابع را در سه حالت مختلف مشاهده می‌کنید:

نرخ جدید (تومان)درصد تغییرتصمیمنتیجه
۱۹۰٬۰۰۰حدود ۰٫۱۶٪skipقیمت‌ها تغییر نمی‌کنند
۱۹۳٬۱۱۵حدود ۱٫۸٪applyقیمت همهٔ محصولات به‌روز می‌شود
۲۱۰٬۰۰۰حدود ۱۰٫۷٪holdمنتظر بازبینی مدیر می‌ماند

مقادیر ۰٫۵ و ۵ درصد صرفاً پیشنهاد اولیه هستند. علاوه بر این، شما عزیزان می‌توانید آن‌ها را بر اساس سیاست فروش و میزان حساسیت بازار خود تنظیم کنید.

تذکر: حالت hold به معنای نادیده گرفتن تغییر نیست. اگر جهش نرخ واقعی باشد، اسکریپت تا زمانی که مدیر آن را تأیید نکند همچنان در همین حالت باقی می‌ماند. بنابراین حتماً برای این حالت یک اعلان (مثلاً ایمیل به مدیر) در نظر بگیرید.

ذخیرهٔ خروجی API قیمت دلار و به‌روزرسانی قیمت محصولات در دیتابیس

برای اینکه محافظ نوسان بتواند کار کند، باید آخرین نرخ اعمال‌شده را جایی ذخیره کنیم. از طرفی، نگهداری تاریخچهٔ تصمیم‌ها برای عیب‌یابی نیز بسیار مفید است. به همین دلیل دو جدول در نظر می‌گیریم:

CREATE TABLE products (
    id             INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    title          VARCHAR(255)    NOT NULL,
    price_usd      DECIMAL(10, 2)  NOT NULL,
    margin_percent DECIMAL(5, 2)   NOT NULL DEFAULT 15.00,
    price_toman    BIGINT UNSIGNED NOT NULL DEFAULT 0,
    updated_at     DATETIME        NULL
);

CREATE TABLE dollar_rates (
    id         INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    rate       INT UNSIGNED NOT NULL,
    status     VARCHAR(10)  NOT NULL,
    created_at DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP
);

جدول products قیمت دلاری و درصد سود هر کالا را نگه می‌دارد و قیمت تومانی محاسبه‌شده نیز در ستون price_toman ذخیره می‌شود. در مقابل، جدول dollar_rates هر نرخ دریافتی را همراه با تصمیم محافظ ثبت می‌کند.

حالا همهٔ قطعات را در یک اسکریپت کنار هم قرار می‌دهیم. به مثال زیر توجه کنید:

<?php
// فایل update-prices.php

require __DIR__ . '/pricing.php';

// اطلاعات اتصال به دیتابیس نیز از متغیرهای محیطی خوانده می‌شود
$pdo = new PDO(getenv('DB_DSN'), getenv('DB_USER'), getenv('DB_PASS'), [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);

try {
    $newRate = fetchDollarRate();
} catch (RuntimeException $e) {
    // در صورت خطا، قیمت‌های فعلی فروشگاه دست‌نخورده باقی می‌مانند
    error_log('Dollar rate fetch failed: ' . $e->getMessage());
    exit(1);
}

// آخرین نرخی که واقعاً روی محصولات اعمال شده است
$lastRate = $pdo->query(
    "SELECT rate FROM dollar_rates WHERE status = 'apply' ORDER BY id DESC LIMIT 1"
)->fetchColumn();
$lastRate = ($lastRate === false) ? null : (int) $lastRate;

$decision = decideRate($newRate, $lastRate);

// ثبت نرخ دریافتی و تصمیم محافظ برای گزارش‌گیری
$pdo->prepare('INSERT INTO dollar_rates (rate, status) VALUES (?, ?)')
    ->execute([$newRate, $decision['status']]);

if ($decision['status'] === 'hold') {
    // در این نقطه می‌توانید برای مدیر ایمیل یا پیامک ارسال کنید
    error_log("Rate change too large: {$lastRate} -> {$newRate}");
}

if ($decision['status'] !== 'apply') {
    echo "No update ({$decision['status']})\n";
    exit(0);
}

$products = $pdo->query('SELECT id, price_usd, margin_percent FROM products')
    ->fetchAll(PDO::FETCH_ASSOC);

$update = $pdo->prepare(
    'UPDATE products SET price_toman = ?, updated_at = NOW() WHERE id = ?'
);

// همهٔ محصولات در یک تراکنش به‌روز می‌شوند تا قیمت‌ها ناقص باقی نمانند
$pdo->beginTransaction();
try {
    foreach ($products as $product) {
        $price = calculateTomanPrice(
            (float) $product['price_usd'],
            $decision['rate'],
            (float) $product['margin_percent']
        );
        $update->execute([$price, $product['id']]);
    }
    $pdo->commit();
} catch (Throwable $e) {
    $pdo->rollBack();
    error_log('Price update failed: ' . $e->getMessage());
    exit(1);
}

echo 'Updated ' . count($products) . " products with rate {$decision['rate']}\n";

نکتهٔ کلیدی این اسکریپت، استفاده از تراکنش است. در واقع اگر به‌روزرسانی حتی یک محصول با خطا مواجه شود، تمام تغییرات برگردانده می‌شوند. در نتیجه هیچ‌گاه وضعیتی پیش نمی‌آید که نیمی از محصولات با نرخ جدید و نیمی دیگر با نرخ قدیم قیمت‌گذاری شده باشند.

اگر فروشگاه شما ۴۰۰ محصول داشته باشد و نرخ جدید ۱۹۳٬۱۱۵ تومان باشد، خروجی اجرای اسکریپت به صورت زیر خواهد بود:

Updated 400 products with rate 193115

زمان‌بندی خودکار فراخوانی API قیمت دلار با Cron

تا اینجا اسکریپتی داریم که با یک بار اجرا، کل فرایند به‌روزرسانی قیمت محصولات را انجام می‌دهد. اکنون باید آن را زمان‌بندی کنیم تا بدون دخالت انسان و در فواصل منظم اجرا شود. ساده‌ترین روش روی سرورهای لینوکسی، استفاده از Cron است. به مثال زیر توجه کنید:

# اجرای اسکریپت هر ۳۰ دقیقه یک بار
# دستور flock از اجرای هم‌زمان دو نسخه از اسکریپت جلوگیری می‌کند
*/30 * * * * flock -n /tmp/update-prices.lock php /var/www/shop/cron/update-prices.php >> /var/log/update-prices.log 2>&1

با این زمان‌بندی، اسکریپت روزانه ۴۸ بار اجرا می‌شود و هر اجرا تنها یک درخواست به API قیمت دلار ارسال می‌کند. بنابراین مصرف سهمیه کاملاً قابل پیش‌بینی است و به تعداد بازدیدکنندگان سایت ربطی ندارد. فاصلهٔ اجرا را متناسب با پلن خود و میزان حساسیت فروشگاه به نرخ دلار تنظیم کنید.

نکته: Cron متغیرهای محیطی نشست کاربر را بارگذاری نمی‌کند. لذا مقادیری مانند KARINA_API_TOKEN و DB_DSN را یا در بالای فایل crontab تعریف کنید یا از یک اسکریپت واسط برای بارگذاری آن‌ها استفاده کنید.

اگر پروژهٔ شما با Laravel نوشته شده است، پیشنهاد می‌کنم آموزش اتصال API قیمت در لاراول با Http Client، Cache و Scheduler را نیز مطالعه کنید. در آن مطلب، همین منطق را با ابزارهای داخلی لاراول پیاده‌سازی کرده‌ایم. همچنین برای آشنایی بیشتر با قالب زمان‌بندی، می‌توانید مستندات رسمی crontab را ببینید.

چند توصیهٔ تکمیلی برای محیط پروداکشن

پیش از انتقال این راهکار به سرور پروداکشن، به چند نکتهٔ مهم توجه فرمایید:

  • ابتدا اسکریپت را روی محیط لوکال و با یک نسخه از دیتابیس آزمایش کنید و قیمت‌های محاسبه‌شده را با محاسبهٔ دستی مقایسه کنید.
  • فایل لاگ را به صورت دوره‌ای بررسی کنید تا خطاهای اتصال یا حالت‌های hold از چشم شما پنهان نمانند.
  • مقدار quota.remaining را در ریسپانس API قیمت دلار زیر نظر داشته باشید تا پیش از اتمام سهمیه، پلن خود را بررسی کنید.
  • اگر می‌خواهید آستانه‌های محافظ نوسان را دقیق‌تر تعیین کنید، رفتار گذشتهٔ نرخ دلار را با API تاریخچه قیمت دلار بررسی کنید.
  • برای شفافیت بیشتر با مشتری، می‌توانید زمان آخرین به‌روزرسانی قیمت را کنار محصول نمایش دهید.

اگر فروشگاه شما نیز قیمت پایهٔ کالاها را به دلار نگه می‌دارد، می‌توانید با تهیهٔ یکی از پلن‌های کارینا و ساختن توکن در داشبورد، همین امروز API قیمت دلار را به اسکریپت بالا متصل کنید و قیمت‌گذاری دستی را کنار بگذارید.

حرف آخر اینکه: به‌روزرسانی خودکار قیمت محصولات فقط ضرب دو عدد نیست؛ دریافت مطمئن نرخ، اعمال حاشیه سود، گرد کردن اصولی و محافظت در برابر نوسان شدید، چهار ستون اصلی آن هستند. با جدا کردن دریافت نرخ از صفحات سایت و اجرای زمان‌بندی‌شده، فروشگاهی سریع و قیمت‌هایی همواره به‌روز خواهید داشت.

خب به پایان آموزش «به‌روزرسانی خودکار قیمت محصولات فروشگاه با API قیمت دلار» رسیدیم. امیدوارم این مبحث مورد توجه شما واقع شده باشد. چنانچه ابهام، اشکال یا سؤالی داشتید و یا مورد خاصی در پروژه‌هایتان تجربه کرده‌اید، می‌توانید در بخش دیدگاه‌ها با ما و بقیهٔ همراهان کارینا به اشتراک بگذارید. همچنین پیشنهاد می‌گردد بلاگ کارینا را دنبال کنید تا از جدیدترین آموزش‌های تخصصی بهره‌مند شوید.

پرسش و پاسخ

سوالات متداول

هر چند وقت یک بار باید قیمت محصولات را با نرخ دلار به‌روز کنم؟

این موضوع به حساسیت بازار شما و سهمیهٔ پلن‌تان بستگی دارد. برای بیشتر فروشگاه‌ها اجرای هر ۳۰ تا ۶۰ دقیقه کافی است، به‌ویژه وقتی محافظ نوسان تغییرات جزئی را نادیده می‌گیرد.

اگر API در دسترس نباشد، قیمت‌های سایت چه می‌شوند؟

در روش این آموزش، هر خطا باعث توقف اسکریپت می‌شود و قیمت‌های قبلی در دیتابیس دست‌نخورده باقی می‌مانند. بنابراین هیچ‌گاه قیمت صفر یا ناقص روی سایت نمایش داده نمی‌شود.

آیا می‌توانم برای هر محصول حاشیه سود متفاوتی تعیین کنم؟

بله؛ کافی است درصد سود را در ستون جداگانه‌ای برای هر محصول ذخیره کنید. تابع محاسبه، این درصد را هنگام ساخت قیمت تومانی اعمال می‌کند.

چرا نباید API قیمت دلار را در هر بار نمایش صفحهٔ محصول فراخوانی کرد؟

این کار سرعت سایت را به سرعت شبکه وابسته می‌کند و سهمیهٔ API را به نسبت تعداد بازدیدها مصرف می‌کند. ذخیرهٔ قیمت در دیتابیس و به‌روزرسانی زمان‌بندی‌شده هم سریع‌تر است و هم قابل پیش‌بینی.

اشتراک‌گذاری
همه مطالب مجله

دیدگاه‌ها

هنوز دیدگاهی ثبت نشده است. اولین نفر باشید!

دیدگاه خود را بنویسید