#P1485
GET /api/v2/base/certificate
Route Info
| Method |
Endpoint |
Controller |
Middleware |
Purpose |
| GET |
/api/v2/base/certificate |
V2BaseController@showCertificate |
authWithJwt |
واکشی مشخصات گواهینامهی خاص بر اساس id و شعبه کاربر. |
منطق عملکرد تابع
تابع showCertificate دادهی یک گواهینامه خاص را از جدول certificates واکشی میکند. ورودیهای branch از JWT و id از Request دریافت میشود. سپس فیلدهای غیرضروری (مانند created_at، updated_at و branch) از خروجی حذف میشوند و شیء نهایی در قالب کلید payload به کاربر برگردانده میشود.
| نام پارامتر |
نوع داده |
منبع |
الزامی |
توضیح |
| branch |
integer |
JWT / Header |
بله |
شناسه شعبه کاربر. |
| id |
integer |
Query / Body |
بله |
شناسه گواهینامه موردنظر برای نمایش جزئیات آن. |
نمونه درخواست:
GET /api/v2/base/certificate?id=129
Authorization: Bearer {JWT_TOKEN}
خروجی (Response)
| فیلد |
نوع داده |
توضیح |
| payload.id |
integer |
شناسه گواهینامه. |
| payload.title |
string |
عنوان گواهینامه. |
| payload.license_number |
string |
شماره مجوز یا سریال گواهینامه. |
| payload.exporter |
string |
نهاد صادرکننده گواهی. |
| payload.expiration |
string|date |
تاریخ انقضای گواهی. |
| payload.document |
string |
مسیر فایل پیوست (تصویر یا PDF) در Storage. |
| payload.content |
string |
محتوای متنی گواهی در صورت وجود. |
| meta.timestamp |
integer |
زمان سیستم در لحظه پاسخ. |
نمونه پاسخ:
{
"meta": {
"timestamp": 1750669255
},
"payload": {
"id": 129,
"title": "مجوز درجه دو",
"license_number": "LIC-2025-23",
"exporter": "وزارت گردشگری ایران",
"expiration": "2025-12-30",
"document": "media/certificates/license.png",
"content": null,
"description": "گواهی معتبر رزرو اقامتگاه سطح دو."
}
}
نکات امنیتی
- احراز هویت با JWT الزامی است.
- فیلتر روی
branch باعث جلوگیری از دسترسی بینشعبهای میشود.
- فایل یا مسیر سند مستقیماً ارسال نمیشود، تنها مسیر کنترلشده برمیگردد.
- کوئری ساده با خروجی مستقیم و بدون Join.
- بدلیل درخواست تکی، نیاز به Cache Redis ندارد (اما قابل پیادهسازی با TTL 2m).
- پاسخ JSON سبک و بدون سربار پردازشی است.
وابستگیها
- use Illuminate\Support\Facades\DB;
- use Exception;
- use Illuminate\Http\Request;
- use Illuminate\Support\Facades\Response;
کدهای خطا
| کد |
شرح خطا |
منبع |
| 400 |
خطا در اجرای کوئری یا Exception داخلی. |
Catch(Exception) |
| 404 |
گواهینامه با این شناسه یافت نشد. |
DB::first() |
پیشنهادهای امنیتی
- افزودن بررسی مجاز بودن نقش کاربر (
can('view_certificate')).
- رمزنگاری مسیر فایل
document در Storage.
- اعمال Rate Limiting در سطح IP برای جلوگیری از Brute Force روی idها.
پیشنهادهای بهبود
- افزودن پارامتر
preview=true برای نمایش تصویر بندانگشتی.
- افزودن فیلد نسخهگذاری در گواهینامهها جهت History Tracking.
- اتصال سیستم هشدار انقضا به کنترلر Dashboard.
ممیزی و لاگها
- نوع لاگ پیشنهادی:
ReadCertificateDetails.
- شامل فیلدهای:
operator_id، branch، certificate_id.
- سطح لاگ: Info.
جمعبندی
این مسیر برای واکشی دقیق اطلاعات هر گواهینامه طراحی شده و پاسخ سبک و تمیز JSON با کلید payload ارائه میدهد. برای افزایش امنیت و مقیاسپذیری، در نسخه آینده پیشنهاد میشود RBAC و Cache Redis اضافه گردد.
