🔗 آدرس پایه (Base URL)
تمام درخواستها باید به آدرس زیر ارسال شوند:
https://pardazmaan.ir/wp-json/mjc/v1
تمام ارتباطات فقط از طریق HTTPS پشتیبانی میشود. درخواست HTTP با خطای امنیتی رد میشود.
🔑 احراز هویت (Authentication)
ارسال API Key معتبر برای تمام endpoint ها الزامی است. اولویت روشها:
1) هدر پیشنهادی
X-API-Key: mjc_your_api_key_here
2) هدر جایگزین
X-MJC-API-Key: mjc_your_api_key_here
3) Query String (فقط توسعه)
?api_key=mjc_your_api_key_here
هشدار امنیتی: API Key را هرگز در کلاینت عمومی (HTML/JS) قرار ندهید.
📦 قرارداد پاسخ (Response Contract)
برای یکنواختی، تمام پاسخها دارای ساختار استاندارد زیر هستند:
موفق
{
"success": true,
"data": {},
"meta": {
"request_id": "req_abc123",
"version": "v1"
}
}
خطا
{
"success": false,
"error": {
"code": "invalid_parameter",
"message": "پارامتر month باید بین 1 تا 12 باشد.",
"details": { "month": 13 }
},
"meta": {
"request_id": "req_abc123",
"version": "v1"
}
}
📡 Endpoint ها
GET
/jalali/{year}/{month}/{day}
اطلاعات یک روز
اطلاعات یک روز جلالی شامل وضعیت تعطیل و فهرست رویدادها را برمیگرداند.
| پارامتر | نوع | الزامی | قوانین اعتبارسنجی | مثال |
|---|
year | integer | الزامی | بین 1300 تا 1499 | 1405 |
month | integer | الزامی | بین 1 تا 12 | 1 |
day | integer | الزامی | وابسته به ماه/کبیسه (اعتبار تاریخ کامل بررسی میشود) | 1 |
expand | integer | اختیاری | 0 یا 1؛ اگر 1 باشد metadata رویدادها برمیگردد | expand=1 |
نمونه درخواست
curl --request GET \
--url "https://pardazmaan.ir/wp-json/mjc/v1/jalali/1405/1/1?expand=1" \
--header "X-API-Key: mjc_your_api_key_here"
نمونه پاسخ موفق (200)
{
"success": true,
"data": {
"date": "1405-01-01",
"is_holiday": true,
"events": [
{
"title": "آغاز نوروز",
"type": "national",
"is_holiday": true,
"description": "",
"source": "official_calendar"
},
{
"title": "عید سعید فطر",
"type": "religious",
"is_holiday": true,
"description": "",
"source": "official_calendar"
}
]
},
"meta": {
"request_id": "req_8f91f8",
"version": "v1"
}
}
GET
/events
فهرست رویدادها
فهرست رویدادها را بر اساس سال/ماه با قابلیت صفحهبندی برمیگرداند.
| پارامتر | نوع | الزامی | پیشفرض | قوانین |
|---|
year | integer | اختیاری | سال جاری جلالی | 1300..1499 |
month | integer | اختیاری | — | 1..12 |
limit | integer | اختیاری | 100 | 1..500 |
offset | integer | اختیاری | 0 | >= 0 |
نمونه درخواست
curl --request GET \
--url "https://pardazmaan.ir/wp-json/mjc/v1/events?year=1405&month=1&limit=50&offset=0" \
--header "X-API-Key: mjc_your_api_key_here"
نمونه پاسخ موفق (200)
{
"success": true,
"data": {
"items": [
{
"id": 142,
"title": "نوروز — جشن سال نو",
"jalali_date": "1405-01-01",
"gregorian_date": "",
"event_type": "national",
"is_holiday": true,
"description": "",
"source": "official_calendar"
}
],
"pagination": {
"total": 14,
"limit": 50,
"offset": 0
},
"filters": {
"year": 1405,
"month": 1
}
},
"meta": {
"request_id": "req_8112af",
"version": "v1"
}
}
⚡ خطاها و کدهای وضعیت
| HTTP | error.code | توضیح | اقدام پیشنهادی |
|---|
| 400 | invalid_parameter / invalid_date | ورودی نامعتبر یا تاریخ غیرواقعی | پارامترها را اصلاح کنید |
| 401 | missing_api_key / invalid_api_key | کلید API ارسال نشده یا نامعتبر است | کلید معتبر را در هدر بفرستید |
| 404 | route_not_found | مسیر API نادرست است | URL را بررسی کنید |
| 429 | rate_limit_exceeded | بیش از حد مجاز درخواست ارسال شده | بر اساس Retry-After مجدداً تلاش کنید |
| 500 | internal_error | خطای داخلی سرور | با backoff مجدد تلاش کنید |
نمونه خطا (400)
{
"success": false,
"error": {
"code": "invalid_date",
"message": "تاریخ واردشده معتبر نیست.",
"details": {
"year": 1405,
"month": 12,
"day": 31
}
},
"meta": {
"request_id": "req_2290ad",
"version": "v1"
}
}
⏱️ محدودیت نرخ، Timeout و Retry
- Rate Limit: حداکثر 60 درخواست در دقیقه برای هر API Key.
- Headers: در پاسخ ممکن است هدرهای
X-RateLimit-Limit، X-RateLimit-Remaining و Retry-After ارسال شود.
- Timeout پیشنهادی کلاینت: 10 ثانیه.
- Retry policy: فقط برای 429 و 5xx با Exponential Backoff (مثلاً 1s, 2s, 4s).
پاسخ endpoint روزانه /jalali/{year}/{month}/{day} تا 24 ساعت cache میشود.
🧭 نسخهبندی و پایداری API
- نسخه فعلی در مسیر:
/wp-json/mjc/v1
- Backward-compatible تغییرات غیرشکننده در v1 منتشر میشوند.
- تغییرات شکننده فقط با نسخه جدید (مثل
v2) ارائه خواهد شد.
- در صورت deprecation، حداقل 90 روز قبل اطلاعرسانی میشود.
🧪 نمونه کدهای کامل
JavaScript (Node.js / fetch)
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 10000);
(async () => {
try {
const res = await fetch("https://pardazmaan.ir/wp-json/mjc/v1/jalali/1405/1/1", {
method: "GET",
headers: { "X-API-Key": "mjc_your_api_key_here" },
signal: controller.signal
});
const json = await res.json();
if (!res.ok || !json.success) {
throw new Error(json?.error?.message || "API error");
}
console.log(json.data);
} catch (e) {
console.error(e.message);
} finally {
clearTimeout(timeout);
}
})();
PHP (WordPress wp_remote_get)
$url = 'https://pardazmaan.ir/wp-json/mjc/v1/events?year=1405&month=1&limit=50&offset=0';
$response = wp_remote_get($url, [
'timeout' => 10,
'headers' => [
'X-API-Key' => 'mjc_your_api_key_here',
'Accept' => 'application/json',
],
]);
if (is_wp_error($response)) {
error_log($response->get_error_message());
return;
}
$status = wp_remote_retrieve_response_code($response);
$body = wp_remote_retrieve_body($response);
$data = json_decode($body, true);
if ($status !== 200 || empty($data['success'])) {
error_log($data['error']['message'] ?? 'Unknown API error');
return;
}
print_r($data['data']);
