مستندات API قیمت نبض بازار

شروع سریع

آدرس پایه:

اولین درخواست

curl "https://nabzebazaar.ir/api/v1/prices/latest?brand=Samsung&model=Galaxy%20A07&storage_gb=128&ram_gb=4" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

قیمت‌ها عدد صحیح و با واحد تومان برگردانده می‌شوند؛ جداکننده هزارگان داخل مقدار JSON وجود ندارد.

احراز هویت

کلید API را فقط در هدر اختصاصی زیر بفرستید:

X-API-Key: nb_live_xxxxxxxx_xxxxxxxxxxxxxxxxx

کلید را داخل URL، کد سمت مرورگر، اپ عمومی یا مخزن Git قرار ندهید. درخواست API باید از بک‌اند یا سرور خودتان ارسال شود.

قیمت‌های جاری

هر عضو data یک SKU مستقل است. تفاوت حافظه، RAM، 4G/5G، کشور نسخه و اقلام داخل جعبه باعث ایجاد SKU جدا می‌شود.

{
  "success": true,
  "data": [
    {
      "product": {
        "product_id": "prd_...",
        "title": "Samsung Galaxy A07 128GB 4GB",
        "brand": "Samsung",
        "model": "Galaxy A07",
        "storage_gb": 128,
        "ram_gb": 4,
        "network": null,
        "variant": null
      },
      "market_summary": {
        "currency": "toman",
        "market_floor": {"price": 34899000, "color": "بنفش", "store": "همراه تل"},
        "average_market": {"price": 36081260, "method": "average_of_each_color_lowest_3"},
        "average_color_floors": {"price": 35663420, "method": "average_of_each_color_floor"},
        "cheapest_color_average": {"price": 35130433, "color": "بنفش", "offers_used": 3, "method": "average_of_lowest_3"},
        "color_count": 5,
        "available_offer_count": 27
      },
      "colors": [
        {
          "name": "بنفش",
          "summary": {
            "floor": 34899000,
            "average_lowest_3": 35130433,
            "offers_used_for_average": 3,
            "outlier_removed_from_average": false,
            "available_offer_count": 7
          },
          "offers": [
            {"store_id":"shop_...","store_name":"همراه تل","seller_name":null,"price":34899000,"available":true,"url":null}
          ]
        }
      ]
    }
  ],
  "meta": {
    "source_updated_at": "2026-08-24T14:30:00+03:30",
    "summary_scope": "all_colors_of_variant",
    "page": 1,
    "per_page": 20,
    "total_products": 1,
    "delivered_price_records": 27
  }
}

پارامترهای فیلتر

تعریف کف و میانگین‌ها

اگر رنگی حداقل سه قیمت داشته باشد و ارزان‌ترین قیمت بیش از ۵٪ از قیمت دوم پایین‌تر باشد، آن قیمت فقط از محاسبه میانگین کنار گذاشته می‌شود. قیمت همچنان در پیشنهادها و کف بازار باقی می‌ماند.

رنگ، فروشگاه و فروشنده

store_name منبع اصلی قیمت است. در مارکت‌پلیس‌هایی مانند دیجی‌کالا، seller_name فروشنده داخل آن مارکت‌پلیس است. املاهای معادل رنگ‌ها با فرهنگ رنگ نبض‌بازار یکسان‌سازی می‌شوند.

تاریخچه قیمت

این endpoint در پلن‌های دارای تاریخچه فعال است. مقدار product_id را از خروجی قیمت جاری بردارید.

curl "https://nabzebazaar.ir/api/v1/prices/history?product_id=prd_xxx&days=30&interval=day" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "product": {"product_id":"prd_xxx","model":"Galaxy A07","storage_gb":128},
    "currency":"toman",
    "interval":"day",
    "series":{"مشکی":[{"timestamp":"2026-08-24T00:00:00+03:30","price":34900000,"min_price":34700000,"max_price":35100000,"samples":12}]}
  },
  "meta":{"days":30,"history_days_allowed":30,"point_count":1,"delivered_price_records":1}
}

Webhook تغییر قیمت

در پلن‌های حرفه‌ای می‌توانید URL عمومی HTTPS ثبت کنید. Secret امضا فقط در پاسخ ساخت نمایش داده می‌شود.

ساخت

curl -X POST "https://nabzebazaar.ir/api/v1/webhooks" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/nabz","events":["prices.updated"]}'

فهرست و غیرفعال‌سازی

