API Reference
مستندات API
PersianToolbox APIهای عمومی و مستند. برای توسعهدهندگانی که میخواهند نرخ ارز، قوانین حقوق، دادههای تقویم یا ابزارهای اعتبارسنجی را به پروژه خود اضافه کنند.
Base URL
https://persiantoolbox.irAuthentication
بیشتر endpointهای عمومی نیازی به احراز هویت ندارند. برای endpointهای حساس (مانند اطلاعات کاربر، سابقه)، از توکن JWT در هدر Authorization استفاده کنید:
Authorization: Bearer {your_jwt_token}توکن را از طریق POST /api/auth/login دریافت کنید.
Rate Limiting
محدودیت نرخ بر اساس کلید IP اعمال میشود. در صورت تجاوز، کد ۴۲۹ برگردانده میشود:
{
"ok": false,
"reason": "RATE_LIMITED",
"resetAt": 1719500000000
}سیاستهای محدودیت در هر endpoint در جدول زیر مشخص شده است.
Endpoints
| Method | Path | توضیحات | Auth | Rate Limit |
|---|---|---|---|---|
GET | /api/health | بررسی سلامت سرویس بدون محدودیت. وضعیت uptime، حافظه و نسخه. | — | — |
GET | /api/ready | بررسی آمادگی سرویس بدون محدودیت. برای k8s/liveness probe مناسب. | — | — |
GET | /api/version | نسخه سرویس بدون محدودیت. شماره نسخه و تایماستمپ آخرین دیپلوی. | — | — |
GET | /api/public/stats | آمار عمومی سایت تعداد ابزارها، بازدیدها، مقالات. | — | — |
GET | /api/market | نرخهای ارز و طلا نرخ لحظهای دلار، یورو، سکه، طلا از چند منبع. | — | ۳۰ req/min |
GET | /api/data/salary-laws | قوانین حقوق و دستمزد پارامترهای بیمه، مالیات، حداقل حقوق ۱۴۰۵. | — | ۶۰ req/min |
GET | /api/site-settings | تنظیمات عمومی سایت عنوان، توضیحات، لینک شبکههای اجتماعی. | — | — |
GET | /api/enamad-verification | نماد اعتماد (JSON) فایل JSON برای نمایش نماد اعتماد در iFrame. | — | — |
POST | /api/auth/login | ورود کاربر Body: { email, password }. Returns token. | — | ۳۰ req/min |
POST | /api/auth/register | ثبتنام کاربر Body: { email, password }. Returns token. | — | ۳۰ req/min |
GET | /api/auth/me | اطلاعات کاربر Header: Authorization: Bearer {token} | ✅ | — |
POST | /api/analytics | ارسال رویداد Body: { event, page, referrer, ... } | — | ۱۲۰ req/min |
GET | /api/history/share/[token] | دریافت ابزار اشتراکی با توکن اشتراک، دادههای ذخیرهشده ابزار را برمیگرداند. | — | — |
POST | /api/push/subscribe | عضویت در نوتیفیکیشن Body: { endpoint, p256dh, auth } | — | — |
GET | /api/usage/check | بررسی محدودیت مصرف محدودیت کاربر در ابزارهای پریمیوم. | — | — |
GET | /robots.txt | فایل robots.txt فایل ایستا — خزندههای مجاز و نقشه سایت. | — | — |
GET | /sitemap.xml | نقشه سایت XML ۲۳۵+ صفحه ایستا و پویا. | — | — |
GET | /feed.xml | خوراک RSS/Atom خوراک وبلاگ برای RSS reader. | — | — |
Example: Health Check
سادهترین endpoint برای تست اتصال:
curl https://persiantoolbox.ir/api/health
Response:
{
"status": "ok",
"version": "6.8.0",
"uptime": 12345,
"memory": {
"rss": 789,
"heapUsed": 150
},
"node": "v20.20.2"
}Error Handling
همه endpointها خطاها را با ساختار یکسان برمیگردانند:
{
"ok": false,
"error": "توضیح خطا",
"reason": "ERROR_CODE"
}HTTP Status Codes:
200— موفق400— ورودی نامعتبر401— نیاز به احراز هویت403— دسترسی غیرمجاز (CSRF)429— محدودیت نرخ500— خطای سرور
Support
برای سوالات فنی، پیشنهادات یا گزارش باگ در API: