بررسی کلید با سرور پاتریس
سایت میتواند با POST /api/site/v1/verify از سرور پاتریس بپرسد کلیدش معتبر است یا نه. این فراخوانی اختیاری است و برای نمایش وضعیت اتصال در پنل مدیریت سایت به کار میرود.
چرا این فراخوانی اختیاری است؟
اعتبار کلید، اشتراک و امکانات حساب را پاتریس یار خودش با سرور پاتریس بررسی میکند. سایت فقط کلید ارسالی پاتریس یار را با کلید خود مقایسه میکند. این endpoint به مدیر سایت کمک میکند خطاهایی مثل پایان اشتراک یا IP غیرمجاز را زودتر ببیند.
پیشنیازها
- کلید API حساب پاتریس.
- دسترسی سرور سایت به سرور پاتریس.
Endpoint
POST https://patrisyar.payava.com/api/site/v1/verify
هدرها
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
X-Payava-Key | string | بله | کلید API حساب پاتریس. |
Content-Type | string | بله | application/json; charset=utf-8 |
پارامترها
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
siteUrl | string | خیر | آدرس اصلی سایت. |
pluginVersion | string | خیر | نسخهی پیادهسازی شما. |
پیادهسازی در وردپرس
بررسی کلید (مثلاً روزی یک بار با wp-cron)
function my_patris_verify_key()
{
$response = wp_remote_post(rtrim(PATRIS_CLOUD_URL, '/') . '/api/site/v1/verify', [
'timeout' => 20,
'headers' => [
'Content-Type' => 'application/json; charset=utf-8',
'X-Payava-Key' => (string) get_option('my_patris_api_key'),
],
'body' => wp_json_encode(['siteUrl' => home_url(), 'pluginVersion' => 'my-patris-connector-1.0.0']),
]);
if (is_wp_error($response)) {
return null; // keep the previous result
}
$result = json_decode(wp_remote_retrieve_body($response), true);
update_option('my_patris_key_check', $result, false); // valid, status, message, validUntilShamsi, callerIp
return $result;
}
نمونه پاسخ موفق
پاسخ همیشه 200 است، حتی وقتی کلید معتبر نیست. نتیجه را از valid و status بخوانید.
200 OK — کلید معتبر
{
"valid": true,
"status": "valid",
"message": "کلید معتبر است. اشتراک تا 1406/08/16 فعال است.",
"tenantName": "فروشگاه نمونه",
"keyName": "سایت اصلی",
"validUntil": "2027-11-07",
"validUntilShamsi": "1406/08/16",
"scopes": ["shop", "cloud_orders"],
"requestsPerMinute": 60,
"callerIp": "185.0.0.10",
"checkAgainSeconds": 86400,
"serverTime": "2026-11-07T09:00:00Z"
}
200 OK — کلید نامعتبر
{
"valid": false,
"status": "no_subscription",
"message": "اشتراک این حساب پاتریس فعال نیست یا تمام شده است. برای تمدید با پشتیبانی پایاوا تماس بگیرید.",
"tenantName": null,
"keyName": null,
"validUntil": null,
"validUntilShamsi": null,
"scopes": [],
"requestsPerMinute": 0,
"callerIp": "185.0.0.10",
"checkAgainSeconds": 86400,
"serverTime": "2026-11-07T09:00:00Z"
}
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
valid | boolean | بله | کلید قابلاستفاده است یا نه. |
status | string | بله | یکی از valid، unknown_key، revoked، tenant_inactive، no_subscription، ip_not_allowed. |
message | string | بله | پیام فارسی قابلنمایش به مدیر سایت. |
tenantName | string | خیر | نام حساب پاتریس. فقط وقتی کلید معتبر است. |
keyName | string | خیر | نام کلید در پنل پاتریس. فقط وقتی کلید معتبر است. |
validUntil | string | خیر | آخرین روز اشتراک، با قالب yyyy-MM-dd. |
validUntilShamsi | string | خیر | آخرین روز اشتراک به تاریخ شمسی. |
scopes | string[] | بله | امکانات فعال حساب: shop، mypatris، cloud_orders. |
requestsPerMinute | integer | بله | سقف درخواست این کلید در دقیقه. |
callerIp | string | خیر | IP سرور سایت از دید سرور پاتریس. برای محدودیت IP به پشتیبانی اعلام کنید. |
checkAgainSeconds | integer | بله | فاصلهی پیشنهادی تا بررسی بعدی، به ثانیه (۸۶۴۰۰ یعنی یک روز). |
serverTime | string | بله | زمان سرور به UTC. |
کدهای خطا
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
400 | key_required | — | هدر X-Payava-Key ارسال نشده است. |
429 | rate_limited | — | تعداد درخواستهای این کلید در دقیقه از حد مجاز گذشته است. هدر Retry-After را ببینید. |
نکتهها
- روزی یک بار کافی است (
checkAgainSeconds). این endpoint را در هر درخواست کاربر صدا نزنید. - این فراخوانی هم از سقف درخواست کلید در دقیقه کم میکند.