GET /webhooks
DELETE /webhooks?id=WEBHOOK_ID

اعتبارسنجی امضا

بدنه خام درخواست را با HMAC-SHA256 و Secret دریافتی امضا کنید و با هدر زیر به‌صورت ثابت‌زمان مقایسه کنید:

X-Nabz-Signature: sha256=HEX_HMAC
X-Nabz-Event: prices.updated
X-Nabz-Delivery: evt_xxx

ارسال ناموفق با فاصله افزایشی تا ۵ بار تکرار می‌شود. URL فقط HTTPS عمومی است، redirect دنبال نمی‌شود و مقصدهای private/reserved مسدودند.

مصرف و سهمیه

هر رکورد قابل محاسبه در سهمیه برابر است با یک پیشنهاد قیمت تحویلی از ترکیب «SKU + رنگ + فروشگاه». فیلدهای خلاصه هزینه رکورد اضافه ندارند.

curl "https://nabzebazaar.ir/api/v1/usage" \
  -H "X-API-Key: YOUR_API_KEY"

هدرهای پاسخ نیز مقدار باقی‌مانده را نشان می‌دهند:

X-Monthly-Record-Limit: 100000
X-Monthly-Records-Remaining: 82460
X-RateLimit-Limit: 30

در حالت عادی با رسیدن به سقف، پاسخ 429 برمی‌گردد. اضافه‌مصرف فقط پس از تأیید قراردادی مدیر فعال می‌شود و فیلدهای overage_records و estimated_overage_toman در خروجی مصرف قابل پایش‌اند.

امنیت و قواعد استفاده

• کلید را فقط در بک‌اند نگه دارید و هرگز در JavaScript مرورگر یا اپ قابل استخراج قرار ندهید.
• برای سرورهای ثابت، IP Allowlist را هنگام صدور کلید فعال کنید.
• برای محیط توسعه و تولید کلیدهای جدا بگیرید و در صورت افشا فوراً کلید را لغو و جایگزین کنید.
• دریافت انبوه خارج از سهمیه، اشتراک‌گذاری کلید و بازفروش خام داده بدون مجوز قراردادی ممنوع است.
• در خطاهای 429 و 5xx از backoff استفاده کنید؛ polling تهاجمی لازم نیست.

کلید کامل در سامانه نبض‌بازار ذخیره نمی‌شود؛ بنابراین بازیابی ممکن نیست و باید کلید جدید صادر شود.

کدهای خطا

SDK و نمونه‌کد

نسخه‌های آماده دانلود: Python · PHP · Node.js. در production کلید را از متغیر محیطی یا secret manager بخوانید.

Python

import requests

response = requests.get(
    "https://nabzebazaar.ir/api/v1/prices/latest",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"brand": "Samsung", "model": "Galaxy A07", "storage_gb": 128},
    timeout=30,
)
response.raise_for_status()
products = response.json()["data"]

PHP

<?php
$url = 'https://nabzebazaar.ir/api/v1/prices/latest?brand=Samsung&storage_gb=128';
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY'],
    CURLOPT_TIMEOUT => 30,
]);
$data = json_decode(curl_exec($ch), true);

Node.js

const url = new URL('https://nabzebazaar.ir/api/v1/prices/latest');
url.searchParams.set('brand', 'Samsung');
url.searchParams.set('storage_gb', '128');

const response = await fetch(url, {
  headers: {'X-API-Key': 'YOUR_API_KEY'}
});
const body = await response.json();

چک‌لیست راه‌اندازی مشتری

1. از صفحه پلن‌ها، تست رایگان یک‌روزه یا خرید آنلاین را انتخاب کنید.
2. بعد از ورود با موبایل تأییدشده، کلید فقط یک‌بار در حساب API نمایش داده می‌شود؛ همان لحظه آن را امن ذخیره کنید.
3. ابتدا /usage، سپس یک درخواست محدود قیمت جاری تست شود.
4. شناسه product_id در دیتابیس مشتری نگهداری شود و قیمت بر اساس model/storage/RAM/color نمایش داده شود.
5. برای 429 و 5xx retry کنترل‌شده و برای تغییرات Webhook پیاده‌سازی شود.
6. پیش از پایان دوره، مصرف و تاریخ تمدید از حساب API پایش شود.

برای تست اولیه، با ۵ تا ۱۰ SKU شروع کنید؛ پس از تطبیق خروجی، دامنه کالاها را افزایش دهید.