رها API

راهنمای توسعه‌دهنده

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

شروع سریع

  1. ورود: با حساب یکپارچهٔ رها دیتا (SSO) وارد شوید. حساب جداگانه لازم نیست.
  2. اپ و کلید پیش‌فرض: بعد از اولین ورود یک «اپ پیش‌فرض» با یک کلید اختصاصی برایتان ساخته می‌شود. کلیدها را در اپ‌ها و کلیدها ببینید، بسازید یا باطل کنید.
  3. اشتراک: API موردنظر را پیدا کنید و از تب «قیمت‌ها» یک پلن را برای اپ خود فعال کنید (بیشتر APIها پلن رایگان دارند).
  4. فراخوانی: در تب Endpoints همان‌جا درخواست آزمایشی بفرستید یا نمونه‌کد آماده را کپی کنید.

ساختار آدرس

همهٔ درخواست‌ها از دروازهٔ (Gateway) رها عبور می‌کنند:

https://gw.rahadata.ir/{api}/{endpoint}

مثلاً اگر شناسهٔ API instagram و مسیر Endpoint /user/{username} باشد:

https://gw.rahadata.ir/instagram/user/nasa?lang=fa

پارامترهای مسیر داخل آدرس، پارامترهای کوئری بعد از ? و بدنهٔ درخواست‌های POST/PUT/PATCH معمولاً به‌صورت JSON ارسال می‌شود. آدرس پایهٔ هر API در تب «درباره» همان API آمده است.

احراز هویت

کلید اپ را در هدر X-Raha-Key بفرستید:

X-Raha-Key: rk_xxxxxxxxxxxxxxxxxxxxxxxx
  • کلید را فقط سمت سرور نگه دارید و هرگز در کد سمت مرورگر یا اپ موبایل منتشر نکنید.
  • اشتراک‌ها برای هر اپ جداگانه‌اند؛ کلیدهای یک اپ همگی از اشتراک‌های همان اپ استفاده می‌کنند.
  • اگر کلیدی لو رفت، از پنل یک کلید تازه بسازید و کلید قبلی را باطل کنید.

محدودیت نرخ و سهمیه

هر پلن دو محدودیت دارد: سرعت (درخواست در دقیقه) و سهمیهٔ ماهانه. وضعیت آن در هدرهای پاسخ برمی‌گردد:

هدرمعنا
x-ratelimit-requests-limitسهمیهٔ کل دورهٔ جاری پلن شما
x-ratelimit-requests-remainingتعداد درخواست باقی‌مانده از سهمیه
x-ratelimit-requests-resetثانیه‌های باقی‌مانده تا تمدید سهمیه
retry-afterفقط در پاسخ ۴۲۹: چند ثانیه بعد دوباره تلاش کنید

کدهای خطا

خطاهای خود دروازه بدنهٔ JSON به شکل {"error": "…"} دارند. سایر کدها مستقیماً از سرویس فروشنده برمی‌گردند.

کدعلتچه کنید
401هدر X-Raha-Key ارسال نشدهکلید اپ را در هدر بفرستید.
403کلید نامعتبر یا باطل‌شده است، یا اپ به این API اشتراک نداردکلید را بررسی کنید و از تب «قیمت‌ها» پلن فعال کنید.
404API یا Endpoint با این آدرس وجود نداردشناسهٔ API، مسیر و متد HTTP را با مستندات تطبیق دهید.
429از سرعت مجاز در دقیقه یا سهمیهٔ ماهانهٔ پلن «سخت» عبور کرده‌ایدطبق retry-after صبر کنید یا پلن را ارتقا دهید.
502سرویس فروشنده پاسخ نامعتبر داد یا در دسترس نیستکمی بعد تلاش کنید؛ اگر ادامه داشت در تب «گفت‌وگو» گزارش دهید.
504سرویس فروشنده در مهلت مقرر پاسخ نداددوباره تلاش کنید؛ درخواست‌های سنگین را کوچک‌تر کنید.

صورت‌حساب و پرداخت

  • کیف پول: اعتبار تومانی پیش‌پرداخت که از کیف پول و فاکتورها شارژ می‌شود. خرید پلن از کیف پول فوری است؛ پرداخت مستقیم با کارت بانکی هم ممکن است.
  • پلن‌ها ماهانه‌اند و در پایان هر دوره به‌طور خودکار تمدید می‌شوند (قابل لغو از پنل).
  • سقف سخت: پس از اتمام سهمیه، درخواست‌ها با کد ۴۲۹ رد می‌شوند و هزینهٔ اضافه‌ای ندارید.
  • سقف نرم: پس از اتمام سهمیه، سرویس قطع نمی‌شود و هر درخواست مازاد با نرخ «اضافه‌مصرف» همان پلن حساب و در پایان دوره از کیف پول کسر می‌شود.
  • مالیات: مالیات بر ارزش افزوده طبق قانون به مبلغ پلن‌ها اضافه می‌شود.
  • فاکتور رسمی: برای هر پرداخت، صورت‌حساب الکترونیکی در سامانهٔ مؤدیان صادر می‌شود؛ اطلاعات حقیقی/حقوقی خود را در پروفایل کامل کنید.

نمونه‌کد

cURL

curl --request GET \
	--url 'https://gw.rahadata.ir/instagram/user/nasa' \
	--header 'X-Raha-Key: YOUR_RAHA_KEY'

Python

import requests

url = "https://gw.rahadata.ir/instagram/user/nasa"
headers = {"X-Raha-Key": "YOUR_RAHA_KEY"}

response = requests.get(url, headers=headers, timeout=30)
if response.status_code == 429:
    print("Retry after", response.headers.get("retry-after"), "seconds")
else:
    print("Remaining:", response.headers.get("x-ratelimit-requests-remaining"))
    print(response.json())

نمونه‌کد هر Endpoint به ۱۱ زبان (Node.js، PHP، Go، Java، C#، Kotlin، Swift، Dart و…) در صفحهٔ همان API آماده است.