راهنمای API نرخ v2

شروع سریع

curl --fail-with-body \
  -H "Authorization: Bearer $NERKH_API_KEY" \
  -H "Origin: https://example.com" \
  https://nerkh.xhesam.com/api/latest

احراز هویت

ابتدا یک حساب رایگان بسازید و یک دامنه HTTPS دقیق ثبت کنید. سپس کلید را فقط در هدر Authorization و دامنه را در هدر Origin بفرستید. کلید را در URL، لاگ یا Repository قرار ندهید.

ساخت حساب رایگان

Authorization: Bearer nrkh_xxxxxxxxxxxxxxxxxxxx
Origin: https://example.com

Endpointها

متد	مسیر	کاربرد
GET	`/api/latest`	آخرین دسته‌بندی‌ها و نرخ‌ها
GET	`/api/categories`	تعریف دسته‌بندی‌ها
GET	`/api/categories/:category_id`	یک دسته‌بندی و نرخ‌های آن
GET	`/api/rates/:rate_id`	جزئیات یک نرخ
GET	`/api/history/:rate_id`	تاریخچه یک نرخ

پارامترهای تاریخچه

یکی از range یا بازه from/to را استفاده کنید. بیشترین بازه مجاز ۹۰ روز است.

/api/history/price_usd?range=7d
/api/history/price_usd?range=30d
/api/history/price_usd?range=90d
/api/history/price_usd?from=2026-07-01&to=2026-07-12

قرارداد پاسخ

همه پاسخ‌های موفق metadata نسخه، واحد، timezone، زمان تولید و سهمیه باقی‌مانده را دارند.

{
  "ok": true,
  "provider": "Nerkh",
  "schema_version": "1.0.0",
  "api_version": "2.0.0",
  "unit": "IRR",
  "timezone": "UTC",
  "generated_at": "2026-07-12T12:00:00Z",
  "limits": {
    "daily_limit": 100,
    "remaining": 99,
    "reset_at": "2026-07-13T00:00:00.000Z"
  }
}

خطاها

HTTP	Error
400	`invalid_query / invalid_range / invalid_date`
401	`unauthorized`
403	`origin_required / origin_not_allowed`
404	`category_not_found / rate_not_found / not_found`
405	`method_not_allowed`
429	`daily_limit_exceeded`
503	`service_unavailable / data_unavailable`

تبدیل واحد و زمان

مقادیر API همیشه ریال و timestampها همیشه UTC هستند. تبدیل نمایشی بر عهده مصرف‌کننده است.

const toman = response.item.price.value / 10;
const tehran = new Intl.DateTimeFormat("fa-IR", {
  dateStyle: "medium",
  timeStyle: "short",
  timeZone: "Asia/Tehran"
}).format(new Date(response.generated_at));

نکات امنیتی

هر حساب رایگان دقیقاً یک توکن و یک Origin دارد. Origin در همه درخواست‌ها الزامی است و جایگزین API key نیست.

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset
X-Request-Id