#P1477
POST /countries-cities/get
Route Info
| Method |
Endpoint |
Controller |
Middleware |
Purpose |
| POST |
/api/v2/countries-cities/get |
V2BaseController@getCountiesOrCities |
authWithJwt |
دریافت لیست کشورها یا شهرها براساس نوع درخواست (`type`)، با امکان جستوجو و فیلتر وابسته به شناسه والد |
منطق عملکرد تابع
تابع
getCountiesOrCities مسئول واکشی اطلاعات جغرافیایی کشورها و شهرها است و رفتار آن براساس فیلد
type (مقدار
country یا
city) تغییر میکند:
- ابتدا مقدار
type بررسی میشود تا مشخص شود دادههای کشوری یا شهری باید خوانده شود.
- در صورت حضور
parent_id، فقط شهرهای مربوط به آن کشور واکشی میشوند.
- در صورت ارسال فیلد
search، شرط فیلتر با عملگر LIKE روی کلیدهای نامهای فارسی و انگلیسی اجرا میشود.
- نتیجه نهایی بهصورت آرایهای از اشیاء شامل شناسه، عنوان فارسی/انگلیسی و والد (در صورت وجود) بازگردانده میشود.
- در صورت خطا یا فقدان داده، پاسخ با وضعیت `status:false` و شرح خطا برگردانده میشود.
| نام فیلد |
نوع داده |
الزامی |
توضیح |
| type |
string |
بله |
مشخصکننده سطح داده مورد نیاز: مقدار country برای دریافت کشورها و city برای شهرها. |
| parent_id |
integer |
خیر |
در حالت city، شناسه کشور والد جهت محدودسازی نتایج. |
| search |
string |
خیر |
عبارت جستوجو جهت فیلتر نام شهر یا کشور. |
| branch |
integer |
بله |
شناسه شعبه برای اعتبارسنجی JWT و سطح دسترسی داده. |
نمونه درخواست:
POST /api/v2/countries-cities/get
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json
{
"type": "city",
"parent_id": 118,
"search": "تهران",
"branch": 5
}
خروجی (Response)
| فیلد |
نوع داده |
توضیح |
| status |
boolean |
وضعیت موفقیت عملیات |
| items[].id |
integer |
شناسه یکتای کشور یا شهر |
| items[].title.fa |
string |
نام فارسی کشور یا شهر |
| items[].title.en |
string |
نام انگلیسی کشور یا شهر |
| items[].category.title.fa |
string|null |
نام فارسی کشور والد (برای شهرها) |
| meta.timestamp |
integer |
زمان تولید پاسخ (یونیکس) |
نمونه پاسخ موفق:
{
"status": true,
"items": [
{
"id": 548,
"title": { "fa": "تهران", "en": "Tehran" },
"category": { "title": { "fa": "ایران", "en": "Iran" } }
}
],
"meta": { "timestamp": 1750668858 }
}
نمونه پاسخ خطا:
{
"status": false,
"error": { "code": 400, "message": "پارامتر type نامعتبر است." },
"meta": { "timestamp": 1750668869 }
}
نکات امنیتی
- اعتبارسنجی JWT از طریق middleware
authWithJwt انجام میشود.
- در صورت ارسال type=city، باید چک شود که شعبه کاربر مجاز به دسترسی داده کشور والد باشد.
- در نسخه فعلی کنترل سطح دسترسی برای cross-branch وجود ندارد و باید در Enterprise اضافه شود.
وابستگیها
- use Illuminate\Support\Facades\DB;
- use Illuminate\Http\Request;
- use Carbon\Carbon;
کدهای خطا
| کد |
شرح خطا |
منبع |
| 1006 |
توکن JWT منقضی یا نامعتبر |
authWithJwt |
| 1001 |
پارامتر type نامعتبر یا خالی است |
getCountiesOrCities() |
| 500 |
خطا در واکشی دادهها از پایگاهداده |
DB::table('countries') |
پیشنهادهای امنیتی
- اضافه کردن کنترل سطح شعبه برای جلوگیری از تزریق parent_id غیرمجاز.
- ثبت لاگ در SystemLog با نوع
ReadGeoData برای هر درخواست.
- افزودن rate-limit برای جلوگیری از دسترسی مکرر و حملات enumeration.
پیشنهادهای بهبود
- افزودن صفحهبندی (pagination) برای تعداد زیاد شهرها.
- پشتیبانی از پارامتر
locale برای ترجمه عنوانها بر اساس زبان کاربر.
- افزودن فیلد
iso_code برای کشورها جهت استانداردسازی.
ممیزی و لاگها
- لاگکردن درخواست هر کاربر شامل فیلدهای
operator_id، branch_id و type.
- سطح لاگ توصیهشده: Info.
جمعبندی
مسیر /countries-cities/get سازوکار اصلی دریافت دادههای جغرافیایی است. با وجود سادگی، نبود کنترل سطح دسترسی بین شعب میتواند نقطه ضعف امنیتی باشد. در نسخهٔ Enterprise لازم است مکانیزمهای cache و rate-limit، audit log و کنترل اعتبار parent_id حتماً فعال شوند تا پاسخ سریع و ایمن بماند.