مسیرها و احراز هویت
همهی درخواستهای پاتریس یار به سایت شما زیر مسیر ثابت /patris-yar ارسال میشوند و کلید API در هدر X-Payava-Key میآید. سایت باید پیش از هر کاری این کلید را با کلید ذخیرهشدهی خود مقایسه کند.
مسیرها کجا قرار میگیرند؟
در اتصال «سایت اختصاصی (REST API)» پاتریس یار، آدرس سایت (یا آدرس API) را در فیلد «آدرس API» وارد میکنید. پاتریس یار پیشوند ثابت /patris-yar و بعد مسیر هر endpoint را به انتهای این آدرس اضافه میکند:
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
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-Key | string | بله | کلید API حساب پاتریس. باید دقیقاً با کلید ذخیرهشده در سایت برابر باشد. |
Content-Type | string | برای POST | پاتریس یار بدنه را با application/json; charset=utf-8 و بدون فشردهسازی میفرستد. |
قواعد بررسی
- اگر کلیدی در سایت ذخیره نشده یا هدر خالی است، پاسخ
401بدهید. - مقایسه را با تابع زمان-ثابت (constant-time) انجام دهید تا کلید با حملهی زمانی حدس زده نشود.
- پاسخ خطا را با قالب
codeوmessageبرگردانید. جزئیات در قالب خطاها.
نمونهکد
نمونههای زیر پایهی همهی صفحههای بعدی هستند. در هر صفحه فقط handler همان endpoint آمده و فرض شده این پایه وجود دارد. متغیر store لایهی دادهی خود شماست.
- curl
- C#
- Python
- PHP
- Node.js
- Go
curl -i https://shop.example.com/patris-yar/ping \
-H "X-Payava-Key: YOUR_API_KEY"
using System.Security.Cryptography;
using System.Text;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<IShopStore, ShopStore>(); // your data layer
var app = builder.Build();
var patris = app.MapGroup("/patris-yar")
.AddEndpointFilter(async (ctx, next) =>
{
var expected = app.Configuration["Patris:ApiKey"] ?? "";
var given = ctx.HttpContext.Request.Headers["X-Payava-Key"].ToString();
var ok = expected.Length > 0 &&
CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(expected), Encoding.UTF8.GetBytes(given));
if (!ok)
return Results.Json(new { code = "payava_patris_unauthorized", message = "Invalid API key" }, statusCode: 401);
return await next(ctx);
});
// patris.MapGet("/ping", ...); // see the next pages
app.Run();
import hmac
import os
from fastapi import APIRouter, Depends, FastAPI, Header, Request
from fastapi.responses import JSONResponse
API_KEY = os.environ.get("PATRIS_API_KEY", "")
class PatrisAuthError(Exception):
pass
def require_key(x_payava_key: str = Header(default="")):
if not API_KEY or not hmac.compare_digest(API_KEY.encode(), x_payava_key.encode()):
raise PatrisAuthError()
app = FastAPI()
@app.exception_handler(PatrisAuthError)
async def on_auth_error(request: Request, exc: PatrisAuthError):
return JSONResponse({"code": "payava_patris_unauthorized", "message": "Invalid API key"}, status_code=401)
router = APIRouter(prefix="/patris-yar", dependencies=[Depends(require_key)])
# @router.get("/ping") ... see the next pages
app.include_router(router) # after all routes are added
<?php
declare(strict_types=1);
header('Content-Type: application/json; charset=utf-8');
function respond(int $status, array $body): never
{
http_response_code($status);
echo json_encode($body, JSON_UNESCAPED_UNICODE);
exit;
}
function json_body(): array
{
$data = json_decode(file_get_contents('php://input') ?: '', true);
return is_array($data) ? $data : [];
}
$expected = (string) getenv('PATRIS_API_KEY');
$given = (string) ($_SERVER['HTTP_X_PAYAVA_KEY'] ?? '');
if ($expected === '' || !hash_equals($expected, $given)) {
respond(401, ['code' => 'payava_patris_unauthorized', 'message' => 'Invalid API key']);
}
$prefix = '/patris-yar';
$path = (string) parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
$route = '/' . trim(substr($path, strpos($path, $prefix) + strlen($prefix)), '/');
$method = $_SERVER['REQUEST_METHOD'];
$store = new ShopStore(); // your data layer
// if ($method === 'GET' && $route === '/ping') { ... } see the next pages
respond(404, ['code' => 'rest_no_route', 'message' => 'No route was found']);
const crypto = require('crypto');
const express = require('express');
const store = require('./store'); // your data layer
const app = express();
app.use(express.json({ limit: '20mb' })); // product batches can be large
const API_KEY = process.env.PATRIS_API_KEY || '';
function requireKey(req, res, next) {
const given = Buffer.from(req.get('X-Payava-Key') || '');
const expected = Buffer.from(API_KEY);
if (!expected.length || given.length !== expected.length || !crypto.timingSafeEqual(given, expected)) {
return res.status(401).json({ code: 'payava_patris_unauthorized', message: 'Invalid API key' });
}
next();
}
const router = express.Router();
router.use(requireKey);
// router.get('/ping', ...) see the next pages
app.use('/patris-yar', router);
app.listen(3000);
package main
import (
"crypto/subtle"
"encoding/json"
"net/http"
"os"
)
const base = "/patris-yar"
var apiKey = os.Getenv("PATRIS_API_KEY")
func writeJSON(w http.ResponseWriter, status int, v any) {
w.Header().Set("Content-Type", "application/json; charset=utf-8")
w.WriteHeader(status)
json.NewEncoder(w).Encode(v)
}
func requireKey(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
given := r.Header.Get("X-Payava-Key")
if apiKey == "" || subtle.ConstantTimeCompare([]byte(apiKey), []byte(given)) != 1 {
writeJSON(w, http.StatusUnauthorized, map[string]string{"code": "payava_patris_unauthorized", "message": "Invalid API key"})
return
}
next.ServeHTTP(w, r)
})
}
func main() {
patris := http.NewServeMux()
// patris.HandleFunc("GET "+base+"/ping", ping) see the next pages
root := http.NewServeMux()
root.Handle(base+"/", requireKey(patris))
http.ListenAndServe(":8080", root)
}
مسیر را در وبسرور چطور به برنامه برسانم؟
اگر سایت پشت Apache یا Nginx است، مسیر /patris-yar/ باید به برنامهی شما برسد. برای نمونهی PHP بالا:
RewriteEngine On
RewriteRule ^patris-yar/ payava-patris.php [L,QSA]
location /patris-yar/ {
try_files $uri /payava-patris.php?$query_string;
}
نکتهها
درخواستها از IP اینترنت رایانهی فروشگاه میآیند که معمولاً ثابت نیست. محدودیت IP روی این مسیر نگذارید، مگر IP ثابت داشته باشید. فایروال یا CDN هم نباید درخواستهای بدون مرورگر (مثلاً با چالش JavaScript) را مسدود کند.
- مهلت هر درخواست در پاتریس یار ۱۲۰ ثانیه است.
- همیشه از HTTPS استفاده کنید. کلید در هر درخواست ارسال میشود.