پرش به مطلب اصلی

بررسی کلید با سرور پاتریس

سایت می‌تواند با POST /api/site/v1/verify از سرور پاتریس بپرسد کلیدش معتبر است یا نه. این فراخوانی اختیاری است و برای نمایش وضعیت اتصال در پنل مدیریت سایت به کار می‌رود.

چرا این فراخوانی اختیاری است؟​

اعتبار کلید، اشتراک و امکانات حساب را پاتریس یار خودش با سرور پاتریس بررسی می‌کند. سایت فقط کلید ارسالی پاتریس یار را با کلید خود مقایسه می‌کند. این endpoint به مدیر سایت کمک می‌کند خطاهایی مثل پایان اشتراک یا IP غیرمجاز را زودتر ببیند.

پیش‌نیازها​

  • کلید API حساب پاتریس.
  • دسترسی سرور سایت به سرور پاتریس.

Endpoint​

POST https://patrisyar.payava.com/api/site/v1/verify

هدرها​

نامنوعالزامیتوضیح
X-Payava-Keystringبلهکلید API حساب پاتریس.
Content-Typestringبلهapplication/json; charset=utf-8

پارامترها​

نامنوعالزامیتوضیح
siteUrlstringخیرآدرس اصلی سایت.
pluginVersionstringخیرنسخه‌ی پیاده‌سازی شما.

نمونه درخواست​

بررسی کلید
curl -X POST https://PATRIS_CLOUD_URL/api/site/v1/verify \
-H "X-Payava-Key: YOUR_API_KEY" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{"siteUrl":"https://shop.example.com","pluginVersion":"custom-1.0.0"}'

نمونه پاسخ موفق​

پاسخ همیشه 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"
}
نامنوعالزامیتوضیح
validbooleanبلهکلید قابل‌استفاده است یا نه.
statusstringبلهیکی از valid، unknown_key، revoked، tenant_inactive، no_subscription، ip_not_allowed.
messagestringبلهپیام فارسی قابل‌نمایش به مدیر سایت.
tenantNamestringخیرنام حساب پاتریس. فقط وقتی کلید معتبر است.
keyNamestringخیرنام کلید در پنل پاتریس. فقط وقتی کلید معتبر است.
validUntilstringخیرآخرین روز اشتراک، با قالب yyyy-MM-dd.
validUntilShamsistringخیرآخرین روز اشتراک به تاریخ شمسی.
scopesstring[]بلهامکانات فعال حساب: shop، mypatris، cloud_orders.
requestsPerMinuteintegerبلهسقف درخواست این کلید در دقیقه.
callerIpstringخیرIP سرور سایت از دید سرور پاتریس. برای محدودیت IP به پشتیبانی اعلام کنید.
checkAgainSecondsintegerبلهفاصله‌ی پیشنهادی تا بررسی بعدی، به ثانیه (۸۶۴۰۰ یعنی یک روز).
serverTimestringبلهزمان سرور به UTC.

کدهای خطا​

نامنوعالزامیتوضیح
400key_required—هدر X-Payava-Key ارسال نشده است.
429rate_limited—تعداد درخواست‌های این کلید در دقیقه از حد مجاز گذشته است. هدر Retry-After را ببینید.

نکته‌ها​

  • روزی یک بار کافی است (checkAgainSeconds). این endpoint را در هر درخواست کاربر صدا نزنید.
  • این فراخوانی هم از سقف درخواست کلید در دقیقه کم می‌کند.