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

مسیرها و احراز هویت

همه‌ی درخواست‌های پاتریس یار به سایت شما زیر مسیر ثابت /patris-yar ارسال می‌شوند و کلید API در هدر X-Payava-Key می‌آید. سایت باید پیش از هر کاری این کلید را با کلید ذخیره‌شده‌ی خود مقایسه کند.

مسیرها کجا قرار می‌گیرند؟​

در اتصال «سایت اختصاصی (REST API)» پاتریس یار، آدرس سایت (یا آدرس API) را در فیلد «آدرس API» وارد می‌کنید. پاتریس یار پیشوند ثابت /patris-yar و بعد مسیر هر endpoint را به انتهای این آدرس اضافه می‌کند:

آدرس واردشده: https://shop.example.com
GET https://shop.example.com/patris-yar/ping
GET https://shop.example.com/patris-yar/orders?limit=50
POST https://shop.example.com/patris-yar/products
آدرس واردشده: https://shop.example.com/api
GET https://shop.example.com/api/patris-yar/ping
GET https://shop.example.com/api/patris-yar/orders?limit=50
  • پیشوند /patris-yar ثابت است تا مسیرهای پاتریس یار با مسیرهای خود سایت (مثل /orders یا /products) تداخل نداشته باشند.
  • اگر آدرس واردشده خودش با /patris-yar تمام شود، پاتریس یار آن را دوباره اضافه نمی‌کند.
  • اگر آدرس را بدون https:// وارد کنید، پاتریس یار https:// را فرض می‌کند. / انتهای آدرس حذف می‌شود.
  • در ادامه‌ی مستندات، آدرس واردشده https://shop.example.com فرض شده است.

کلید API چیست و از کجا می‌آید؟​

کلید را پشتیبانی پایاوا برای حساب پاتریس شما می‌سازد و فقط یک بار نمایش داده می‌شود. قالب آن ppk_ و پس از آن ۴۰ حرف و عدد انگلیسی است:

نمونه‌ی قالب کلید
X-Payava-Key: ppk_YOUR_API_KEY_40_CHARACTERS_XXXXXXXXXXXX
  • همین کلید را هم در تنظیمات سایت و هم در پاتریس یار وارد می‌کنید.
  • سایت فقط کلید دریافتی را با کلید ذخیره‌شده مقایسه می‌کند. اعتبار کلید، اشتراک و امکانات حساب را پاتریس یار با سرور پاتریس بررسی می‌کند.
  • کلید را در متغیر محیطی یا فایل تنظیمات بیرون از مخزن کد نگه دارید و هرگز در log ننویسید.

سایت کلید را چطور بررسی کند؟​

هدرها​

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

قواعد بررسی​

  • اگر کلیدی در سایت ذخیره نشده یا هدر خالی است، پاسخ 401 بدهید.
  • مقایسه را با تابع زمان-ثابت (constant-time) انجام دهید تا کلید با حمله‌ی زمانی حدس زده نشود.
  • پاسخ خطا را با قالب code و message برگردانید. جزئیات در قالب خطاها.

نمونه‌کد​

نمونه‌های زیر پایه‌ی همه‌ی صفحه‌های بعدی هستند. در هر صفحه فقط handler همان endpoint آمده و فرض شده این پایه وجود دارد. متغیر store لایه‌ی داده‌ی خود شماست.

تست کلید با curl
curl -i https://shop.example.com/patris-yar/ping \
-H "X-Payava-Key: YOUR_API_KEY"

مسیر را در وب‌سرور چطور به برنامه برسانم؟​

اگر سایت پشت Apache یا Nginx است، مسیر /patris-yar/ باید به برنامه‌ی شما برسد. برای نمونه‌ی PHP بالا:

.htaccess (Apache)
RewriteEngine On
RewriteRule ^patris-yar/ payava-patris.php [L,QSA]
nginx
location /patris-yar/ {
try_files $uri /payava-patris.php?$query_string;
}

نکته‌ها​

دسترسی از رایانه‌ی فروشگاه

درخواست‌ها از IP اینترنت رایانه‌ی فروشگاه می‌آیند که معمولاً ثابت نیست. محدودیت IP روی این مسیر نگذارید، مگر IP ثابت داشته باشید. فایروال یا CDN هم نباید درخواست‌های بدون مرورگر (مثلاً با چالش JavaScript) را مسدود کند.

  • مهلت هر درخواست در پاتریس یار ۱۲۰ ثانیه است.
  • همیشه از HTTPS استفاده کنید. کلید در هر درخواست ارسال می‌شود.