راهنمای توسعهدهنده
هر API در رها با یک کلید واحد و یک الگوی یکسان فراخوانی میشود. این راهنما همهٔ چیزی است که برای شروع لازم دارید.
شروع سریع
- ورود: با حساب یکپارچهٔ رها دیتا (SSO) وارد شوید. حساب جداگانه لازم نیست.
- اپ و کلید پیشفرض: بعد از اولین ورود یک «اپ پیشفرض» با یک کلید اختصاصی برایتان ساخته میشود. کلیدها را در اپها و کلیدها ببینید، بسازید یا باطل کنید.
- اشتراک: API موردنظر را پیدا کنید و از تب «قیمتها» یک پلن را برای اپ خود فعال کنید (بیشتر APIها پلن رایگان دارند).
- فراخوانی: در تب 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 اشتراک ندارد | کلید را بررسی کنید و از تب «قیمتها» پلن فعال کنید. |
| 404 | API یا 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 آماده است.