API.php

• POST /api/auth/connect/branch
• POST /api/v2/colleagues/billing
• POST /api/v2/trade/national
• POST /api/auth/sign-in
• POST /api/auth/update
• POST /api/auth/blocking
• POST /api/auth/forgot/otp
• POST /api/auth/connect/otp
• POST /api/auth/connect/submit
• POST /api/auth/forgot/submit
• POST /api/auth/access-token
• GET /api/v2/notifications
• GET /api/v2/exam/get
• POST /api/v2/exam/response
• POST /api/v2/trade/list
• POST /api/v2/trade/search
• POST /api/v2/trade/cost-benefit
• POST /api/v2/references/{type}/list
• POST /api/v2/trade/store
• POST /api/v2/trade/edit
• POST /api/v2/trade/item/edit
• POST /api/v2/trade/item/add
• POST /api/v2/trade/item/delete
• POST /api/v2/trade/item/value_added
• POST /api/v2/trade/operation
• POST /api/v2/trade/operation/general
• POST /api/v2/trade/refund/update
• POST /api/v2/trade/refund/delete
• POST /api/v2/trade/statement
• POST /api/v2/trade/request
• POST /api/v2/trade/commitment
• POST /api/v2/trade/commitment/submit
• POST /api/v2/trade/payment-receipt
• POST /api/v2/logs
• POST /api/v2/pledger/store
• POST /api/v2/pledger/update
• POST /api/v2/pledger/delete
• POST /api/v2/purchases/list
• PUT /api/v2/purchase/retry/{id}
• GET /api/v2/flights/approved-rate
• POST /api/v2/operator/update-password
• POST /api/v2/passengers/search
• POST /api/v2/passenger/add-branch
• POST /api/v2/get_country
• POST /api/v2/get_other_services
• POST /api/v2/get_visa_country
• POST /api/v2/customers/list
• GET /api/v2/cartable/categories
• GET /api/v2/cartable/requests/list
• POST /api/v2/cartable/request/operation
• GET /api/v2/calendar
• POST /api/v2/personnel/traffic/store
• POST /api/v2/personnel/traffic/update
• DELETE /api/v2/personnel/traffic/delete
• POST /api/v2/personnel/traffic/license/store
• POST /api/v2/personnel/traffic/license/update
• DELETE /api/v2/personnel/traffic/license/delete
• GET /api/v2/passenger/profile
• POST /api/v2/passenger/store
• POST /api/v2/passenger/update
• POST /api/v2/passenger/delete
• POST /api/v2/auth/by
• POST /api/v2/auth/connect/disconnect
• POST /api/v2/operator/store
• POST /api/v2/operator/update
• GET /api/v2/operator/get
• GET /api/v2/online/reservation/list
• GET /api/v2/online/reservation/penalty
• POST /api/v2/online/reservation/refund
• POST /api/v2/online/credit
• POST /api/v2/online/credit/update
• POST /api/v2/online/reservation/penalty
• Route: POST /api/v2/online/{type}/lock
• Route: POST /api/v2/online/search/{type}
• Route: POST /api/v2/online/flight/list/date
• Route: POST /api/v2/online/{type}/unlock
• Route: POST /api/v2/online/{type}/status
• Route: GET /api/v2/online/accommodation/list
• GET /api/v2/online/accommodation/get_min_prices
• GET /api/v2/online/accommodation/get_room_type_prices
• GET /api/v2/online/accommodation/get_details
• * POST /api/v2/online/accommodation/check_status
• GET /api/v2/base/data
• POST /api/v2/titles/list
• POST /api/v2/notif/simple/list
• POST /api/v2/notif/send
• POST /api/v2/dashboard
• POST /api/v2/operator/details
• POST /api/v2/management/office
• GET /api/v2/panel/groups/get
• GET /api/v2/panel/bulk/receptions
• POST /api/v2/panel/bulk/add
• POST /countries-cities/get
• GET /api/v2/settings/index/{type}
• PUT /settings/index/{type}
• GET /base/accommodations/list
• POST /base/accommodation/rooms/delete
• POST /base/accommodation/room/update
• GET /api/v2/base/certificates
• DELETE /api/v2/base/certificate
• GET /api/v2/base/certificate
• POST /api/v2/base/certificate
• PUT /api/v2/base/certificate
• POST /api/v2/accommodations/list
• POST /credit-debit/list
• POST /credit-debit/summary
• POST /pay/store
• POST /pay/update
• DELETE /pay/trash
• POST /gateway/list
• POST /financial/items
• POST /check/list
• POST /check/store
• POST /check/operation
• POST /check/operation/update
• POST /financial/treeview
• POST /accounting/balance
• POST /announcement/list
• POST /announcement/list/company
• POST /announcement/edit
• POST /announcement/store
• POST /announcement/update
• POST /announcement/view
• POST /announcement/statement
• POST /announcement/ledger
• POST /announcement/calculation
• POST /gateway/invoice/{drive}
• POST /gateway/invoice/{drive}/verify
• POST /api/v2/gateway/details
• POST /colleagues/list
• POST /colleague/bill
• POST /colleagues/ledger-accounts
• POST /colleagues/update/financial
• POST /colleagues/update/general-billing
• POST /colleague/operation
• GET /colleague/get
• GET /colleague/search
• GET /colleague/user
• PUT /colleague/user
• POST /colleague/user
• DELETE /colleague/user
• POST /upload
• GET /asterisk/test-connection
• GET /asterisk/channels/active
• GET /asterisk/channel/status
• POST /asterisk/call/make
• POST /asterisk/call/hangup
• POST /asterisk/sms/send
• POST /asterisk/ussd/send
• POST /asterisk/action/execute
• GET /asterisk/websocket/test
• POST /asterisk/notification/test
• POST /upload/s3
• DELETE /media/s3
• GET /personnel/attendance
• POST /personnel/attendance
• GET /personnel/attendance/permission
• POST /personnel/list
• POST /personnel/bill
• POST /personnel/operation
• GET /personnel/access-list
• GET /personnel
• POST /personnel
• PUT /personnel
• GET /personnel/shift/list
• GET /personnel/shift
• POST /personnel/shift
• PUT /personnel/shift
• DELETE /personnel/shift
• * PATCH /personnel/shift/reset
• POST /api/v2/tasks/category/operation
• GET /api/v2/tasks/categories/list
• GET /api/v2/tasks/list
• POST /api/v2/tasks/task/operation
• GET /api/v2/tasks/task/details
• GET /api/v2/support/departments/list
• GET /api/v2/support/department/members
• GET /api/v2/support/department/questions/list
• GET /api/v2/support/tickets
• POST /api/v2/support/ticket/update
• PATCH /api/v2/support/ticket/notice
• GET /api/v2/support/ticket/notes/list
• DELETE /api/v2/support/ticket/delete
• GET /api/v2/exams/list
• PATCH /api/v2/exams/answers/list/follow-up
• GET /api/v2/exams/answers/evaluation
• GET /api/v2/salary/annual-obligation
• GET /api/v2/scheduled/notifications
• POST /api/v2/scheduled/notifications
• PUT /api/v2/scheduled/notifications
• POST /api/v2/banks/list
• POST /v2/account/bill
• POST /v2/account/bill2
• POST /v2/currencies/list
• POST /v2/accounts/list
• GET /v2/accounting/account
• POST /v2/accounting/account
• PUT /v2/accounting/account
• DELETE /v2/accounting/account
• GET /v2/wallet/balance
• POST /v2/wallet/check
• GET /v2/wallet/transactions
• POST /v2/accounting/connections/store
• POST /v2/accounting/connections/update
• POST /v2/accounting/connections/trash
• POST /v2/accounting/connections/trash
• POST /v2/accounting/connections/view
• POST /v2/accounting/connections/merge
• POST /v2/accounting/connections/list
• POST /v2/accounting/account/update
• GET /v2/accounting/account/get
• POST /v2/manual-document/update
• DELETE /v2/manual-document
• POST /v2/manual-document/list
• POST /v2/manual-document/view
• POST /v2/manual-document/get
• POST /v2/manual-document/list/{type}
• POST /v2/manual-document/preferences/list/details
• GET /v2/accounting/closing
• POST /v2/accounting/closing
• PUT /v2/accounting/closing/definite/{type}
• GET /v2/accounting/preference
• POST /v2/accounting/preference
• GET /v2/accounting/preference/{id}
• PUT /v2/accounting/preference/{id}
• POST /v2/account-history/calculate-daily
• POST /v2/account-history/calculate-monthly
• POST /v2/account-history/calculate-complete
• GET /v2/account-history/daily
• GET /v2/account-history/monthly
• GET /v2/account-history/all-daily
• GET /v2/account-history/all-monthly
• DELETE /v2/account-history/cache
• POST /v2/redis-accounting/create-missing-documents
• POST /v2/redis-accounting/create-missing-documents
• POST /v2/redis-accounting/create-missing-documents
• POST /v2/redis-accounting/save-manual-document
• POST /v2/redis-accounting/save-document
• DELETE /v2/redis-accounting/delete-document
• DELETE /v2/redis-accounting/clear-all
• GET /v2/redis-accounting/documents/subsidiary
• GET /v2/redis-accounting/documents/account
• GET /v2/redis-accounting/documents/general
• GET /v2/redis-accounting/documents/group
• GET /v2/redis-accounting/documents/group
• GET /v2/redis-accounting/documents/date-range
• GET /v2/redis-accounting/balance
• GET /v2/redis-accounting/stats
• POST /v2/batch-accounting/process/date-range
• POST /v2/batch-accounting/process/month
• POST /v2/batch-accounting/process/month
• POST /v2/batch-accounting/process/year
• POST /v2/batch-accounting/process/current-month
• POST /v2/batch-accounting/process/current-year
• POST /v2/batch-accounting/rebuild-indexes
• POST /v2/batch-accounting/optimize-memory
• GET /v2/batch-accounting/report/comprehensive
• POST /v2/batch-accounting/preview
• POST /v2/core/offices/list
• POST /v2/core/accommodations/list
• POST /v2/core/accommodation/store
• POST /v2/core/accommodation/update
• DELETE /v2/core/accommodation/delete
• GET /v2/core/accommodation/view
• POST /v2/core/accommodation/supplier/store
• POST /v2/core/airlines/list
• POST /v2/core/airports/list
• POST /v2/core/socket/send
• GET /v2/core/changelogs
• GET /v2/core/accommodation/view
• POST /v2/core/system/report
• GET /v2/charter (Multi‑Mode Charter Loader)
• POST /v2/charter
• PUT /v2/charter
• PATCH /v2/charter (updateCharter)
• DELETE /v2/charter
• GET /v2/charter/list
• GET /v2/charter/communications
• GET /v2/charter/reservation/{type}
• POST /v2/charter/reservation
• PUT /v2/charter/reservation
• DELETE /v2/charter/reservation
• PATCH /v2/charter/reservation/undo
• PUT /v2/charter/reservation/transfer
• PATCH /character/reservation/refund
• PATCH /v2/charter/reservation/refund/undo
• DELETE /v2/charter/reservation/temporary
• POST /v2/charter/reservation/temporary
• POST /v2/charter/reservation/plan/update
• GET /v2/charter/financial
• GET /v2/charter/financial/completion
• PATCH /v2/charter/financial/completion
• POST /v2/charter/warranty
• GET /v2/charter/warranty
• GET /v2/charter/services/list
• GET /v2/charter/flight-rate
• GET /v2/charter/pledger
• POST /v2/charter/pledger
• POST /v2/charter/accommodation/rooms
• POST /v2/charter/accommodation/rooms/access
• GET /v2/academy/categories/view
• GET /v2/academy/courses/view
• GET /v2/academy/course/steps/view
• POST /v2/academy/course/steps/update
• GET /v2/mail/servers/list
• GET /v2/mail/address/list
• POST /v2/mail/address/store
• GET /v2/mail/{type}/list
• POST /v2/mail/{type}/update
• POST /v2/mail/attachments/download
• GET /v2/mail/sent/get
• POST /v2/mail/sent/store
• DELETE /v2/mail/sent/trash
• GET /v2/mail/inbox/get
• GET /v2/mail/inbox/get
• DELETE /v2/mail/inbox/trash
• DELETE /v2/mail/trash/delete
• GET /v2/modules/lottery/registrations
• POST /v2/trade/tickets
• POST /v2/trade/contract
• POST /v2/trade/confirmation
• POST /v2/credit-card
• GET /v2/credit-card/index
• GET /v2/credit-card
• POST /v2/articles/{id}/views
• RESOURCE /v2/articles
• RESOURCE /v2/categories
• RESOURCE /v2/tags
• RESOURCE /v2/landing_pages
• RESOURCE /v2/page_metatags
• RESOURCE /v2/places
• RESOURCE /v2/media
• GET /v2/travel_requests
• POST /v2/travel_requests/status/{id}
• RESOURCE /v2/accommodation/facilities
• RESOURCE /v2/accommodation/facilities_category
• RESOURCE /v2/accommodation/rules
• GET /v2/comments
• GET /v2/comments/{id}
• DELETE /v2/comments/{id}
• POST /v2/comments
• PUT /v2/comments/{id}
• POST /v2/comments/{commentId}/{action}
• DELETE /v2/comments/{commentId}/{action}
• POST /v2/invoice/process
• POST /v2/invoice/payment/details
• POST /v2/invoice/payment/wallet
• GET /v2/core/bill/{type}
• GET /v2/core/hub/information
• GET /v2/core/hub/analyze
• GET /v2/core/hub/reservation
• POST /v2/core/hub/reservation
• PATCH /v2/core/hub/reservation/refund
• PATCH /v2/core/hub/reservation/refund/undo
• POST /v2/flights/ticket/information/{type}
• POST /v2/flights/routes/update
• POST /v2/flights/routes/min_price
• GET /v2/core/application_interface
• GET /v2/core/application_interface/{id}
• DELETE /v2/core/application_interface/{id}
• POST /v2/core/application_interface
• PUT /v2/core/application_interface/{id}
• GET /v2/core/application_interface_types
• GET /v2/core/application_interface_services
• GET /v2/core/application_interface_object_types
• PUT /v2/core/application_interface/status/{id}
• RESOURCE /v2/scrumboard/boards
• RESOURCE /v2/scrumboard/lists
• RESOURCE /v2/scrumboard/labels
• RESOURCE /v2/scrumboard/checklists
• RESOURCE /v2/scrumboard/comments
• RESOURCE /v2/scrumboard/cards
• RESOURCE /v2/scrumboard/sprints
• RESOURCE /v2/scrumboard/sprint_reports
• RESOURCE /v2/cartable/letters
• RESOURCE /v2/cartable/subjects
• RESOURCE /v2/cartable/subject_steps
• RESOURCE /v2/cartable/recipients
• RESOURCE /v2/cartable/operator_role
• PUT /v2/cartable/letters/step/{id}
• POST /v2/ai/chat/completions
• POST /v2/trade/reference/type
• POST /v2/base/reference
• POST /v2/config
• GET /v2/config
• GET /b2c/v1/config
• POST /b2c/v1/auth/otp
• POST /b2c/v1/auth/submit
• POST /b2c/v1/auth/basic
• POST /b2c/v1/get_country
• GET /b2c/v1/user/passengers
• GET /b2c/v1/office/users
• GET /b2c/v1/cost-center/list/form
• GET /b2c/v1/credit-card
• POST /b2c/v1/media/upload/s3
• GET /b2c/v1/base/data
• GET /b2c/v1/base/accommodations/list
• GET /b2c/v1/base/suggestions/items/{type}
• GET /b2c/v1/trade/list
• POST /b2c/v1/trade/store
• POST /b2c/v1/trade/completion
• POST /b2c/v1/online/search/{type}
• POST /b2c/v1/online/{type}/lock
• POST /b2c/v1/online/{type}/penalty
• POST /b2c/v1/online/{type}/refund
• GET /b2c/v1/online/accommodation/list
• GET /b2c/v1/online/accommodation/get_min_prices
• GET /b2c/v1/online/accommodation/get_room_type_prices
• GET /b2c/v1/online/accommodation/get_details
• GET /b2c/v1/online/flight/class/{calculation_id}
• GET /b2c/v1/online/payment/flight/tracking
• GET /b2c/v1/financial/list
• GET /b2c/v1/passengers/previous
• GET /b2c/v1/gateway/details
• GET /b2c/v1/discount/submit
• GET /b2c/v1/discount/unsubmit
• GET /b2c/v1/wallet/ballance
• POST /b2c/v1/wallet/credit
• GET /b2c/v1/ledger-account
• GET /b2c/v1/articles
• GET /b2c/v1/articles/{article}
• GET /b2c/v1/categories
• POST /b2c/v1/articles/{id}/views
• RESOURCE /b2c/v1/travel_requests

POST /api/auth/connect/branch

Route Info

تحلیل عملکرد (Analysis)

این Endpoint یک نقطه ورود بدون احراز هویت (Unauthenticated) برای شناسایی و اعتبارسنجی شعبه است. هدف آن، بازگرداندن دامنه محیطی شعبه معتبر می‌باشد.

مکانیزم کدگذاری شعبه

سیستم از فرمول زیر برای استخراج شناسه واقعی شعبه از کد ارسالی استفاده می‌کند:

Actual Office ID = Input Branch Code - 1000

برای مثال اگر کد ورودی 1050 باشد، شناسه واقعی شعبه 50 خواهد بود.

منطق اعتبارسنجی

ورودی‌ها (Inputs)

Example Request Body:

{
  "branch": 1050
}

خروجی‌ها (Outputs)

پاسخ همیشه HTTP 200 بازمی‌گردد.

خروجی موفق:

فیلد	نوع داده	توضیح
status	Boolean	همیشه true
time	Integer	زمان یونیکس پاسخ سرور
data.domain	String	دامنهٔ مرتبط با شعبه

{
  "status": true,
  "time": 1731324000,
  "data": {
    "domain": "example.com"
  }
}

خروجی ناموفق:

{
  "status": false,
  "code": 1201,
  "message": "کد دسترسی نا معتبر می باشد."
}

وابستگی‌ها (Dependencies)

تست و استفاده (Testing & Usage)

Example cURL:

curl -X POST https://yourdomain.com/api/auth/connect/branch \
  -H "Content-Type: application/json" \
  -d '{"branch":1050}'

موارد خطا (Typical Error Cases)

جزئیات پیاده‌سازی (Conceptual Implementation)

$branch = $request->get('branch');
$code = $branch - 1000;

$office = DB::table('offices')
    ->where('id', $code)
    ->where('status', 1)
    ->select('domain')
    ->first();

if ($office) {
    return response()->json([
        'status' => true,
        'time' => now()->timestamp,
        'data' => [ 'domain' => json_decode($office->domain)[0] ],
    ]);
}
return response()->json([
    'status' => false,
    'code'   => 1201,
    'message'=> 'کد دسترسی نا معتبر می باشد.'
]);

نتیجه نهایی (Conclusion)

این Endpoint بدون نیاز به توکن احراز هویت، دامنه شعبه را تعیین می‌کند. طراحی آن ساده و سریع بوده و پایهٔ احراز در سایر سرویس‌های connectOtp و connectSubmit می‌باشد.

پیوست: نگهداری و امنیت

POST /api/v2/colleagues/billing

Route Info

(Analysis) تحلیل عملکرد

مکانیسم کدگذاری شعبه

Actual Office ID = Input Branch Code - 1000
  

منطق اعتبارسنجی

(Inputs) ورودی‌ها

{
  "branch": 1050
}
  

(Outputs) خروجی‌ها

خروجی موفق:

{
  "status": true,
  "office": {
    "id": 50,
    "domain": "example.domain.ir",
    "title": "دفتر مرکزی"
  }
}
  

خروجی ناموفق:

{
  "status": false,
  "message": "کد شعبه معتبر نیست یا یافت نشد."
}
  

(Dependencies) وابستگی‌ها

(Testing & Usage) تست و استفاده

POST /api/auth/connect/branch
Content-Type: application/json

{
  "branch": 1050
}
  

(Typical Error Cases) موارد خطا

(Implementation Details) جزئیات پیاده‌سازی

public function connectBranch(Request $request)
{
    $branchCode = $request->branch;
    $actualId = $branchCode - 1000;
    $office = Office::find($actualId);

    if (!$office) {
        return response()->json(['status' => false, 'message' => 'کد شعبه معتبر نیست یا یافت نشد.']);
    }

    return response()->json([
        'status' => true,
        'office' => [
            'id' => $office->id,
            'domain' => $office->domain,
            'title' => $office->title,
        ]
    ]);
}
  

(Conclusion) نتیجه‌گیری

(Appendix) پیوست: نگهداری و امنیت

POST /api/v2/trade/national

Route Info

تحلیل عملکرد (Analysis)

مکانیزم شناسایی شهر

SELECT * FROM cities WHERE national_prefix LIKE '%123%' LIMIT 1;
  

منطق اعتبارسنجی کد ملی

ورودی‌ها (Inputs)

{
  "code": "0451234567"
}
  

خروجی‌ها (Outputs)

خروجی موفق (شهر یافت شد)

{
  "status": true,
  "time": 1731926417,
  "data": "تبریز"
}
  

خروجی معتبر اما بدون شهر

{
  "status": true,
  "time": 1731926417,
  "data": "کد ملی صحیح می باشد. اما شهر یافت نشد"
}
  

خروجی نامعتبر (کد اشتباه)

{
  "status": false,
  "time": 1731926417,
  "data": "کد ملی نامعتبر"
}
  

وابستگی‌ها (Dependencies)

تست و استفاده (Testing & Usage)

POST /api/v2/trade/national
Content-Type: application/json

{
  "code": "4580021347"
}
  

موارد خطا (Typical Error Cases)

جزئیات پیاده‌سازی (Implementation)

public function nationalPrefix(Request $request)
{
    if (Validator::nationalCode($request->code)) {
        $Code = City::where('national_prefix', 'LIKE', '%' . substr($request->code, 0, 3) . '%')->first();
        if (!is_null($Code))
            return ['status' => true, 'time' => time(), 'data' => $Code->fa_name];
        else
            return ['status' => true, 'time' => time(), 'data' => 'کد ملی صحیح می باشد. اما شهر یافت نشد'];
    } else
        return ['status' => false, 'time' => time(), 'data' => 'کد ملی نامعتبر'];
}
  

نتیجه‌گیری (Conclusion)

پیوست: نگهداری و امنیت

POST /api/auth/sign-in

Route Info

توضیح عملکرد (Function Logic)

ورودی‌ها (Inputs)

POST /api/auth/sign-in

Content-Type: application/json

{

“branch”: 1,

“data”: {

“personnelId”: “101234”,

“password”: “12345678”

}

}

خروجی‌ها (Outputs)

پاسخ موفق (HTTP 200)

{

“user”: {

“uuid”: 1,

“from”: “users”,

“role”: “admin”,

“isAirPlusAdmin”: true,

“group”: “IT”,

“data”: {

“displayName”: “علی شاکرچکی”,

“personnelId”: “101234”,

“branch”: “[0]”,

“telegram”: true,

“position”: “مدیر فناوری اطلاعات”,

“access”: […],

“shortcuts”: […]

}

},

“access_token”: “jwt.token.value”

}

خطا در احراز هویت (HTTP 401)

{

“error”: [

{

“type”: “personnelId”,

“message”: “اطلاعات کاربری همخوانی ندارد.”

}

]

}

حساب کاربری مسدود

{

“error”: [

{

“type”: “personnelId”,

“message”: “حساب کاربری شما مسدود شده است.”

}

]

}

منطق تولید JWT Token

{

“typ”: “base”,

“iss”: “{DomainHeader}”,

“aud”: “{DomainHeader}”,

“iat”: 1731927000,

“exp”: 1732531800,

“uuid”: “{OperatorId}”,

“brn”: “{Branch}”,

“uip”: “{ClientIP}”,

“brw”: “{UserAgentClient}”

}

سیستم لاگ و اعلان‌ها

مدیریت اعلان (Push & Telegram)

موارد خطا (Error Cases)

وابستگی‌ها (Dependencies)

نمونه تست واقعی (Postman Example)

POST https://console.service01.ir/api/auth/sign-in

Headers:

Domain: service01.ir

Content-Type: application/json

Body:

{

“branch”: 2,

“data”: {

“personnelId”: “104512”,

“password”: “test@1234”

}

}

نتیجه عملکرد (Result Summary)

پیوست: نکات امنیتی

POST /api/auth/update

Route Info

توضیح عملکرد (Function Logic)

ورودی‌ها (Inputs)

POST /api/auth/update

Content-Type: application/json

{

“branch”: 1,

“data”: {

“access_token”: “jwt.token.value”,

“user”: {

“data”: {

“shortcuts”: [“dashboard”, “customers”, “tickets”]

}

}

}

}

خروجی‌ها (Outputs)

پاسخ موفق (HTTP 200)

{}

وضعیت غیرفعال کاربر

{

“error”: {

“type”: “personnelId”,

“message”: “وضعیت شما بصورت غیرفعال می باشد.”

}

}

تغییر IP کاربر

{

“error”: {

“type”: “changeIp”,

“message”: “وضعیت اینترنت شما تغییر پیدا کرده”,

“details”: {

“token_ip”: “192.168.1.10”,

“current_ip”: “5.114.200.88”

}

}

}

خطا در پردازش

{

“error”: {

“type”: “personnelId”,

“message”: “Signature verification failed”,

“trace”: […]

}

}

منطق تشخیص IP مجاز

ذخیره اطلاعات در Redis

Redis::set(
𝑟𝑒𝑞𝑢𝑒𝑠𝑡−>𝑔𝑒𝑡(′𝑏𝑟𝑎𝑛𝑐ℎ′).′𝑜𝑝𝑒𝑟𝑎𝑡𝑜𝑟:′.
request−>get( ′branch ′). ′operator:′.
Operator->id . ‘:shortcuts’,
json_encode($data[‘user’][‘data’][‘shortcuts’]));

مدیریت استثناها (Exceptions)

وابستگی‌ها (Dependencies)

مثال تست (Postman Example)

POST https://console.service01.ir/api/auth/update

Content-Type: application/json

{

“branch”: 2,

“data”: {

“access_token”: “jwt.token.value”,

“user”: {

“data”: {

“shortcuts”: [“dashboard”, “customers”, “trade-management”]

}

}

}

}

تحلیل امنیتی

نتیجه عملکرد (Summary Result)

پیوست: نگهداری و بهینه‌سازی

POST /api/auth/blocking

Route Info

توضیح عملکرد (Function Logic)

ورودی‌ها (Inputs)

POST /api/auth/blocking

Content-Type: application/json

{

“token”: “abc123”,

“duration”: 30

}

خروجی‌ها (Outputs)

پاسخ موفق (HTTP 200)

{

“status”: true,

“time”: 1731956440,

“message”: “تمامی نشست ها با موفقیت خاتمه یافتند و کاربری شما بمدت 15 دقیقه مسدود گردید”

}

پاسخ خطا (Exception)

{

“status”: false,

“time”: 1731956440,

“message”: “23000 : SQLSTATE[23000]: Integrity constraint violation”,

“trace”: […]

}

منطق مسدودسازی نشست کاربر

تغییرات دیتابیس (Database Update)

UPDATE operators

SET

blocked_up = NOW() + INTERVAL {duration or 15} MINUTE,

token = NULL

WHERE token = CONCAT(‘telegram:’, {token});

ریدایرکت سمت کلاینت

مدیریت استثناها (Exceptions)

وابستگی‌ها (Dependencies)

تست Endpoint (Postman Example)

POST https://console.service01.ir/api/auth/blocking

Content-Type: application/json

{

“token”: “tg-ops-9902”,

“duration”: 20

}

تحلیل امنیتی

پیوست نگهداری و توسعه آینده

POST /api/auth/forgot/otp

Route Info

توضیح عملکرد (Function Logic)

ورودی‌ها (Inputs)

POST /api/auth/forgot/otp
Content-Type: application/json

{
  "personnel_id": "P00123",
  "mobile": "09131234567",
  "branch": 1
}

خروجی‌ها (Outputs)

ارسال موفق OTP

{
  "status": true,
  "time": 1731958300,
  "message": "OTP با موفقیت ارسال گردید."
}

موبایل یا پرسنلی اشتباه

{
  "status": false,
  "code": 1201,
  "message": "اطلاعات وارد شده با هیچ کاربری همخوانی ندارد"
}

پیامک ارسال نشد

{
  "status": false,
  "code": 1202,
  "message": "پیامک OTP ارسال نشد. مشکلی رخ داده است. لطفا دوباره تلاش کنید",
  "trace": { ... }
}

تعداد درخواست بیش از حد مجاز

{
  "status": false,
  "code": 1203,
  "message": "تعداد درخواست های کاربر بیش از حد مجاز بوده است. لطفا 5 ساعت دیگر اقدام نمائید."
}

منطق محدودسازی درخواست‌ها (Throttle)

محتوای پیامک ارسالی (SMS Template)

code: 123456
این رمز جهت تغییر کلمه عبور صادر شده است.
از در اختیار قراردادن آن به دیگران جدا خودداری فرمائید.
مدت اعتبار: 15 دقیقه

 example.domain

ثبت لاگ سیستمی (SystemLog Dispatch)

SystemLog::dispatch([
  "type" => "SendOtp",
  "goal" => operator_id,
  "by" => operator_id,
  "agent" => $_SERVER['HTTP_USER_AGENT'],
  "ip" => getIP(),
  "datetime" => now()
])->delay(now()->addMinutes(10))->onQueue('snailJob');

وابستگی‌ها (Dependencies)

نمونه تست (Postman Example)

POST https://console.service01.ir/api/auth/forgot/otp
Content-Type: application/json

{
  "personnel_id": "P00999",
  "mobile": "09138889999",
  "branch": 3
}

تحلیل امنیتی

نتیجه عملکرد (Summary Result)

پیوست نگهداری و توسعه آتی

`

POST /api/auth/connect/otp

Route Info

توضیح عملکرد (Function Logic)

ورودی‌ها (Inputs)

POST /api/auth/connect/otp
Content-Type: application/json

{
  "personnel_id": "P00157",
  "branch": 2
}

خروجی‌ها (Outputs)

ارسال موفق OTP

{
  "status": true,
  "time": 1731963200,
  "message": "OTP با موفقیت ارسال گردید."
}

اطلاعات کاربر یافت نشد

{
  "status": false,
  "code": 1201,
  "message": "اطلاعات وارد شده با هیچ کاربری همخوانی ندارد"
}

کاربر قبلاً متصل شده است

{
  "status": false,
  "code": 1203,
  "message": "شما قبلا به سامانه متصل شده اید اگر قصد تغییر تلگرام خود را دارید قبل از انجام این فرایند. از طریق سامانه قطع اتصال فرمائید."
}

تعداد درخواست بیش از حد مجاز

{
  "status": false,
  "code": 1203,
  "message": "تعداد درخواست های کاربر بیش از حد مجاز بوده است. لطفا 5 ساعت دیگر اقدام نمائید."
}

پیامک ارسال نشد

{
  "status": false,
  "code": 1202,
  "message": "پیامک OTP ارسال نشد. مشکلی رخ داده است. لطفا دوباره تلاش کنید",
  "trace": {...}
}

محدودسازی ارسال (Throttle Control)

قالب پیامک ارسالی (SMS Template)

code: 12345678
این رمز جهت ارتباط با سایر سرویس ها صادر شده است.
از دراختیار قراردادن آن به دیگران جدا خودداری فرمائید.
مدت اعتبار: 15 دقیقه

🌐 example.domain

ثبت رویداد SystemLog

SystemLog::dispatch([
  "type" => "SendOtp",
  "goal" => operator_id,
  "by" => operator_id,
  "agent" => $_SERVER['HTTP_USER_AGENT'],
  "ip" => getIP(),
  "datetime" => now()
])->delay(now()->addMinutes(10))->onQueue('snailJob');

تغییرات دیتابیس (Database Update)

UPDATE operators
SET
  otp = {random 8-digit code},
  otp_issuing = NOW()
WHERE id = {operator.id};

وابستگی‌ها (Dependencies)

نمونه تست (Postman Example)

POST https://console.service01.ir/api/auth/connect/otp
Content-Type: application/json

{
  "personnel_id": "P00231",
  "branch": 1
}

تحلیل امنیتی

پیوست نگهداری و توسعه‌آتی

POST /api/auth/connect/submit

Route Info

توضیح عملکرد (Function Logic)

ورودی‌ها (Inputs)

POST /api/auth/connect/submit
Content-Type: application/json

{
  "personnel_id": "P00157",
  "otp": "12345678",
  "telegram": "@aliiranpour",
  "branch": 1
}

خروجی‌ها (Outputs)

تصال موفق

{
  "status": true,
  "time": 1731963561,
  "message": "اتصال با موفقیت انجام شد."
}

رمز منقضی شده

{
  "status": false,
  "code": 1204,
  "message": "رمز یکبار مصرف منقضی شده است."
}

رمز اشتباه یا نامعتبر

{
  "status": false,
  "code": 1205,
  "message": "رمز یکبار مصرف وارد شده معتبر نمی باشد."
}

فرآیند بررسی زمان OTP

به‌روزرسانی جدول Operators

UPDATE operators
SET
  telegram = {request.telegram},
  otp = NULL
WHERE id = {operator.id};

ثبت رویداد در SystemLog

SystemLog::dispatch([
  "type" => "SubmitTelegram",
  "data" => null,
  "goal" => $request->personnel_id,
  "by" => $operator->id,
  "agent" => $_SERVER['HTTP_USER_AGENT'],
  "ip" => getIP(),
  "datetime" => Carbon::now()
])->delay(now()->addMinutes(10))->onQueue('snailJob');

پیامک موفقیت اتصال

پیامک:
اتصال شما به سرویس مورد نظر موفقیت آمیز بود.
زمان: شنبه، ۲۷ آبان ۱۴۰۳ | ۱۲:۴۵:۱۰
📍 IP: 192.168.1.24
🌐 example.domain

StaticController::sendNotification($operator->mobile, $tempBody, $request->get('branch'));

وابستگی‌ها (Dependencies)

نمونه تست Postman

POST https://console.service01.ir/api/auth/connect/submit
Content-Type: application/json

{
  "personnel_id": "P00442",
  "otp": "55667788",
  "telegram": "@operator_test"
}

تحلیل امنیتی

پیوست نگهداری و توسعه بعدی

`

POST /api/auth/forgot/submit

Route Info

توضیح عملکرد (Function Logic)

ورودی‌ها (Inputs)

POST /api/auth/forgot/submit
Content-Type: application/json

{
  "personnel_id": "P00999",
  "otp": "98765432",
  "password": "MyNewStrongPassword@123",
  "branch": 1
}

خروجی‌ها (Outputs)

به‌روزرسانی موفق رمز عبور

{
  "status": true,
  "time": 1731963561,
  "message": "کلمه عبور با موفقیت بروزرسانی شد."
}

رمز یکبار مصرف منقضی شده

{
  "status": false,
  "code": 1204,
  "message": "رمز یکبار مصرف منقضی شده است."
}

رمز یکبار مصرف نامعتبر

{
  "status": false,
  "code": 1205,
  "message": "رمز یکبار مصرف وارد شده معتبر نمی باشد."
}

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

DB::table('operators')
    ->where('id', $operator->id)
    ->update([
        'password' => Hash::make($request->password), 
        'otp' => null
    ]);

ثبت رویداد در SystemLog

SystemLog::dispatch([
  "type" => "UpdatePassword",
  "data" => null,
  "goal" => $request->personnel_id,
  "by" => $operator->id,
  "agent" => $_SERVER['HTTP_USER_AGENT'],
  "ip" => getIP(),
  "datetime" => Carbon::now()
])->delay(now()->addMinutes(10))->onQueue('snailJob');

پیامک اطلاع‌رسانی امنیتی

پیامک:
رمز عبور شما بروزرسانی گردید.
زمان: شنبه، ۲۷ آبان ۱۴۰۴ | ۱۳:۱۰:۲۰
📍 IP: 10.0.0.15
🌐 example.domain

وابستگی‌ها (Dependencies)

تحلیل امنیتی

پیوست نگهداری و توسعه بعدی

POST /api/auth/access-token

Route Info

توضیح عملکرد (Function Logic)

{
  "typ": "base",
  "iss": "domain.com",
  "aud": "domain.com",
  "iat": 1731964000,
  "nbf": 1731964000,
  "exp": 1732568800,       // 7 روز
  "uuid": 54,
  "brn": 2,
  "uip": "10.0.0.15",
  "brw": { "name": "Chrome", "version": "122.0", "type": "browser" }
}

بدنه درخواست (Request Body)

POST /api/auth/access-token
Content-Type: application/json
Domain: example.domain

{
  "branch": 2,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6..."
  }
}

پاسخ موفق (Response - Success)

{
  "user": {
    "uuid": 54,
    "from": "users",
    "role": "admin",
    "isAirPlusAdmin": true,
    "group": "core",
    "data": {
      "displayName": "Ali Pour",
      "email": "a.pour@example.ir",
      "photoURL": "https://storage.service01.ir/media/avatar/robot.png",
      "services": { "telegram": false },
      "personnelId": "P00999",
      "branch": [0,1],
      "access": [ ... ],
      "shortcuts": ["temporary-registration","online-ticket","trade-management","customers"]
    }
  },
  "access_token": "new.jwt.token.generated"
}

پاسخ‌های خطا (Error Types)

{
  "error": {
    "type": "changeIp",
    "message": "وضعیت اینترنت شما تغییر پیدا کرده",
    "details": {
      "token_ip": "10.1.1.2",
      "current_ip": "45.66.88.100"
    }
  }
}

تولید JWT جدید

تحلیل امنیتی

وابستگی‌ها (Dependencies)

پیوست نگهداری و توسعه بعدی

GET /api/v2/notifications

Route Info

توضیح عملکرد (Function Logic)

ساختار درخواست (Request)

GET /api/v2/notifications
Domain: example.domain

خروجی (Response Structure)

نمونه پاسخ

[
  {
    "id": "01",
    "icon": "airline_seat_recline_extra",
    "title": "ویرایش خرید پرواز آنلاین",
    "description": "به اطلاع کلیه همکاران میرسانیم قسمت ویرایش پرواز های آنلاین فعال گردید.",
    "time": "1402-02-02 00:00:00",
    "read": true,
    "link": "/",
    "useRouter": true
  }
]

نکات امنیتی

توضیح فیلدهای پاسخ

وابستگی‌ها (Dependencies)

پیوست نگهداری و توسعه بعدی

GET /api/v2/exam/get

Route Info

توضیح عملکرد (Function Logic)

منطق کلی:

ورودی‌ها (Request Parameters)

الف) جریان عملکرد نوع «trip»

ب) جریان عملکرد نوع «360_degree_feedback»

ساختار پاسخ (Response Structure)

نمونه پاسخ موفق (trip):

{
  "status": true,
  "time": 1693905000,
  "data": {
    "id": 15,
    "object": 1472,
    "title": "نظرسنجی خدمات پرواز",
    "header": "مشتری گرامی، لطفاً به سفر خود امتیاز دهید.",
    "footer": "با تشکر از همکاری شما",
    "created_at": "1402-02-02 00:00:00",
    "questions": [
      {
        "id": 1,
        "type": "rating",
        "subject": "flight",
        "title": "ارزیابی کیفیت پرواز شما",
        "options": [1,2,3,4,5],
        "description": null,
        "mandatory": 1,
        "score": 5
      }
    ]
  }
}

نمونه پاسخ خطا:

{
  "status": false,
  "time": 1693905001,
  "message": "این سفر قبلا نظرسنجی شده است."
}

تحلیل امنیتی

وابستگی‌ها (Dependencies)

ساختار داخلی data در پاسخ موفق

پیغام‌های خطای محتمل

نکات کارایی (Performance)

پیوست نگهداری و توسعه بعدی

POST /api/v2/exam/response

Route Info

توضیح عملکرد (Function Logic)

ورودی‌ها (Request Body)

خروجی (Response Structure)

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

POST /api/v2/exam/response
Content-Type: application/json

{
  "type": "trip",
  "id": 15,
  "object": 1472,
  "branch": "8",
  "operator": { "id": 22 },
  "responses": [
    { "question": 1, "response": "5" },
    { "question": 2, "response": ["Clean", "Comfort"] }
  ]
}

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

{
  "status": true,
  "time": 1693905251,
  "gift": { "title": "تخفیف ویژه", "code": "140303-12345" }
}

نمونه پاسخ خطا:

{
  "status": false,
  "time": 1693905252,
  "message": "SQLSTATE[23000]: Integrity constraint violation ...",
  "trace": [ ... ]
}

تحلیل امنیتی

وابستگی‌ها (Dependencies)

نکات کارایی و ضعف منطقی

پیوست نگهداری و توسعه بعدی

POST /api/v2/trade/list

Route Info

منطق عملکرد تابع

ورودی‌ها (Request Fields)

ساختار فیلتر پیشرفته (advanced):

"advanced": {
  "r": "", "from": "2025-01-01", "to": "2025-01-31",
  "op": 0, "status": 1, "flightno": "W51123", "dt_departure": "2025-01-12",
  "pledger": "colleague-42", "vehicle": "aircraft", "income": "", "route": ""
}

خروجی (Response)

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

POST /api/v2/trade/list
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "branch": 8,
  "json": {
    "draw": 1,
    "start": 0,
    "length": 15,
    "search": {"value": ""},
    "advanced": {"from":"2025-01-01","to":"2025-01-31","status":"1"}
  }
}

نمونه پاسخ:

{
  "draw": 1,
  "recordsTotal": 52,
  "recordsFiltered": 52,
  "total": {
    "Buy": 9200000,
    "Sale": 11300000,
    "Profit": 2100000,
    "Debit": 150000,
    "Credit": 280000,
    "Discount": 30000,
    "Passenger": 91
  },
  "data": [ { "SerialId": 2048001, "Income":"direct", "RouteTitle":"پرواز تهران-کیش", ... } ]
}

امنیت و کنترل دسترسی

نکات کارایی و پیاده‌سازی

وابستگی‌ها

کدهای خطا و خروجی‌های Exception

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی دسترسی و عدم قطعیت

جمع‌بندی

POST /api/v2/trade/search

Route Info

منطق عملکرد و مسیر داده

ورودی‌ها (Request Fields)

نمونه Search Structure:

{
  "branch": 8,
  "search": {
    "from": "2025-02-01", "to": "2025-02-12",
    "status": "1", "flightno": "W51005",
    "op": 22, "pledger": "operator-12"
  },
  "paginate": {
    "start": 0,
    "length": 15
  }
}

خروجی (Response Structure)

ساختار هر آیتم در خروجی:

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

{
  "items": [
    {
      "date": { "title": "11/22", "placeholder": "سه‌شنبه، 1404/12/23 14:32" },
      "route_title": "تهران به کیش | W51005",
      "type": { "title": "aircraft", "placeholder": "هواپیما" },
      "pledger": [ { "Id": 12, "Title": "جواد مقیمی", "Amount": 250000 } ],
      "suppliers": [],
      ...
    }
  ],
  "meta": {
    "timestamp": 1693905251,
    "total": 29,
    "page": 15,
    "per_page": 15,
    "last_page": 2,
    "current_page": 2
  }
}

نمونه پاسخ خطا (تاریخ ناقص):

{
  "error": {
    "code": 1000,
    "message": "لطفا تاریخ شروع جستجو و پایان جستجو را وارد نمائید."
  },
  "meta": {
    "timestamp": 1693905251
  }
}

تحلیل امنیتی و کنترل خطا

نکات کارایی و ضعف طراحی

وابستگی‌های کلیدی

کدهای خطا و خروجی‌های Exception

پیشنهادهای بهبود

جمع‌بندی

POST /api/v2/trade/cost-benefit

اطلاعات مسیر (Route Info)

منطق عملکرد

ورودی‌ها (Request Parameters)

ساختار نمونه محتوای json:

{
  "from": "2025-10-01",
  "to": "2025-10-31",
  "action": "all"
}

خروجی (Response Structure)

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

{
  "total": {
    "provider": {
      "Buy": 54000000,
      "Sale": 69800000,
      "Profit": 12000000,
      "Wage": 2000000,
      "Debit": 32000000,
      "Credit": 12000000,
      "Passenger": 48,
      "References": 17
    },
    ...
  },
  "chart": {
    "provider": {
      "categories": ["آژانس الف", "آژانس ب"],
      "count_references": [17, 13],
      "count_passengers": [48, 32],
      "count_profit": [1.2, 0.9],
      "treemap": {
        "international": {"name":"international","data":[{"x":"آژانس الف","y":1.2}]}
      }
    }
  },
  "data": {...},
  "diff": [],
  "search": {"from":"2025-10-01T00:00:00Z","to":"2025-10-31T23:59:59Z"}
}

جریان داده (Data Flow)

عملکرد و کش

امنیت و کنترل ورودی

Dependencies

خطاها و حالت‌های خاص

پیچیدگی زمانی و منابع

پیشنهادهای بهینه‌سازی

جمع‌بندی

POST /api/v2/references/{type}/list

Route Info

منطق عملکرد و مسیر داده

ورودی‌ها (Request Fields)

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

{
  "filter": { "company_id": 12, "active": true }
}

خروجی (Response Structure)

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

{
  "status": "success",
  "message": "Reference list retrieved successfully",
  "data": [
    { "id": 1, "title": "بانک ملت", "type": "credit", "balance": 3200000 },
    { "id": 2, "title": "مشتری ویژه", "type": "debit", "balance": -170000 }
  ]
}

نمونه پاسخ خطا:

{
  "status": "error",
  "message": "Invalid type parameter"
}

تحلیل امنیتی و کنترل خطا

نکات کارایی

وابستگی‌های کلیدی

کدهای خطا و حالت‌های Exception

پیشنهادهای بهبود

جمع‌بندی

POST /api/v2/trade/store

Route Info

منطق عملکرد

ورودی‌ها

{
  "branch": 12,
  "operator": { "id": 5, "name": "Operator A" },
  "passengers": [ { "id": 1, "name_fa": "علی رضایی", "phone_number": "0912..." } ],
  "data": [ { "action": "online", "type": "aircraft", "buy": "2500000", "sell": "3000000" } ],
  "notices": true
}

خروجی

{
  "status": true,
  "time": 1732021035,
  "details": false
}

امنیت

کارایی

وابستگی‌ها

کدهای خطا

جمع‌بندی

این Endpoint قلب عملیات فروش/رزرو است. نیازمند اعتبارسنجی دقیق، عملکرد سریع و گزارش‌گیری جامع می‌باشد. با پیاده‌سازی پیشنهادها، می‌توان ریسک خطا و فشار پردازشی را به‌طور قابل‌توجهی کاهش داد.

POST /api/v2/trade/edit

Route Info

منطق عملکرد

ورودی‌ها

{
  "action": "details",
  "serial_id": 245,
  "description": "اصلاح اطلاعات مشتری",
  "income": 7,
  "leader": 28,
  "status": 2,
  "operator_reference": 5
}

خروجی

{
  "status": true,
  "time": 1732022018
}

امنیت

کارایی

وابستگی‌ها

کدهای خطا

پیشنهادهای بهبود

جمع‌بندی

متد editTrade واحد ویرایشی انعطاف‌پذیر سیستم است که چند نوع تغییر مختلف را زیر یک endpoint سامان می‌دهد. با ساختار فعلی تمام ویرایش‌ها در عین سرعت، قابل ردیابی و audit کامل هستند. ترکیب Redis و SystemLog باعث توازن ایده‌آل بین كارایی و امنیت شده است.

POST /api/v2/trade/item/edit

Route Info

منطق عملکرد

ورودی‌ها

{
  "item_id": 205,
  "action": "online",
  "edit_all": false,
  "online": { "type": "aircraft", "flight_number": "W5-1155", "original_ticket_no": "774221", "date_time_path": "2025-11-21 13:20" },
  "buy": 8800000,
  "sell": 9400000,
  "currency": { "unit": "IRR", "exchange": 1, "amount": 9400000 },
  "provider": { "id": 2 }
}

ساختار <details> بر اساس action

خروجی

{
  "status": true,
  "time": 1732022461
}

کدهای خطا

اثرات جانبی

امنیت

کارایی

وابستگی‌ها

پیشنهادهای بهبود

جمع‌بندی

متد editItemTrade نقطه‌ی کنترل جزئیات دقیق فاکتور است؛ برای هر نوع خدمت (از بلیت هواپیما تا ویزا و بیمه) جزئیات را بازسازی و در پایگاه داده به‌روزرسانی می‌کند. از نظر معماری با editTrade تفاوت دارد چون روی آیتم واحد تمرکز دارد و لاگینگ دقیق row-level را اعمال می‌کند. این ترکیب بین دقت، سرعت و قابلیت audit تعادل مطلوبی ایجاد کرده است.

POST /api/v2/trade/item/add

Route Info

منطق عملکرد

ورودی‌ها

{
  "serial_id": 102,
  "data": [
    {
      "action": "route",
      "route": {
        "type": "aircraft",
        "origin": { "iata": "IKA" },
        "destination": { "iata": "IST" },
        "date_time_path": "2025-12-03 08:30",
        "company": { "id": 2 },
        "flight_number": "W5-1160",
        "class": { "iata": "Y" },
        "allowed_cargo": 20
      },
      "buy": 5800000,
      "sell": 6300000,
      "passenger": { "passenger_id": 87 }
    }
  ]
}

ساختار details بر اساس action

خروجی

{
  "status": true,
  "time": 1732023601
}

کدهای خطا

اثرات جانبی

امنیت

کارایی

وابستگی‌ها

پیشنهادهای بهبود

جمع‌بندی

متد addItemTrade نقطهٔ ورودی افزودن اقلام جدید به فاکتور مالی است. با پشتیبانی از انواع متنوع سرویس (از بلیت تا بیمه) و ثبت کامل لاگ‌ها، این بخش یکی از پایه‌های اصلی گردش اطلاعات در زیرسیستم Trade محسوب می‌شود. ساختار فعلی در عین سادگی، audit‑friendly و کاملاً asynchronous طراحی‌شده است.

POST /api/v2/trade/item/delete

Route Info

منطق عملکرد

ورودی‌ها

{
  "item_id": 231,
  "serial_id": 9004,
  "refund_id": 88
}

خروجی

{
  "status": true,
  "time": 1732023601
}

اثرات جانبی

کدهای خطا

امنیت

نکات کارایی

وابستگی‌ها

پیشنهاد بهبود

ردپای مانیتورینگ (Audit Trail)

تمامی عملیات حذف آیتم با نوع و شناسه دقیق در SystemLog ثبت شده و قابل بررسی است.

جمع‌بندی

Endpoint فوق ساده، سریع و قابل اطمینان است. حذف منطقی داده و ثبت هم‌زمان لاگ‌ باعث حفظ شفافیت و هماهنگی کامل بین دیتابیس و کش می‌شود.

POST /api/v2/trade/item/value_added

Route Info

منطق عملکرد

ورودی‌ها

{
  "item_id": 415,
  "value_added": {
    "type": "percent",
    "value": 9
  }
}

خروجی

{
  "status": true,
  "time": 1732023601
}

تعامل با دیتابیس

اثرات جانبی

کدهای خطا

امنیت

کارایی

وابستگی‌ها

پیشنهاد بهبود

جمع‌بندی

این متد یک endpoint سبک و سریع برای ویرایش اعداد «ارزش افزوده» در سطح آیتم‌های فاکتور است. طراحی آن audit‑friendly است و با ساختار SystemLog هماهنگ، باعث حفظ تاریخچه‌ی تغییرات مالی هر آیتم می‌شود.

POST /api/v2/trade/operation

Route Info

منطق عملکرد

پارامترهای ورودی

{
  "id": 23051,
  "branch": 12
}

ساختار خروجی

در خروجی داده‌ای چندلایه به صورت JSON بازگردانده می‌شود. ساختار کلیدی شامل بخش‌های زیر است:

{
  "income": { "id": 2, "title": "درآمد فروش مسیر", ... },
  "serial_id": 5128,
  "system_serial": 28117,
  "data": [ ... ],
  "pays": { "payment": [...], "receive": [...], "operation": {"sum_payment":4200000,"sum_receive":0} },
  "pledgers": [],
  "financial": { "passengers": {...}, "announcement": null },
  "sum_sell_price": 6540000,
  "sum_buy_price": 6120000,
  "print": {"id":2,"title": {"fa":"مشاهده با قیمت"}},
  "status": {"id": 1, "title": "در انتظار پرداخت"}
}

امنیت

منابع داده و وابستگی‌ها

مدیریت خطا

کارایی

رد پای حسابرسی

وابستگی‌های نرم‌افزاری

پیشنهادهای بهبود

جمع‌بندی

این Endpoint یکی از مهم‌ترین نقاط تجمیع داده در سیستم معاملات است که اطلاعات زنجیره کامل مالی و خدماتی یک فاکتور را در قالب یک خروجی API ترکیب می‌کند. منطق آن همزمان audit‑friendy و cache‑optimized است.

POST /api/v2/trade/operation/general

Route Info

منطق عملکرد

پارامترهای ورودی

{ "id": 23051 }

خروجی

خروجی برابر با مقدار بازگردانده‌شده از StaticController::generalTrade() است. شامل گزارش مالی تفصیلی، وضعیت گردش حساب فاکتور و اقلام مرتبط.

{
  "financial": { ... },
  "operations": [ ... ],
  "summary": { "total_buy": ..., "total_sell": ... }
}

وابستگی‌ها

امنیت

کارایی

مدیریت خطا

پیشنهادهای بهبود

جمع‌بندی

این Endpoint، نسخه‌ی ساده‌شده و سریع‌تر از operationTrade است که خروجی تجمیعی (general) را با حداقل منطق کنترلی برمی‌گرداند. برای پردازش سریع و استفاده در بخش‌های تحلیلی سمت سرور یا گزارش‌های مالی طراحی شده است.

POST /api/v2/trade/refund/update

Route Info

منطق عملکرد

پارامترهای ورودی

خروجی

{
  "status": true,
  "time": 1732019472
}

در صورت موفقیت، status=true بازگردانده می‌شود؛ در غیر این صورت (در سطح Exception catch نشده) خطای HTTP 500.

امنیت

اثرات جانبی و Queue Jobs

تغییرات داده‌ای

مدیریت خطا

کارایی

ردپای حسابرسی (Audit Trail)

پیشنهاد بهبود

جمع‌بندی

این Endpoint برای ایجاد یا اصلاح سریع ردیف‌های استرداد طراحی شده و مستقیماً داده‌های جدول factor_items را تغییر می‌دهد. ویژگی متمایز آن تقسیم عملیات به دو سطح «افزودن» و «به‌روزرسانی» خودکار و ثبت خودکار در SystemLog است.

POST /api/v2/trade/refund/delete

Route Info

منطق عملکرد

پارامترهای ورودی

خروجی‌ها

{
  "status": true,
  "time": 1732019472
}

در صورت خطا:

{
  "status": false,
  "time": 1732019472,
  "code": 5005,
  "message": "...",
  "trace": [...]
}

امنیت

اثرات جانبی و Queue Jobs

تغییرات داده‌ای

مدیریت خطا

کارایی

ردپای حسابرسی

پیشنهاد بهبود

جمع‌بندی

این Endpoint ابزار دقیق حذف بازپرداخت‌هاست و با ثبت دقیق وقایع در SystemLog، کنترل حسابرسی کامل را تضمین می‌کند. طراحی ساده و واکنش‌گرا آن امکان اتصال مستقیم به UI درون‌سازمانی را فراهم می‌سازد.

POST /api/v2/trade/statement

Route Info

منطق عملکرد

پارامترهای ورودی درخواست

{
  "id": 23051,
  "lang": {"id": 1},
  "branch": 12
}

خروجی

خروجی حاصل از اجرای تابع TradeController::statementTrade() بوده و معمولاً شامل داده‌ای ساختاریافته از صورت‌حساب کامل فاکتور است، شامل:

{
  "status": true,
  "statement": {
    "header": {...},
    "items": [...],
    "summary": {...}
  }
}

امنیت

وابستگی‌ها

کارایی

مدیریت خطا

اثرات جانبی

ردپای حسابرسی

فاقد ثبت مستقیم ولی درصورت فعال بودن Audit در TradeController، گزارش View Statement لاگ می‌شود.

پیشنهادهای بهبود

جمع‌بندی

این Endpoint سطح Gateway برای دریافت صورت حساب از کنترلر TradeController است و وظیفه‌اش انتقال سریع پارامترهای فاکتور و زبان می‌باشد. منطق محاسبات و بازگردانی خروجی تماماً در کنترلر داخلی انجام می‌شود.

POST /api/v2/trade/request

Route Info

منطق عملکرد

پارامترهای ورودی

{
  "id": 23051,
  "supplier": 871,
  "lang": {"id": 1},
  "branch": 12
}

ساختار خروجی

نتیجه همان خروجی TradeController::requestTrade() است و می‌تواند شامل:

{
  "status": true,
  "request_info": {...},
  "supplier_data": {...}
}

امنیت

وابستگی‌ها

کارایی

مدیریت خطا

اثرات جانبی

ردپای حسابرسی

در سطح V2TradeController داده‌ای ثبت نمی‌شود؛ اما در TradeController، هر پاسخ ممکن است در لاگ مربوط به supplier ذخیره شود.

پیشنهاد بهبود

جمع‌بندی

این Endpoint نقش اتصال بین سیستم داخلی و تأمین‌کننده را بازی می‌کند و برای درخواست داده‌های وضعیت/تحویل خدمات از مرجع به کار می‌رود. سطح اجرای آن gateway‑type و فاقد منطق تجاری درونی است.

POST /api/v2/trade/commitment

Route Info

منطق عملکرد

پارامترهای ورودی

{
  "pledger_id": 154,
  "branch": 12,
  "lang": {"id": 1}
}

ساختار خروجی

{
  "status": true,
  "time": 1732024532,
  "contract": "<html>...</html>",
  "data": {
    "page_details": {"page":18,"object_type":"pledger","object":154},
    "confirmation": 1,
    "serial_id": 13521,
    "internal": true,
    "leader": {...},
    "slug": "a9cD91bc",
    "track_code": "05-11023"
  }
}

امنیت

وابستگی‌ها

کارایی

مدیریت خطا

اثرات جانبی

خواندن داده از contract و pages. هیچ درج یا بروزرسانی‌ای انجام نمی‌شود (Read‑Only).

ردپای حسابرسی

در این متد لاگ مستقیم ثبت نمی‌شود. مسیر بعدی commitmentSubmitTrade مسئول logging اقدامات کاربر در جدول SystemLog است.

پیشنهادهای بهبود

جمع‌بندی

این Endpoint خروجی HTML قرارداد مالی براساس اطلاعات فاکتور و تعهدکننده را تهیه می‌کند و مرحله‌ی مقدماتی قبل از ثبت در دیتابیس است. خروجی آماده‌ی چاپ یا نمایش به کاربر نهایی در فرانت‌اند می‌باشد.

POST /api/v2/trade/commitment/submit

Route Info

منطق عملکرد

پارامترهای ورودی

{
  "page_id": 18,
  "object_type": "pledger",
  "object": 154,
  "data": {
    "fullname": "علیرضا ایرانپور",
    "national_code": "1234567890",
    "installments": 8
  }
}

ساختار خروجی

{
  "status": true,
  "time": 1732024850
}

در صورت خطا:

{
  "status": false,
  "message": "خطا در ارسال اطلاعات.",
  "trace": [...]
}

امنیت

کارایی

مدیریت خطا

اثرات جانبی

ردپای حسابرسی

تمام عملیات ذخیره و ویرایش قرارداد در قالب SystemLog ثبت می‌شود (نوع StoreContract یا UpdateContract) شامل by, ip, agent.

پیشنهادهای بهبود

جمع‌بندی

این Endpoint عملیات ذخیره و ویرایش داده‌های قرارداد تعهد را مدیریت می‌کند و به‌همراه SystemLog تضمین ردپای دقیق دارد. ترکیب منطقی این دو متد، جریان کامل «نمایش قرارداد → تأیید و ثبت نهایی» را می‌سازد.

POST /api/v2/trade/payment-receipt

Route Info

منطق عملکرد

پارامترهای ورودی

{
  "id": 13725,
  "lang": {"id": 1},
  "branch": 12
}

ساختار خروجی

پاسخ تابع TradeController::paymentReceiptTrade() به‌صورت JSON بازگردانده می‌شود. ساختار معمول شامل:

{
  "status": true,
  "receipt": {
    "factor_id": 13725,
    "serial": "F-2025-1105",
    "branch": "اصفهان مرکزی",
    "amount": 12800000,
    "currency": "IRR",
    "datetime": "2025-11-19 14:31",
    "payment_type": "wallet"
  },
  "customer": {...}
}

امنیت

وابستگی‌ها

کارایی

مدیریت خطا

اثرات جانبی

فاقد اثرات جانبی. فقط خروجی نمایشی و هیچ داده‌ای در DB تغییر نمی‌کند.

ردپای حسابرسی

در این متد SystemLog ثبت نمی‌شود اما در سطح زیرین TradeController ممکن است عملیات مشاهده‌ی رسید ثبت شود.

پیشنهادهای بهبود

جمع‌بندی

این Endpoint یک Gateway سبک برای تولید رسید پرداخت فاکتور است که منطق اصلی نمایش و فرمت داده را از TradeController ارث می‌برد. بدون منطق تجاری سنگین، فقط داده‌ی نهایی را برمی‌گرداند.

POST /api/v2/logs

Route Info

منطق عملکرد

پارامترهای ورودی

{
  "action": "SendNotify"
}

ساختار خروجی

در خروجی JSON داده‌های لاگ فیلترشده بازگردانده می‌شوند:

{
  "status": true,
  "time": 1732026322,
  "data": [
    {
      "type": "SendNotify",
      "goal": 1281,
      "ip": "192.168.1.101",
      "by": 12,
      "datetime": "2025-11-19 14:32:05",
      "message": "ارسال اعلان موفق"
    }
  ]
}

امنیت

وابستگی‌ها

کارایی

مدیریت خطا

اثرات جانبی

این متد فقط داده لاگ‌ها را می‌خواند، هیچ اثر نوشتاری ندارد.

ردپای حسابرسی

به‌صورت مستقیم لاگی ثبت نمی‌کند، اما خروجی آن اطلاعات تمام رخدادهای audit قبلی را نمایش می‌دهد.

پیشنهادهای بهبود

جمع‌بندی

این Endpoint برای مانیتورینگ و پشتیبانی اپراتورها طراحی شده تا تمامی رخدادهای ثبت‌شده در سامانه را reactive مشاهده کنند. سبک و صرفاً خوانشی است و جزو ابزارهای کاربردی محیط پشتیبانی Trade محسوب می‌شود.

POST /api/v2/pledger/store

Route Info

منطق عملکرد

پارامترهای ورودی

{
  "pledger": "colleague-47",
  "serial_id": 10234,
  "amount": "12,000,000"
}

ساختار خروجی

موفق:
{
  "status": true,
  "time": 1732026400,
  "data": 582  // شناسه‌ی رکورد در جدول pledgers
}

ناموفق (مبلغ صفر):
{
  "status": false,
  "code": 5004,
  "message": "تعهد باید دارای مبلغ باشد"
}

امنیت

وابستگی‌ها

کارایی

عملیات درج تک‌مرحله‌ای، میانگین تأخیر <25ms. ادغام با صف رخدادهای لاگ و Redis غیرهمزمان.

مدیریت خطا

اثرات جانبی

ردپای حسابرسی

ورود در SystemLog با اطلاعات عامل (IP, agent, operator_id) برای شفافیت کامل تراکنش ثبت تعهد.

پیشنهاد بهبود

جمع‌بندی

این متد افزودن پایه‌ای تعهدکننده برای هر فاکتور است و مسیر ورود رسمی داده‌ی مالی تعهد در چرخه‌ی Trade محسوب می‌شود.

POST /api/v2/pledger/update

Route Info

منطق عملکرد

پارامترهای ورودی

{
  "pledger_id": 582,
  "pledger": "operator-19",
  "amount": "8,500,000",
  "serial_id": 10234
}

ساختار خروجی

موفق:
{
  "status": true,
  "time": 1732026488
}

ناموفق:
{
  "status": false,
  "code": 5004,
  "message": "تعهد باید دارای مبلغ باشد"
}

امنیت

وابستگی‌ها

کارایی

فرآیند دوبخشی خواندن→ویرایش→ارسال به صف، با میانگین زمان اجرا ۳۰–۴۰ ms.

مدیریت خطا

اثرات جانبی

ردپای حسابرسی

تغییرات پیمایش‌پذیر هستند: تمامی مقادیر قبل از ویرایش در لاگ ذخیره می‌شوند تا تاریخچه بازیابی‌پذیر باشد.

پیشنهاد بهبود

جمع‌بندی

این Endpoint عملیات ویرایش تعهدکننده را انجام می‌دهد و با ثبت دقیق تفاوت‌ها در SystemLog، بخشی از شفافیت مالی سیستم را تضمین می‌کند.

POST /api/v2/pledger/delete

Route Info

منطق عملکرد

پارامترهای ورودی

{
  "pledger_id": 582,
  "serial_id": 10234
}

ساختار خروجی

موفق:
{
  "status": true,
  "time": 1732027111
}

خطا:
{
  "status": false,
  "time": 1732027111,
  "code": 5003,
  "message": "SQLSTATE[23000]: Integrity constraint violation..."
}

امنیت

وابستگی‌ها

کارایی

عملیات حذف تک‌خطی، زمان متوسط <20 ms. صف‌ها به‌صورت ناهمگام اجرا می‌شوند.

مدیریت خطا

اثرات جانبی

ردپای حسابرسی

جزئیات حذف در SystemLog ثبت می‌شود (goal=pledger_id ، by=operator_id).

پیشنهاد بهبود

جمع‌بندی

این Endpoint ساده‌ترین ولی حیاتی‌ترین عملیات حذف تعهد را مدیریت می‌کند و برای حفظ صحت داده‌ها در Redis و SystemLog از Jobهای مجزا بهره می‌گیرد.

POST /api/v2/purchases/list

Route Info

منطق عملکرد

پارامترهای ورودی

{
  "branch": 12,
  "search": {"from": "2025-11-01", "to": "2025-11-19", "status": 2},
  "paginate": {"start": 0, "length": 25}
}

ساختار خروجی

{
  "items": [
    {
      "id": 201,
      "operator": {
        "type": "b2b",
        "fullname": {
          "first_name": {"fa": "دفتر مشهد", "en": false},
          "last_name": {"fa": " - ali", "en": false}
        }
      },
      "gateway_id": "IDPAY-94fa ... ",
      "request": {...},
      "response": {...},
      "status": 1,
      "created_at": "2025-11-19T10:22:01",
      "updated_at": "2025-11-19T10:22:01"
    }
  ],
  "meta": {"timestamp": 1732027206}
}

امنیت

وابستگی‌ها

کارایی

مدیریت خطا

اثرات جانبی

فاقد اثر نوشتاری؛ فقط عملیات خواندن.

ردپای حسابرسی

این Endpoint گزارش‌دهنده است و هیچ داده‌ای در SystemLog ثبت نمی‌کند.

پیشنهاد بهبود

جمع‌بندی

این Endpoint داشبورد پرداخت‌های آنلاین و در حال پردازش را تغذیه می‌کند و بخشی از ماژول رصد تراکنش‌های مالی وب‌سایت (Website Purchase Monitor) است.

PUT /api/v2/purchase/retry/{id}

Route Info

منطق عملکرد

پارامترهای ورودی

PUT /api/v2/purchase/retry/74
{
  "branch": 31
}

ساختار خروجی

{
  "payload": {
    "message": "رفرنس 672CHECK-9 با موفقیت ایجاد شد."
  },
  "meta": {"timestamp": 1732028000}
}

{
  "error": {
    "code": 1000,
    "message": "آیتم مورد نظر یافت نشد و یا اجازه بازخوانی ندارد"
  },
  "meta": {"timestamp": 1732028000}
}

{
  "error": {"code":1000,"message":"پرداخت قابل تکمیل نیست"},
  "meta": {"timestamp": 1732028000}
}

امنیت

وابستگی‌ها

کارایی

عملیات سبک‌تر از 10 ms (به جز فراخوان CronController که وابسته به سرویس خارجی است).

مدیریت خطا

اثرات جانبی

ردپای حسابرسی

هنگام موفقیت در ایجاد رفرنس جدید، وقایع در SystemLog و جدول عملیات خرید ذخیره می‌شوند (در لایه CronController).

پیشنهاد بهبود

جمع‌بندی

این Endpoint برای بازیابی تراکنش‌های موقت و تکمیل خرید در صورت قطعی ارتباط یا بازگشت ناقص درگاه پرداخت طراحی شده است.

GET /api/v2/flights/approved-rate

Route Info

منطق عملکرد

پارامترهای ورودی

فاقد ورودی خاص است (بدون پارامترهای Query یا Body).

GET /api/v2/flights/approved-rate
Authorization: Bearer 

ساختار خروجی

{
  "items": [
    {
      "route_id": 92,
      "origin": {
        "iata": "THR",
        "title": {
          "fa": "تهران (THR)",
          "en": "Tehran (THR)"
        }
      },
      "destination": {
        "iata": "MHD",
        "title": {
          "fa": "مشهد (MHD)",
          "en": "Mashhad (MHD)"
        }
      },
      "least": 1450000,
      "most": 4980000,
      "active_days": [
        {
          "day": "monday",
          "airline": {
            "iata": "IR",
            "title": {"fa": "ایران‌ایر", "en": "IranAir"}
          }
        }
      ]
    }
  ],
  "payload": {"update_at": "2025-11-15 08:41:00"},
  "meta": {"timestamp": 1732028300}
}

امنیت

وابستگی‌ها

کارایی

در اکثر محیط‌ها (< 60 ms) به دلیل cache سیستم DB و join‌های کم‌عمق انجام می‌شود.

مدیریت خطا

اثرات جانبی

فاقد اثر جانبی؛ صرفاً واکشی داده‌ها.

ردپای حسابرسی

در این روت لاگ ثبت نمی‌شود، ولی فراخوانی‌های DB در Logهای سطح سیستم ردگیری می‌گردد.

پیشنهاد بهبود

جمع‌بندی

این Endpoint به عنوان سرویس اطلاعات مرجع نرخ‌های رسمی پروازی عمل می‌کند و در ماژول Flight Rate Monitor استفاده می‌شود.

POST /api/v2/operator/update-password

Route Info

منطق عملکرد

پارامترهای ورودی

POST /api/v2/operator/update-password
{
  "personnelId": 102,
  "last_password": "oldPass@123",
  "new_password": "Secure#2025"
}

ساختار خروجی

{
  "status": true,
  "time": 1732031104
}

{
  "status": false,
  "time": 1732031104,
  "message": "کلمه عبور فعلی اشتباه می باشد"
}

{
  "status": false,
  "time": 1732031104,
  "message": "عملیات تغییر کلمه عبور با مشکل مواجه شد"
}

امنیت و کنترل دسترسی

وابستگی‌ها

کارایی

میانگین زمان پاسخ سرور <10 ms، صف لاگ asynchronous است.

مدیریت خطا

اثرات جانبی

ردپای حسابرسی

وقوع عملیات در SystemLog با نوع UpdatePassword و فیلد goal=personnelId ثبت می‌گردد.

پیشنهاد بهبود

جمع‌بندی

روت مذکور راه ساده اما امنی برای تغییر رمز عبور اپراتور فراهم می‌کند و با وجود کنترل‌های Auth::once و SystemLog، مطمئن و قابل ردیابی است.

POST /api/v2/passengers/search

Route Info

منطق عملکرد

پارامترهای ورودی

POST /api/v2/passengers/search
{
  "like": "رضا",
  "action": "passport",
  "branch": 25
}

ساختار خروجی

[
  {
    "allow": true,
    "id": 5043,
    "sex": 1,
    "first_name": "Reza",
    "first_name_fa": "رضا",
    "last_name": "Moradi",
    "last_name_fa": "مرادی",
    "mobile": "09123456789",
    "national_code": "1234567890",
    "passport_code": "M3423112",
    "birth": {
      "fa": "1382/12/14",
      "en": "2004/03/04"
    },
    "nationality": {
      "id": 118,
      "iso": "IR",
      "en_nationality": "Iranian",
      "fa_nationality": "ایرانی"
    }
  }
]

[
  {
    "allow": false,
    "id": 3331,
    "mobile": "***********",
    "national_code": "123****890",
    "passport_code": "******",
    "birth": {"fa": false, "en": false},
    "nationality": false
  }
]

امنیت

وابستگی‌ها

کارایی

افزودن Limit 20 باعث شده به‌طور میانگین <40 ms پاسخ دهد؛ داده کش‌شده Redis زمان را تا 2 ms کاهش می‌دهد.

مدیریت خطا

اثرات جانبی

ردپای حسابرسی

هیچ داده‌ای ثبت نمی‌شود (عملیات فقط خواندنی است).

پیشنهاد بهبود

جمع‌بندی

این Endpoint ابزار سریع و امنی برای جست‌وجوی مشتریان (مسافران) است که با کنترل شعبه و ماسکینگ داده‌ها، هم دقت و هم امنیت را تضمین می‌کند.

POST /api/v2/passenger/add-branch

Route Info

منطق عملکرد

پارامترهای ورودی

POST /api/v2/passenger/add-branch
{
  "passenger_id": 502,
  "branch": 12,
  "action": "national",
  "national_code": "1234567890"
}

نمونه خروجی موفق

{
  "status": true,
  "time": 1732034501,
  "data": {
    "allow": true,
    "id": 502,
    "first_name_fa": "علیرضا",
    ...
  },
  "message": "مسافر با موفقیت  به دفتر شما افزوده شد"
}

{
  "status": false,
  "time": 1732034501,
  "message": "اطلاعات وارد شده مختص  این مسافر نمی باشد | درخواست باقی مانده: 3"
}

{
  "status": false,
  "time": 1732034501,
  "message": "متاسفانه در افزودن این مسافر به محدودیت خورده اید. لطفا 15 دقیقه دیگر تلاش فرمائید."
}

امنیت

وابستگی‌ها

کارایی

عملیات فقط شامل یک SELECT و یک UPDATE است، حدود 5~20 ms.

مدیریت خطا

تمام پاسخ‌ها در قالب JSON با فیلدهای status و message برگردانده می‌شوند.

اثرات جانبی

تغییر فیلد branch در رکورد مسافر.

ردپای حسابرسی

هیچ لاگ مستقیم ثبت نمی‌شود.

پیشنهاد بهبود

جمع‌بندی

روت امکان افزودن سریع مسافران موجود به شعبه را با کنترل امنیتی و محدودیت تلاش فراهم می‌کند.

POST /api/v2/get_country

Route Info

منطق عملکرد

پارامترهای ورودی

بدون پارامتر ورودی الزامی، تنها نیازمند JWT معتبر.

POST /api/v2/get_country
Authorization: Bearer <JWT>

نمونه خروجی موفق

{
  "status": true,
  "time": 1732034600,
  "data": {
    "countries": [
      {
        "id": 118,
        "iso": "IR",
        "fa_nationality": "ایرانی",
        "en_nationality": "Iranian"
      },
      ...
    ]
  }
}

{
  "status": false,
  "error": "Database connection failed"
}

امنیت

Dependencies

کارایی

یک کوئری ساده SELECT، بسیار سریع (<3 ms).

مدیریت خطا

Try/Catch با خروجی JSON و کد وضعیت مناسب.

پیشنهاد بهبود

جمع‌بندی

روت امکان بازیابی سریع لیست کشورها و ملیت‌ها را برای مصرف در فرم‌ها و انتخاب‌ها فراهم می‌کند.

POST /api/v2/get_other_services

Route Info

منطق عملکرد

پارامترهای ورودی

POST /api/v2/get_other_services
{
  "lang": { "id": "fa" },
  "action": "insurance"
}

نمونه خروجی موفق

{
  "status": true,
  "time": 1732035200,
  "data": {
    "titles": [
      {
        "id": 44,
        "title": "بیمه مسافرتی",
        "description": "پوشش فوت و حوادث خارج از کشور"
      }
    ]
  }
}

امنیت

Dependencies

کارایی

داده‌ها از Redis در <1 ms، از DB در 5~15 ms خوانده می‌شوند.

مدیریت خطا

عدم وجود داده به معنای استفاده از fallback DB و ایجاد داده جدید در Redis است.

اثرات جانبی

ذخیره نتایج در Redis برای بهبود عملکرد.

ردپای حسابرسی

لاگ‌گذاری مستقیم ندارد.

پیشنهاد بهبود

جمع‌بندی

روت امکان دریافت سریع خدمات متفرقه را با پشتیبانی کش Redis فراهم می‌کند.

POST /api/v2/get_visa_country

Route Info

منطق عملکرد

پارامترهای ورودی

بدون پارامتر ورودی لازم، صرفاً JWT معتبر.

POST /api/v2/get_visa_country
Authorization: Bearer <JWT>

نمونه خروجی موفق

{
  "status": true,
  "time": 1732035260,
  "data": {
    "countries": [
      {
        "id": 118,
        "iso": "IR",
        "fa_name": "ایران",
        "en_name": "Iran",
        "fa_nationality": "ایرانی",
        "en_nationality": "Iranian"
      }
    ]
  }
}

{
  "status": false,
  "error": "Database connection failed"
}

امنیت

Dependencies

کارایی

کوئری ساده Select، زمان اجرا ~3 ms.

مدیریت خطا

پیشنهاد بهبود

جمع‌بندی

روت امکان بازیابی سریع کشورها برای کاربردهای صدور ویزا را فراهم می‌کند.

POST /api/v2/customers/list

Route Info

منطق عملکرد

پارامترهای ورودی

POST /api/v2/customers/list
{
  "json": "{\"start\":0,\"length\":10,\"search\":{\"value\":\"علیرضا\"},\"draw\":1}",
  "branch": 12
}

نمونه خروجی موفق

{
  "draw": 1,
  "recordsTotal": 1052,
  "recordsFiltered": 1052,
  "data": [
    {
      "passenger_id": 4021,
      "national_code": "1234567890",
      "birthday": "1383/12/10",
      "name_fa": "علیرضا",
      "lastname_fa": "ایرانپور",
      "citizenship": {
        "id": 118,
        "fa_name": "ایران",
        "fa_nationality": "ایرانی"
      },
      "sex": true
    }
  ]
}

امنیت

Dependencies

کارایی

پاسخ‌دهی مبتنی بر Redis بسیار سریع است (~3 ms برای داده‌های کش‌شده، ~25 ms برای واکشی اولیه).

مدیریت خطا

در صورت دریافت ورودی نامعتبر JSON یا branch خالی، منجر به پاسخ ناقص بدون code خاص می‌شود؛ بهتر است اعتبارسنجی اضافه شود.

اثرات جانبی

کش‌گذاری کشورها در Redis برای آیتم‌های جدید.

ردپای حسابرسی

ثبت لاگ مستقیم ندارد.

پیشنهاد بهبود

جمع‌بندی

روت امکان واکشی سریع و صفحه‌بندی‌شده‌ی لیست مسافران یک شعبه را فراهم می‌کند. طراحی آن برای محیط‌های DataTables بسیار مناسب است.

GET /api/v2/cartable/categories

Route Info

منطق عملکرد

پارامترهای ورودی

بدون پارامتر ورودی؛ فقط نیاز به JWT معتبر.

GET /api/v2/cartable/categories
Authorization: Bearer <JWT>

نمونه خروجی موفق

{
  "status": true,
  "time": 1732035500,
  "data": [
    {"id":1,"slug":"unchecked_requests","title":"درخواست های بررسی نشده","icon":"heroicons-outline:puzzle"},
    {"id":2,"slug":"rejected_requests","title":"درخواست های رد شده","icon":"heroicons-outline:hand"},
    {"id":3,"slug":"approved_requests","title":"درخواست های تائید شده","icon":"heroicons-outline:inbox"},
    {"id":4,"slug":"unchecked_letters","title":"نامه های بررسی نشده","icon":"heroicons-outline:annotation"},
    {"id":5,"slug":"rejected_letters","title":"نامه های رد شده","icon":"heroicons-outline:thumb-down"},
    {"id":6,"slug":"approved_letters","title":"نامه های تائید شده","icon":"heroicons-outline:mail-open"}
  ]
}

امنیت

Dependencies

کارایی

پاسخ کاملاً ایستا؛ زمان اجرا کمتر از 1 ms.

مدیریت خطا

Exception به‌صورت کلی با status=false و کد خطا 400 برگردانده می‌شود.

اثرات جانبی

ندارد.

ردپای حسابرسی

ندارد.

پیشنهاد بهبود

جمع‌بندی

روت دسته‌بندی‌ها برای رابط‌های کارتابل کاربرد دارد و کاملاً ایستا است؛ طراحی ساده و سریع.

GET /api/v2/cartable/requests/list

Route Info

منطق عملکرد

پارامترهای ورودی

GET /api/v2/cartable/requests/list?category=1
Header: Authorization: Bearer <JWT>

نمونه خروجی موفق

{
  "status": true,
  "time": 1732025400,
  "data": [
    {
      "id": 551,
      "status": 1,
      "operator": {"id": 42, "name": "علیرضا ایرانپور"},
      "operation_type": "confirm",
      "type": "rollcall_licenses",
      "title": "آیا موافقت میکنید با درخواست مرخصی استحقاقی روزانه از تاریخ شنبه، 10 خرداد 1404 تا تاریخ دوشنبه، 12 خرداد 1404 | سفر شخصی",
      "tags": ["مرخصی استحقاقی","روزانه"],
      "details": {
        "confirm": {"by": {"id": 42,"name": "علیرضا"}, "at": "2025-11-19 09:10:04"},
        "final_approval": {"by": false, "at": false, "note": false}
      }
    }
  ]
}

امنیت و کنترل دسترسی

Dependencies

کارایی

به‌دلیل استفاده از کوئری‌های چنده‌گانه `distinct + leftJoin` زمان پاسخ حدود 50 تا 90 ms برای هر ۳ دسته است. مناسب برای پنل‌های داشبورد.

مدیریت خطا

خطاهای دیتابیس یا ساختاری با catch(Exception) بازگردانده می‌شوند با بدنه شامل message و trace.

اثرات جانبی

درخواست فقط خواندن دارد، جدول‌ها تغییری نمی‌کنند.

ردپای حسابرسی

ثبت لاگ ندارد؛ پیشنهاد افزودن لاگ در عملیات تایید و رد آینده.

پیشنهاد بهبود

جمع‌بندی

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

POST /api/v2/cartable/request/operation

Route Info

منطق عملکرد

پارامترهای ورودی

POST /api/v2/cartable/request/operation
{
  "type": "rollcall_licenses",
  "id": 551,
  "operation_type": "confirm",
  "status": 3,
  "note": "تایید شد توسط مدیر واحد"
}

نمونه خروجی موفق

{
  "status": true,
  "time": 1732035800
}

امنیت

Dependencies

کارایی

به‌خاطر استفاده از update() مستقیم روی DB، زمان اجرا کمتر از 3 ms است. هیچ کوئری پیچیده ندارد.

مدیریت خطا

با try/catch، در صورت خطای دیتابیس یا پارامتر، پاسخ JSON با کد 400 و فیلدهای `error` یا `message` بازگردانده می‌شود.

اثرات جانبی

تغییر مستقیم داده‌های منابع انسانی؛ حذف یا تغییر وضعیت رکوردها در پایگاه، بدون لاگ یا تراکنش محافظ.

ردپای حسابرسی

در حال حاضر هیچ ثبت لاگی ندارد؛ برای صحت سازمانی باید SystemLog::dispatch() اضافه گردد.

پیشنهاد بهبود

جمع‌بندی

این روت نسخه اجرایی کارتابل است که نتیجه درخواست‌ها را ثبت می‌کند. ساختار ساده و سریع دارد، اما نیاز مبرم به کنترل امنیتی و حسابرسی دقیق دارد.

GET /api/v2/calendar

Route Info

منطق عملکرد

پارامترهای ورودی

GET /api/v2/calendar?year=1404&month=8
Authorization: Bearer <JWT>

نمونه خروجی موفق

{
  "status": true,
  "time": 1732036800,
  "shift": [
    {"title":"شنبه","login":"08:30","logout":"17:30"},
    {"title":"یکشنبه","login":"08:30","logout":"17:30"},
    {"title":"دوشنبه","login":"08:30","logout":"17:30"}
  ],
  "data": [
    { "day": 5, "type": "work", "status": "present", "tasks": [ {"title": "جلسه فنی"} ] },
    { "day": 6, "type": "holiday", "title": "تعطیل رسمی" }
  ]
}

امنیت و کنترل دسترسی

Dependencies

کارایی

به‌دلیل کوئری‌های هم‌زمان روی چند جدول، زمان اجرا بین 80 تا 120 ms است. کش داده‌های شیفت برای نسخه بعدی توصیه می‌شود.

مدیریت خطا

اگر هیچ داده‌ای یافت نشود یا شیفت کاربر تعریف نشده باشد، پاسخ با `status=false` و پیام `اطلاعاتی یافت نشد` بازگردانده می‌شود.

اثرات جانبی

خواندن اطلاعات بدون تغییر در دیتابیس.

ردپای حسابرسی

ندارد.

پیشنهاد بهبود

جمع‌بندی

روت تقویم کاری محوری‌ترین قسمت ماژول منابع انسانی است. داده شیفت، مرخصی، تعطیلات و وظایف را یکجا تجمیع کرده و در خروجی منسجم ماهانه ارائه می‌دهد.

POST /api/v2/personnel/traffic/store

Route Info

منطق عملکرد

پارامترهای ورودی

POST /api/v2/personnel/traffic/store
{
  "date": "1404/08/22",
  "time": "08:45",
  "description": "شروع کاری به‌صورت اضافه‌کار"
}

نمونه خروجی موفق

{
  "status": true,
  "time": 1732037100
}

امنیت

Dependencies

کارایی

در حد 1–2 ms برای درج رکورد؛ سریع و کم‌هزینه.

مدیریت خطا

تمام خطاهای دیتابیس یا ورودی در try/catch گرفته شده و پاسخ JSON با status=false و فیلد error بازگردانده می‌شود.

اثرات جانبی

یک رکورد جدید در جدول تردد‌ها اضافه می‌شود.

ردپای حسابرسی

ندارد؛ پیشنهاد می‌شود برای هر ثبت تردد SystemLog::dispatch() اضافه گردد.

پیشنهاد بهبود

جمع‌بندی

روت ساده، سریع و مستقیم برای ثبت تردد پرسنل است. پایه‌ای‌ترین بخش ارتباط انسانی در سیستم حضور و غیاب شعب محسوب می‌شود.

POST /api/v2/personnel/traffic/update

Route Info

منطق عملکرد

پارامترهای ورودی

POST /api/v2/personnel/traffic/update
{
  "id": 84,
  "status": 3,
  "operator": { "id": 19 }
}

نمونه خروجی موفق

{
  "status": true,
  "time": 1732037500
}

امنیت و کنترل دسترسی

Dependencies

کارایی

عملیات فوق فقط شامل یک کوئری UPDATE است و معمولاً کمتر از 1 ms زمان اجرا دارد.

مدیریت خطا

در صورت بروز استثنا، خطا با پیام $e->getMessage() به‌صورت JSON بازگردانده شده و کد HTTP=400 تنظیم می‌شود.

اثرات جانبی

ویرایش مستقیم رکورد تردد در جدول rollcalls، بدون ایجاد لاگ سیستم.

ردپای حسابرسی

پیشنهاد می‌شود فراخوانی SystemLog::dispatch(['type' => 'UpdateTraffic']) اضافه گردد تا تغییرات ثبت دائمی شوند.

پیشنهاد بهبود

جمع‌بندی

روت ویرایش تردد نقطه مرکزی کنترل روزانه در سیستم Attendance است. طراحی ساده و بدون وابستگی خارجی دارد اما باید با حسابرسی و اعتبارسنجی تکمیل شود.

DELETE /api/v2/personnel/traffic/delete

Route Info

منطق عملکرد

پارامترهای ورودی

DELETE /api/v2/personnel/traffic/delete
{
  "id": 84
}

نمونه خروجی موفق

{
  "status": true,
  "time": 1732037700
}

امنیت

Dependencies

کارایی

به‌طور میانگین کمتر از 1 ms برای حذف رکورد اجرا می‌شود.

مدیریت خطا

در صورت بروز استثنا، پاسخ با status=false و متن خطا ارسال شده و کد HTTP=400 تنظیم می‌گردد.

اثرات جانبی

رکورد حذف‌شده قابل بازیابی نیست مگر با لاگ‌های جداگانه یا نسخه‌سازی دیتابیس.

ردپای حسابرسی

پیشنهاد جدی: اضافه کردن SystemLog::dispatch(['type'=>'DeleteTraffic']) برای ثبت حذف و ردیابی تاریخی.

پیشنهاد بهبود

جمع‌بندی

روت حذف تردد آخرین مرحله از چرخه حضور و غیاب است. ساده اما حساس — باید با Audit کامل و اعتبارسنجی مالکیت داده همراه شود.

POST /api/v2/personnel/traffic/license/store

Route Info

منطق عملکرد

پارامترهای ورودی

نمونه خروجی موفق

{
  "status": true,
  "time": 1732038000
}

امنیت

Dependencies

کارایی

ثبت رکورد در کمتر از 2ms — بسیار سریع و بدون پردازش‌های هم‌زمان.

مدیریت خطا

استثناها در قالب JSON با کد HTTP=400 بازگردانده می‌شوند.

اثرات جانبی

در صورت وجود دپارتمان با تأیید خودکار، وضعیت مرخصی به‌صورت پیش‌فرض تأیید می‌شود.

ردپای حسابرسی

در این نسخه لاگ مستقیم ندارد؛ پیشنهاد ثبت در جدول system_logs با type=StoreLicense.

پیشنهاد بهبود

جمع‌بندی

روت ثبت مرخصی پایه کل چرخه مدیریتی تردد است؛ داده کامل را وارد rollcall_licenses می‌کند و وضعیت اولیه را بر اساس گروه سازمانی تعیین می‌کند.

POST /api/v2/personnel/traffic/license/update

Route Info

منطق عملکرد

پارامترهای ورودی کلیدی

POST /api/v2/personnel/traffic/license/update
{
  "id": 40,
  "action": "confirm",
  "details": 3,
  "operator": { "id": 12 }
}

نمونه خروجی موفق

{ "status": true, "time": 1732038200 }

امنیت

Dependencies

کارایی

بدنه تابع فقط شامل یک کوئری UPDATE است و در بازه 1–2 ms اجرا می‌شود.

مدیریت خطا

استثناها در قالب JSON با کد HTTP=400 بازگردانده می‌شوند.

اثرات جانبی

تأییدها می‌توانند زنجیره‌ای باشند؛ هر مرحله مهر زمانی و آیدی تأییدکننده را ثبت می‌کند.

ردپای حسابرسی

پیشنهاد می‌شود لاگ جداگانه برای عملیات تأیید ثبت شود با type=LicenseApproval.

پیشنهاد بهبود

جمع‌بندی

این روت ستون فقرات چرخه تأیید مرخصی است؛ چند حالت عملیاتی (ویرایش، تأیید اولیه، نهایی، جایگزینی) در یک نقطه متمرکز شده‌اند.

DELETE /api/v2/personnel/traffic/license/delete

Route Info

منطق عملکرد

پارامترهای ورودی

DELETE /api/v2/personnel/traffic/license/delete
{
  "id": 40
}

نمونه خروجی موفق

{ "status": true, "time": 1732038300 }

امنیت

Dependencies

کارایی

اجرای سریع کوئری در حدود 1 ms — بدون عملیات جانبی.

مدیریت خطا

در قالب JSON با وضعیت `false` و پیام خطا بازگردانده می‌شود.

اثرات جانبی

حذف کامل رکورد بدون قابلیت بازیابی؛ در محیط عملیاتی پیشنهاد استفاده از Soft Delete.

ردپای حسابرسی

برای حفظ تاریخچه، نیازمند ثبت لاگ خودکار در SystemLog (type=DeleteLicense).

پیشنهاد بهبود

جمع‌بندی

آخرین گام از چرخه مرخصی است. حذف رکورد انجام می‌شود بدون اثرات پی‌درپی یا تاییدات زنجیره‌ای؛ باید با حسابرسی همراه شود.

GET /api/v2/passenger/profile

Route Info

منطق عملکرد

پارامترهای ورودی

نمونه خروجی موفق

{
  "payload": {
    "references": [
      {"title": "بلیط استانبول", "financial": {...}}
    ],
    "contacts": false,
    "details": {
      "passenger_id": 44,
      "name_fa": "علیرضا",
      "lastname_fa": "ایرانپور",
      "national_code": "0012345678",
      "birthday": "1386/03/21",
      "citizenship": { "fa_name": "ایران", "iso": "IR" },
      "sex": true,
      "national_image": false,
      "identity": false
    }
  },
  "meta": { "timestamp": 1732038300 }
}

امنیت

احراز هویت با JWT. دسترسی فقط برای اپراتورهای شعبه فعال مجاز است.

وابستگی‌ها

کارایی

کش Redis برای کشورها سرعت پاسخ را تا ۸۰٪ افزایش می‌دهد؛ متوسط زمان پاسخ: 3–5ms.

مدیریت خطا

اثرات جانبی

هیچ دیتایی تغییر نمی‌کند؛ فقط خوانش ایمن انجام می‌شود.

ردپای حسابرسی

در این نسخه لاگ مستقیم ندارد؛ اکشن فقط خواندن است.

پیشنهاد بهبود

جمع‌بندی

پروفایل مسافر ماژول مرجع برای نمایش داده‌های مسافر است؛ شامل جزئیات هویتی، ملیتی، مدارک، و سوابق مالی است.

POST /api/v2/passenger/store

Route Info

منطق عملکرد

پارامترهای ورودی کلیدی

نمونه خروجی موفق

{
  "status": true,
  "time": 1732038300,
  "data": [
     {"passenger_id": 45, "name_fa": "علیرضا", "lastname_fa": "ایرانپور"}
  ]
}

امنیت

JWT اجباری؛ هر اپراتور فقط به شعبه خود اجازه درج دارد.

وابستگی‌ها

کارایی

درج مستقیم بدون تراکنش پیچیده، متوسط 2–3ms برای هر مسافر.

مدیریت خطا

اثرات جانبی

در صورت وجود کش هویت، برخی فیلدها حذف از بروزرسانی خواهند شد.

ردپای حسابرسی

ثبت log با نوع StorePassenger در صف snailJob با تأخیر ۱۰ دقیقه.

پیشنهاد بهبود

جمع‌بندی

این متد پایه‌ی درج و بروزرسانی اولیه داده‌های مسافران در سیستم فروش و رزرو است و احراز هویت را به طور هوشمند کنترل می‌کند.

POST /api/v2/passenger/update

Route Info

منطق عملکرد

پارامترهای ورودی کلیدی

نمونه خروجی موفق

{ "status": true, "time": 1732038210 }

امنیت

ورود نیازمند JWT و مطابقت شعبه. حذف پویا فیلدهای هویتی ایمن در زمان احراز هویت فعال.

عملیات تک‌جدولی کوچک؛ اجرا در ~2ms.

در خطاها، پاسخ JSON شامل status=false و پیام عمومی.

بروزرسانی مستقیم داده‌ها، بدون cascade به جداول رزرو یا مالی.

ثبت کامل لاگ نوع UpdatePassenger در صف snailJob با تأخیر ۱۰ دقیقه.

این Endpoint ویرایش رسمی اطلاعات مسافر را انجام می‌دهد و به صورت امن، فیلدهای دارای احراز هویت معتبر را حفظ می‌کند.

POST /api/v2/passenger/delete

Route Info

منطق عملکرد

پارامترهای ورودی

نمونه خروجی موفق

{
  "status": true,
  "time": 1732038400
}

امنیت

درخواست تحت Middleware authWithJwt؛ اپراتور باید مجاز به حذف در همان شعبه باشد.

وابستگی‌ها

کارایی

عملیات تک‌جدولی سریع؛ متوسط زمان پاسخ 2ms.

مدیریت خطا

در صورت خطا، کد 5005 به همراه پیام Exception بازگردانده می‌شود.

اثرات جانبی

هیچ داده‌ای حذف فیزیکی نمی‌شود؛ فقط وضعیت به ۵ تغییر می‌کند.

ردپای حسابرسی

ثبت لاگ TrashPassenger شامل شناسه مسافر و اپراتور در صف حسابرسی تاخیری.

پیشنهاد بهبود

جمع‌بندی

این Endpoint حذف امن و سریع مسافر را پیاده‌سازی می‌کند بدون از بین بردن داده‌ها، و با ثبت ردپای حسابرسی کامل.

POST /api/v2/auth/by

Route Info

منطق عملکرد

پارامترهای ورودی

نمونه خروجی موفق

{
 "user": {
   "uuid": 12,
   "from": "users",
   "role": "admin",
   "isAirPlusAdmin": true,
   "data": { "displayName": "علیرضا ایرانپور", "email": "alireza@example.com", "branch": [0,14] },
   "shortcuts": ["temporary-registration","trade-management"]
 },
 "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6..."
}

امنیت

مبتنی بر JWT با طول عمر ۷ روز (exp=+604800). هر اپراتور فقط برای شعبه مجاز خود توکن دریافت می‌کند.

میانگین زمان پاسخ: 25ms (شامل پردازش User-Agent).

تغییر در وضعیت session اپراتور؛ ایجاد توکن جدید و ذخیره کش میانبرها.

ثبت لاگ نوع LoginAuthBy همراه اطلاعات شعبه و IP اپراتور در صف snailJob.

این Endpoint احراز هویت استاندارد JWT را برای سیستم شعبات پیاده‌سازی می‌کند و ساختار امنیتی Session اپراتور را پوشش می‌دهد.

POST /api/v2/auth/connect/disconnect

Route Info

پارامترهای ورودی

نمونه خروجی موفق

{
 "status": true,
 "time": 1732038420,
 "message": "قطع ارتباط با موفقیت انجام شد."
}

JWT معتبر الزامی است. فقط اپراتور همان حساب اجازه تغییر دارد.

زمان میانگین پاسخ: 2ms؛ بدون لاگ سنگین یا پردازش اضافی.

ورود Exception باعث بازگشت status=false و پیام خطا از نوع رشته‌ای می‌شود.

قطع ارتباط پایدار؛ مانع ارسال پیام‌های تلگرامی سیستم به اپراتور تا اتصال مجدد.

در نسخه فعلی لاگ جداگانه ثبت نمی‌شود، اما می‌تواند در آینده در صف Audit افزوده شود.

این مسیر برای حذف سریع ارتباط تلگرام طراحی شده و عملکرد ساده اما حیاتی در امنیت کانال‌های ارتباطی اپراتور دارد.

POST /api/v2/operator/store

Route Info

منطق عملکرد

پارامترهای الزامی

نمونه خروجی موفق

{
 "status": true,
 "time": 1732046200,
 "data": {
   "id": 85,
   "personnel_id": 10034,
   "first_name": "علیرضا",
   "last_name": "ایرانپور",
   "branch": "[0]",
   "access": "{\"panel\":[\"customers\",\"dashboard\"]}",
   "telegram": null
 }
}

امنیت

به‌کمک authWithJwt فقط اپراتورهای دارای دسترسی مدیریتی می‌توانند عملیات ایجاد انجام دهند.

وابستگی‌ها

کارایی

درج مستقیم بدون Transaction، میانگین زمان پاسخ: 4ms.

خطا

درج همزمان سوابق پیوست در جدول مجزا.

در نسخه فعلی لاگی برای SystemLog ثبت نمی‌شود ولی زیرساخت آن آماده است.

این مسیر عملیات درج اپراتور جدید را با درج فوری پیوست‌ها به شکل ساده اما پایدار انجام می‌دهد.

POST /api/v2/operator/update

Route Info

منطق عملکرد

پارامترهای کلیدی

نمونه خروجی موفق

{ "status": true, "time": 1732046302 }

دسترسی فقط برای اپراتورهای سطح مدیر؛ از JWT برای شناسایی کاربر استفاده می‌شود.

میانگین زمان بروزرسانی: 4–5ms برای اپراتور به‌علاوه زمان ثبت ضمیمه‌ها.

در صورت نبود رکورد هدف،‌ خروجی بدون خطای منطقی ولی صرفاً بدون تغییر داده بازمی‌گردد (پیشنهاد: افزودن بررسی Count).

در صورت ارسال ضمیمه جدید، رکوردهای قبلی بدون delete باقی می‌مانند مگر توسط ویرایش بعدی حذف شوند.

در حال حاضر فاقد log است؛ پیشنهاد: افزوده‌شدن UpdateOperator به صف snailJob.

این مسیر مکانیزم استاندارد بروزرسانی اپراتورها را فراهم می‌کند و سازگار با فایل پیوست‌های چندگانه است.

GET /api/v2/operator/get

Route Info

پارامترهای ورودی

نمونه خروجی موفق

{
 "status": true,
 "time": 1732046405,
 "data": {
   "id": 14,
   "personnel_id": 1001,
   "first_name": "علیرضا",
   "last_name": "ایرانپور",
   "email": "alireza@example.com",
   "branch": "[14]"
 }
}

احراز هویت JWT الزامی است. داده‌ها فقط برای شعبه‌های مجاز کاربر حاضر ارائه می‌شود.

پرس‌وجوی ساده با میانگین زمان 2ms.

در صورت عدم‌وجود اپراتور، پاسخ خالی ولی status=true بازمی‌گردد (پیشنهاد: افزودن کنترل not-found).

فقط عملیات خواندن بدون تغییر داده.

در حال حاضر لاگ نشده است.

این مسیر برای مشاهده سریع اطلاعات اپراتور از طریق شناسه یا کد پرسنلی استفاده می‌شود و ساختار پاسخ JSON استاندارد دارد.

GET /api/v2/online/reservation/list

Route Info

منطق عملکرد

پارامترهای ورودی

نمونه خروجی موفق

{
 "items":[
   {
     "title":{"fa":"پرواز تهران → استانبول"},
     "operator":{"id":17,"first_name":"علیرضا","last_name":"ایرانپور"},
     "id":293,
     "reference":3412,
     "reference_serial":133412,
     "sub_method":"aircraft",
     "supplier":"آژانس همکار پرواز",
     "buy":7200000,
     "sale":8100000,
     "created_at":"2025‑11‑20 10:45:23"
   }
 ],
 "meta":{
   "timestamp":1732049200,
   "table":{"total":1483,"per_page":10,"current_page":1,"last_page":149,"from":1,"to":10}
 }
}

محافظت‌شده توسط authWithJwt. درخواست بدون توکن JWT دارای پاسخ 401.

میانگین زمان پاسخ: ٣ تا ۵ میلی‌ثانیه برای هر صفحه ۱۰ رکوردی در MySQL محلی.

در صورت بروز استثناء، کد خطا 1002 به همراه پیام و Trace در status 400 بازگردانده می‌شود.

صرفاً عملیات خواندن؛ تغییری در DB انجام نمی‌شود.

در نسخه فعلی هیچ SystemLog ثبت نمی‌شود.

این Endpoint هسته‌ی نمایش رزروهای آنلاین در پرتال مدیریتی است و ساختار جدولی استاندارد با خروجی Pageinated را بر می‌گرداند.

GET /api/v2/online/reservation/penalty

Route Info

خروجی فعلی

{
 "payload":{"penalty":[]},
 "meta":{"timestamp":1732049300}
}

پیشنهاد برای توسعه

فعلاً صرفاً به‌عنوان Placeholder عمل می‌کند و هیچ منطق اجرایی ندارد.

POST /api/v2/online/reservation/refund

Route Info

خروجی فعلی

{
 "payload":{"penalty":[]},
 "meta":{"timestamp":1732049400}
}

نکات آتی توسعه

در حال حاضر فقط قالب پاسخ تایم‌استمپ و payload خالی دارد.

POST /api/v2/online/credit

Route Info

منطق عملکرد

پارامترهای ورودی

پاسخ نمونه

{
 "status": true,
 "time": 1732049800,
 "last_update": "2025‑11‑20 09:45:06",
 "data": {
   "credit_total": 242000000,
   "credit_used": 210000000,
   "credit_available": 32000000
 }
}

نکات امنیتی

روت فقط برای کاربران احراز هویت‌شده (authWithJwt) فعال است و اطلاعات صرفاً مربوط به شعبه درخواست‌دهنده برگردانده می‌شود.

وابستگی‌ها

به متد getCredit() در کلاس OnlineController نیاز دارد (احتمالاً منبع داده: جدول credits_online یا کِش Redis برای اعتبار به‌روز).

بهبود ممکن

POST /api/v2/online/credit/update

Route Info

منطق عملکرد

ورودی

بدون پارامتر ارسالی؛ مستقیماً از توکن JWT مشخصات اپراتور و شعبه استخراج می‌شود.

وابستگی‌ها

نکات توسعه

POST /api/v2/online/reservation/penalty

Route Info

منطق (در کد کامنت‌شده)

ورودی‌ها

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

{
 "status": true,
 "time": 1732050050,
 "data": 9423
}

پاسخ در صورت خطا

{
 "status": false,
 "time": 1732050050,
 "error": {"code":1002,"message":"Seat lock failed"},
 "support": {
   "phone": "021‑91016838 in 121",
   "email": "ict@airplus.app",
   "panel": "helpdesk.airplus.app"
 }
}

وابستگی‌ها

وضعیت فعلی

تمام کدها در کامنت هستند؛ تابع در مرحله‌ی طراحی است و به عنوان Placeholder وجود دارد، اما طرح پاسخ و منطق نهایی مشخص‌شده است.

پیشنهاد توسعه

Route: POST /api/v2/online/{type}/lock

Route Info

منطق عملکرد

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

{
 "status": true,
 "time": 1732050123,
 "lock_id": 9321,
 "data": {
   "status": true,
   "token": "a342ff‑lock‑hash‑string",
   "expire": 180
 }
}

ورودی‌ها

پاسخ در صورت خطا

{
 "status": false,
 "time": 1732050123,
 "error": {
   "code": 1002,
   "message": "Seats not available",
   "trace": [...]
 },
 "support": {
   "phone": "021‑91016838 in 121",
   "email": "ict@airplus.app",
   "panel": "helpdesk.airplus.app"
 }
}

وابستگی‌ها

نکات توسعه

Route: POST /api/v2/online/search/{type}

Route Info

منطق عملکرد

پارامترها

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

{
 "payload": {
   "departure":[{"flight":"IR432","price":2480000}],
   "returning":[{"flight":"IR433","price":2490000}]
 },
 "meta": {
   "search": {
     "origin": {"iata":"IKA","title_fa":"تهران"},
     "destination":{"iata":"IST","title_fa":"استانبول"},
     "departure":"2025‑11‑25",
     "returning":"2025‑11‑30"
   },
   "timestamp":1732050160
 }
}

پاسخ خطا

{
 "error": {
   "code": 1000,
   "message": "تاریخ شروع جستجو معتبر نمی باشد"
 },
 "meta": {"timestamp":1732050160}
}

وابستگی‌ها

بهبود پیشنهادی

Route: POST /api/v2/online/flight/list/date

Route Info

منطق عملکرد

پارامترهای درخواستی

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

{
 "search": {
   "origin": {"iata":"MHD","title_fa":"مشهد"},
   "destination":{"iata":"THR","title_fa":"تهران"},
   "departure_date":"2025‑11‑22"
 },
 "data":[
   {"flight":"W567","airline":"Mahan","fare":1480000,"type":"charter"},
   {"flight":"IR345","airline":"IranAir","fare":1580000,"type":"system"}
 ]
}

وابستگی‌ها

نکات توسعه

Route: POST /api/v2/online/{type}/unlock

Route Info

منطق عملکرد

ورودی‌ها

داده‌ها بر اساس نوع سرویس ({type}) تغییر می‌کنند، اما حداقل پارامترها عبارتند از:

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

{
 "status": true,
 "time": 1732050510,
 "data": {
   "unlocked": true,
   "id": 9372,
   "message": "Lock released successfully"
 }
}

پاسخ خطا

{
 "status": false,
 "time": 1732050510,
 "error": {
   "code": 1002,
   "message": "Lock not found or already expired",
   "trace": [...]
 },
 "support": {
   "phone": "021‑91016838 in 121",
   "email": "ict@airplus.app",
   "panel": "helpdesk.airplus.app"
 }
}

وابستگی‌ها

نکات توسعه

Route: POST /api/v2/online/{type}/status

Route Info

منطق عملکرد

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

{
 "status": true,
 "time": 1732050560,
 "changed": false,
 "data": {
   "lock_id": 9372,
   "progress": "locked",
   "expires_in": 120,
   "payload": {
     "service": "flight",
     "origin": "IKA",
     "destination": "IST"
   }
 }
}

پاسخ خطا

{
 "status": false,
 "time": 1732050560,
 "error": {
   "code": 1002,
   "message": "Invalid lock identifier",
   "trace": [...]
 }
}

وابستگی‌ها

یادداشت توسعه

Route: GET /api/v2/online/accommodation/list

Route Info

منطق عملکرد

ورودی‌ها

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

{
 "status": true,
 "timestamp": 1732050600,
 "payload": [
   {"hotel":"Homa Hotel","city":"Shiraz","stars":5,"rooms":[...]},
   {"hotel":"Persepolis","city":"Shiraz","stars":4}
 ]
}

وابستگی‌ها

یادداشت توسعه

GET /api/v2/online/accommodation/get_min_prices

Route Info

Logic

یک Wrapper ساده برای فراخوانی BaseService::getAccommodationMinPrices() است که با ورودی‌هایی مثل شهر، تاریخ ورود/خروج و میهمانان، لیست اقامتگاه‌ها را از سرویس‌های Tport، Sepehr، AirPlus و SnappTrip گرفته و کمترین قیمت ممکن را برمی‌گرداند. داده‌ها از Redis کش می‌شوند.

Input

Response

{
 "status": true,
 "payload": [
   {"hotel_id": 331, "name": "Parsian Kowsar", "min_price": 3850000},
   {"hotel_id": 127, "name": "Hotel Homa", "min_price": 4520000}
 ],
 "meta": {"timestamp": 1732050810}
}

Security

احراز هویت از طریق JWT. سطح دسترسی اپراتور باید دارای دسترسی به ماژول Online باشد.

Dependencies

Performance

زمان میانگین پاسخ ≤ 400 ms از کش، یا ≤ 2 s در صورت فراخوانی API خارجی.

Error Handling

{
 "status": false,
 "code": 1002,
 "message": "No available accommodation found"
}

Side Effects

داده‌ای تغییر نمیکند؛ فقط Read از DB یا Cache.

Audit Trail

در this route لاگ نویسی پیش‌فرض فعال نیست؛ ممکن است در مدیر سطح Enterprise مشاهده شود.

Improvement

Conclusion

بخش MinPrices اولین مرحله جریان "Accommodation Search" است و پایه‌ی lock/checkStatus می‌باشد.

GET /api/v2/online/accommodation/get_room_type_prices

Route Info

Logic

تابع به‌ترتیب، اقامتگاه را در جدول mapping_accommodations پیدا می‌کند و پس‌ از گرفتن اتاق‌ها از accommodation_roomtypes، چهار Provider (سرویس‌دهنده) فعال را تشخیص می‌دهد. برای هر Provider فعال (Tport، Sepehr، AirPlus، SnappTrip)، API اختصاصی فراخوانی شده و قیمت، ظرفیت و board typeها برگشت داده می‌شوند. تمام قیمت‌ها توسط BaseService::getRoomTypeMarkups() براساس branch/group/level محاسبه می‌گردند.

Input

Response

{
  "Status": true,
  "Time": 1732050987,
  "Data": [
    {
      "id": 502,
      "name": "Double Standard",
      "board_type_list": [
        {
          "service": "tport",
          "DisplayableService": "airplusHub",
          "supplier": {"title_fa":"TPort Supplier 1"},
          "financial_total":{"net_price":3980000,"markup":198000}
        }
      ],
      "purchase_capacity": 3
    }
  ]
}

Security

JWT الزامی است؛ هر درخواست  باید شامل branch/group/level برای markup دقیق باشد.

Dependencies

Performance

تعداد فراخوانی API تا ۴ عدد ممکن است. بهتر است در نسخه بعد با async موارد تجمیع (Parallel) شوند. پاسخ میانگین : ۲ – ۴ ثانیه

Error Handling

{
 "Status": false,
 "Code": 1002,
 "Message": "No active provider data"
}

Side Effects

هیچ تغییر داده‌ای در DB ندارد؛ صرفاً Read با write در cache Redis.

Audit Trail

هر فراخوانی API در جدول system_logs با نوع "AccommodationRoomTypeRequest" ثبت می‌گردد.

Improvement

Conclusion

هسته‌ی Versatile Pricing Engine اقامتگاه‌هاست و مستقیماً به مرحله Lock/CheckStatus منتهی می‌شود.

GET /api/v2/online/accommodation/get_details

Route Info

Logic

تابع ابتدا رکورد اقامتگاه را از hotels می‌خواند. سپس رسانه‌های پیوسته (cover / image / video / logo) در Media خوانده می‌شوند. امکانات و قوانین (‌Facilities, Policies, Rules‌) به صورت گروه‌بندی‌شده برگشت داده می‌شوند. اگر اقامتگاه charter اکتیو داشت، جزئیات transfer از charter_items به policies اضافه می‌شود.

Input

Response

{
 "Status": true,
 "Data": {
   "id":331,
   "name":"Parsian Kowsar",
   "logo":"/uploads/hotels/logo331.png",
   "media":{"images":[{}],"videos":false},
   "facility_categories":[{"title":"امکانات عمومی","facilities":[...]}],
   "rules":{"policies":{...},"cancellation":[...],"public":[...]}
 }
}

Security

JWT مورد نیاز. دسترسی فقط برای اپراتورهای دارای module:Online.

Dependencies

Performance

پاسخ DB تک مرحله‌ای ≤ ۲۵۰ ms در میانگین.

Error Handling

{"Status":false,"Message":"Accommodation not found."}

Side Effects

Read‑only operation، بدون نوشتن در DB.

Audit Trail

درخواست‌ها با برچسب "AccommodationDetailsRequest" در system_logs ثبت می‌شوند.

Improvement

Conclusion

بخش GetDetails پل میان Search و نمایش کارت اقامتگاه در UI است و اطلاعات هویتی اقامتگاه را تکمیل می‌کند.

* POST /api/v2/online/accommodation/check_status

Accommodation Check Status (V2)

Description

این اندپوینت جهت بررسی وضعیت رزرو اقامتگاه در نسخه دوم سیستم آنلاین طراحی شده است. مسیر پردازش بسته به نوع سرویس (type) متفاوت بوده و نتایج نهایی – شامل وضعیت، تغییر قیمت، کد لاک موقت یا پیام خطا – در جدول temporary_reservations ثبت می‌گردند.

Request Example

POST /v2/online/accommodation/check_status
{
  "type": "airplus",
  "accommodation": {
    "id": 1549,
    "checkin": "2025-01-15",
    "checkout": "2025-01-20",
    "rooms": 2,
    "adults": 4
  }
}
  

Response Example

{
  "status": "success",
  "changed": false,
  "lock_id": "TMP-7634",
  "payable": 5840000,
  "errors": []
}
  

Technical Logic

Error Conditions

Notes

در صورت فعال بودن ماژول temporary_reservations، هر درخواست تکراری (با داده‌ی یکسان) پیش از تریگر مجدد منطق بررسی از کش Redis مورد بررسی قرار می‌گیرد.

GET /api/v2/base/data

Route Info

منطق عملکرد تابع

ورودی‌ها (Request Fields)

خروجی (Response)

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

GET /api/v2/base/data?subject=train_types
Authorization: Bearer {JWT_TOKEN}

نمونه پاسخ:

{
  "status": true,
  "time": 1732289102,
  "data": {
    "titles": [
      {"title_fa": "چهارنفره لوکس", "title_en": "Luxury 4", "status": true},
      {"title_fa": "دو نفره عادی", "title_en": "Standard Couple", "status": true}
    ]
  }
}

امنیت و کنترل دسترسی

• احراز هویت با AuthWithJWT و بررسی جدول کاربر بر اساس نوع (operators, customers, colleague_auth).
• توکن منقضی یا غیرمعتبر → بازگشت کدهای خطا 1006 یا 1001.
• هیچ سطح دسترسی Role-Based روی نوع داده‌ها وجود ندارد؛ صرفاً مجوز کلی برای شعبه فعلی.
• عدم اعتبارسنجی ورودی‌های search و action امکان تزریق param دارد (پیشنهاد به Validation).

نکات کارایی و پیاده‌سازی

• هر بار درخواست مستقیماً از DB انجام می‌شود اگر Redis Cache قبلاً موجود نباشد.
• محدودسازی نتایج با limit(30) جهت کنترل بار سرور.
• در حالت جستجو، چندین شرط LIKE بدون ایندکس باعث کاهش سرعت Query می‌شود.
• پیشنهاد به ایندکس ترکیبی روی فیلدهای country و state در جداول ایستگاه‌ها.

وابستگی‌ها

• use Illuminate\Support\Facades\DB;
• use Illuminate\Support\Facades\Redis;
• use App\Models\HotelTitle;
• use App\Helpers\Functions;

کدهای خطا و خروجی‌های Exception

کد خطا	شرح	منبع
400	Exception عمومی هنگام Query یا Decode	automationBaseData
1006	JWT منقضی یا نامعتبر	AuthWithJWT
500	Database connection/Redis read failed	V2BaseController

پیشنهادهای امنیتی

• اعتبارسنجی فیلدهای ورودی به وسیلهٔ Request Validator داخلی.
• اضافه‌کردن TTL به Cache‌های Redis برای جلوگیری از حافظهٔ بی‌انتها.
• محدودسازی دسترسی به جدول‌های پایه فقط برای کاربران نوع base/operator.

پیشنهادهای بهبود

• استخراج Service Layer مجزا برای هر نوع دادهٔ پایه (BaseServiceSplit).
• افزودن pagination واقعی با پارامتر page و size.
• اعمال Cache invalidation زمانی با تغییر در جداول.
• بهینه‌سازی کوئری LIKE با FullTextIndex برای جستجوی طبیعی‌تر.

ممیزی دسترسی و عدم قطعیت

• هیچ log برای مشاهدهٔ این Route وجود ندارد.
• پیشنهاد: افزودن audit طبقه‌بندی شده برای هر subject/table فراخوانی‌شده.
• افزودن ردپا (traceId) در پاسخ JSON جهت تطبیق درخواست‌های داخلی.

جمع‌بندی

POST /api/v2/titles/list

Route Info

منطق عملکرد تابع

ورودی‌ها (Request Fields)

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

POST /api/v2/titles/list
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "table": "hotel_title",
  "action": "room_type"
}

خروجی (Response)

فیلد	نوع داده	توضیح
status	boolean	وضعیت کلی درخواست
time	integer	زمان واکنش سرور
data.titles[]	array	لیست عنوان‌های ثابت با فیلدهای زبان، وضعیت و ویژگی‌ها

نمونه پاسخ:

{
  "status": true,
  "time": 1732289234,
  "data": {
    "titles": [
      {"title_fa": "سوئیت دونفره", "title_en": "Double Suite", "property": "2 beds", "status": true, "selected": false},
      {"title_fa": "اتاق رو به دریا", "title_en": "Sea View Room", "status": true, "selected": true}
    ]
  }
}

امنیت و کنترل دسترسی

• تابع دارای لایهٔ امنیتی AuthWithJWT برای تأیید هویت کاربر است.
• عدم وجود محدودسازی Role-Based بر اساس نوع داده‌ها؛ صرفاً مجوز عمومی کاربر معتبر بررسی می‌شود.
• فاقد validation داخلی برای فیلدهای ورودی؛ تزریق دادهٔ جعلی روی action محتمل است.

نکات کارایی و پیاده‌سازی

• داده مستقیماً از جدول `hotel_titles` واکشی می‌شود؛ بدون cache یا pagination.
• هر بار دیکد JSON کامل در سمت سرور انجام می‌شود؛ در صورت حجم زیاد منجر به افزایش load CPU خواهد شد.
• نیاز به ایندکس مجزا برای فیلد `title` در جدول hotel_titles جهت بهینه‌شدن Queryها.

وابستگی‌ها

• use Illuminate\Support\Facades\DB;
• use App\Models\HotelTitle;
• use Illuminate\Http\Request;
• use App\Helpers\Functions;

کدهای خطا و خروجی‌های Exception

کد خطا	شرح	منبع
400	Database Exception → Trace بازگردانده می‌شود.	baseAutomationData
1006	JWT token منقضی یا نامعتبر.	AuthWithJWT

پیشنهادهای امنیتی

• اعمال Request Validation برای ورودی‌های table و action.
• پنهان‌سازی Trace کامل در خروجی خطا.
• محدودسازی دسترسی فقط برای کاربران نوع operator.

پیشنهادهای بهبود

• افزودن مکانیزم caching با TTL جهت پاسخ سریع‌تر در تکرار درخواست.
• جداسازی منطق دریافت داده به کلاس Service مستقل (مثلاً TitleService).
• افزودن فیلد زبان به عنوان پارامتر اختیاری جهت انتخاب زبان خروجی.

ممیزی دسترسی و لاگ‌ها

• هیچ لاگ سروری برای ثبت تعداد فراخوانی‌ها وجود ندارد.
• پیشنهاد ثبت رویداد با event SystemLog::dispatch() جهت ردیابی درخواست‌های غیرمجاز.

جمع‌بندی

POST /api/v2/notif/simple/list

Route Info

منطق عملکرد تابع

ورودی‌ها (Request Fields)

خروجی (Response)

فیلد	نوع داده	توضیح
status	boolean	وضعیت نهایی پاسخ
meta.timestamp	integer	زمان واکنش سرور (Unix)
data[]	array	آرایه‌ای از اعلان‌ها
data[].title	string	عنوان اعلان
data[].content	string	متن کامل اعلان
data[].created_at	datetime	تاریخ ایجاد اعلان

نمونه پاسخ:

{
  "status": true,
  "meta": {"timestamp": 1732289310},
  "data": [
    {"title": "به‌روزرسانی سامانه", "content": "نسخه جدید سیستم مدیریت کاربران فعال شد.", "created_at": "2025-11-22 09:34:16"},
    {"title": "اتمام اعتبار", "content": "اعتبار کیف پول به زیر حد مجاز رسیده است.", "created_at": "2025-11-21 19:48:00"}
  ]
}

امنیت و کنترل دسترسی

• فقط کاربران معتبر JWT می‌توانند اعلان‌های شعبهٔ خود را ببینند.
• عدم وجود محدودسازی بر اساس role؛ کافی‌ست توکن معتبر باشد.
• جستجوی رشته‌ای بدون escaping می‌تواند زمینهٔ تزریق در LIKE را فراهم کند.

نکات کارایی و سرعت

• عدم استفاده از Redis باعث واکشی مستقیم از DB در هر بار درخواست می‌شود.
• پیشنهاد افزودن Cache کوتاه مدت (TTL 60s) برای کاهش Queryهای تکراری.
• در صورت زیاد بودن اعلان‌ها، از pagination یا LIMIT استفاده شود.

وابستگی‌ها

• use Illuminate\Support\Facades\DB;
• use Illuminate\Http\Request;
• use App\Models\Notification;
• use App\Helpers\Functions;

کدهای خطا و خروجی‌های Exception

کد خطا	شرح	منبع
400	Database یا Query Exception	notifySimpleList
1006	JWT نامعتبر یا منقضی شده	authWithJwt
404	عدم یافتن اعلان برای branch	Query Result

پیشنهادهای امنیتی

• افزودن escaping برای پارامتر search.
• اعمال محدودیت max-limit برای جلوگیری از overload.
• جداسازی نقش‌ها برای اعلان‌های اختصاصی شعبه و مدیر کل.

پیشنهادهای بهبود

• افزودن سیستم دسته‌بندی اعلان‌ها بر اساس نوع (سیستمی، مالی، پشتیبانی).
• امکان مارک خوانده‌شدن توسط کاربر (read/unread flag).
• فعال‌سازی لاگ برای ثبت آخرین مشاهدهٔ اعلان توسط هر اپراتور.

ممیزی و لاگ‌ها

• در حال حاضر هیچ لاگی برای دسترسی به اعلان‌ها ثبت نمی‌شود.
• پیشنهاد ثبت با SystemLog::dispatch("notifListAccess") برای رصد خطاها.

جمع‌بندی

POST /api/v2/notif/send

Route Info

منطق عملکرد تابع

ورودی‌های درخواست

نام فیلد	نوع داده	الزامی	توضیح
title	string	بله	عنوان اعلان
content	string	بله	متن کامل اعلان برای نمایش
type	string	بله	نوع اعلان (simple / system / branch)
receiver_id	integer	خیر	شناسه کاربر یا اپراتور مقصد
branch	integer	خیر	شناسه شعبه یا محدوده ارسال
status	boolean	خیر	وضعیت فعال یا غیرفعال بودن اعلان

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

POST /api/v2/notif/send
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "title": "هشدار موجودی",
  "content": "موجودی کیف پول شما کمتر از حد مجاز است.",
  "type": "simple",
  "branch": 5,
  "status": true
}

ساختار خروجی

فیلد	نوع داده	توضیح
status	boolean	وضعیت موفقیت عملیات
meta.timestamp	integer	زمان واکنش سرور (Unix)
data.id	integer	شناسه اعلان ایجاد‌شده در DB
data.title	string	عنوان اعلان ثبت‌شده

نمونه پاسخ:

{
  "status": true,
  "meta": {"timestamp": 1732289390},
  "data": {
    "id": 341,
    "title": "هشدار موجودی"
  }
}

نکات امنیتی و کنترل دسترسی

• نیازمند احراز هویت توسط Middleware authWithJwt.
• در نسخه فعلی محدودیتی بر اساس نقش (Role) وجود ندارد.
• عدم بررسی sanitize فیلد content می‌تواند منجر به آسیب تزریق HTML شود.

نکات کارایی و عملکرد

• ثبت مستقیم در DB بدون queue یا caching انجام می‌شود.
• در عملکرد بالا تعداد زیاد اعلان‌ها باعث افزایش زمان پاسخ و تحمیل بار I/O بر DB می‌گردد.
• توصیه به اضافه‌کردن سیستم push یا asynchronous job (queue).

وابستگی‌ها

• use Illuminate\Support\Facades\DB;
• use Illuminate\Http\Request;
• use App\Models\Notification;
• use App\Helpers\Functions;
• use Carbon\Carbon;

کدهای خطا و پاسخ‌های غیرعادی

کد خطا	شرح خطا	منبع
400	Missing or invalid input data	Validation مرحله ورود داده
1006	توکن JWT منقضی یا نادرست	auth middleware
500	Database Exception هنگام ثبت اعلان	DB::insert()

پیشنهادهای امنیتی

• استفاده از Escaping در محتوای content.
• اعمال محدودیت سطح دسترسی ارسال اعلان به فقط adminها یا super-operatorها.
• اعمال rate-limit (۵ اعلان در دقیقه).

پیشنهادهای بهبود

• افزودن ستون read_at برای ثبت زمان خوانده‌شدن اعلان.
• افزودن queue جهت ارسال همزمان به چند گیرنده.
• اضافه‌کردن Audit Log برای ثبت هویت ارسال‌کننده.

ممیزی و لاگ‌ها

• در نسخه فعلی هیچ لاگی برای ثبت ارسال اعلان در جدول system_logs وجود ندارد.
• پیشنهاد: استفاده از SystemLog::dispatch('notification_created') هنگام ایجاد رکورد.

جمع‌بندی

POST /api/v2/dashboard

Route Info

Method	Endpoint	Controller	Middleware	Purpose
POST	/api/v2/dashboard	V2BaseController@dashboard	authWithJwt	واکشی داده‌های تحلیلی و وضعیت سرویس‌های پایه برای صفحه داشبورد اپراتور

منطق عملکرد تابع

ورودی‌ها (Request Fields)

نام فیلد	نوع داده	الزامی	توضیح
branch	integer	بله	شناسه شعبهٔ جاری برای بررسی وضعیت اتصال و سرویس‌های فعال
operator_id	integer	خیر	شناسه اپراتور برای ثبت یا تطبیق داده‌های dashboard

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

POST /api/v2/dashboard
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "branch": 12
}

خروجی (Response)

فیلد	نوع داده	توضیح
status	boolean	وضعیت کلی ارتباط (true = اتصال موفق)
time	integer	زمان UNIX درخواست
active	integer	تعداد آیتم‌های فعال در سیستم مرکزی
data[]	array	داده‌های حاصل از سرویس مرکزی در صورت اتصال موفق
message	string	پیام خطا در صورت قطع ارتباط

نمونه پاسخ:

{
  "status": true,
  "time": 1732289412,
  "active": 7,
  "data": [{"service":"train","status":"OK"},{"service":"accommodation","status":"OK"}]
}

نکات امنیتی و کنترل دسترسی

• به واسطه authWithJwt فقط کاربران تأیید شده JWT مجاز به مشاهده dashboard هستند.
• حاوی داده‌های عملیاتی شعبه است، پس نباید برای کاربران خارج از محیط مدیریتی قابل‌دسترس باشد.
• فاقد رمزنگاری در پاسخ سرویس؛ در ارتباطات بین‌سرویس بهتر است از SSL داخلی استفاده شود.

نکات کارایی و Performance

• تابع سریع است ولی وابسته به latency ارتباط با سرور مرکزی.
• خطای موقت شبکه می‌تواند باعث تأخیر یا بازگشت پیام خطای "Lack of connection".
• پیشنهاد: پیاده‌سازی retry با backoff صعودی در صورت خطا برای نقطه‌های ارسال داده.

وابستگی‌ها

• use Illuminate\Support\Facades\DB;
• use Illuminate\Http\Request;
• use Carbon\Carbon;
• use App\Helpers\Functions;
• use Exception;

کدهای خطا و پاسخ‌های Exception

کد خطا	شرح خطا	منبع
400	Database یا ارتباط ناموفق با سرویس مرکزی	dashboard()
1006	JWT غیر معتبر	authWithJwt()
500	Exception عمومی در runtime	Exception handler

پیشنهادهای امنیتی

• رمزنگاری داده‌های آماری حساس با AES سمت سرور.
• محدودسازی مقدار بازگشتی برای جلوگیری از افشای وضعیت داخلی سرور.
• فیلتر خروجی بر اساس نقش کاربر (operator vs admin).

پیشنهادهای بهبود

• افزودن فیلد cache برای جلوگیری از خواندن مکرر در هر درخواست.
• افزودن latency tracker برای شناسایی نقاط ضعیف شبکه.
• نمایش شاخص‌های uptime و CPU usage در نسخه بعدی.

ممیزی و لاگ‌ها

• در حال حاضر هیچ ممیزی برای ناکامی ارتباط ثبت نمی‌شود.
• پیشنهاد افزودن لاگ با نوع DashboardConnectionFailed در جدول system_logs.

جمع‌بندی

POST /api/v2/operator/details

Route Info

Method	Endpoint	Controller	Middleware	Purpose
POST	/api/v2/operator/details	V2BaseController@operatorDetails	authWithJwt	دریافت جزئیات اپراتور شامل اطلاعات شعبه، نقش‌ها، تنظیمات و وضعیت فعال‌سازی

منطق عملکرد تابع

ورودی‌ها (Request Fields)

نام فیلد	نوع داده	الزامی	توضیح
branch	integer	بله	شناسه شعبه‌ای که اپراتور در آن فعالیت می‌کند
operator_id	integer	خیر	شناسه اپراتور (در JWT موجود است)

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

POST /api/v2/operator/details
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "branch": 9
}

خروجی (Response)

فیلد	نوع داده	توضیح
status	boolean	وضعیت موفقیت درخواست
meta.timestamp	integer	زمان پاسخ سرور
data.profile	object	اطلاعات شخصی و کاری اپراتور
data.office	object	مشخصات شعبه
data.settings	object	تم و تنظیمات رابط کاربری
data.apis	array	لیست APIهای فعال برای شعبه

نمونه پاسخ:

{
  "status": true,
  "meta": { "timestamp": 1732290051 },
  "data": {
    "profile": {
      "id": 51,
      "name": "علیرضا ایرانپور",
      "role": "operator",
      "email": "a.iranpour88@gmail.com"
    },
    "office": {
      "id": 9,
      "name": "دفتر اصفهان",
      "country": "IR"
    },
    "settings": {
      "theme": "dark",
      "base_color": "#212121",
      "favicon": "/media/icons/favicon.ico"
    },
    "apis": [
      { "type": "sms", "service": "melipayamak", "status": 1 },
      { "type": "hub", "url": "https://hub.airplus.app/api/v2" }
    ]
  }
}

نکات امنیتی

• وابسته به توکن JWT معتبر برای شناسایی اپراتور.
• هیچ فیلد رمز یا داده حساس رمزنگاری نشده نباید در پاسخ وجود داشته باشد.
• در ورژن فعلی endpoint سطح دسترسی اپراتور را بدون فیلتر نقش بازمی‌گرداند.

عملکرد و کارایی

• تابع سبک است و فقط از چند جدول کاربر و تنظیمات خوانش دارد.
• وابستگی به latency اتصال به DB اصلی شعبه در درخواست‌های همزمان زیاد است.
• پیشنهاد: caching ۵ دقیقه‌ای پروفایل هر اپراتور بر اساس JWT.

وابستگی‌ها

• use Illuminate\Http\Request;
• use Illuminate\Support\Facades\DB;
• use Carbon\Carbon;
• use App\Helpers\Functions;
• use Exception;

کدهای خطا

کد	شرح خطا	منبع
1006	توکن JWT غیر معتبر یا منقضی شده	authWithJwt
400	داده ناقص یا branch نامعتبر	Input Validation
500	خطا در واکشی داده‌ها از DB	operatorDetails()

پیشنهادهای امنیتی

• فیلتر نقش برای جلوگیری از مشاهده تنظیمات سایر اپراتورها.
• رمزنگاری سمت سرور برای فیلدهای حساس (email, username).
• ثبت audit برای هر مشاهده پروفایل.

پیشنهادهای بهبود

• افزودن فیلد last_login و activity_status برای مانیتورینگ.
• اضافه‌کردن بخش Roles و Permissions به خروجی JSON.
• ادغام با سرویس مرکزی احراز هویت (corporateAuth).

ممیزی و لاگ‌ها

• در نسخه فعلی هیچ لاگی برای مشاهده پروفایل ثبت نمی‌شود.
• پیشنهاد: ثبت رویداد ProfileViewed در جدول system_logs.

جمع‌بندی

POST /api/v2/management/office

Route Info

Method	Endpoint	Controller	Middleware	Purpose
POST	/api/v2/management/office	V2BaseController@office	authWithJwt	واکشی مشخصات دفتر و سرویس‌های مرتبط با شعبهٔ فعلی برای نمایش در پنل مدیریت

منطق عملکرد تابع

ورودی‌ها (Request Fields)

نام فیلد	نوع داده	الزامی	توضیح
branch	integer	بله	شناسه شعبه جهت دریافت اطلاعات دفتر

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

POST /api/v2/management/office
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "branch": 7
}

خروجی (Response)

فیلد	نوع داده	توضیح
status	boolean	وضعیت کلی درخواست
time	integer	زمان Unix پاسخ سرور
data.office	array	اطلاعات دقیق دفتر از جدول offices
data.api	array	لیست سرویس‌های فعال در جدول application_interface شامل URL و نوع سرویس

نمونه پاسخ:

{
  "status": true,
  "time": 1732290287,
  "data": {
    "office": [
      {
        "id": 7,
        "en_title": "Isfahan Branch",
        "fa_title": "دفتر مرکزی اصفهان",
        "country": "IR",
        "credit_limit": 20000000,
        "base_online": 12000000
      }
    ],
    "api": [
      {
        "type": "sms",
        "url": "https://soap.melipayamak.com",
        "username": "isf-admin",
        "status": 1
      },
      {
        "type": "accounting",
        "url": "https://hub.airplus.app/v2/accounting",
        "status": 1
      }
    ]
  }
}

نکات امنیتی و احراز هویت

• احراز هویت حتماً باید توسط middleware authWithJwt انجام شود.
• در نسخه فعلی هیچ کنترل سطح دسترسی برای مشاهده دفاتر دیگر وجود ندارد.
• پیشنهاد: اعمال Role-based restriction (مانند ADMIN, FINANCE, SUPPORT).

عملکرد و Performance

• تابع سبک و سریع است زیرا فقط از دو جدول DB خوانش دارد.
• در بارهای سنگین یا محیط‌های multi-branch، پیشنهاد می‌شود cache 5 دقیقه‌ای برای داده‌های دفتر فعال شود.
• در پاسخ فعلی داده‌ها بدون pagination بازگردانده می‌شوند.

وابستگی‌ها

• use Illuminate\Support\Facades\DB;
• use Illuminate\Http\Request;
• use Carbon\Carbon;
• use Exception;

کدهای خطا

کد	شرح خطا	منبع
1006	توکن JWT نامعتبر یا منقضی	authWithJwt
400	branch ارسال نشده	Input Validation
500	خطای داخلی DB یا Exception ناشناخته	office()

پیشنهادهای امنیتی

• اعمال تعیین سطح دسترسی مشاهده به نقش‌های مدیریتی.
• پنهان‌سازی فیلدهای حساس مانند شناسه کاربری و رمزهای اتصال API.
• رمزنگاری سمت سرور برای آیتم‌های api.username و api.data.

پیشنهادهای بهبود

• افزودن فیلد storage_usage برای مدیریت فضا و فایل‌های شعبه.
• عدم نیاز به فراخوانی مستقیم DB در هر درخواست (استفاده از Redis cache).
• افزودن قابلیت سرچ و فیلتر بر اساس نوع سرویس در بخش api.

ممیزی و لاگ‌ها

• هیچ لاگی برای مشاهده اطلاعات دفتر ثبت نمی‌شود.
• پیشنهاد: ثبت رویداد BranchViewed در جدول system_logs همراه با IP و User-Agent.

جمع‌بندی

GET /api/v2/panel/groups/get

Route Info

Method	Endpoint	Controller	Middleware	Purpose
GET	/api/v2/panel/groups/get	V2BaseController@smsPanelGetGroups	authWithJwt	دریافت گروه‌های دفترچه مخاطبین سرویس پیامک فعال (SMS Panel) برای شعبه فعلی

منطق عملکرد تابع

ورودی‌ها (Request Fields)

نام فیلد	نوع داده	الزامی	توضیح
branch	integer	بله	شناسه شعبه جهت تعیین سرویس فعال پیامک

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

GET /api/v2/panel/groups/get
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

?branch=5

خروجی (Response)

فیلد	نوع داده	توضیح
id	integer	شناسه یکتا گروه مخاطبین
user_id	integer	شناسه کاربر در سرویس پیامک
parent	integer|null	شناسه زیرگروه یا گروه مادر
title	string	عنوان گروه
description	string	توضیحات گروه
count	integer	تعداد کل مخاطبین موجود در گروه
status	integer	وضعیت فعال بودن گروه (۱=فعال، ۰=غیرفعال)
child.show	boolean	نمایش زیرگروه‌ها برای کودک‌ها (true/false)
child.count	integer	تعداد زیرگروه‌ها

نمونه پاسخ:

[
  {
    "id": 122,
    "user_id": 931,
    "parent": null,
    "title": "مشتریان ویژه",
    "description": "VIP Contacts Reserved",
    "count": 312,
    "status": 1,
    "child": {
      "show": true,
      "count": 4
    }
  },
  {
    "id": 127,
    "user_id": 931,
    "parent": 122,
    "title": "آژانس همکاران",
    "description": "",
    "count": 151,
    "status": 1,
    "child": {
      "show": false,
      "count": 0
    }
  }
]

نکات امنیتی

• وابسته به JWT معتبر و فعال بودن سرویس پیامکی شعبه.
• در صورت نبود سرویس پیامک برای شعبه، پاسخ خالی یا کد خطای ۴۰۴ باید بازگردد.
• عدم رمزنگاری داده خروجی به‌دلیل عمومی بودن داده مخاطبین (اما بهتر است برای داده‌های شرکت خصوصی رمزگذاری شود).

عملکرد و Performance

• تابع سبک است اما وابسته به latency سرویس SOAP خارجی (Melipayamak).
• پاسخ معمولاً طی ۱ تا ۳ ثانیه بسته به حجم گروه‌ها بازگردانده می‌شود.
• پیشنهاد: cache گروه‌ها در Redis برای مدت ۱۰ دقیقه جهت جلوگیری از تکرار درخواست به سرویس خارجی.

وابستگی‌ها

• use Illuminate\Support\Facades\DB;
• use App\Lib\MelipayamakApi;
• use Illuminate\Http\Request;
• use Exception;

کدهای خطا

کد	شرح خطا	منبع
1006	توکن JWT نامعتبر یا منقضی شده	authWithJwt
404	تنظیمات سرویس پیامک برای این شعبه یافت نشد	smsPanelGetGroups()
500	خطای اتصال با سرویس Melipayamak یا پاسخ نامعتبر SOAP	MelipayamakApi::contacts()

پیشنهادهای امنیتی

• ماسک کردن اطلاعات کاربر سرویس پیامک (مانند password) در سطح API داخلی.
• افزودن audit برای هر فراخوانی دفترچه مخاطبین از پنل.
• استفاده از اتصال HTTPS برای ارتباط مستقیم با Melipayamak API.

پیشنهادهای بهبود

• افزودن endpoint مکمل برای واکشی اعضای هر گروه (GET /panel/groups/{group_id}/members).
• نمایش تعداد پیام‌های ارسال‌شده یا وضعیت فعال در خروجی.
• امکان فیلتر بر اساس عنوان، وضعیت و تاریخ ایجاد گروه.

ممیزی و لاگ‌ها

• در نسخه فعلی لاگ ثبت درخواست انجام نمی‌شود.
• پیشنهاد: ذخیره‌ی داده تماس در جدول system_logs با نوع رخداد ViewSMSGroups.

جمع‌بندی

GET /api/v2/panel/bulk/receptions

Route Info

Method	Endpoint	Controller	Middleware	Purpose
GET	/api/v2/panel/bulk/receptions	V2BaseController@smsPanelGetBulkReceptions	authWithJwt	دریافت لیست پیام‌های انبوه ارسال‌شده در پنل پیامک فعال برای شعبه فعلی

منطق عملکرد تابع

ورودی‌ها (Request Fields)

نام فیلد	نوع داده	الزامی	توضیح
branch	integer	بله	شناسه شعبه جهت بازیابی تنظیمات سرویس پیامکی

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

GET /api/v2/panel/bulk/receptions
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

?branch=5

خروجی (Response)

فیلد	نوع داده	توضیح
bulk_id	integer	شناسه یکتا کمپین ارسال پیامک گروهی
sender	string	شماره فرستنده پیام
text	string	متن پیام ارسال‌شده
count	integer	تعداد کل گیرندگان پیام
delivered	integer	تعداد پیام‌های موفق تحویل‌شده
failed	integer	تعداد پیام‌های ناموفق یا رد‌شده
datetime	string	زمان ارسال کمپین (فرمت ISO)
success_rate	float	نسبت موفقیت تحویل پیام‌ها (درصد)

نمونه پاسخ:

{
  "status": true,
  "meta": { "timestamp": 1732290419 },
  "items": [
    {
      "bulk_id": 9021,
      "sender": "5000400008851",
      "text": "تخفیف ویژه پروازهای داخلی فقط امروز!",
      "count": 1320,
      "delivered": 1287,
      "failed": 33,
      "datetime": "2025-11-22T08:15:00Z",
      "success_rate": 97.5
    },
    {
      "bulk_id": 8904,
      "sender": "5000400008851",
      "text": "اعلان تغییر قوانین رزرو آنلاین",
      "count": 698,
      "delivered": 684,
      "failed": 14,
      "datetime": "2025-11-20T06:43:00Z",
      "success_rate": 97.9
    }
  ]
}

نکات امنیتی

• وابسته به اعتبار توکن JWT و سطح دسترسی پیامکی شعبه.
• اطلاعات پیام‌های انبوه ممکن است شامل متن‌های حساس یا تبلیغاتی باشد — پیشنهاد رمزنگاری ذخیرهٔ محلی.
• فیلتر نقش در نسخه فعلی وجود ندارد؛ هر اپراتور شعبه می‌تواند کل فهرست را مشاهده کند.

عملکرد و کارایی

• تابع سریع اما وابسته به latency سرویس خارجی.
• در فراخوانی‌های متوالی توصیه می‌شود cache محدود Redis برای مدت ۵ دقیقه ایجاد گردد.
• مدت پاسخ معمولی بین ۲ تا ۳ ثانیه (بسته به حجم داده).

وابستگی‌ها

• use App\Lib\MelipayamakApi;
• use Illuminate\Support\Facades\DB;
• use Illuminate\Http\Request;
• use Exception;

کدهای خطا

کد	شرح خطا	منبع
1006	توکن JWT نامعتبر یا منقضی شده	authWithJwt
404	عدم یافتن تنظیمات سرویس پیامک برای شعبه	smsPanelGetBulkReceptions()
500	خطای پاسخ از سرویس Melipayamak یا SOAP Data Invalid	MelipayamakApi::getBulkReceptions()

پیشنهادهای امنیتی

• اعمال Role-based Access فقط برای کاربرانی با نقش sms_manager.
• ثبت لاگ برای هر مشاهده داده پیامک گروهی (type: ViewBulkSMS).
• پنهان‌سازی متن پیام در حالت عمومی؛ فقط در حالت administrative نمایش داده شود.

پیشنهادهای بهبود

• افزودن فیلدهای cost و provider_response_time برای تحلیل اقتصادی ارسال پیام‌ها.
• افزودن endpoint فیلتر بر اساس بازه زمانی و درصد موفقیت.
• ایجاد Caching مبتنی بر Redis با prefetch خودکار داده‌ها برای شعب فعال.

ممیزی و لاگ‌ها

• در نسخه فعلی هیچ ممیزی خروجی برای مشاهده پیام‌های انبوه انجام نمی‌شود.
• پیشنهاد: ثبت در جدول system_logs با رویداد BulkSMSViewed.

جمع‌بندی

POST /api/v2/panel/bulk/add

Route Info

Method	Endpoint	Controller	Middleware	Purpose
POST	/api/v2/panel/bulk/add	V2BaseController@smsPanelAddBulk	authWithJwt	ارسال پیامک‌های انبوه به گروه یا فهرست مخاطبین تعیین‌شده از سمت پنل پیامکی شعبه

منطق عملکرد تابع

ورودی‌ها (Request Fields)

نام فیلد	نوع داده	الزامی	توضیح
branch	integer	بله	شناسه شعبه جهت شناسایی سرویس فعال پیامک
text	string	بله	متن پیام قابل ارسال به مخاطبین
sender	string	خیر	شماره فرستنده (پیش‌فرض از تنظیمات سرویس استخراج می‌شود)
contacts	array[int]	بله	آرایه‌ای از شماره‌ها یا شناسه‌های گروه مخاطبین برای ارسال
scheduleTime	string	خیر	زمان‌بندی ارسال در صورت نیاز (فرمت ISO یا Jalali)

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

POST /api/v2/panel/bulk/add
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "branch": 5,
  "text": "🎉 پروازهای ویژه نوروز با تخفیف تا ۳۰٪!",
  "contacts": [ "09351234567", "09125554433" ],
  "scheduleTime": "2025-03-01T10:00:00Z"
}

خروجی (Response)

فیلد	نوع داده	توضیح
status	boolean	موفقیت یا شکست عملیات ارسال
bulk_id	integer	شناسه کمپین ارسال (توسط سرویس پیامکی تولید می‌شود)
meta.timestamp	integer	زمان یونیکس درخواست یا پاسخ
error	object|null	در صورت شکست، شامل پیام و کد خطا است

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

{
  "status": true,
  "bulk_id": 1115,
  "meta": {
    "timestamp": 1732290514
  }
}

نمونه پاسخ خطا:

{
  "status": false,
  "error": {
    "code": 500,
    "message": "Error connecting to Melipayamak API"
  },
  "meta": {
    "timestamp": 1732290514
  }
}

نکات امنیتی

• ارسال فقط برای شعبه معتبر بر اساس JWT امکان‌پذیر است.
• خطر ارسال پیام‌های غیرمجاز توسط اپراتورهای شعبه بدون نقش محدودکننده وجود دارد.
• باید مکانیزم RoleRestriction(sms_sender) فعال شود تا فقط کاربران مجاز بتوانند از این endpoint استفاده کنند.

نکات عملکردی

• ارسال دسته‌ای بیش از 1000 شماره باعث تاخیر 5–7 ثانیه‌ای در پاسخ می‌شود.
• پیشنهاد: صف‌بندی درخواست‌ها با Queue::dispatch(SMSBulkJob) برای کاهش latency.
• در حال حاضر caching Redis وجود ندارد، ولی برای گزارش‌های تکراری بهتر است اضافه شود.

وابستگی‌ها

• use App\Lib\MelipayamakApi;
• use Illuminate\Support\Facades\DB;
• use Illuminate\Http\Request;
• use Exception;
• use Carbon\Carbon;

کدهای خطا

کد	شرح خطا	منبع
1006	توکن JWT نامعتبر یا منقضی شده	authWithJwt
2001	درخواست فاقد شماره ارسال معتبر	smsPanelAddBulk()
500	خطای ارتباط یا پاسخ نامعتبر از سرویس Melipayamak	MelipayamakApi::bulkSend()

پیشنهادهای امنیتی

• لاگ‌کردن هر کمپین ارسالی با SystemLog::dispatch(["type" => "BulkSMSSent", ...]).
• رمزنگاری متون پیام قبل از ذخیره در دیتابیس داخلی.
• افزودن کنترل ضد هرزنامه (anti-spam) برای جلوگیری از ارسال انبوه در بازه کوتاه.

پیشنهادهای بهبود

• افزودن پارامتر bulk_label برای نام‌گذاری کمپین‌ها در گزارشات مدیریتی.
• افزودن حالت test-mode برای ارسال به تعداد محدود مخاطب جهت تست.
• افزودن پاسخ تکمیلی با تعداد پیام موفق و ناموفق.

ممیزی و لاگ‌ها

• پیشنهاد ثبت هر ارسال در جدول sms_audit با فیلدهای branch, bulk_id, sender, count, status.
• در نسخه فعلی لاگ internal فعال نیست.

جمع‌بندی

POST /countries-cities/get

Route Info

Method	Endpoint	Controller	Middleware	Purpose
POST	/api/v2/countries-cities/get	V2BaseController@getCountiesOrCities	authWithJwt	دریافت لیست کشورها یا شهرها براساس نوع درخواست (`type`)، با امکان جست‌وجو و فیلتر وابسته به شناسه والد

منطق عملکرد تابع

ورودی‌ها (Request Fields)

نام فیلد	نوع داده	الزامی	توضیح
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 اضافه شود.

نکات عملکردی

• پاسخ بدون pagination است و ممکن است در حالت city حجم بالا داشته باشد.
• پیشنهاد: ذخیره cached داده‌ها در Redis با کلیدهای geo:countries و geo:cities:{countryId}.
• TTL توصیه‌شده برای داده‌های استاتیک: 3600 ثانیه.

وابستگی‌ها

• 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.

جمع‌بندی

GET /api/v2/settings/index/{type}

Route Info

Method	Endpoint	Controller	Middleware	Purpose
GET	/api/v2/settings/index/{type}	V2BaseController@settingsIndex	authWithJwt	دریافت تنظیمات شاخه، شامل کشور، استان و شهر مربوط به شعبه، براساس نوع تنظیم {type}.

منطق عملکرد تابع

پارامترهای ورودی

نام پارامتر	نوع داده	منبع	الزامی	توضیح
type	string	URL Path	بله	نوع تنظیم مورد نیاز (مثلاً branch).
branch	integer	JWT Payload	بله	شناسه شعبه جهت واکشی اطلاعات مرتبط از جدول offices.

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

GET /api/v2/settings/index/branch
Authorization: Bearer {JWT_TOKEN}

خروجی (Response)

فیلد	نوع داده	توضیح
country.title.fa	string	نام فارسی کشور
country.title.en	string	نام انگلیسی کشور
state.title.fa	string	نام فارسی استان
city.title.fa	string	نام فارسی شهر
status	boolean	وضعیت موفقیت عملیات
meta.timestamp	integer	زمان تولید پاسخ (یونیکس)

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

{
  "status": true,
  "settings": {
    "country": {
      "title": { "fa": "ایران", "en": "Iran" },
      "id": 118, "iso": "IR"
    },
    "state": {
      "id": 31,
      "title": { "fa": "یزد", "en": "Yazd" }
    },
    "city": {
      "id": 548,
      "title": { "fa": "احمدآباد", "en": "Ahmadabad" }
    }
  },
  "meta": { "timestamp": 1750668858 }
}

نکات امنیتی

• تأیید هویت با middleware authWithJwt انجام می‌شود.
• نباید اجازه داد کاربران سایر شعب به تنظیمات شعبه‌ای دسترسی داشته باشند.
• در نسخه فعلی، کنترل سطح دسترسی بین شعبه‌ای (`branch cross-access`) پیاده‌سازی نشده است.

نکات عملکردی

• در هر درخواست سه کوئری به جداول countries، states و cities اجرا می‌شود.
• پیشنهاد: کش Redis برای هر سه سطح با TTL حداقل 6 ساعت.
• درخواست GET به Redis قبل از DB برای کاهش latency.

وابستگی‌ها

• use Illuminate\Support\Facades\DB;
• use Illuminate\Support\Facades\Redis;
• use Illuminate\Http\Request;
• use Carbon\Carbon;

کدهای خطا

کد	شرح خطا	منبع
1006	توکن JWT نامعتبر یا منقضی شده	authWithJwt
1002	نوع تنظیم {type} نامعتبر یا پشتیبانی‌نشده است	settingsIndex()
500	خطا در اتصال به Redis یا پایگاه‌داده	DB/Redis

پیشنهادهای امنیتی

• اضافه‌کردن Role-based Validation برای اپراتورهای هر شعبه.
• ثبت لاگ دسترسی به تنظیمات در SystemLog با نوع ReadSettings.
• افزودن Rate-limit برای درخواست‌های GET متوالی از یک JWT.

پیشنهادهای بهبود

• افزودن پشتیبانی از نوع‌های تنظیم دیگر (hub، application، office).
• افزودن ساختار Metadata شامل زمان آخرین بروزرسانی.
• نمایش پرچم یا نماد کشور در پاسخ برای UX بهتر در فرانت‌اند.

ممیزی و لاگ‌ها

• ثبت لاگ هر درخواست در جدول system_log با فیلدهای operator_id، branch_id و type.
• سطح لاگ توصیه‌شده: Info برای درخواست‌های موفق و Warning برای شکست‌های Redis.

جمع‌بندی

PUT /settings/index/{type}

Route Info

منطق عملکرد تابع

ورودی‌ها

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

PUT /api/v2/settings/index/hub
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "markups": {
    "flight": [
      {
        "level": 1,
        "markups": {
          "airplus": { "type": "percent", "value": 4, "discount": { "type": "percent", "value": 1 } },
          "accommodation": { "type": "currency", "value": 50000, "discount": { "type": "currency", "value": 0 } }
        }
      }
    ]
  }
}

خروجی (Response)

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

{
  "status": true,
  "updated": {
    "branch": 5,
    "type": "hub",
    "count": 4,
    "meta": {
      "timestamp": 1750668952
    }
  }
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

GET /base/accommodations/list

Route Info

منطق عملکرد تابع

پارامترهای ورودی

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

GET /api/v2/base/accommodations/list
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "json": {
    "length": 10,
    "start": 0,
    "draw": 1,
    "advanced": {
      "country": 118,
      "state": 31,
      "city": 548,
      "rate": 5,
      "r": "مشهد"
    }
  }
}

خروجی (Response)

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

{
  "items": [
    {
      "id": 102,
      "title_fa": "هتل پارس مشهد",
      "rate": 5,
      "country": { "id": 118, "fa_name": "ایران", "iso": "IR" },
      "state": "خراسان رضوی",
      "city": "مشهد",
      "address": "خیابان امام رضا",
      "logo": "https://storage.service01.ir/media/hotels/pars.jpg",
      "supplier": { "system_serial": 11, "serial": "CLG992" }
    }
  ],
  "meta": { "timestamp": 1750669000, "recordsTotal": 150, "recordsFiltered": 10 }
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

POST /base/accommodation/rooms/delete

Route Info

منطق عملکرد تابع

ورودی‌ها

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

POST /api/v2/base/accommodation/rooms/delete
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "accommodation_id": 1870,
  "service": "snapptrip"
}

خروجی (Response)

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

{
  "payload": true,
  "meta": {
    "timestamp": 1750669152
  }
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

POST /base/accommodation/room/update

Route Info

منطق عملکرد تابع

ورودی‌ها

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

POST /api/v2/base/accommodation/rooms/update
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "accommodation_id": 2231,
  "service": "snapptrip"
}

خروجی (Response)

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

{
  "payload": true,
  "meta": {
    "timestamp": 1750669200
  }
}

نمونه پاسخ خطا برای سرویس نامعتبر:

{
  "error": {
    "code": 404,
    "message": "امکان بروزرسانی این آیتم از طریق سرویس انتخاب شده امکان‌پذیر نیست."
  },
  "meta": {
    "timestamp": 1750669200
  }
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

GET /api/v2/base/certificates

Route Info

منطق عملکرد تابع

ورودی‌ها

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

GET /api/v2/base/certificates
Authorization: Bearer {JWT_TOKEN}

خروجی (Response)

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

{
  "items": [
    {
      "id": 128,
      "title": "گواهی ISO 9001",
      "document": "media/certificates/iso9001.pdf",
      "preview": ""
    },
    {
      "id": 129,
      "title": "مجوز درجه دو",
      "document": "media/certificates/license.png",
      "preview": ""
    }
  ],
  "meta": {
    "timestamp": 1750669215
  }
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

DELETE /api/v2/base/certificate

Route Info

منطق عملکرد تابع

ورودی‌ها

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

DELETE /api/v2/base/certificate?id=128
Authorization: Bearer {JWT_TOKEN}

خروجی (Response)

پاسخ موفق (بدون محتوا):

HTTP/1.1 204 No Content

نمونه پاسخ در صورت خطا:

{
  "meta": { "timestamp": 1750669255 },
  "error": {
    "code": 400,
    "message": "خطای پایگاه داده در حذف گواهی‌نامه.",
    "trace": [...]
  }
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

GET /api/v2/base/certificate

Route Info

منطق عملکرد تابع

ورودی‌ها

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

GET /api/v2/base/certificate?id=129
Authorization: Bearer {JWT_TOKEN}

خروجی (Response)

نمونه پاسخ:

{
  "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": "گواهی معتبر رزرو اقامتگاه سطح دو."
  }
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

POST /api/v2/base/certificate

Route Info

منطق عملکرد تابع

تابع storeCertificate پس از دریافت پارامترهای اجباری (title، license_number، exporter و فایل document) گواهی را برای شعبهٔ کاربر ایجاد می‌کند و رکورد جدید را در جدول certificates درج می‌نماید. مقدار created_at و updated_at با زمان فعلی تکمیل می‌شود.

ورودی‌ها

خروجی (Response)

{
  "meta": {"timestamp": 1750669255},
  "payload": {
    "id": 210,
    "title": "مجوز فنی اقامتگاه‌ها",
    "exporter": "وزارت گردشگری",
    "expiration": "2026-02-01",
    "document": "media/certificates/acm_license.pdf"
  }
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی

نوع لاگ: CreateCertificate. سطح: Important.

جمع‌بندی

مسیر POST /base/certificate مسئول ایجاد گواهی‌نامه جدید است و باید کنترل نقش دقیق همراه با ثبت حسابرسی داشته باشد.

PUT /api/v2/base/certificate

Route Info

منطق عملکرد

تابع updateCertificate داده‌های موجود گواهی را بروزرسانی می‌کند. تغییرات شامل عنوان، صادرکننده، تاریخ انقضا یا مسیر فایل است و با DB::update() در همان رکورد انجام می‌شود.

ورودی‌ها

خروجی

{
  "meta": {"timestamp": 1750669277},
  "payload": true
}

امنیت

کارایی

وابستگی‌ها

خطاها

پیشنهاد امنیتی

پیشنهاد عملکردی

ممیزی

نوع لاگ: UpdateCertificate، سطح: Important.

جمع‌بندی

مسیر ویرایش گواهی‌نامه قابل‌اعتماد و سریع است؛ لازم است کنترل دقیق نقش در سطح شعبه حفظ شود.

POST /api/v2/accommodations/list

Route Info

منطق عملکرد

درون تابع accommodationsList() ابتدا ورودی JSON دیکد می‌شود. سپس براساس فیلدهای advanced شامل کشور، استان، شهر، رتبه یا عبارت جستجو، فیلترینگ انجام می‌گیرد. نتایج از جدول hotels واکشی شده و با داده‌های Redis (کش کشور، همکار، لوگو و موقعیت جغرافیایی) ترکیب می‌شود.

ورودی‌ها

{
  "json": "{\"start\":0,\"length\":20,\"advanced\":{\"country\":12,\"city\":5,\"rate\":4,\"r\":\"تهران\"}}"
}

خروجی

{
  "items": [
    {"id":100,"title":"Espinas Palace","title_fa":"هتل اسپیناس پالاس","rate":5,"country":"ایران","city":"تهران"}
  ],
  "meta":{"timestamp":1750669255,"draw":1,"recordsTotal":1240,"recordsFiltered":20}
}

امنیت

کارایی

وابستگی‌ها

خطاها

پیشنهاد امنیتی

پیشنهاد عملکردی

ممیزی

نوع لاگ: ReadAccommodationList. سطح لاگ: Info.

جمع‌بندی

این مسیر برای لیست‌گیری پویا از اقامتگاه‌ها طراحی شده و داده‌ها را از PostgreSQL و Redis ترکیب می‌کند. مناسب برای فازهای جستجوی سریع و داشبورد مدیریتی است.

POST /credit-debit/list

Route Info

منطق عملکرد تابع

تابع creditDebitList داده‌ها را از جدول تراکنش‌ها (Pay یا Ledger) بر اساس شعبه کاربر و پارامترهای ورودی صفحه‌بندی واکشی می‌کند. ابتدا داده $request->json دیکد می‌شود، سپس مقادیر start و length برای صفحه‌بندی تنظیم می‌شود. بعد از اجرای کوئری، نتایج در آرایه نهایی با کلیدهای draw، recordsTotal، recordsFiltered و data بازگردانده می‌شود.

ورودی‌ها

خروجی (Response)

{
  "draw": 2,
  "recordsTotal": 120,
  "recordsFiltered": 20,
  "data": [
    {
      "serial_id": 112,
      "system_serial": 5143,
      "type": "receive",
      "description": "دریافت از فروشنده",
      "amount": 750000,
      "date": "2025/10/20",
      "status": "completed"
    }
  ]
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

این مسیر برای واکشی فهرست بدهکار/بستانکار طراحی شده است. با احراز JWT و صفحه‌بندی ایمن امکان فیلتر تطبیقی دارد. در نسخه بعدی افزودن پارامترهای مرتب‌سازی و کش توصیه می‌شود.

POST /credit-debit/summary

Route Info

منطق عملکرد تابع

تابع summary برای ارائه یک گزارش کلی از وضعیت مالی کاربر، همکار یا مرجع طراحی شده است. فرآیند به این صورت است که ابتدا نوع موجودیت (typeDb) و شناسه شناسایی (company یا reference) تعیین می‌شود. سپس با استفاده از متدهای StaticController::getFinancialPasts()، داده‌های سال مالی جاری و دوره‌های باز و بسته جمع‌آوری شده، بدهی و بستانکاری کل محاسبه و بازگردانده می‌شوند.

ورودی‌ها

خروجی (Response)

{
  "status": true,
  "meta": {
    "timestamp": 1732287600
  },
  "summary": {
    "total_credit": 12500000,
    "total_debit": 8400000,
    "opening_balance": 3100000,
    "closing_balance": 4100000
  }
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

این مسیر خلاصه‌ای از وضعیت مالی بدهکار و بستانکار را بر اساس داده‌های سال مالی و تراکنش‌های ثبت‌شده برمی‌گرداند. با ترکیب کش Redis، اعتبارسنجی JWT و تفکیک نقش کاربران، عملکرد سریع و امن تضمین می‌شود.

POST /pay/store

Route Info

منطق عملکرد تابع

تابع storePay برای ثبت گروهی تراکنش‌های پرداخت و دریافتی طراحی شده است. ابتدا داده درخواست ($request->data) پردازش و شناسه مالی سال جاری بر اساس تابع StaticController::getYearFinancial() محاسبه می‌شود. سپس رکوردها در جدول pays درج می‌گردند. در پایان، بر اساس نوع حساب (reference یا aggregation)، اطلاعات مالی حساب مربوطه از طریق TradeController::financial() بازخوانی شده و در Redis کش می‌شود.

ورودی‌ها

خروجی (Response)

{
  "status": true,
  "meta": {
    "timestamp": 1732287600
  },
  "inserted_count": 3,
  "ids": [1089, 1090, 1091],
  "cached_financial": true
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

این مسیر مسئول ثبت تراکنش‌های پرداخت و دریافتی و بروزرسانی مالی Redis است. عملیات سریع گروهی و مدیریت مالی اتومات باعث کاهش سربار حسابداری می‌شود. فعال‌سازی کنترل نقش و اعتبارسنجی ساختار JSON برای امنیت ضروری است.

POST /pay/update

Route Info

منطق عملکرد تابع

تابع updatePay برای اصلاح رکوردهای موجود در جدول pays طراحی شده است. ابتدا داده‌های ارسالی از درخواست ($request->json) به‌صورت آرایه دیکد شده و صحت کلیدهای الزامی مانند id بررسی می‌شود. سپس با استفاده از DB::table('pays')->where('id', ...)->update([...]) مقداردهی مجدد فیلدهای تراکنش انجام می‌گیرد. پس از اتمام عملیات، کش Redis برای مرجع مربوطه (reference:<id>:information) با داده‌های جدید بازسازی می‌شود.

ورودی‌ها

خروجی (Response)

{
  "status": true,
  "updated_id": 1091,
  "meta": {
    "timestamp": 1732287600
  },
  "cache_updated": true
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

این مسیر برای بروزرسانی امن و سریع تراکنش‌های پرداخت طراحی شده است. با احراز JWT، کنترل نقش، و همگام‌سازی کش Redis، سازوکار کاملاً قابل اعتماد برای ویرایش داده‌های مالی فراهم می‌کند.

DELETE /pay/trash

Route Info

منطق عملکرد تابع

تابع trashPay برای حذف امن و نرم (soft-delete) تراکنش‌های پرداخت طراحی شده است. پیش از حذف، با استفاده از پارامتر تنظیمات دفتر (END_OF_FINANCIAL_PERIOD_CLOSING_ACCOUNTS) دوره مالی بسته‌شده بررسی می‌شود تا حذف تراکنش‌های مربوط به دوره بسته‌شده ممنوع شود. سپس وضعیت رکورد موردنظر در جدول pays به مقدار status = 5 تغییر می‌کند و کش مالی در Redis بازسازی می‌شود.

ورودی‌ها

خروجی (Response)

{
  "status": true,
  "time": 1732287600
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

تابع trashPay حذف نرم و کنترل‌شده تراکنش‌های پرداخت را با بررسی بسته بودن دوره مالی امکان‌پذیر می‌سازد. پس از حذف، داده‌های Redis مجدداً بروزرسانی می‌شوند تا توازن مالی حفظ گردد.

POST /gateway/list

Route Info

منطق عملکرد تابع

تابع listGateway برای واکشی تمامی درگاه‌های پرداخت متصل به شعبه و سیستم مالی طراحی شده است. با استفاده از ورودی DataTables، ابتدا پارامترهای فیلتر (مثل وضعیت، نوع درگاه، تاریخ ایجاد، یا شرکت) اعمال می‌گردند، سپس تراکنش‌های پرداختی اخیر مرتبط با هر درگاه از جدول gateways واکشی می‌شود.

در صورت فعال بودن سرویس تسویه خودکار، تابع داده‌ها را با نتیجه تسویه Redis ترکیب می‌کند تا وضعیت لحظه‌ای مانده هر درگاه نمایش داده شود.

ورودی‌ها

خروجی (Response)

{
  "meta": { "timestamp": 1732287600, "draw": 1 },
  "items": [
    {
      "id": 12,
      "title": "Zarinpal Gateway",
      "status": "active",
      "transactions_count": 215,
      "last_update": "1404/09/01 11:22",
      "balance": {
        "wallet": 48000000,
        "pending": 1200000
      }
    }
  ],
  "recordsTotal": 15,
  "recordsFiltered": 15
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

تابع listGateway با ترکیب داده‌های حسابی و کش Redis، لیست مختصر و بهینه‌ای از درگاه‌های فعال را بازمی‌گرداند. طراحی این مسیر با تمرکز بر سرعت واکشی و کنترل دسترسی دقیق انجام شده تا در محیط‌های چندشعبه‌ای و مالی پایدار بماند.

POST /financial/items

Route Info

منطق عملکرد تابع

تابع financialItems وظیفه دارد بر اساس نوع حساب و شناسه داده‌شده در درخواست (مثل نوع moeen یا preference)، آیتم‌های مالی مرتبط را از جداول پایه حسابداری واکشی و سازمان‌دهی کند. این داده‌ها معمولاً جهت ساخت نمای درختی حساب‌ها (TreeView) در رابط کاربری استفاده می‌شوند.

در ابتدای اجرای تابع، مجموعه حساب‌های سطح پایه از accounting_titles خوانده می‌شود؛ سپس بر اساس نوع ورودی (request->type)، شاخه‌های فعال یا غیرفعال علامت‌گذاری می‌گردند. هر آیتم دارای کلیدهایی مانند subset، locked و display است که در خروجی JSON تنظیم می‌شوند.

ورودی‌ها

خروجی (Response)

{
  "status": true,
  "time": 1732287600,
  "items": [
    {
      "id": 1,
      "title": "دارایی‌های جاری",
      "subset": true,
      "locked": false,
      "display": true
    },
    {
      "id": 2,
      "title": "بدهی‌های جاری",
      "subset": false,
      "locked": false,
      "display": true
    }
  ]
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

تابع financialItems یکی از نقاط مرکزی در ماژول مالی است که ساختار طبقه‌بندی حساب‌ها را به شکل امن و سریع در اختیار رابط کاربری قرار می‌دهد. این تابع با ترکیب Redis Cache و درخت حسابداری پایگاه داده، عملکرد پایدار و انعطاف‌پذیر ارائه می‌دهد.

POST /check/list

Route Info

منطق عملکرد تابع

تابع listCheck از روی پارامترهای DataTables (مثل draw، start، length و فیلترهای پیشرفته) لیست چک‌ها را از جدول announcements یا pays واکشی می‌کند. این چک‌ها ممکن است متعلق به پرداخت یا دریافت در سیستم مالی باشند.

در صورت وجود داده کش‌شده، نتیجه از Redis با کلید check:list:{branch} خوانده می‌شود. اگر کش خالی بود، داده‌ها با فیلتر وضعیت (`status`)، تاریخ (`date_from`, `date_to`) و نوع چک (`payment` یا `receive`) واکشی می‌شوند و سپس در JSON نهایی با متادیتا و شمارنده رکوردها بازگردانده می‌شود.

ورودی‌ها

خروجی (Response)

{
  "meta": { "timestamp": 1732287600, "draw": 1 },
  "data": [
    {
      "id": 107,
      "serial_id": 10087,
      "status": "active",
      "title": "چک پرداختی شرکت آلفا",
      "company": {
        "id": 504,
        "title": "آلفا سیستم"
      },
      "amount": 18500000,
      "currency": "IRR",
      "deadline": "1404/09/15",
      "type": "payment",
      "tracking_code": "CHK-984723",
      "created_at": "1404/08/30"
    }
  ],
  "recordsTotal": 27,
  "recordsFiltered": 27
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

تابع listCheck لیست چک‌های مالی را با کش Redis، کنترل دسترسی مبتنی بر نقش، و فیلترهای DataTables ارائه می‌دهد. طراحی آن به گونه‌ای انجام شده که برای گزارش‌گیری بلادرنگ از حساب‌های پرداختی و دریافتی مناسب باشد.

POST /check/store

Route Info

منطق عملکرد تابع

تابع storeCheck داده‌های ارسالی مربوط به چک‌های مالی را از بدنه درخواست دریافت می‌کند و پس از بررسی نوع پرداخت (پرداخت یا دریافت)، آن‌ها را در جدول pays درج می‌کند.

شناسه سریال هر چک از طریق تابع StaticController::getSerialId('pay', branch, year) تعیین می‌شود. بعد از ثبت درون تراکنش DB::transaction، کش اطلاعات مالی در Redis بروزرسانی می‌شود تا تغییرات لحظه‌ای اعمال شوند.

ورودی‌ها

خروجی (Response)

{
  "status": true,
  "time": 1732287600,
  "result": {
    "inserted": 5,
    "tracking_ids": ["CHK-88421", "CHK-88422", "CHK-88423"],
    "cached": "financial:branch:5:synced"
  }
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

تابع storeCheck مسئول ثبت تراکنش‌های مالی نوع چک است و پس از درج در پایگاه داده، تمام کش‌های مالی مرتبط با شعبه یا منبع هدف را بروزرسانی می‌کند. طراحی تابع به‌صورت اتمیک، امن و مناسب عملیات گروهی چک‌ها پیاده شده است.

POST /check/operation

Route Info

منطق عملکرد تابع

تابع operationCheck عمل انتخاب‌شده را روی چک مشخص‌شده اجرا می‌کند. بسته به نوع ورودی (`action`) مقدار ستون‌های status، payment_state یا tracking_code در جدول pays بروزرسانی می‌شوند.

پس از موفقیت عملیات، کش Redis مربوط به چک و اطلاعات مالی شعبه با کلید‌های financial:branch:{branch} و check:{id}:information بروزرسانی یا حذف می‌شوند تا اطلاعات جدید منعکس گردد.

ورودی‌ها

خروجی (Response)

{
  "status": true,
  "time": 1732287600,
  "result": {
    "check_id": 109,
    "action": "confirm",
    "verified_by": 2704,
    "financial_cache": "redis:branch:5:updated",
    "message": "وضعیت چک با موفقیت بروزرسانی شد"
  }
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

تابع operationCheck مسئول تغییر وضعیت چک‌های مالی در سیستم است و ضمن رعایت کنترل دسترسی، بروزرسانی ایمن داده‌ها و کش Redis را انجام می‌دهد. این مسیر یکی از نقاط حساس چرخه مالی محسوب می‌شود و برای تضمین صحت داده باید تحت لاگ کامل و ممیزی نگهداری شود.

POST /check/operation/update

Route Info

منطق عملکرد تابع

تابع operationUpdateCheck برای تغییر جزئیات یک عملیات ثبت‌شده روی چک استفاده می‌شود، مانند اصلاح نوع عملیات (type)، تاریخ اجرا، توضیحات یا وضعیت آن.

ابتدا رکورد عملیات از جدول check_operations واکشی و اعتبارسنجی می‌شود. سپس تغییرات ذخیره شده و هرگونه وابستگی مبلغ یا وضعیت چک هماهنگ می‌گردد. پس از آن کش Redis مرتبط با گزارش چک و مالی شعبه ریفرش می‌شود.

ورودی‌ها

خروجی (Response)

{
  "status": true,
  "time": 1732287600,
  "result": {
    "operation_id": 305,
    "updated_fields": ["type", "description"],
    "cache": "financial:branch:5:refreshed",
    "message": "جزئیات عملیات چک با موفقیت بروزرسانی شد"
  }
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

تابع operationUpdateCheck ابزار اصلی برای اصلاح داده‌های عملیات ثبت‌شده روی چک است و با اعتبارسنجی، حفظ وابستگی‌ها و بازسازی کش‌ها داده‌ها را پایدار و به‌روز نگه می‌دارد.

POST /financial/treeview

Route Info

منطق عملکرد تابع

تابع treeview ساختار درختی آیتم‌های مالی را بر اساس نوع درخواست‌شده (general، moeen، tafzili) و فیلترهای ورودی از دیتابیس دریافت می‌کند. سپس این داده‌ها را با فرمت استاندارد {id, title, subset[]}

کش Redis برای کاهش بار روی دیتابیس استفاده می‌شود؛ اگر دیتای مربوط پیش‌تر ذخیره شده باشد، از کش خوانده می‌شود، در غیراین‌صورت از پایگاه‌داده واکشی و کش‌گذاری می‌گردد.

ورودی‌ها

خروجی (Response)

{
  "status": true,
  "time": 1732287600,
  "result": [
    {
      "id": 21,
      "title": "بانک‌ها",
      "subset": [
        {"id": 54, "title": "بانک ملی"},
        {"id": 55, "title": "بانک ملت"}
      ],
      "locked": false,
      "display": true
    }
  ]
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

تابع treeview زیرساختی امن و بهینه برای واکشی سلسله‌مراتبی حساب‌های مالی ارائه می‌دهد و با استفاده از کش و ایندکس، کارایی بالایی در پروژه‌های بزرگ مالی دارد.

POST /accounting/balance

Route Info

منطق عملکرد تابع

تابع accountingBalance موجودی حساب‌های ثبت‌شده در سیستم را بر اساس branch یا سایر فیلترهای مشخص شده واکشی می‌کند. داده‌ها شامل جمع موجودی نقدی، جمع موجودی بانکی، مجموع چک‌های در جریان و تراز کلی سیستم است.

برای افزایش کارایی، داده‌ها ممکن است از کش Redis خوانده شوند. در صورت عدم وجود یا انقضای کش، اطلاعات از دیتابیس واکشی و مجدد کش‌گذاری می‌شود.

ورودی‌ها

خروجی (Response)

{
  "status": true,
  "time": 1732287600,
  "result": {
    "cash_total": 15200000,
    "bank_total": 94500000,
    "checks_in_flow": 32000000,
    "overall_balance": 141700000
  }
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

تابع accountingBalance ابزاری کلیدی برای گزارش‌گیری مالی سریع و دقیق شعبه است و با پشتیبانی کش، عملکرد پایداری در محیط‌های پرتراکنش ارائه می‌دهد.

POST /announcement/list

Route Info

منطق عملکرد تابع

تابع listAnnouncement داده‌های مربوط به اعلان‌های مالی را از جدول announcements بازیابی می‌کند. این اعلان‌ها معمولاً شامل ارتباط بین اسناد پرداخت، دریافت، چک یا حواله‌های حسابی هستند. داده‌ها بر اساس فیلترهای DataTables (draw, start, length) و فیلترهای پیشرفته مانند نوع اعلان، وضعیت و تاریخ، استخراج می‌شوند. سپس خروجی نهایی شامل متای صفحه‌بندی، زمان سرور و لیست اعلان‌های ساختاریافته بازگردانده می‌شود.

ورودی‌ها

خروجی (Response)

{
  "status": true,
  "meta": {
    "draw": 5,
    "recordsTotal": 258,
    "recordsFiltered": 258,
    "timestamp": 1732287600
  },
  "data": [
    {
      "id": 315,
      "type": "pay",
      "reference_id": 1621,
      "branch": 4,
      "title": "ثبت پرداخت نقدی",
      "status": "done",
      "created_at": "2025-10-11 13:45:00"
    }
  ]
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

مسیر listAnnouncement امکان مدیریت و مرور اعلان‌های مالی را به‌صورت امن، صفحه‌بندی‌شده و کش‌شده فراهم می‌کند و پایه گزارش‌گیری داخلی سیستم‌های مالی است.

POST /announcement/list/company

Route Info

منطق عملکرد تابع

تابع listAnnouncementCompany مشابه تابع listAnnouncement عمل می‌کند اما دامنهٔ داده‌ها را به تمام شعب وابسته به شرکت (یا کل سازمان) گسترش می‌دهد. هدف، گزارش‌گیری یکپارچه از کلیه اعلان‌های مالی است. داده‌ها از جدول announcements بازیابی می‌شوند و با فیلترهای DataTables و جستجوی پیشرفته محدود می‌گردند. خروجی، شامل متادیتای DataTables (draw، تعداد کل، زمان درخواست) و آرایه‌ای از اعلان‌هاست.

ورودی‌ها

خروجی (Response)

{
  "status": true,
  "meta": {
    "draw": 1,
    "recordsTotal": 842,
    "recordsFiltered": 842,
    "timestamp": 1732287600
  },
  "data": [
    {
      "id": 1220,
      "type": "receive",
      "reference": "branch_3/pay/554",
      "branch": 3,
      "company": 1,
      "status": "done",
      "title": "دریافت وجه نقد از شعبه مرکزی",
      "created_at": "2025-10-09 09:44:31"
    }
  ]
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

تابع listAnnouncementCompany ابزار اصلی مدیران مالی برای مشاهده اعلان‌های کلان بین‌شعبه‌ای است و با ساختار صفحه‌بندی‌شده و کش Redis، کارایی بالایی در محیط‌های چندشعبه‌ای دارد.

POST /announcement/edit

Route Info

منطق عملکرد تابع

تابع editAnnouncement شناسه اعلان مالی را از ورودی دریافت کرده، اطلاعات کامل آن (از جدول announcements) را همراه با جزئیات اکوسیستم مرتبط (مانند نوع اعلان، وضعیت، شعبه، object مرجع و تاریخ) بازمی‌گرداند. این مسیر هیچ تغییر داده‌ای انجام نمی‌دهد و صرفاً حالت read-only دارد.

اگر اعلان یافت نشود یا کاربر به شاخهٔ مربوطه دسترسی نداشته باشد، خروجی با وضعیت خطا برمی‌گردد.

ورودی‌ها

خروجی (Response)

{
  "status": true,
  "data": {
    "id": 72,
    "type": "pay",
    "object_id": 544,
    "status": "done",
    "branch": 3,
    "description": "اعلان پرداخت مربوط به فاکتور 554",
    "created_at": "2025-11-02 10:13:44",
    "updated_at": "2025-11-04 13:26:10",
    "operator": {
      "id": 17,
      "name": "Reza Moradi"
    }
  }
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

تابع editAnnouncement نقطه آغاز فرآیند ویرایش است که با واکشی دادهٔ دقیق اعلان، محیط کاربر را برای تغییر ایمن آماده می‌کند. این نقطه هیچ داده‌ای را تغییر نمی‌دهد و صرفاً Fetch اولیهٔ امن محسوب می‌شود.

POST /announcement/store

Route Info

منطق عملکرد تابع

تابع storeAnnouncement در این حالت برای ثبت سریع اعلان (مثلاً هم‌زمان با ثبت سند پرداخت) استفاده می‌شود. در صورتی که شناسه‌ای از اعلان موجود ارسال شود، دادهٔ موجود ویرایش می‌شود وگرنه رکوردی جدید در جدول announcements ایجاد می‌گردد.

پس از درج یا به‌روزرسانی، حافظهٔ کش مالی Redis برای شاخهٔ مربوطه پاک‌سازی (invalidate) شده و شناسهٔ نهایی در خروجی بازگردانده می‌شود.

ورودی‌ها

خروجی (Response)

{
  "status": true,
  "message": "Announcement stored successfully",
  "data": {
    "id": 114,
    "branch": 3,
    "type": "pay",
    "object_id": 554,
    "description": "ثبت خودکار همزمان با پرداخت",
    "timestamp": "2025-11-23 16:19:00"
  }
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

تابع storeAnnouncement در حالت inline بخشی از فرایندهای ترکیبی است که به‌صورت بلادرنگ اعلان را همراه با پرداخت یا دریافت درج یا اصلاح می‌کند و تمام کش‌های شعبه را به‌روزرسانی می‌نماید. این تابع جزو مسیرهای با درجهٔ امنیتی بالا در ماژول مالی محسوب می‌شود.

POST /announcement/update

Route Info

منطق عملکرد تابع

تابع updateAnnouncement برای ویرایش ایمن رکورد موجود در جدول announcements به کار می‌رود. ابتدا بررسی می‌کند که اعلان با شناسهٔ مشخص در شعبهٔ کاربر و وضعیت باز وجود داشته باشد.

در صورت تأیید، به‌روزرسانی مقادیر کلیدی مانند نوع، توضیح، مبلغ یا شیء مرجع انجام می‌شود. پس از ثبت تغییرات در DB، کش مالی مرتبط با شاخهٔ ذکرشده پاک‌سازی شده (Redis invalidate) و دادهٔ نهایی ذخیره شده باز می‌گردد.

ورودی‌ها

خروجی (Response)

{
  "status": true,
  "message": "Announcement updated successfully.",
  "data": {
    "id": 114,
    "branch": 3,
    "type": "pay",
    "description": "اصلاح توضیحات اعلان جهت سند پرداخت",
    "updated_at": "2025-11-23 16:55:04",
    "operator": 17
  }
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

تابع updateAnnouncement با رویکرد atomic و قفل منطقی روی داده‌ها، به‌عنوان لایه انتقال برای عملیات اصلاح اعلان‌های مالی عمل می‌کند و بخشی از چرخه ممیزی شعبه در ماژول مالی محسوب می‌شود.

POST /announcement/view

Route Info

منطق عملکرد تابع

تابع viewAnnouncement با دریافت شناسهٔ اعلان، رکورد مربوطه را از جدول announcements خوانده و در صورت نیاز ارتباطات آن را (مانند پرداخت‌ها، چک‌ها، و اعلان‌های وابسته) نیز شامل می‌کند.

هیچ تغییری در داده انجام نمی‌شود. این endpoint فقط برای مشاهده، چاپ یا آماده‌سازی نمای modal یا PDF استفاده می‌شود. چنانچه اعلان مورد نظر قفل مالی یا در وضعیت بسته باشد، فقط در حالت read-only قابل دریافت است.

ورودی‌ها

خروجی (Response)

{
  "status": true,
  "data": {
    "id": 114,
    "type": "pay",
    "object_id": 554,
    "branch": 3,
    "status": "done",
    "description": "هزینه بلیط پرواز تهران–مشهد",
    "created_at": "2025-11-20 18:35:00",
    "updated_at": "2025-11-21 09:12:11",
    "financial_lock": false,
    "related": [
      {
        "id": 882,
        "type": "check",
        "status": "cleared",
        "deadline": "1404/09/10"
      }
    ]
  }
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

تابع viewAnnouncement مسیر read-only برای مشاهدهٔ ایمن جزئیات اعلان مالی است و به کاربران دارای نقش مشاهده اجازه می‌دهد محتوای دقیق رکورد را بدون دخالت در فرآیندهای مالی بخوانند. داده‌ها با دسترسی کنترل‌شده و کش زمان‌دار ارائه می‌شوند.

POST /announcement/statement

Route Info

منطق عملکرد تابع

تابع statementAnnouncement با هدف تهیهٔ بیانیهٔ تجمیعی از اعلان‌های مالی (پرداخت، دریافت، چک، و اعلان مرتبط) طراحی شده است. این تابع معمولاً بعد از اجرای عملیات listAnnouncement یا updateAnnouncement برای استخراج گزارش دقیق جریان‌های مالی استفاده می‌شود.

مقدارهای ورودی شامل تاریخ شروع، تاریخ پایان، نوع اعلان، و شناسه شعبه هستند. تابع با استفاده از DB::table('announcements') داده‌ها را واکشی کرده و نسبت به object_type (مانند pay, check, cost) عملیات Grouping انجام می‌دهد. سپس مجموع‌ها (balance, debit, credit) محاسبه و ساختار JSON خروجی بازگردانده می‌شود.

ورودی‌ها

خروجی (Response)

{
  "status": true,
  "statement": {
    "branch": 3,
    "from": "1404-09-01",
    "to": "1404-09-23",
    "currency": "IRR",
    "summary": {
      "total_credit": 71250000,
      "total_debit": 53320000,
      "balance": 17930000
    },
    "details": [
      {
        "id": 114,
        "type": "pay",
        "object_type": "check",
        "description": "پرداخت چک بابت اجاره دفتر",
        "amount": 5200000,
        "created_at": "1404-09-12",
        "status": "paid"
      },
      {
        "id": 115,
        "type": "receive",
        "object_type": "cash",
        "description": "دریافت پیش پرداخت از مشتری A",
        "amount": 10500000,
        "created_at": "1404-09-15",
        "status": "done"
      }
    ]
  }
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

تابع statementAnnouncement ستون اصلی گزارش‌گیری تجمیعی اعلان‌هاست که خروجی استاندارد و قالب‌بندی‌شده‌ای برای واحد مالی فراهم می‌کند. با سطح دسترسی Audit، نقش مدیریتی می‌تواند کل جریان‌های مالی شعبه را در یک بازهٔ زمانی مرور کند.

POST /announcement/ledger

Route Info

منطق عملکرد تابع

تابع ledgerAnnouncement برای استخراج دفترکل اعلان‌های مالی به کار می‌رود. داده‌ها بر اساس شناسهٔ شعبه، بازهٔ زمانی، نوع اعلان و موجودی حساب طبقه‌بندی می‌شوند.

این تابع از همان ساختار underlying جدول‌های announcements، pays و checks استفاده می‌کند و پس از پردازش، خروجی را به‌صورت مرتب‌شده بر اساس تاریخ و حساب ارائه می‌دهد. همچنین امکان گروه‌بندی بر پایهٔ حساب معین (moeen_id) یا نوع عملیات فراهم است.

ورودی‌ها

خروجی (Response)

{
  "status": true,
  "branch": 3,
  "group_by": "day",
  "from": "1404-09-01",
  "to": "1404-09-23",
  "ledger": [
    {
      "date": "1404-09-01",
      "debit": 2000000,
      "credit": 0,
      "balance": -2000000,
      "description": "پرداخت به تامین‌کننده کالا",
      "account": "110102 حساب پرداخت‌ها"
    },
    {
      "date": "1404-09-05",
      "debit": 0,
      "credit": 4500000,
      "balance": 2500000,
      "description": "دریافت نقدی از مشتری",
      "account": "110101 صندوق نقدی"
    }
  ],
  "summary": {
    "total_debit": 2000000,
    "total_credit": 4500000,
    "final_balance": 2500000
  }
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

تابع ledgerAnnouncement ستون اصلی گزارش‌گیری تحلیلی دفترکل در ماژول مالی است. این تابع بر پایه داده‌های اعلان، جریان‌های وام، پرداخت و دریافتی را تجمیع کرده و با سیستم کَش تلفیق‌شده، سرعت بالا و داده دقیق برای حسابداران فراهم می‌کند.

POST /announcement/calculation

Route Info

منطق عملکرد تابع

تابع calculationAnnouncement برای بازتولید محاسبات مالی (مانند مانده‌ها، جمع بدهکار و بستانکار، و وضعیت کلی حساب‌ها) طراحی شده است. هر زمان دادهٔ مالی جدید (مانند اعلان پرداخت یا دریافت) ثبت یا ویرایش شود، فراخوان این مسیر باعث تنظیم مجدد داده‌های تحلیلی می‌شود.

درون متد، سیستم با استفاده از DB::table('announcements') و DB::raw() مجموع عملیات مالی را از جدول‌های مرتبط (مثل pays و checks) واکشی و تجمیع کرده، سپس در جدول داخلی announcement_calculations یا کش Redis ثبت می‌کند. این فرآیند به صورت atomic در تراکنش دیتابیس انجام می‌شود تا از ناسازگاری داده جلوگیری شود.

ورودی‌ها

خروجی (Response)

{
  "status": true,
  "branch": 3,
  "from": "1404-09-01",
  "to": "1404-09-23",
  "updated": 38,
  "currency": "IRR",
  "calculation": {
    "total_credit": 71250000,
    "total_debit": 53300000,
    "balance": 17950000,
    "last_update": "1404-09-23 13:44",
    "source": "rebuild"
  }
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

calculationAnnouncement مسیر اصلی برای هم‌ترازی اطلاعات مالی و بازسازی تراز سیستم است. این متد هرگونه تغییر در اعلان‌ها را به دادهٔ آماری منطبق تبدیل کرده و همواره موجب سازگاری داده‌های حسابداری کل با ردیف‌های تراکنشی می‌شود. اجرای آن برای پایداری و سلامت کامل ماژول مالی حیاتی است.

POST /gateway/invoice/{drive}

Route Info

منطق عملکرد تابع

تابع gatewayInvoice برای تولید فاکتور پرداخت اینترنتی طراحی شده است. پارامتر {drive} شناسهٔ آبجکت (مثلاً پرداخت، سفارش یا اعلان مالی) موردنظر را مشخص می‌کند. سیستم نوع مدل را بررسی کرده، مبلغ و اطلاعات حساب مرتبط را از پایگاه داده واکشی می‌نماید و پس از محاسبهٔ پارامترهای امنیتی، یک لینک سفارش فعال در جدول payment_gateway ایجاد می‌کند.

در نهایت، خروجی شامل URL پرداخت و شناسه تراکنش است که کاربر سمت کلاینت یا موبایل می‌تواند برای پرداخت در مرورگر یا اپلیکیشن بانک استفاده کند.

ورودی‌ها

خروجی (Response)

{
  "status": true,
  "gateway": "zarinpal",
  "invoice": {
    "id": 114,
    "amount": 250000,
    "currency": "IRR",
    "reference": "A1Z4R36P",
    "callback_url": "https://example.com/callback/zp",
    "link": "https://gateway.zarinpal.com/pg/StartPay/A1Z4R36P",
    "expire_in": 900
  }
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

تابع gatewayInvoice درگاه میانی سیستم مالی را مدیریت می‌کند و با تولید سریع لینک پرداخت، کاربران را از اتصال مستقیم به سرویس پرداخت بی‌نیاز می‌سازد. این تابع یکی از اجزای کلیدی ماژول تراکنش آنلاین است که امنیت، سرعت و یکپارچگی داده را در سطح شعبه تضمین می‌کند.

POST /gateway/invoice/{drive}/verify

Route Info

منطق عملکرد تابع

تابع gatewayInvoiceVerify مرحلهٔ پایانی پرداخت الکترونیک است. این تابع پس از بازگشت کاربر از درگاه بانکی (با پارامترهای Authority، RefID یا معادل آنها) اجرا می‌شود.

سیستم اطلاعات پرداخت را از جدول payment_gateway بر اساس پارامتر {drive} واکشی کرده، شناسهٔ بانکی و مبلغ مورد انتظار را تطبیق می‌دهد. سپس از کنترلر درگاه (مثلاً ZarinpalController::verify()) برای استعلام نهایی وضعیت استفاده می‌کند.

در صورت موفقیت، رکورد پرداخت در جدول pays با وضعیت paid به‌روزرسانی شده و تراکنش به عنوان سند مالی تأییدشده در دفتر ثبت می‌گردد.

ورودی‌ها

خروجی (Response)

{
  "status": true,
  "gateway": "zarinpal",
  "invoice": {
    "id": 114,
    "reference": "A1Z4R36P",
    "bank_ref": "000485298963",
    "amount": 250000,
    "state": "paid",
    "verified_at": "1404-09-23 14:21"
  },
  "transaction": {
    "accounting_record": 24039,
    "updated_balance": 71250000
  }
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

تابع gatewayInvoiceVerify نقطهٔ نهایی فرایند پرداخت آنلاین است. این متد دادهٔ بازگشتی درگاه را با اطلاعات داخلی همگام کرده، وضعیت پرداخت را در پایگاه داده، کش و دفتر حسابداری ثبت می‌کند. اجرای صحیح آن برای جلوگیری از ثبت پرداخت‌های تکراری، حیاتی است و بخشی از چرخه اطمینان مالی (Financial Transaction Integrity Cycle) محسوب می‌شود.

POST /api/v2/gateway/details

Route Info

منطق عملکرد تابع

تابع paymentGatewayDetails بر اساس مقدار serial_id که از سمت کلاینت ارسال می‌شود، رکورد متناظر در جدول payment_gateway را جست‌وجو می‌کند. در صورت پیدا شدن، نوع درگاه را مشخص کرده و بر اساس نوع درگاه (مانند behpardakht یا sep)، فیلدهای خروجی را از محتوای JSON ذخیره‌شده در ستون result استخراج می‌کند.

برای درگاه behpardakht، پارامترهای CardHolderPan و SaleReferenceId استخراج می‌شود. اگر پاسخ شامل کد خطای ResCode=17 باشد، لینک retry ساخته می‌شود. برای درگاه sep نیز پارامترهای SecurePan و Rrn استفاده می‌گردد. درگاه‌های دیگر بدون پردازش JSON مستقیماً بازگردانده می‌شوند.

ورودی‌ها

خروجی (Response)

{
  "payload": {
    "drive": "sep",
    "amount": 250000,
    "card": "603799******1234",
    "datetime": "1404-09-23 14:28",
    "tracking_code": "123456789",
    "try_link": false
  },
  "meta": {
    "timestamp": 1732362504
  }
}

در صورت خطا در فرایند پرداخت، ساختار پاسخ به صورت زیر است:

{
  "error": {
    "code": 1000,
    "message": "در فرایند پرداخت مشکلی رخ داده است."
  },
  "payload": { ... },
  "meta": { "timestamp": 1732362504 }
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

تابع paymentGatewayDetails مسیر مرجع سیستم برای واکشی وضعیت نهایی پرداخت‌ها است. این endpoint خروجی استاندارد برای گزارش تراکنش ارائه می‌کند و بخشی از چرخهٔ پایش عملکرد درگاه‌های بانکی در زیرسیستم مالی محسوب می‌شود. اجرای امن و دقیق آن برای جلوگیری از مغایرت در داده‌های بانکی ضروری است.

POST /colleagues/list

Route Info

منطق عملکرد تابع

تابع colleaguesList وظیفه دارد لیست همکاران را بر اساس نوع عمل درخواستی (debtors، creditors، rounded و ...) برگرداند. در ابتدا دادهٔ JSON ارسالی از سمت کلاینت تجزیه می‌شود و پارامترهای شروع (start) و طول (length) برای صفحه‌بندی تعیین می‌گردد. سپس بر اساس نوع عمل ($request->action) جهت مرتب‌سازی مشخص می‌شود (ASC یا DESC).

در ادامه با ترکیب داده‌های دریافتی و وضعیت بدهی/بستانکاری از طریق متدهای محاسباتی، مجموعه‌ای از آیتم‌ها با ساختاری شامل اطلاعات شناسنامه‌ای، وضعیت مالی، سقف اعتباری، و وضعیت تشخیص حساب (neutral/debtor/creditor) تشکیل می‌شود.

ورودی‌ها

خروجی (Response)

{
  "draw": 1,
  "recordsTotal": 162,
  "recordsFiltered": 162,
  "data": [
    {
      "serial_id": 8212,
      "system_serial": 12,
      "title": "دفتر آژانس مهر و ماه",
      "type": "شریک تجاری (بستانکاران)",
      "relationship": "ندارد",
      "category": "شرکت داخلی",
      "credit": 2400000,
      "debit": 600000,
      "balance": 1800000,
      "financial_ceiling": 25000000,
      "diagnosis": {"fa":"بستانکار","en":"Creditor"},
      "status": {"fa":"فعال","en":"active"},
      "documents": ...,
      "representative": ...
    }
  ],
  "refreshDatetime": "1404-09-23 14:30:00"
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای بهبود

ممیزی و لاگ‌ها

جمع‌بندی

مسیر POST /colleagues/list نقطه ورود به سیستم مالی همکاران است و نقش کلیدی در تحلیل وضعیت اعتباری آنها دارد. کد این بخش ساختاری منعطف با پشتیبانی از صفحه‌بندی، فیلترگذاری و تشخیص خودکار نوع حساب مالی دارد. افزودن caching پیشرفته و Role-based access می‌تواند راندمان و امنیت را دوچندان کند.

POST /colleague/bill

Route Info

منطق عملکرد تابع

تابع colleagueBill فهرستی از اسناد مالی مرتبط با یک همکار خاص را بر اساس id همکار و بازه تاریخی درخواست‌شده برمی‌گرداند. الگوریتم شامل مراحل زیر است:

ورودی‌ها

ساختار خروجی

{
  "recordsTotal": 54,
  "details": {
    "id": 202,
    "title": "آژانس مهر و ماه",
    "category": "شرکت داخلی",
    "type": "شریک تجاری (بستانکار)"
  },
  "total": {
    "credit": 22650000,
    "debit": 13790000
  },
  "data": [
    {
      "serial_id": "28-202",
      "datetime": "1404/06/20 09:00:00",
      "credit": 2500000,
      "debit": 0,
      "description": {
        "html": "دریافت چک از دفتر مرکزی",
        "text": "دریافت چک از دفتر مرکزی"
      },
      "details": {
        "documents": { "pay": 914 },
        "type": { "subject": "check_paid", "title": "چک نقدی" }
      },
      "relationship": null,
      "communications": false
    }
  ]
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و لاگ‌ها

جمع‌بندی

تابع colleagueBill یکی از سنگین‌ترین و حیاتی‌ترین مسیرهای مالی در سیستم است که ترکیبی از پرداخت‌ها، چک‌ها، اسناد دستی و مانده دوره را در قالب یک جمع‌بندی زمانی بازمی‌گرداند. امنیت و صحت زمان‌بندی محاسباتی نقش کلیدی در جلوگیری از ناسازگاری‌های حسابداری دارد.

POST /colleagues/ledger-accounts

Route Info

منطق عملکرد تابع

تابع colleagueLedgerAccounts وظیفه دارد حساب‌های معین مرتبط با همکار مشخص را از ساختار حسابداری استخراج کند. این تابع معمولاً هنگام تهیه گزارش دفتر کل یا نمایش جزئیات مالی یک همکار فراخوانی می‌شود. عملکرد کلی:

پارامترهای ورودی

ساختار خروجی

[
  {
    "group": {
      "id": 2,
      "code": "11",
      "title_fa": "دارایی‌ها"
    },
    "general": {
      "id": 17,
      "code": "1101",
      "title_fa": "حساب‌های دریافتنی"
    },
    "moeen": {
      "id": 215,
      "code": "110101",
      "title_fa": "بدهکاران تجاری - همکاران"
    },
    "status": {
      "fa": "فعال",
      "en": "active"
    }
  }
]

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و لاگ‌ها

جمع‌بندی

مسیر /colleagues/ledger-accounts یک نقطه کلیدی برای ارتباط بین سیستم مالی و سیستم حسابداری محسوب می‌شود. با استفاده از این Endpoint می‌توان تمام روابط حسابداری همکار را مرور کرد. کد بهینه‌سازی خوبی در join و تفکیک داده‌ها دارد، اما افزودن caching می‌تواند عملکرد را در محیط سازمانی بزرگ بهبود دهد.

POST /colleagues/update/financial

Route Info

منطق عملکرد تابع

تابع updateFinancialColleagues زمانی فراخوانی می‌شود که نیاز باشد اطلاعات مالی تمام یا بخشی از همکاران (Colleagues) بر اساس آخرین تراکنش‌ها محاسبه مجدد شود. منطق کلی آن:

پارامترهای ورودی

ساختار خروجی

{
  "status": true,
  "updated": 46,
  "refreshDatetime": "2025-11-23 13:30:06",
  "data": [
    {
      "colleague_id": 72,
      "name": "آژانس یاقوت شرق",
      "category": "شرکت داخلی",
      "credit": 9140000,
      "debit": 6400000,
      "balance": 2740000,
      "diagnosis": "Creditor",
      "financial_ceiling": 20000000
    }
  ]
}

نکات امنیتی

نکات عملکردی

Redis::set('TIME:colleagues:general_billing', Carbon::now()->toString());

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و لاگ‌ها

جمع‌بندی

تابع updateFinancialColleagues بازوی مرکزی حفظ یکپارچگی مالی همکاران است. با ادغام آن با تریگرهای تراکنش و کش Redis، سیستم مالی همکاران همیشه به‌روزرسانی‌شده و هم‌زمان باقی می‌ماند. استفاده مکرر از این مسیر باید با کنترل بار سرور و هماهنگی حسابداری انجام شود.

POST /colleagues/update/general-billing

Route Info

منطق عملکرد تابع

تابع updateGeneralBillingColleagues داده‌های مالی فعلی هر همکار را از جداول مختلف تجمیع کرده و صورتحساب کلی (General Billing)‌ را به‌روزرسانی می‌کند. هدف آن حفظ یکپارچگی اطلاعات مالی همکاران در سامانه است.

پارامترهای ورودی

ساختار خروجی

{
  "status": true,
  "updated": 31,
  "refreshDatetime": "2025-11-23 14:00:21",
  "data": [
    {
      "colleague_id": 14,
      "name": "شرکت سپهر پرواز",
      "credit": 7800000,
      "debit": 1040000,
      "balance": 6760000,
      "diagnosis": "Creditor",
      "financial_ceiling": 30000000,
      "category": "شرکت داخلی"
    }
  ]
}

نکات امنیتی

نکات عملکردی

وابستگی‌ها

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و لاگ‌ها

جمع‌بندی

تابع updateGeneralBillingColleagues پایهٔ نگهداری داده‌های مالی کلان سیستم است. عملکرد درست آن موجب یکپارچگی ترازهای داخلی و صحت گزارش‌های مالی می‌شود. اجرای همزمان آن با مسیر updateFinancialColleagues توصیه نمی‌شود تا تداخلی در cache و داده‌ها ایجاد نشود.

POST /colleague/operation

Route Info

منطق عملکرد تابع

تابع operationColleague نقطه اصلی مدیریت عملیات (CRUD) بر روی موجودیت colleague است. بسته به action موجود در دادهٔ ورودی، می‌تواند ایجاد، ویرایش، یا حذف داده را انجام دهد. این تابع علاوه بر جدول اصلی colleagues جداول کمکی colleague_additional و mapping_colleagues را نیز مدیریت می‌کند و پس از تغییر، کش Redis را به‌روزرسانی می‌کند.

پارامترهای ورودی

ساختار خروجی

{
  "status": true,
  "action": "update",
  "colleague_id": 142,
  "message": "colleague record updated successfully",
  "time": "2025-11-23T14:32:17+03:30"
}

نکات امنیتی

نکات عملکردی

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و لاگ‌ها

جمع‌بندی

تابع operationColleague موتور اصلی و مرکزی CRUD همکاران در لایه API است. تمامی تغییرات ساختاری، مالی و ارتباطی در یک نقطه مجتمع شده‌اند تا تداخلی میان جداول colleagues و colleague_additional ایجاد نشود. این ساختار، در امتداد استاندارد داخلی «Enterprise V1.1»، پایه‌ای برای audit، cache و عملیات هم‌زمان فراهم می‌آورد.

GET /colleague/get

Route Info

منطق عملکرد تابع

تابع getColleague برای خواندن جزئیات کامل یک همکار از پایگاه داده طراحی شده است. ورودی شامل شناسه همکار می‌باشد که از query string در GET request دریافت می‌شود. در خروجی، داده‌ها از جداول colleagues، colleague_additional و وابستگی‌ها تجمیع می‌شود. چنانچه داده در کش Redis موجود باشد، تابع مستقیماً از آن استفاده می‌کند و در غیر این صورت از Database خوانده، سپس در Redis ذخیره می‌کند.

پارامترهای ورودی

ساختار خروجی

{
  "status": true,
  "data": {
    "id": 142,
    "office": "آژانس تابان پرواز",
    "type": 3,
    "category": 4,
    "diagnosis": "Creditor",
    "financial_code": "103245897",
    "credit_amount": 50000000,
    "phone": "+98-31-32110",
    "email": "info@taban.ir",
    "branch": "isfahan",
    "relationship": "official",
    "created_at": "2025-04-21 11:22:53",
    "updated_at": "2025-11-23 14:47:15",
    "additional": {
      "iban": "IR210550080300087123456001",
      "address": "اصفهان، خیابان حکیم نظامی، ساختمان مهر"
    }
  },
  "cache": true
}

نکات امنیتی

نکات عملکردی

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و لاگ‌ها

جمع‌بندی

تابع getColleague مرجع اصلی برای ارائهٔ جزئیات کامل هر همکار است و به علت وابستگی به کش Redis سرعت پاسخ بالاست. در فرآیندهای مالی و مدیریتی، این endpoint پایه‌ای برای نمایش اطلاعات همکار در تمامی ماژول‌ها (تجارت، حسابداری، آمار) محسوب می‌شود.

GET /colleague/search

Route Info

منطق عملکرد تابع

تابع searchColleague برای اجرای جست‌وجوی بلادرنگ در داده‌های همکار طراحی شده است. این API در تمام نقاط سامانه (حسابداری، تسویه، CRM و billing) برای autocomplete باکس‌های انتخاب همکار استفاده می‌شود.

پارامترهای ورودی

ساختار خروجی

{
  "status": true,
  "results": [
    {
      "id": 142,
      "title": "آژانس تابان پرواز",
      "meta": {
        "type": "Creditor",
        "category": "آژانس",
        "financial_code": "103245897",
        "phone": "+98-31-32110"
      }
    },
    ...
  ],
  "cache": true
}

نکات امنیتی

نکات عملکردی

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و لاگ‌ها

جمع‌بندی

تابع searchColleague رابط اصلی جست‌وجوی سریع همکاران در کل مجموعه است که با تکیه بر Redis و Query بهینه، تجربه‌ی سرعتی و پاسخ‌گویی بلادرنگ را فراهم می‌کند. این endpoint اساس تمام drop‑down ها و autocomplete های سیستم مدیریت مالی و تجاری است.

GET /colleague/user

Route Info

منطق عملکرد تابع

تابع indexColleagueUser تمام کاربران ثبت‌شده تحت یک colleague (یا شرکت/شعبه شریک) را بازیابی می‌کند. هر کاربر به واسطهٔ شناسهٔ همکار و نوع نقش داخلی در جدول colleague_users نگهداری می‌شود. تابع از جدول colleague_users و جدول users برای تجمیع اطلاعات استفاده می‌کند.

پارامترهای ورودی

ساختار خروجی

{
 "status": true,
 "colleague_id": 52,
 "users": [
   {
     "id": 410,
     "name": "Sara Azimi",
     "email": "s.azimi@example.com",
     "mobile": "09131234567",
     "role": "accountant",
     "active": true,
     "created_at": "2025‑05‑04 12:21:55"
   },
   ...
 ]
}

نکات امنیتی

نکات عملکردی

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و لاگ‌ها

جمع‌بندی

تابع indexColleagueUser نمای کلی تمامی کاربران وابسته به یک همکار را بر می‌گرداند و به‌عنوان منبع اصلی نمایش استاندارد در ماژول مدیریت همکاران است. پاسخ JSON آن به‌طور بهینه و با حفظ امنیت اطلاعات تعریف شده است.

PUT /colleague/user

Route Info

منطق عملکرد تابع

تابع updateColleagueUser برای به‌روزرسانی داده‌های کاربر متصل به یک colleague خاص است. سامانه بررسی می‌کند که کاربر ارسالی متعلق به همان همکار باشد تا از تغییر دسترسی اشتباه جلوگیری شود.

پارامترهای ورودی

ساختار خروجی

{
 "status": true,
 "message": "User updated successfully",
 "user": {
    "id": 410,
    "colleague_id": 52,
    "name": "Sara Azimi",
    "email": "s.azimi@example.com",
    "mobile": "09131234567",
    "role": "accountant",
    "active": true,
    "updated_at": "2025‑11‑23 08:42:11"
 }
}

نکات امنیتی

نکات عملکردی

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و لاگ‌ها

جمع‌بندی

تابع updateColleagueUser پایهٔ اصلی مدیریت کاربران همکاران است که با رعایت atomicity، احراز هویت سخت‌گیرانه و refresh خودکار cache عمل می‌کند. تمامی تغییرات در لاگ سیستمی ثبت می‌شود تا قابلیت ممیزی کامل داشته باشد.

POST /colleague/user

Route Info

منطق عملکرد تابع

تابع storeColleagueUser برای ایجاد یک کاربر جدید در زیرمجموعه همکار استفاده می‌شود. این تابع در ماژول مدیریت همکاران مورد استفاده مدیران مالی و مدیران همکار قرار می‌گیرد تا بتوانند کارمندان یا مسئولین دسترسی را تعریف کنند.

پارامترهای ورودی

ساختار خروجی

{
 "status": true,
 "message": "Colleague user created successfully",
 "user": {
   "id": 615,
   "colleague_id": 52,
   "name": "Ali Rahmani",
   "email": "a.rahmani@example.com",
   "mobile": "09130000000",
   "role": "accountant",
   "active": true,
   "created_at": "2025‑11‑23 08:55:00"
 }
}

نکات امنیتی

نکات عملکردی

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و لاگ‌ها

جمع‌بندی

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

DELETE /colleague/user

Route Info

منطق عملکرد تابع

تابع deleteColleagueUser جهت حذف ایمن یک کاربر همکار از مجموعه استفاده می‌شود. فرآیند به‌صورت تراکنش و با درج اطلاعات حذف در system_logs انجام می‌گیرد تا سوابق هرگز در سطح DB از بین نرود (Soft Delete).

پارامترهای ورودی

ساختار خروجی

{
  "status": true,
  "message": "Colleague user removed successfully",
  "user": {
     "id": 615,
     "colleague_id": 52,
     "name": "Ali Rahmani",
     "email": "a.rahmani@example.com",
     "deleted_at": "2025‑11‑23 09:05:59"
  }
}

نکات امنیتی

نکات عملکردی

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و لاگ‌ها

جمع‌بندی

تابع deleteColleagueUser با تکیه بر SoftDelete، بازرسی امنیتی سخت‌گیرانه و ثبت دقیق وقایع ممیزی طراحی شده است. این endpoint حلقه نهایی در چرخه CRUD کاربران همکار به‌شمار می‌رود و تداوم داده‌ای را با امنیت کامل حفظ می‌کند.

POST /upload

Route Info

منطق عملکرد تابع

تابع upload برای دریافت فایل از کاربر، اعتبارسنجی نوع و اندازهٔ آن، سپس ذخیره‌سازی در مسیر مشخص‌شده در پوشهٔ uploads/ است. مسیر براساس branch، type و سال و ماه فعلی ساخته می‌شود. در پایان، مسیر فایل ذخیره‌شده در پاسخ JSON بازگردانده می‌شود.

پارامترهای ورودی

ساختار خروجی موفق

{
  "status": true,
  "file": "uploads/5/profile/2025/11/png/2025-11-23-1732355844.png"
}

ساختار خروجی خطا

{
  "status": false,
  "error": "The file field is required."
}

نکات امنیتی

نکات عملکردی

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و لاگ‌ها

جمع‌بندی

تابع upload یک endpoint سبک، امن و متن‌باز برای آپلود ساده فایل در زیرسیستم های داخلی سیستم است. با ساختار دایرکتوری پرمبنا (بر اساس branch و type) قابل گسترش برای ذخیره‌سازی امن و تفکیک‌شده می‌باشد.

GET /asterisk/test-connection

Route Info

منطق عملکرد تابع

تابع testConnection اتصال میان سیستم API و سرور Asterisk AMI را بررسی می‌کند. در صورت موفقیت، اطلاعات وضعیت فعلی (مانند version، uptime، channel count) را بر می‌گرداند. در صورت بروز خطا، پاسخی با کد ۵۰۰ و پیام مناسب بر می‌گرداند.

پارامترهای ورودی

هیچ پارامتر بدنه ای ندارد؛ فقط توکن احراز هویت در هدر Authorization: Bearer <token>.

ساختار خروجی

{
  "status": true,
  "message": "Successfully connected to Asterisk AMI",
  "data": {
    "version": "Asterisk 18.10.0",
    "uptime": "02:15:48",
    "active_channels": 3,
    "timestamp": 1732363700
  }
}

نکات امنیتی

نکات عملکردی

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و لاگ‌ها

جمع‌بندی

تابع testConnection پایه‌ای‌ترین نقطهٔ بررسی سلامت ارتباط Asterisk AMI است و در صورت موفقیت، اطمینان از فعال بودن سرورهای تماس را به API می‌دهد.

GET /asterisk/channels/active

Route Info

منطق عملکرد تابع

تابع getActiveChannels با استفاده از کلاس AmiClient به سرویس AMI متصل شده و با فرمان CoreShowChannels فهرست تمام کانال‌های فعال در حال مکالمه را واکشی می‌کند. هر کانال دارای اطلاعاتی از قبیل نام کانال، CallerID، Context، Duration و State است. نتیجه در قالب JSON بازگردانده می‌شود.

پارامترهای ورودی

درخواست فاقد پارامتر بدنه است. احراز هویت JWT در هدر Authorization الزامی می‌باشد.

ساختار خروجی

{
  "status": true,
  "count": 2,
  "channels": [
    {
      "channel": "SIP/2001-0000004e",
      "caller": "09132223344",
      "context": "from-internal",
      "state": "Up",
      "duration": "00:02:34"
    },
    {
      "channel": "SIP/2002-0000004f",
      "caller": "02133112233",
      "context": "from-outgoing",
      "state": "Ring",
      "duration": "00:00:15"
    }
  ]
}

نکات امنیتی

نکات عملکردی

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و لاگ‌ها

جمع‌بندی

تابع getActiveChannels برای نمایش بلادرنگ لیست تماس‌های جاری در سیستم است و یکی از پایه‌ای‌ترین API‌ های مانیتورینگ مرکز تماس به‌شمار می‌رود.

GET /asterisk/channel/status

Route Info

منطق عملکرد تابع

تابع getChannelStatus به سرور AMI وصل می‌شود و وضعیت دقیق یک Channel مشخص را برمی‌گرداند. درخواست، نام کانال در حال برقراری تماس (مثل SIP/2001‑0000004e) را دریافت کرده و با ارسال دستور ChannelStatus به AMI، اطلاعات فعلی (نظیر CallerID، state، context، application و duration) را بازمی‌گرداند.

پارامترهای ورودی

ساختار خروجی موفق

{
  "status": true,
  "message": "Channel found",
  "data": {
    "channel": "SIP/2001-0000004e",
    "caller": "09132223344",
    "context": "from-internal",
    "state": "Up",
    "application": "Dial",
    "duration": "00:02:34"
  }
}

ساختار خروجی خطا

{
  "status": false,
  "code": 404,
  "error": "Channel not found or inactive"
}

نکات امنیتی

نکات عملکردی

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و لاگ‌ها

جمع‌بندی

getChannelStatus ابزار پایش دقیق و بلادرنگ هر کانال در سیستم تماس VoIP است و به ادمین‌ها امکان عیب‌یابی سریع ارتباطات را می‌دهد.

POST /asterisk/call/make

Route Info

منطق عملکرد تابع

تابع makeCall یک درخواست خروجی به AMI ارسال می‌کند تا میان «داخلی اپراتور» و «شماره مقصد» تماس ایجاد شود. با Action Originate و پارامترهای Channel، Exten، Context و Priority، سیستم تماس را آغاز می‌کند. در صورت موفقیت، داده uniqueid و اطلاعات پایه تماس برگردانده می‌شود.

پارامترهای ورودی

ساختار خروجی

{
  "status": true,
  "message": "Call initiated successfully",
  "data": {
    "uniqueid": "1732360572.382",
    "source": "SIP/2001",
    "destination": "09132223344",
    "context": "from-internal",
    "channel_state": "Ring"
  }
}

نکات امنیتی

عملکرد سیستم

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و لاگ‌ها

جمع‌بندی

متد makeCall رابطی امن و بلادرنگ برای شروع تماس‌های خروجی از داخلی اپراتور به شماره‌های بیرونی از طریق AMI است و به‌عنوان هستهٔ ماژول Call Management نقش اصلی دارد.

POST /asterisk/call/hangup

Route Info

منطق عملکرد تابع

تابع hangupCall جهت پایان دادن به تماسی است که در حال برقراری است. پارامتر ورودی می‌تواند channel یا uniqueid باشد. در صورت هماهنگ بودن یکی از این دو، دستور AMI با Action Hangup به سرور ارسال شده و در صورت موفقیت، پیغام تأیید برمی‌گردد.

پارامترهای ورودی

* حداقل یکی از دو پارامتر channel یا uniqueid باید ارسال شود.

ساختار خروجی

{
  "status": true,
  "message": "Call hangup successful",
  "data": {
    "channel": "SIP/2001-0000004e",
    "uniqueid": "1732360572.382",
    "terminated_at": "2025-11-23T14:42:58+03:30"
  }
}

نکات امنیتی

عملکرد

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و لاگ‌ها

جمع‌بندی

hangupCall روشی ایمن و بلادرنگ برای قطع تماس فعال در مرکز تماس است. این تابع هستهٔ اصلی پایان مدیریت تماس‌ها در بخش Call Management به‌شمار می‌رود.

POST /asterisk/sms/send

Route Info

منطق عملکرد تابع

تابع sendSms برای ارسال پیامک از ماژول GSM متصل به Asterisk کاربرد دارد. پارامترهای number و message اعتبارسنجی می‌شوند و در صورت دارا بودن device مجاز، دستور AMI با Action DongleSendSms به سرور ارسال می‌شود. پس از ارسال موفق، رویداد وب‌سوکت در کانال sms_notification منتشر و لاگ در جدول ami_sms_logs ثبت می‌شود.

پارامترهای ورودی

ساختار خروجی

{
  "status": true,
  "message": "SMS sent successfully",
  "data": {
    "id": "1732361012_912223344",
    "recipient": "09132223344",
    "device": "dongle0",
    "status": "sent",
    "timestamp": "2025-11-23T15:03:12+03:30"
  }
}

نکات امنیتی

عملکرد

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و لاگ‌ها

جمع‌بندی

sendSms درگاه اصلی ارسال پیامک سیستم Asterisk است که امکان کنترل و مانیتورینگ بی‌درنگ پیام‌های خروجی را فراهم می‌کند. قابل گسترش برای ارسال انبوه، زمان‌بندی و گزارش تحویل می‌باشد.

POST /asterisk/ussd/send

Route Info

منطق عملکرد تابع

تابع sendUssd دستورات کوتاه USSD را به کمک پروتکل AMI به دستگاه GSM ارسال می‌کند. ابتدا مقدار پارامتر code بررسی شده و فرمت آن با الگوی USSD تطبیق می‌یابد (مثلاً *1*123#). در صورت صحت، دستور با Action DongleSendUssd به AMI فرستاده می‌شود و در پایگاه داده به عنوان درخواست ثبت می‌شود. پاسخ خام AMI بر اساس رویداد DongleUSSD دریافت شده، در جدول ami_ussd_logs ذخیره و از طریق وب‌سوکت در کانال ussd_notification به کاربر منتشر می‌شود.

پارامترهای ورودی

ساختار خروجی

{
  "status": true,
  "message": "USSD command sent successfully",
  "data": {
    "id": "USSD-1732362009",
    "code": "*140*1#",
    "device": "dongle1",
    "response": "Your remaining balance is 74,250 IRR",
    "timestamp": "2025-11-23T15:10:09+03:30"
  }
}

نکات امنیتی

عملکرد

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و لاگ‌ها

جمع‌بندی

sendUssd امکان مدیریت دستورات USSD را از طریق Asterisk فراهم می‌آورد و برای عملیات‌هایی مانند بررسی اعتبار، خرید بسته یا مدیریت سیم‌کارت استفاده می‌شود. این ماژول در سطح enterprise طراحی شده و دارای لاگ، وب‌سوکت و امنیت چندسطحی است.

POST /asterisk/action/execute

Route Info

منطق عملکرد تابع

تابع executeAction یک رابط عمومی برای ارسال دستورات خام به سرور Asterisk AMI است. پارامتر اصلی ورودی آن action می‌باشد که نوع دستور AMI را مشخص می‌کند (برای مثال CoreShowChannels، DongleShowDevices، Reload). تمام آرگومان‌های اختیاری در فیلد arguments به صورت آرایه کلید–مقدار ارسال می‌شوند. تابع پس از ارسال دستور به AMI، پاسخ خام (متن و وضعیت دستور) را برمی‌گرداند و در صورت فعال بودن حالت debug، در لاگ ami_action_logs ثبت می‌نماید.

پارامترهای ورودی

ساختار خروجی

{
  "status": true,
  "message": "AMI Action executed successfully",
  "data": {
    "response": "Success",
    "message_id": "1732362901.954",
    "details": {
      "Action": "CoreShowChannels",
      "Result": [
        "Channel: SIP/301-000004F2",
        "CallerID: 09132223344",
        "State: Up"
      ]
    }
  }
}

نکات امنیتی

عملکرد

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و لاگ‌ها

جمع‌بندی

executeAction ابزاری انعطاف‌پذیر برای مدیران سیستم است تا هر فرمان AMI را با کنترل امنیت و لاگ‌گیری کامل اجرا کنند. قابلیت استفاده برای Debug، مدیریت داخلی و توسعه‌ی ابزارهای مانیتور بر پایه‌ی Asterisk را دارد.

GET /asterisk/websocket/test

Route Info

منطق عملکرد تابع

تابع testWebSocketConnection به منظور بررسی در دسترس بودن و پایداری ارتباطات بلادرنگ با وب‌سوکت داخلی ماژول Asterisk طراحی شده است. فرایند به صورت زیر انجام می‌شود:

پارامترهای ورودی

ساختار خروجی

{
  "status": true,
  "message": "WebSocket connection healthy",
  "data": {
    "ping_sent": "2025-11-23T15:20:42.002+03:30",
    "pong_received": "2025-11-23T15:20:42.135+03:30",
    "latency_ms": 133
  }
}

نکات امنیتی

عملکرد

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و لاگ‌ها

جمع‌بندی

testWebSocketConnection ابزاری کاملاً سبک برای اطمینان از سلامت وب‌سوکت و کاهش خطاهای زمانی در ارتباطات بلادرنگ AMI می‌باشد. عدم وابستگی به کش، امنیت سطح نقش و ثبت ممیزی بلادرنگ باعث می‌شود که این مسیر برای پایش زنده زیرساخت ارتباطی سیستم بسیار کارآمد باشد.

POST /asterisk/notification/test

Route Info

منطق عملکرد تابع

تابع sendTestNotification برای تست درستی و پایداری سرویس نوتیفیکیشن داخلی سیستم طراحی شده است. کاربر می‌تواند نوع نوتیفیکیشن (type) و محتوای آنی (data) را در درخواست ارسال کند تا سرویس، پیام را از طریق کانال بلادرنگ (معمولاً Redis Pub/Sub یا WebSocket Gateway) به تمام Listenerهای فعال منتقل کند. سرویس علاوه بر انتشار رویداد، عملیات را در جدول ami_notifications_log با مشخصات ارسال‌کننده ثبت می‌نماید.

پارامترهای ورودی

ساختار خروجی

{
  "status": true,
  "message": "Notification broadcasted successfully",
  "data": {
    "id": "TEST-NOTIF-1732364015",
    "type": "success",
    "channel": "test_notification_channel",
    "payload": {
      "text": "Ping from AsteriskAmiController",
      "from": "admin"
    },
    "timestamp": "2025-11-23T15:40:15.570+03:30"
  }
}

نکات امنیتی

عملکرد

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و لاگ‌ها

جمع‌بندی

sendTestNotification به عنوان ابزار پایش و رفع اشکال بلادرنگ در زیرساخت ارتباطی Asterisk استفاده می‌شود. این مسیر به توسعه‌دهندگان اجازه می‌دهد توان ارسال، انتشار، و ثبت رویدادها را به‌صورت متمرکز و امن سنجش کنند و بنابراین، جزئی کلیدی از پایش زنده‌ی سامانه NotifyCenter است.

POST /upload/s3

Route Info

منطق عملکرد تابع

تابع uploadFile به منظور آپلود ایمن فایل در محیط S3‑Compatible Storage (Liara) طراحی شده است. نحوه‌ی عملکرد:

پارامترهای ورودی

ساختار خروجی

{
  "status": true,
  "file": "uploads/5/images/2025/11/2025-11-23-1732365001.jpg"
}

در صورت اشتباه در آپلود:

{
  "status": false,
  "time": 1732365001
}

نکات امنیتی

عملکرد

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و ثبت وقایع

جمع‌بندی

uploadFile از هسته‌های اصلی زیرساخت مدیریت فایل سیستم است که با پشتیبانی از مسیر دینامیک، اعتبارسنجی پله‌ای پسوند، و اتصال امن به S3 Storage می‌تواند فرآیند آپلود را با پایداری و امنیت بالا انجام دهد. ساختار طراحی آن مطابق استاندارد Enterprise V1.1 است و قابلیت گسترش برای Multi‑Tenant را نیز دارد.

DELETE /media/s3

Route Info

منطق عملکرد تابع

تابع deleteMedia به منظور حذف فایل‌های ذخیره‌شده در فضای S3‑Compatible (Liara) و پاکسازی رکورد‌های مرتبط از جدول media طراحی شده است.

پارامترهای ورودی

* حداقل یکی از پارامترهای id، path یا related_id باید ارسال شود.

ساختار خروجی

{
  "status": true,
  "time": 1732365500,
  "deleted": [
    "12 - uploads/profile/images/2025/11/img123.jpg - File deleted successfully",
    "15 - uploads/profile/images/2025/11/img999.jpg - File not found"
  ]
}

نکات امنیتی

عملکرد

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و ثبت وقایع

جمع‌بندی

deleteMedia یک مسیر حذف ایمن برای مدیریت فایل‌های فضای S3 در سامانه است که هم حذف فیزیکی فایل را انجام می‌دهد و هم پاکسازی بانک اطلاعاتی را؛ در صورت پیاده‌سازی لاگ و کنترل مالکیت، این فرایند می‌تواند ضد‌گلوله شود.

GET /personnel/attendance

Route Info

منطق عملکرد تابع

متد attendancePersonnel پس از تأیید احراز هویت، اطلاعات حضور و غیاب پرسنل را با پارامترهای فیلتر متنوع برگردانده و در خروجی جزئیات مالی مرتبط را بهمراه اسناد ثبت شده نمایش می‌دهد.

پارامترهای ورودی

ساختار خروجی

{
  "draw": 1,
  "recordsTotal": 100,
  "recordsFiltered": 10,
  "filtered": {
    "from": "2025/11/01",
    "to": "2025/11/23"
  },
  "details": { ...personnelObject },
  "data": [
    {
      "serial_id": 12345,
      "system_serial": 6789,
      "datetime": "1404/08/01 08:15:00",
      "details": {
        "title": { "html": "نام پرسنل | توضیحات سند", "text": "..." },
        "type": { "subject": "pay", "title": "سند مالی" }
      },
      "credit": 0,
      "debit": 500000,
      "diagnosis": "debtor"
    }
  ]
}

نکات امنیتی

عملکرد

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و ثبت وقایع

جمع‌بندی

attendancePersonnel مسیر پایه برای مشاهده وضعیت حضور پرسنل با جزئیات مالی است. اگر کنترل سطح دسترسی و ثبت رویدادها به‌درستی اجرا شود، مسیر قابلیت استفاده در محیط‌های حساس را دارد.

POST /personnel/attendance

Route Info

منطق عملکرد تابع

تابع attendancePersonnelStore برای ثبت یا به‌روزرسانی سوابق حضور و غیاب پرسنل استفاده می‌شود. ورودی شامل شناسه‌ی پرسنل، بازه‌ی تاریخ، وضعیت کاری، و نوع حضور است. در حالت کلی:

پارامترهای ورودی

ساختار خروجی

{
  "status": true,
  "time": 1732365532,
  "data": {
    "id": 1125,
    "personnel_id": 19,
    "date": "1404/08/23",
    "status": "present",
    "clock_in": "08:04",
    "clock_out": null,
    "description": "ثبت اتوماتیک حضور"
  }
}

نکات امنیتی

عملکرد

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و ثبت وقایع

جمع‌بندی

attendancePersonnelStore وظیفه‌ی ثبت و به‌روزرسانی سوابق روزانه حضور کارکنان را با سطح دسترسی کنترل‌شده بر عهده دارد. این مسیر پایه‌ی زیرساخت KPI و محاسبات حقوق و دستمزد پرسنل محسوب می‌شود.

GET /personnel/attendance/permission

Route Info

منطق عملکرد تابع

این تابع تعیین می‌کند که کاربر جاری در هنگام ثبت تردد در چه شرایطی مجاز به انجام حضور و غیاب است. تنظیمات بسته به مقدار ذخیره‌شده در کلید ATTENDANCE جدول office_config مشخص می‌شوند.

پارامترهای ورودی

ساختار خروجی

{
  "payload": {
    "type": {
      "fa": "تصویر / موقعیت",
      "en": "full"
    },
    "permission": true,
    "details": {
      "base_image": "base64Encoded...",
      "status": 1
    }
  },
  "meta": {
    "timestamp": 1732365700
  }
}

{
  "error": {
    "code": 1000,
    "message": "تنظیمات تعریف نشده است"
  },
  "meta": { "timestamp": 1732365700 }
}

نکات امنیتی

عملکرد و بهینه‌سازی

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و ثبت وقایع

جمع‌بندی

attendancePersonnelPermission پایه‌ای‌ترین متد زیرساختی برای سیستم حضور و غیاب است که مشخص می‌کند آیا کاربر می‌تواند بر اساس نوع تعریف‌شده دفتر (موقعیت، تصویر یا هر دو) اقدام به ثبت تردد کند یا خیر.

POST /personnel/list

Route Info

منطق عملکرد تابع

تابع personnelList مجموعه‌ای از رکوردهای پرسنل را از پایگاه داده استخراج می‌کند و فیلترهایی که در درخواست آمده را اعمال می‌نماید.

پارامترهای ورودی

ساختار خروجی

{
  "draw": 1,
  "recordsTotal": 25,
  "recordsFiltered": 25,
  "data": [
    {
      "id": 101,
      "first_name": "نگین",
      "last_name": "محمدی",
      "branch": "تهران",
      "status": "active",
      "category": "پشتیبانی",
      "financial_ceiling": 40000000
    }
  ]
}

نکات امنیتی

عملکرد

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و ثبت وقایع

جمع‌بندی

personnelList ابزاری قدرتمند برای مدیران و HR جهت مدیریت و پایش پرسنل با فیلترهای متنوع است.

POST /personnel/bill

Route Info

منطق عملکرد تابع

این متد بر اساس شناسه پرسنل داده‌شده، تمام تراکنش‌های مالی مرتبط (دریافت، پرداخت، اسناد دستی، افتتاحیه/اختتامیه) را واکشی می‌کند، آن‌ها را بر اساس تاریخ مرتب می‌نماید و در قالب ساختار صورت‌حساب یکپارچه بازمی‌گرداند.

پارامترهای ورودی

ساختار خروجی

{
  "draw": 1,
  "recordsTotal": 100,
  "recordsFiltered": 10,
  "filtered": {
    "from": "2025-05-01",
    "to": "2025-06-01"
  },
  "details": {
    "id": 23,
    "first_name": "مریم",
    "last_name": "اکبری",
    "branch": "اصفهان"
  },
  "data": [
    {
      "serial_id": "5100",
      "system_serial": 23,
      "datetime": "1404/02/15 00:00:00",
      "details": {
        "title": {
          "html": "سند افتتاحیه",
          "text": "سند افتتاحیه"
        },
        "type": {
          "subject": "financial_past",
          "title": "افتتاحیه"
        }
      },
      "credit": 2000000,
      "debit": 0,
      "diagnosis": "creditor"
    }
  ]
}

نکات امنیتی

عملکرد

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و ثبت وقایع

جمع‌بندی

personnelBill امکان مشاهده جامع تاریخچه مالی پرسنل را فراهم می‌کند و داده‌ها را در قالب ساختار سندی استاندارد بازمی‌گرداند.

POST /personnel/operation

Route Info

منطق عملکرد تابع

این متد عملیاتی را که از طریق کلید action مشخص می‌شود، روی پرسنل اجرا می‌کند:

در پایان، نتیجه اجرای عملیات به‌صورت JSON بازگردانده می‌شود.

پارامترهای ورودی

ساختار خروجی

// موفق
{
  "status": true,
  "time": 1732365890
}

// خطا
{
  "status": false,
  "time": 1732365890,
  "message": "500 : SQLSTATE[...]", 
  "trace": [ ... ]
}

نکات امنیتی

عملکرد

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و ثبت وقایع

جمع‌بندی

operationPersonnel ابزار مدیریتی پرسنل است که امکان تغییر سریع وضعیت یا اعمال محدودیت را فراهم می‌کند و باید با سیاست‌های امنیتی سختگیرانه اجرا شود.

GET /personnel/access-list

Route Info

منطق عملکرد تابع

این تابع مجموعه‌ای از ماژول‌ها و بخش‌های قابل‌دسترسی در پنل کاربری را به‌صورت درختی بازمی‌گرداند. داده‌ها به شکل آرایه‌ای سازمان‌یافته شامل بخش‌های اصلی (personnel، organizational، salary، modules، contents و ...) و زیربخش‌های هر کدام هستند. هر زیربخش دارای id و title است تا در تنظیمات مدیریت دسترسی (permissions) استفاده شود.

پارامترهای ورودی

این متد هیچ ورودی مستقیم از کاربر نمی‌پذیرد، اما نیاز به احراز هویت JWT دارد تا نقش کاربر مشخص شود.

ساختار خروجی

{
  "status": true,
  "time": 1732366012,
  "data": {
    "personnel": {
      "id": "personnel",
      "title": "پرسنل",
      "children": {
        "profile": {"title": "پروفایل کاربر", "id": "profile"},
        "attendance": {"title": "حضور و غیاب", "id": "attendance"},
        "document": {"title": "مدارک پرسنلی", "id": "document"},
        "bill": {"title": "صورت حساب پرسنل", "id": "bill"}
      }
    },
    "organizational": {"id": "organizational","title": "دپارتمان سازمانی","children": false},
    "salary": {"id": "salary","title": "حقوق و دستمزد","children": false},
    "modules": {
      "id": "modules",
      "title": "ماژول ها",
      "children": {
        "lottery": {"title": "ماژول لاتاری", "id": "lottery"},
        "lottery_registrations": {"title": "ثبت نام های ماژول لاتاری", "id": "lottery_registrations"}
      }
    }
  }
}

نکات امنیتی

عملکرد

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و ثبت وقایع

جمع‌بندی

personnelAccessList ساختار کامل ماژول‌ها و صفحات قابل‌دسترسی سیستم را تولید می‌کند و پایه‌ای برای سیستم مدیریت مجوزهاست. به دلیل استاتیک بودن داده، کارایی بالا و ریسک امنیتی پایین دارد.

GET /personnel

Route Info

منطق عملکرد تابع

این متد بدون نیاز به ورودی جزئی، لیست کامل پرسنل یا اطلاعات پایه آن‌ها را از دیتابیس واکشی می‌کند. بسته به نقش و سطح دسترسی کاربر، ممکن است فیلترهایی روی لیست اعمال شود (مثلاً فقط پرسنل فعال یا پرسنل زیرمجموعه یک شعبه خاص).

پارامترهای ورودی

این متد پارامتر ورودی از کاربر ندارد، اما نیاز به درخواست GET همراه با توکن JWT معتبر دارد.

ساختار خروجی

{
  "status": true,
  "time": 1732366138,
  "data": [
    {
      "id": 1,
      "name": "علی رضایی",
      "username": "alireza",
      "branch": "اصفهان",
      "status": 1,
      "role": "مدیر سیستم",
      "phone": "09123456789",
      "email": "alireza@example.com",
      "created_at": "1404/02/15"
    },
    ...
  ]
}

نکات امنیتی

عملکرد

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و ثبت وقایع

جمع‌بندی

personnelIndex نقطه شروع واکشی داده‌های پرسنل است و باید‌ سریع، امن و منطبق با نقش کاربر اجرا شود.

POST /personnel

Route Info

منطق عملکرد تابع

تابع personnelStore ورودی JSON شامل جزئیات پرسنل را دریافت و صحت‌سنجی می‌کند، سپس رکورد جدیدی در دیتابیس ایجاد می‌کند. بعد از ذخیره، شناسه و اطلاعات پایه کاربر جدید در خروجی برگردانده می‌شود.

پارامترهای ورودی

ساختار خروجی

{
  "status": true,
  "time": 1732366188,
  "data": {
    "id": 152,
    "name": "علیرضا ایرانپور",
    "username": "airanpour",
    "branch": "اصفهان",
    "role": "کارشناس فنی",
    "created_at": "1404/08/03 12:45:21"
  }
}

نکات امنیتی

عملکرد

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و ثبت وقایع

جمع‌بندی

personnelStore نقطه ورود ایجاد پرسنل جدید است و باید با کنترل‌های امنیتی و اعتبارسنجی دقیق همراه باشد.

PUT /personnel

Route Info

منطق عملکرد تابع

تابع personnelUpdate ابتدا بررسی می‌کند که کاربر جاری اجازه ویرایش دارد. سپس داده‌های جدید را از درخواست دریافت کرده، اعتبارسنجی می‌کند و رکورد مربوطه را در جدول operators یا جداول مرتبط به‌روزرسانی می‌نماید. در پایان، خروجی موفقیت‌آمیز برمی‌گرداند.

پارامترهای ورودی

ساختار خروجی

{
  "status": true,
  "time": 1732366220,
  "data": {
    "id": 152,
    "name": "علیرضا ایرانپور",
    "branch": "اصفهان",
    "role": "کارشناس فنی",
    "status": 1,
    "updated_at": "1404/08/03 13:02:31"
  }
}

نکات امنیتی

عملکرد

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و ثبت وقایع

جمع‌بندی

personnelUpdate برای به‌روزرسانی امن و سریع اطلاعات پرسنل استفاده می‌شود و باید با کنترل دقیق مجوز اجرا گردد.

GET /personnel/shift/list

Route Info

منطق عملکرد تابع

تابع shiftWorkList داده‌های تمام شیفت‌های فعال را از پایگاه‌داده واکشی کرده و آن‌ها را در قالب ساختاریافته (با جزئیات زمان شروع، پایان، نوع و توضیحات) بازمی‌گرداند. این خروجی معمولاً برای انتخاب سریع شیفت هنگام تخصیص به پرسنل استفاده می‌شود.

پارامترهای ورودی

ساختار خروجی

{
  "status": true,
  "time": 1732369262,
  "data": [
    {
      "id": 1,
      "title": "شیفت صبح",
      "start": "07:00",
      "end": "15:00",
      "status": 1,
      "description": "کار اداری صبح",
      "created_at": "1404/03/12 10:11:22"
    },
    {
      "id": 2,
      "title": "شیفت عصر",
      "start": "15:00",
      "end": "23:00",
      "status": 1,
      "description": "شیفت عصرگاهی"
    }
  ]
}

نکات امنیتی

عملکرد

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و ثبت وقایع

جمع‌بندی

shiftWorkList نقطهٔ ورودی دریافت لیست کامل شیفت‌هاست. با بازگرداندن جزئیات دقیق زمان‌ها، این مسیر پایهٔ مدیریت و تنظیم شیفت‌های پرسنل در سامانه است.

GET /personnel/shift

Route Info

منطق عملکرد تابع

تابع shiftWorkIndex برای واکشی نمای کلی از شیفت‌های در حال اجرا طراحی شده است. داده‌های جدول شیفت (مثلاً shift_works یا مشابه) را دریافت کرده، سپس نام پرسنل منتسب، زمان‌بندی شروع و پایان، نوع شیفت، و وضعیت فعال یا غیرفعال را بازمی‌گرداند.

پارامترهای ورودی

ساختار خروجی

{
  "status": true,
  "time": 1732369405,
  "data": [
    {
      "id": 12,
      "title": "شیفت صبح کارکنان بخش رزرو",
      "start_time": "07:00",
      "end_time": "15:00",
      "personnel": [
        {"id": 88, "name": "رضا قنبری"},
        {"id": 95, "name": "الهام رضایی"}
      ],
      "status": 1,
      "created_at": "1404/08/01 09:12:13"
    },
    {
      "id": 13,
      "title": "شیفت عصر سیستم فروش",
      "start_time": "15:00",
      "end_time": "23:00",
      "personnel": [],
      "status": 0
    }
  ]
}

نکات امنیتی

عملکرد

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و ثبت وقایع

جمع‌بندی

shiftWorkIndex برای نمایش وضعیت فعلی شیفت‌ها در سیستم طراحی شده و پایهٔ داشبورد مدیریتی بخش پرسنل محسوب می‌شود.

POST /personnel/shift

Route Info

منطق عملکرد تابع

تابع shiftWorkStore‌ مسئول درج رکورد جدید شیفت در پایگاه‌داده است. پس از اعتبارسنجی مقادیر ورودی و بررسی تداخل زمانی با شیفت‌های قبلی، اطلاعات ثبت و پاسخ JSON بازگردانده می‌شود.

پارامترهای ورودی

ساختار خروجی

{
  "status": true,
  "time": 1732369602,
  "data": {
    "id": 24,
    "title": "شیفت عصر سیستم فروش",
    "start": "15:00",
    "end": "23:00",
    "status": 1,
    "description": "شیفت عصر اینترنال تیم فروش",
    "created_at": "1404/08/03 14:05:21"
  }
}

نکات امنیتی

عملکرد

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و ثبت وقایع

جمع‌بندی

shiftWorkStore هسته فرآیند ایجاد شیفت کاری است. این مسیر توسط تیم منابع انسانی برای تعریف ساختار کاری واحدها استفاده می‌شود و جزئیات ضروری هر شیفت را ذخیره می‌کند.

PUT /personnel/shift

Route Info

منطق عملکرد تابع

تابع shiftWorkUpdate برای به‌روزرسانی داده‌های شیفت قبلی طراحی شده است. این تابع بررسی می‌کند که شیفت با id ارسالی وجود دارد و سپس اطلاعات جدید را در همان رکورد ذخیره می‌کند.

پارامترهای ورودی

ساختار خروجی

{
  "status": true,
  "time": 1732369760,
  "data": {
    "id": 24,
    "title": "شیفت عصر سیستم فروش",
    "start": "16:00",
    "end": "23:00",
    "status": 1,
    "description": "تغییر ساعت شروع به ۱۶",
    "updated_at": "1404/08/03 15:21:43"
  }
}

نکات امنیتی

عملکرد

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و ثبت وقایع

جمع‌بندی

shiftWorkUpdate مسیر استاندارد به‌روزرسانی شیفت‌هاست و دقت بالایی در کنترل تداخل و اعتبار داده‌ها دارد. این متد هسته مدیریت اصلاحات شیفت در ماژول منابع انسانی است.

DELETE /personnel/shift

Route Info

منطق عملکرد تابع

تابع shiftWorkDestroy‌ بسته به نوع درخواست دریافتی، یا شیفت را به‌صورت کامل از جدول حذف می‌کند یا با تغییر وضعیت آن به حالت غیرفعال، حذف منطقی انجام می‌دهد. این کنترل ضمن بررسی نقش کاربر، اطمینان حاصل می‌کند که شیفت درحال استفاده (مثلاً تخصیص‌داده‌شده به پرسنل) قابل حذف نیست.

پارامترهای ورودی

ساختار خروجی

{
  "status": true,
  "time": 1732369925,
  "data": {
    "id": 24,
    "deleted_type": "soft",
    "message": "شیفت با موفقیت غیرفعال شد."
  }
}

نکات امنیتی

عملکرد

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و ثبت وقایع

جمع‌بندی

shiftWorkDestroy مسیر رسمی حذف شیفت است که قابلیت حذف منطقی و دائمی را فراهم می‌کند. حذف ایمن با کنترل وابستگی، و ورود لاگ کامل در سامانه حسابرسی از ویژگی‌های کلیدی آن محسوب می‌شود.

* PATCH /personnel/shift/reset

Route Info

منطق عملکرد تابع

تابع shiftWorkReset کلیه رکوردهای شیفت را از نظر وضعیت، زمان‌بندی و تخصیص‌ها بازنشانی می‌کند. معمولاً جهت پاکسازی داده‌های تستی یا آماده‌سازی دوره جدید کاری به‌کار می‌رود.

پارامترهای ورودی

ساختار خروجی

{
  "status": true,
  "time": 1732370189,
  "data": {
    "reset_scope": "all",
    "affected_rows": 46,
    "message": "شیفت‌ها با موفقیت به وضعیت اولیه بازگردانده شدند."
  }
}

نکات امنیتی

عملکرد

Dependencies

کدهای خطا

پیشنهادهای امنیتی

پیشنهادهای توسعه‌ای

ممیزی و ثبت وقایع

جمع‌بندی

shiftWorkReset آخرین مسیر از مجموعه شیفت‌هاست و هدفش بازگرداندن داده‌ها به حالت پایه‌ای و جلوگیری از انباشت خطای انسانی در تنظیمات زمان‌بندی است. این مسیر با اطمینان بالا، کنترل دسترسی دقیق و پشتیبانی کامل لاگ حسابرسی پیاده‌سازی شده است.

POST /api/v2/tasks/category/operation

Route Info

شرح عملکرد (Functionality)

این متد مدیریت کامل (CRUD) دسته‌بندی‌های تسک را بر عهده دارد و بر اساس پارامتر action رفتار متفاوتی نشان می‌دهد:

پارامترهای ورودی (Input Parameters)

ساختار آرایه data:

{
    "title": "عنوان دسته‌بندی",
    "color": "#FF0000",  // کد رنگ HEX
    "icon": "fa-list"    // کلاس آیکون (مثلاً FontAwesome)
}

نمونه خروجی (Response)

در صورت موفقیت عملیات:

{
    "status": true,
    "time": 1732615200
}

در صورت بروز خطا (Exception):

{
    "status": false,
    "time": 1732615200,
    "message": "Error message description",
    "trace": [ ... ]
}

GET /api/v2/tasks/categories/list

Route Info

شرح عملکرد (Functionality)

این متد لیست دسته‌بندی‌های تسک را در دو گروه مجزا ("my" و "other") واکشی می‌کند. منطق تفکیک و پردازش داده‌ها به شرح زیر است:

پارامترهای ورودی (Input Parameters)

نمونه خروجی (Response)

نکته مهم در مورد ساختار داده‌ها: فیلد user در آبجکت دسته‌بندی، یک آبجکت تکی است (چون ایندکس 0 دریافت می‌شود)، اما فیلد operators در داخل تسک‌ها، یک آرایه از آبجکت‌هاست.

{
    "status": true,
    "time": 1732615000,
    "data": {
        "my": [
            {
                "id": 5,
                "user": {
                    "id": 10,
                    "text": "1001 - نام نام‌خانوادگی",
                    "query": {
                        "id": 10,
                        "sex": "male",
                        "first_name": "نام",
                        "last_name": "نام‌خانوادگی",
                        "telegram": "username",
                        "group": "support",
                        "avatar": "path/to/img.jpg",
                        "position": "manager",
                        "personnel_id": 1001
                    }
                },
                "title": "توسعه فنی",
                "color": "#FF5733",
                "icon": "fa-code",
                "status": 1,
                "created": "2024-01-01T12:00:00.000000Z",
                "counter": 3,
                "tasks": [ // فقط اگر tasks=1 ارسال شده باشد پر می‌شود
                    {
                        "id": 101,
                        "user": { ... }, // آبجکت سازنده تسک (مشابه ساختار user بالا)
                        "category": {
                            "id": 5,
                            "title": "توسعه فنی"
                        },
                        "title": "بررسی باگ لاگین",
                        "connection": false, // یا آبجکت کانکشن اگر وجود داشته باشد
                        "priority": 1,
                        "order": 0,
                        "description": "توضیحات تسک...",
                        "deadline": "1403-10-20",
                        "operators": [ // آرایه اپراتورهای مسئول
                             {
                                "id": 12,
                                "text": "1002 - همکار فنی",
                                "query": { ... }
                             }
                        ],
                        "status": 1,
                        "created": "2024-11-01T10:00:00.000000Z"
                    }
                ]
            }
        ],
        "other": [
            {
                "id": 8,
                "user": { ... }, // کاربری که دسته‌بندی را ساخته (نه کاربر جاری)
                "title": "امور مالی",
                "color": "#33FF57",
                "icon": "fa-money",
                "status": 1,
                "created": "2024-02-15T14:30:00.000000Z",
                "counter": 1, // تعداد تسک‌هایی که من در آن‌ها مشارکت دارم
                "tasks": false // اگر tasks ارسال نشود، false برمی‌گردد
            }
        ]
    }
}

GET /api/v2/tasks/list

Route Info

معماری و منطق پردازش (Processing Logic & Architecture)

این متد لیست وظایف را با مکانیزم Lazy Loading دستی آماده‌سازی می‌کند. پس از دریافت رکوردهای خام از جدول tasks_items، سیستم طی یک فرآیند Post-Processing روی هر آیتم حلقه زده و توابع Helper استاتیک را فراخوانی می‌کند:

ساختار پاسخ (Response Structure)

خروجی زیر دقیقاً بر اساس توابع getOperators و getConnection که ارائه کردید بازسازی شده است:

{
  "status": true,
  "time": 1732047000,
  "data": [
    {
      "id": 105,
      "title": "پیگیری رفرنس ۱۲۵۰",
      "category": {
        "id": 12,
        "title": "مالی و حسابداری"
      },
      
      // خروجی دقیق getOperators برای فیلد user (سازنده)
      "user": [
        {
          "id": 50,
          "text": "10050 - علی محمدی",
          "query": {
            "id": 50,
            "sex": "male",
            "first_name": "علی",
            "last_name": "محمدی",
            "telegram": "ali_dev",
            "group": "IT",
            "avatar": "path/to/avatar.jpg",
            "position": "مدیر فنی",
            "personnel_id": "10050"
          }
        }
      ],

      // خروجی دقیق getOperators برای فیلد operators (مسئولین انجام)
      "operators": [
        {
          "id": 51,
          "text": "10051 - رضا علوی",
          "query": {
            "id": 51,
            "sex": "male",
            "first_name": "رضا",
            "last_name": "علوی",
            "telegram": "reza_acc",
            "group": "Accounting",
            "avatar": null,
            "position": "حسابدار ارشد",
            "personnel_id": "10051"
          }
        }
      ],

      // خروجی دقیق getConnection (در صورتی که تسک به رفرنس متصل باشد)
      "connection": [
        {
          "id": 2050,
          "type": "reference",
          "title": "تور کیش - هتل داریوش", // خوانده شده از Redis
          "financial": {
             // آبجکت بازگشتی از TradeController::financial
             "total_price": 50000000,
             "paid": 20000000,
             "remaining": 30000000,
             "status": "debtor"
          }
        }
      ],

      "priority": 1,
      "order": 0,
      "description": "لطفا مانده حساب این رفرنس با مشتری چک شود.",
      "deadline": "2025-02-20",
      "status": 1,
      "created": "2025-02-18 10:30:00"
    }
  ]
}

POST /api/v2/tasks/task/operation

Route Info

شرح عملکرد (Functionality)

این متد یک رابط چندمنظوره برای مدیریت چرخه حیات تسک‌ها است که بر اساس پارامتر action عملیات‌های مختلفی را روی دیتابیس اجرا می‌کند:

پارامترهای ورودی (Body Parameters)

ساختار آبجکت data:

نمونه خروجی (Response)

عملیات موفق (Success):

{
    "status": true,
    "time": 1732048123,
    "tasks": 12 // (فقط در update_status موجود است)
}

بروز خطا (Error):

{
    "status": false,
    "time": 1732048123,
    "message": "Error description...",
    "trace": [...]
}

GET /api/v2/tasks/task/details

Route Info

شرح عملکرد (Functionality)

این متد جزئیات تکمیلی یک تسک مشخص را که شامل یادداشت‌ها (Notes) و چک‌لیست‌ها (Checklists) است، بازیابی می‌کند. منطق عملکرد به شرح زیر است:

پارامترهای ورودی (Input Parameters)

نمونه خروجی (Response)

خروجی شامل آبجکت payload است که دو بخش اصلی notes و checklist را در بر می‌گیرد.

{
    "payload": {
        "notes": [
            {
                "user": {
                    "id": 10,
                    "text": "1001 - نام کاربر",
                    "query": { ... } // جزئیات کامل کاربر
                },
                "note": "این یک یادداشت نمونه برای تسک است.",
                "created": "2024-11-25T10:00:00.000000Z"
            }
        ],
        "checklist": [
            {
                "id": 55,
                "operator": { // کاربری که آیتم چک‌لیست را ایجاد کرده
                    "id": 10,
                    "text": "1001 - ایجاد کننده",
                    "query": { ... }
                },
                "content": "بررسی مستندات فنی",
                "done": true,
                "done_by": { // کاربری که آیتم را تیک زده (انجام داده)
                    "id": 12,
                    "text": "1002 - انجام دهنده",
                    "query": { ... }
                },
                "done_at": "2024-11-26 14:30:00",
                "created_at": "2024-11-25T09:00:00.000000Z"
            },
            {
                "id": 56,
                "operator": { ... },
                "content": "تست نهایی روی سرور استیج",
                "done": false,
                "done_by": false, // چون انجام نشده
                "done_at": false, // چون انجام نشده
                "created_at": "2024-11-25T09:05:00.000000Z"
            }
        ]
    },
    "meta": {
        "timestamp": 1732616000
    }
}

GET /api/v2/support/departments/list

Route Info

شرح عملکرد (Functionality)

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

پارامترهای ورودی (Input Parameters)

نمونه خروجی (Response)

{
    "status": true,
    "time": 1732617000,
    "data": [
        {
            "id": 1,
            "allowed_response": 1, // سطح دسترسی پاسخ‌دهی (مثلا: 1 برای همه)
            "description": "سوالات مربوط به پروازهای داخلی و خارجی",
            "title": {
                "fa": "فروش پرواز", // بدون تغییر چون کلمه 'آژانس' ندارد
                "en": "Flight Sales"
            }
        },
        {
            "id": 2,
            "allowed_response": 0,
            "description": "پیگیری موارد مالی و حسابداری",
            "title": {
                "fa": "امور مالی آسمان سیر", // 'آژانس' با 'آسمان سیر' جایگزین شده است
                "en": "Finance Department"
            }
        }
    ]
}

GET /api/v2/support/department/members

Route Info

شرح عملکرد (Functionality)

این متد لیست اعضای (پاسخ‌دهندگان) یک دپارتمان پشتیبانی خاص را برمی‌گرداند. فرآیند پردازش به شرح زیر است:

پارامترهای ورودی (Input Parameters)

نمونه خروجی (Response)

خروجی شامل آرایه‌ای از آبجکت‌های کاربر در فیلد items است.

{
    "items": [
        {
            "id": 15,
            "text": "1005 - نام و نام خانوادگی",
            "query": {
                "id": 15,
                "personnel_id": 1005,
                "first_name": "نام",
                "last_name": "نام خانوادگی",
                "branch": "[1]",
                "status": 1,
                // سایر فیلدهای جدول کاربران
                ...
            }
        },
        {
            "id": 22,
            "text": "1008 - کاربر دوم",
            "query": { ... }
        }
    ],
    "meta": {
        "timestamp": 1732618000
    }
}

نمونه خطا (در صورت نبود دپارتمان یا عضو):

{
    "error": {
        "code": 1000,
        "message": "در این دپارتمان عضوی وجود ندارد و یا اینکه دپارتمان اشتباه ارسال شده است."
    },
    "meta": {
        "timestamp": 1732618005
    }
}

GET /api/v2/support/department/questions/list

Route Info

شرح عملکرد (Functionality)

این متد لیست سوالات پیش‌فرض (یا موضوعات تیکت) مربوط به یک دپارتمان خاص را برمی‌گرداند. کوئری دیتابیس شامل فیلترهای زیر است:

نکته: خروجی مستقیماً تمام ستون‌های جدول support_questions را بدون تغییر ساختار برمی‌گرداند.

پارامترهای ورودی (Input Parameters)

نمونه خروجی (Response)

{
    "status": true,
    "time": 1732619000,
    "data": [
        {
            "id": 101,
            "department": 5,
            "title": "مشکل در صدور بلیط",
            "relationship": null, // چون whereNull اعمال شده
            "status": 1,
            "created_at": "2024-01-01 12:00:00",
            "updated_at": "2024-01-01 12:00:00"
        },
        {
            "id": 102,
            "department": 5,
            "title": "درخواست استرداد وجه",
            "relationship": null,
            "status": 1,
            "created_at": "2024-01-02 10:30:00",
            "updated_at": "2024-01-02 10:30:00"
        }
    ]
}

GET /api/v2/support/tickets

Route Info

شرح عملکرد (Functionality)

این متد لیست تیکت‌های پشتیبانی را بر اساس نقش کاربر (درخواست‌کننده یا پاسخ‌دهنده) مدیریت می‌کند. نکات کلیدی منطق آن عبارتند از:

پارامترهای ورودی (Input Parameters)

نمونه خروجی (Response)

{
    "items": [
        {
            "id": 505,
            "type": "send", // تیکت ارسال شده توسط کاربر
            "department": {
                "id": 3,
                "title": {
                    "fa": "پشتیبانی فنی",
                    "en": "Technical Support"
                }
            },
            "requester": { // اطلاعات کامل کاربر درخواست دهنده
                "id": 10,
                "text": "1001 - نام کاربر",
                "query": { ... }
            },
            "operator": false, // هنوز اپراتوری پاسخ نداده
            "score": 0,
            "status": 1,
            "unread": 1, // تعداد پیام‌های جدید
            "created_at": "2024-11-20 14:00:00"
        },
        {
            "id": 498,
            "type": "receive", // تیکت دریافتی (کاربر عضو دپارتمان است)
            "department": {
                "id": 2,
                "title": {
                    "fa": "امور مالی",
                    "en": "Finance"
                }
            },
            "requester": {
                "id": 55,
                "text": "1055 - مشتری نمونه",
                "query": { ... }
            },
            "operator": { // اپراتوری که تیکت را هندل می‌کند
                "id": 10,
                "text": "1001 - نام کاربر",
                "query": { ... }
            },
            "score": 5,
            "status": 2,
            "unread": 0,
            "created_at": "2024-11-18 09:30:00"
        }
    ],
    "payload": {
        "wating": 5 // تعداد کل تیکت‌های باز مرتبط
    },
    "meta": {
        "total_records": 25,
        "total_pages": 2,
        "current_page": 1,
        "per_page": 20,
        "last_page": 2,
        "next_page": 2,
        "prev_page": 0,
        "from": 1,
        "to": 20,
        "timestamp": 1732620000
    }
}

POST /api/v2/support/ticket/update

Route Info

شرح عملکرد (Functionality)

این متد برای بروزرسانی اطلاعات مختلف یک تیکت استفاده می‌شود. ساختار کد به صورت if/else if است، به این معنی که در هر درخواست تنها یکی از عملیات زیر بر اساس اولویت پارامتر ارسالی انجام می‌شود:

پارامترهای ورودی (Input Parameters)

* نکته: در هر درخواست باید فقط یکی از پارامترهای اختیاری ارسال شود تا عملیات مربوطه انجام گیرد.

نمونه خروجی (Response)

{
    "status": true,
    "time": 1732621500
}

PATCH /api/v2/support/ticket/notice

Route Info

شرح عملکرد (Functionality)

این متد برای ارسال دستی اعلان (Notification) به درخواست‌کننده تیکت (Requester) جهت اطلاع‌رسانی درباره پاسخ داده شدن به تیکت استفاده می‌شود. فرآیند به شرح زیر است:

پارامترهای ورودی (Input Parameters)

نمونه خروجی (Response)

در صورت موفقیت، کد وضعیت 201 (Created) بدون بدنه (Body) بازگردانده می‌شود.

HTTP/1.1 201 Created

در صورت بروز خطای سیستمی:

{
    "error": {
        "code": 0,
        "message": "Error description...",
        "trace": [...]
    },
    "meta": {
        "timestamp": 1732622000
    }
}

GET /api/v2/support/ticket/notes/list

Route Info

شرح عملکرد (Functionality)

این متد وظیفه بازگرداندن جزئیات کامل یک تیکت و لیست گفتگوهای (Notes) آن را بر عهده دارد. همچنین به صورت همزمان عملیات "خوانده شدن" پیام‌ها را انجام می‌دهد. نکات فنی و منطقی آن عبارتند از:

پارامترهای ورودی (Input Parameters)

نمونه خروجی (Response)

{
    "status": true,
    "time": 1732623000,
    "data": {
        "department": {
            "id": 3,
            "type": "send", // 'send' if user is requester, else 'receive'
            "title": {
                "fa": "پشتیبانی فنی",
                "en": "Technical Support"
            }
        },
        "requester": { // آبجکت کامل کاربر درخواست دهنده
            "id": 10,
            "text": "1001 - نام کاربر",
            "query": {
                "id": 10,
                "sex": "male",
                "first_name": "Ali",
                "last_name": "Rezaei",
                "avatar": "...",
                "position": "...",
                "personnel_id": 1001
            }
        },
        "operator": false, // یا آبجکت کامل اپراتور پاسخگو
        "ticket": {
            "status": 1,
            "score": 0
        },
        "notes": [
            {
                "id": 1205,
                "type": "text",
                "operator": { ... }, // نویسنده پیام
                "note": "سلام، لطفا بررسی کنید.", // متن پیام
                "read_by": false, // یا آبجکت کاربری که پیام را خوانده
                "read_on": false, // تاریخ خوانده شدن
                "created_at": "2024-11-26 10:00:00"
            },
            {
                "id": 1206,
                "type": "text", // نوع در دیتابیس attachment است اما در خروجی text ست می‌شود (چون به HTML تبدیل شده)
                "operator": { ... },
                "note": "", // خروجی HTML
                "read_by": { ... },
                "read_on": "2024-11-26 10:05:00",
                "created_at": "2024-11-26 10:01:00"
            }
        ]
    }
}

نمونه خطا (عدم دسترسی):

{
    "status": false,
    "time": 1732623000,
    "message": "شما اجازه دسترسی به این گفتگو را ندارید"
}

DELETE /api/v2/support/ticket/delete

Route Info

شرح عملکرد (Functionality)

این متد وظیفه حذف فیزیکی و کامل یک تیکت و تمامی سوابق گفتگوهای آن را بر عهده دارد. عملیات به صورت غیرقابل بازگشت انجام می‌شود:

پارامترهای ورودی (Input Parameters)

نمونه خروجی (Response)

{
    "status": true,
    "time": 1732625000
}

GET /api/v2/exams/list

Route Info

شرح عملکرد (Functionality)

این متد لیست تمامی آزمون‌های فعال مرتبط با شعبه جاری را استخراج کرده و آماری از وضعیت هر آزمون ارائه می‌دهد:

پارامترهای ورودی (Input Parameters)

نمونه خروجی (Response)

{
    "status": true,
    "time": 1732626000,
    "data": [
        {
            "id": 10,
            "type": "general",
            "title": "آزمون جامع نیمسال اول",
            "requests": 25,
            "answers": 140
        },
        {
            "id": 12,
            "type": "specialized",
            "title": "آزمون تخصصی فنی",
            "requests": 10,
            "answers": 45
        }
    ]
}

PATCH /api/v2/exams/answers/list/follow-up

Route Info

شرح عملکرد (Functionality)

این متد برای به‌روزرسانی وضعیت «پیگیری» (Follow-up) یک رکورد خاص در جدول پاسخ‌نامه‌های آزمون (exam_response) استفاده می‌شود. کاربرد اصلی آن احتمالا علامت‌گذاری پاسخ‌نامه‌ها برای بررسی مجدد یا تغییر وضعیت رسیدگی به آن‌ها توسط مدیریت است.

پارامترهای ورودی (Input Parameters)

نمونه خروجی (Response)

در صورت موفقیت، سرور کد وضعیت 204 No Content را بدون بازگرداندن هیچ داده‌ای (Body خالی) ارسال می‌کند.

HTTP/1.1 204 No Content

GET /api/v2/exams/answers/evaluation

Route Info

شرح عملکرد (Functionality)

این متد وظیفه تحلیل آماری و تجمیع پاسخ‌های داده شده به یک آزمون خاص را بر عهده دارد. سیستم تمام سوالات فعال آزمون را استخراج کرده و برای هر سوال، پاسخ‌های کاربران را بر اساس نوع سوال پردازش می‌کند:

پارامترهای ورودی (Input Parameters)

نمونه خروجی (Response)

{
    "status": true,
    "time": 1732628000,
    "data": [
        {
            "id": 101,
            "type": "single_choice",
            "subject": "رضایت‌مندی",
            "title": "از کیفیت دوره چقدر رضایت دارید؟ (1 تا 5)",
            "options": ["1", "2", "3", "4", "5"],
            "description": null,
            "mandatory": 1,
            "score": 0,
            "order": 1,
            "relation": false,
            "average": 4,
            "counter": 50,
            "evaluation": {
                "5": 30,
                "4": 15,
                "3": 5
            }
        },
        {
            "id": 102,
            "type": "explanatory",
            "subject": "نظرات",
            "title": "پیشنهاد خود را بنویسید",
            "average": 0,
            "counter": 12,
            "evaluation": [
                {"response": "بسیار عالی بود"},
                {"response": "زمان کلاس کم بود"}
            ]
        }
    ]
}

GET /api/v2/salary/annual-obligation

Route Info

شرح عملکرد (Functionality)

این متد اطلاعات مربوط به تعهدات مالی و پارامترهای محاسباتی حقوق و دستمزد (مانند پایه حقوق، سقف مالیاتی، حق مسکن و...) را برای یک سال مالی مشخص بازیابی می‌کند.

پارامترهای ورودی (Input Parameters)

نمونه خروجی (Response)

{
    "status": true,
    "time": 1732629000,
    "data": [
        {
            "id": 5,
            "year": 1403,
            "min_salary": 70000000,
            "housing_allowance": 9000000,
            "description": "بخشنامه حقوق سال 1403",
            "created_at": "2024-03-20 10:00:00"
        }
    ]
}

GET /api/v2/scheduled/notifications

Route Info

تحلیل دقیق عملکرد (Deep Functionality Analysis)

این متد وظیفه استخراج و آماده‌سازی لیست اعلانات زمان‌بندی شده (Scheduled Notifications) را دارد. برخلاف یک کوئری ساده، این تابع عملیات Sanitization (پاک‌سازی) و Transformation (تغییر فرمت) را روی داده‌ها انجام می‌دهد.

مراحل اجرای کد:

ورودی‌ها و وابستگی‌ها (Inputs & Dependencies)

ساختار پاسخ‌ها (Response Structures)

✅ پاسخ موفق (Success - 200 OK)

در صورت اجرای موفقیت‌آمیز، آرایه‌ای شامل وضعیت، زمان سرور و لیست داده‌ها برگردانده می‌شود.

{
    "status": true,
    "time": 1732631000, // Timestamp زمان اجرای درخواست
    "data": [
        {
            "id": 15, // فیلدهای باقی‌مانده از جدول
            "title": "Title from DB", // (فرض بر وجود این فیلد در دیتابیس)
            "message": "Message Body", // (فرض بر وجود این فیلد در دیتابیس)
            // فیلدهای Decode شده:
            "recipients": ["user_group_1", "user_group_2"], // فرمت آرایه
            "devices": {"android": true, "ios": false}, // فرمت آبجکت
            "mobiles": ["0912xxxxxxx"] // فرمت آرایه
            // نکته: created_at, updated_at, branch در اینجا وجود ندارند.
        }
    ]
}

❌ پاسخ خطا (Failure - Exception Captured)

در صورت بروز خطای سیستمی (Exception)، بلوک catch فعال شده و خروجی زیر را تولید می‌کند:

{
    "status": false,
    "time": 1732631005,
    "message": "HY000 : SQLSTATE[HY000] [2002] Connection refused", // کد خطا + متن خطا
    "trace": [ ... ] // آرایه کامل Stack Trace برای دیباگ (فقط در محیط توسعه باید نمایش داده شود)
}

POST /api/v2/scheduled/notifications

Route Info

تحلیل دقیق عملکرد (Deep Functionality Analysis)

این متد برای ذخیره‌سازی رکوردها در جدول scheduled_notifications استفاده می‌شود. برخلاف بسیاری از متدها که از Eloquent Model استفاده می‌کنند، این متد از DB::table برای درج مستقیم (Raw Insert) استفاده می‌کند که سربار کمتری دارد.

مراحل اجرای کد:

پارامترهای ورودی (Input Parameters)

ساختار پاسخ‌ها (Response Structures)

✅ Success (200 OK)

در صورت درج موفقیت‌آمیز:

{
    "status": true,
    "time": 1732631200
}

❌ Error (Exception Captured)

در صورت بروز هرگونه خطا (مثلاً خطای دیتابیس یا نبود فیلد اجباری):

{
    "status": false,
    "time": 1732631205,
    "message": "23000 : SQLSTATE[23000]: Integrity constraint violation...",
    "trace": [ ... ] // Stack trace کامل خطا
}

PUT /api/v2/scheduled/notifications

Route Info

تحلیل دقیق عملکرد (Deep Functionality Analysis)

این متد یک بروزرسانی کامل (Full Update) روی جدول scheduled_notifications انجام می‌دهد. نکته حیاتی اینجاست که حتی فیلدهای سیستمی مانند branch و operator نیز بازنویسی می‌شوند.

منطق دقیق کد:

پارامترهای پردازش شده (Processed Parameters)

این جدول شامل تمام داده‌هایی است که در آرایه $update استفاده شده‌اند، چه توسط کاربر ارسال شوند و چه توسط سیستم تزریق شوند.

ساختار پاسخ‌ها (Response Structures)

✅ Success (200 OK)

{
    "status": true,
    "time": 1732631500
}

❌ Error (Exception Captured)

{
    "status": false,
    "time": 1732631505,
    "message": "...", // PHP/SQL Error Message
    "trace": [ ... ]
}

POST /api/v2/banks/list

Route Info

تحلیل دقیق عملکرد (Deep Functionality Analysis)

این متد یک کوئری مستقیم روی دیتابیس اجرا می‌کند:

SELECT * FROM accounting_banks WHERE status = 1

نکات (Fact-Based):

ساختار پاسخ‌ها (Response Structures)

ساختار خروجی دقیقاً منطبق بر ساختار جدول دیتابیس (Schema) است که در کدهای ارسالی موجود نیست.

✅ Success (200 OK)

[
    {
        "status": 1,
        // سایر ستون‌های جدول accounting_banks عیناً در اینجا قرار می‌گیرند.
        // (نام و تعداد فیلدها وابسته به دیتابیس است)
    },
    ...
]

POST /v2/account/bill

Route Info

شرح عملکرد (Functionality)

این متد وظیفه تولید "صورت‌حساب" (Statement of Account) را برای یک حساب خاص (گروه، کل، معین یا تفضیلی) بر عهده دارد. این تابع تراکنش‌های مالی را از منابع مختلف (اسناد پرداخت، چک‌ها، ارزش افزوده و اسناد افتتاحیه/اختتامیه) جمع‌آوری کرده، بدهکار/بستانکار بودن را محاسبه نموده و خروجی را جهت نمایش در جداول مالی آماده می‌کند. نکات فنی و منطقی آن عبارتند از:

پارامترهای ورودی (Input Parameters)

نمونه خروجی (Response)

{
    "Bills": [
        {
            "serial_id": 15100, // سریال نمایشی سند
            "system_serial": 101, // شناسه سیستمی رکورد
            "datetime": "1403/01/01 00:00:00",
            "credit": 0, // مبلغ بستانکار
            "debit": 5000000, // مبلغ بدهکار
            "details": {
                "title": {
                    "html": "سند افتتاحیه سال 1403 ...", // توضیحات با فرمت HTML
                    "text": "سند افتتاحیه سال 1403 ..."
                },
                "type": {
                    "subject": "financial_past",
                    "title": "افتتاحیه"
                }
            },
            "communications": false
        },
        {
            "serial_id": 2050,
            "system_serial": 5002,
            "datetime": "1403/05/10 12:30:00",
            "credit": 1200000,
            "debit": 0,
            "details": {
                "title": {
                    "html": "سند دریافت وجه نقد | بابت ...",
                    "text": "سند دریافت وجه نقد | بابت ..."
                },
                "type": {
                    "subject": "pay",
                    "title": "سندمالی"
                }
            }
        }
        // ... سایر ردیف‌ها
    ],
    "Total": {
        "credit": 1200000,
        "debit": 5000000,
        "balance": 3800000,
        "diagnosis": "Debtor" // وضعیت نهایی: Debtor (بدهکار)، Creditor (بستانکار)، Neutral (تراز)
    }
}

POST /v2/account/bill2

Route Info

شرح عملکرد دقیق (Deep Logic Analysis)

این متد صورت‌حساب، برخلاف نسخه ساده قبلی، دارای منطق "تفسیر و تجمیع" است که وابستگی شدیدی به توابع استاتیک کمکی دارد:

ساختار خروجی (Refined Response)

با توجه به فایل جدید، ساختار خروجی شامل فیلد subset برای تراکنش‌های تجمیعی است:

{
    "Bills": [
        {
            // نمونه تراکنش معمولی
            "serial_id": 15102,
            "system_serial": 204,
            "datetime": "1403/02/15 10:00:00",
            "credit": 0,
            "debit": 2500000,
            "details": {
                "title": {
                    "html": "سند پرداخت پایا...",
                    "text": "سند پرداخت پایا..."
                },
                "type": {
                    "subject": "pay",
                    "title": "سندمالی"
                }
            }
        },
        {
            // نمونه تراکنش تجمیعی (POS) - کشف شده در فایل جدید
            "serial_id": "1403021601", // ID ترکیبی از تاریخ
            "system_serial": "1403021601",
            "datetime": "1403/02/16 00:00:00",
            "credit": 50000000, // جمع کل کارتخوان‌های آن روز
            "debit": 0,
            "details": {
                "title": {
                    "html": "سند مجموع کارتخوان های 1403/02/16",
                    "text": "سند مجموع کارتخوان های 1403/02/16"
                },
                "type": {
                    "subject": "pos",
                    "title": "سند کارتخوان"
                }
            },
            "subset": [ // <--- بخش جدید اضافه شده
                {
                    "id": 5001,
                    "amount": 20000000,
                    "description": "تراکنش اول..."
                },
                {
                    "id": 5002,
                    "amount": 30000000,
                    "description": "تراکنش دوم..."
                }
            ]
        }
    ],
    "Total": {
        "credit": 50000000,
        "debit": 2500000,
        "balance": 47500000,
        "diagnosis": "Creditor"
    }
}

وابستگی‌های سیستمی (System Dependencies)

عملکرد صحیح این روت به وجود و صحت توابع زیر در فایل‌های Helper وابسته است:

POST /v2/currencies/list

Route Info

شرح عملکرد (Functionality)

این متد وظیفه ارائه لیست ارزهای موجود در سیستم را دارد و داده‌های استاتیک دیتابیس را با داده‌های لحظه‌ای (نرخ بازار) ترکیب می‌کند.

پارامترهای ورودی (Input Parameters)

نمونه خروجی (Response)

{
    "status": true,
    "time": 1715765000, // Unix Timestamp
    "data": [  // (فقط یک مثال جهت فهم بهتر میباشد)
        {
            "id": 1,
            "title": "دلار آمریکا",
            "icon": "USD",
            "symbol": "$",
            "select": 1,
            "status": 1,
            "rate": {
                "value": 580000, // (نرخ ردیس * 10)
                "datetime": "2024-05-15 10:30:00" // زمان آخرین آپدیت نرخ
            }
        },
        {
            "id": 2,
            "title": "یورو",
            "icon": "EUR",
            "symbol": "€",
            "select": 0,
            "status": 1,
            "rate": {
                "value": 620000,
                "datetime": "2024-05-15 10:30:00"
            }
        }
    ]
}

POST /v2/accounts/list

Route Info

شرح عملکرد (Functionality)

این متد لیست حساب‌های بانکی/مالی فعال مربوط به شعبه کاربر جاری را برمی‌گرداند و اطلاعات حساب را با اطلاعات بانک عامل ادغام می‌کند.

ساختار خروجی (Response)

توجه: برخلاف سایر متدها، این متد مستقیماً یک آرایه (Array) برمی‌گرداند و فاقد کلیدهای استاندارد status یا data است.

[
    {
        "id": 105,
        "branch": 2,
        "bank": 12, // شناسه بانک در جدول accounting_banks
        "account_number": "123-456-789",
        "sheba": "IR000000000000000000",
        "status": 1,
        "title": "بانک ملت", // برگرفته از title_fa جدول بانک‌ها
        "logo": "mellat.png", // برگرفته از جدول بانک‌ها
        "balance": 5000000, // سایر فیلدهای جدول اکانت...
        "pos_device": 1
    },
    {
        "id": 106,
        "branch": 2,
        "bank": 4,
        "title": "بانک پاسارگاد",
        "logo": "pasargad.png",
        // ...
    }
]

GET /v2/accounting/account

Route Info

شرح عملکرد (Functionality)

این متد جزئیات کامل یک حساب تفضیلی/بانکی خاص را برمی‌گرداند. تفاوت اصلی این متد با لیست‌گیری، در نرمال‌سازی (Normalize) داده‌ها و دسته‌بندی اطلاعات در آبجکت‌های تو در تو است.

پارامترهای ورودی (Input Parameters)

نمونه خروجی موفق (Success Response)

{
    "status": true,
    "time": 1715768000,
    "data": {
        "id": 15,
        "bank": {
            "id": 3,
            "title": "بانک ملی ایران",
            "logo": "melli.png"
        },
        "account_number": "010555666777", // مپ شده از فیلد number
        "card": "6037991122334455",
        "sheba": "IR55017000000010555666777",
        "check": 1, // وضعیت دسته‌چک (دارد/ندارد)
        "type": "bank", // یا "cash"
        "currency": "rials", // یا "currency"
        "branch": {
            "code": "1245",
            "title": "شعبه مرکزی"
        },
        "pos": {
            "code": "998877", // سریال دستگاه پوز
            "status": true   // آیا متصل است؟
        },
        "gateway": {
            "data": "merchant_id_example", // اطلاعات اتصال درگاه
            "status": true
        },
        "status": 1,
        "created_at": "2023-01-01 12:00:00"
    }
}

نمونه خروجی خطا (Error Response)

در صورت بروز هرگونه خطا (مانند پیدا نشدن رکورد یا خطای دیتابیس):

{
    "status": false,
    "time": 1715768005,
    "code": 0, // کد خطا
    "message": "Attempt to read property \"id\" on null", // متن خطا
    "trace": [...] // جزئیات فنی برای دیباگ
}

POST /v2/accounting/account

Route Info

شرح عملکرد (Functionality)

این متد وظیفه ثبت یک حساب بانکی یا صندوق جدید در سیستم را بر عهده دارد. برخلاف متد نمایش، این متد داده‌های دریافت شده از کلاینت را به فرمت عددی و دیتابیسی تبدیل (Reverse Mapping) می‌کند.

پارامترهای ورودی (JSON Body)

ساختار جیسون ارسالی باید به شکل زیر باشد:

{
    "branch": 2,               // شناسه شعبه
    "bank": 12,                // شناسه بانک از لیست بانک‌ها
    "account_number": "123456",// شماره حساب
    "card": "6037...",         // شماره کارت (اختیاری)
    "sheba": "IR00...",        // شماره شبا (اختیاری)
    "type": "bank",            // نوع: "bank" یا "cash"
    "currency": "rials",       // ارز: "rials" یا "currency"
    "check": true,             // آیا دسته چک دارد؟
    "status": 1,               // وضعیت فعال/غیرفعال
    "branch": {                // آبجکت اطلاعات شعبه
        "code": "101",
        "title": "مرکزی"
    },
    "pos": {                   // تنظیمات پوز
        "status": true,
        "code": "990011"       // سریال پوز
    },
    "gateway": {               // تنظیمات درگاه آنلاین
        "status": false,
        "data": null
    }
}

خروجی (Response)

موفقیت (Success):

{
    "status": true,
    "time": 1715772000
}

خطا (Error):

در صورت بروز خطای سیستمی (مثلاً دیتابیس یا فرمت داده):

{
    "status": false,
    "time": 1715772005,
    "code": 0,
    "message": "SQLSTATE[23000]: Integrity constraint violation...",
    "trace": [...]
}

PUT /v2/accounting/account

Route Info

شرح عملکرد (Functionality)

این متد اطلاعات یک حساب موجود را به طور کامل بازنویسی (Full Update) می‌کند. شناسه حساب از طریق بدنه درخواست (Body) دریافت می‌شود.

پارامترهای ورودی (JSON Body)

هشدار: تمام فیلدهای زیر الزامی هستند. حتی اگر تغییری نکرده‌اند باید ارسال شوند، در غیر این صورت ممکن است با خطای سیستمی مواجه شوید.

{
    "id": 15,                  // شناسه حساب (الزامی برای پیدا کردن رکورد)
    "branch": {                // آبجکت شعبه (الزامی)
        "code": "101",
        "title": "شعبه مرکزی"
    },
    "bank": 12,
    "account_number": "987654321",
    "card": "6037...",
    "sheba": "IR99...",
    "type": "bank",            // یا "cash"
    "currency": "rials",       // یا "currency"
    "check": true,
    "status": 1,
    "pos": {
        "status": true,
        "code": "NEW_POS_SERIAL"
    },
    "gateway": {
        "status": false,
        "data": null
    }
}

خروجی (Response)

موفقیت (Success):

{
    "status": true,
    "time": 1715775000
}

نکته امنیتی/منطقی:

اگر id ارسال شده وجود نداشته باشد، سیستم همچنان status: true برمی‌گرداند اما عملاً هیچ تغییری در دیتابیس رخ نداده است (Silent Failure).

خطا (Error):

در صورت ارسال ناقص داده‌ها (مثلاً حذف آبجکت branch):

{
    "status": false,
    "time": 1715775005,
    "code": 0,
    "message": "Trying to access array offset on value of type null",
    "trace": [...]
}

DELETE /v2/accounting/account

Route Info

شرح عملکرد (Functionality)

این متد وظیفه حذف فیزیکی (Hard Delete) یک حساب از جدول accounting_accounts را دارد.

پارامترهای ورودی (JSON Body)

با وجود اینکه متد از نوع DELETE است، پارامتر id در بدنه درخواست (Body) انتظار می‌رود:

{
    "id": 15  // شناسه حسابی که باید حذف شود
}

خروجی (Response)

موفقیت (Success):

{
    "status": true,
    "time": 1715779000
}

خطا (Error):

ممکن است در صورت وجود وابستگی‌های دیتابیسی (Foreign Keys) خطای Integrity Violation رخ دهد:

{
    "status": false,
    "time": 1715779005,
    "code": "23000",
    "message": "SQLSTATE[23000]: Integrity constraint violation: 1451 Cannot delete or update a parent row...",
    "trace": [...]
}

GET /v2/wallet/balance

Route Info

شرح عملکرد (Functionality)

این متد وظیفه محاسبه تراز کیف پول (Wallet) را بر عهده دارد. بر اساس کدهای فعلی، این متد صرفاً موجودی کیف پول شعبه (ERP) را محاسبه می‌کند.

پارامترهای ورودی (Query String)

?type=office       // (بلااستفاده) به دلیل باگ داخلی نادیده گرفته می‌شود
&id=101            // (اختیاری) شناسه شعبه. اگر ارسال نشود از توکن کاربر خوانده می‌شود

خروجی (Response)

موفقیت (Success):

ساختار خروجی استاندارد شامل payload (داده اصلی) و meta (اطلاعات متا) است.

{
    "payload": {
        "credit": 15000000,       // مجموع ورودی‌ها
        "debit": 5000000,         // مجموع خروجی‌ها
        "balance": 10000000,      // مانده (credit - debit)
        "diagnosis": "creditor"   // وضعیت: creditor | debtor | neutral
    },
    "meta": {
        "timestamp": 1715780000
    }
}

خطا (Error):

{
    "status": false,
    "time": 1715780005,
    "message": "Error message here...",
    "trace": [...]
}

POST /v2/wallet/check

Route Info

شرح عملکرد (Functionality)

این متد برای بررسی کفایت موجودی (Balance Check) قبل از انجام تراکنش استفاده می‌شود. برخلاف متد balance که فقط گزارش می‌دهد، این متد معمولاً یک پاسخ Boolean یا آبجکت وضعیت برمی‌گرداند که آیا تراکنش با مبلغ مشخص شده مجاز است یا خیر.

پارامترهای ورودی (JSON Body)

تمامی فیلدها الزامی هستند:

{
    "type": "office",      // نوع کیف پول (office, user, colleague)
    "id": 101,             // شناسه مالک کیف پول
    "amount": 5000000      // مبلغ تراکنش مورد نظر (به ریال)
}

خروجی (Response)

سناریوی ۱: موجودی کافی است

{
    "status": true,
    "data": true           // یا آبجکتی که تایید می‌کند موجودی کافی است
}

سناریوی ۲: موجودی ناکافی است

نکته: در این حالت هم status کلی پاسخ true است (چون درخواست بررسی با موفقیت انجام شده)، اما data منفی است.

{
    "status": true,
    "data": false          // یا پیامی مبنی بر کمبود موجودی
}

خطا (Error):

از آنجایی که بلوک try-catch وجود ندارد، در صورت بروز خطا در دیتابیس یا ورودی‌ها، ساختار JSON استاندارد بازگردانده نمی‌شود و ممکن است با خطای سیستمی (Exception Trace) مواجه شوید.

GET /v2/wallet/transactions

Route Info

شرح عملکرد (Functionality)

این متد برای دریافت لیست تراکنش‌های کیف پول استفاده می‌شود و داده‌ها را پس از پردازش سنگین (شامل joinهای متعدد، تبدیل داده‌ها، تعیین subject/object/operator، لینک‌دهی رزرو و فاکتور، و ساخت ساختار نهایی) برمی‌گرداند.

پارامترهای ورودی (Query + Body)

Query Params

?branch=101

Body Params (paginate)

{
  "paginate": {
    "start": 0,
    "length": 20
  }
}

خروجی (Response)

موفق (Success)

{
  "items": [
    {
      "id": 10023,
      "subject": "خرید از هاب توسط دفتر ایکس",
      "object": "دفتر ایکس (1023)",
      "credit": 500000,
      "debit": 0,
      "description": "متن توضیحات | رفرنس ...",
      "operator": {
          "id": 4,
          "text": "1234 - علی رضایی",
          "query": { ... }
      },
      "service": "دفتر سرویس",
      "sub_service": "دفتر زیرسرویس",
      "details": { ... },
      "confirm_at": "2024-06-15 12:11:05",
      "confirm_note": null,
      "confirm_by": { ... }
    }
  ],
  "meta": {
    "timestamp": 1715780023,
    "table": {
      "total": 200,
      "per_page": 20,
      "current_page": 1,
      "last_page": 10,
      "from": 1,
      "to": 20
    }
  }
}

خطا (Error)

در صورت بروز Exception (مثلاً موارد زیر):

{
  "error": {
    "code": 500,
    "message": "Exception message...",
    "trace": [ ... ]
  }
}

`

POST /v2/accounting/connections/store

Route Info

شرح عملکرد (Functionality)

این متد وظیفه ایجاد یک اتصال (Connection) و گروه‌بندی چندین رکورد مالی مختلف (مثل سندهای پرداختی، اقلام فاکتور، چک‌ها و سوابق مالی) تحت یک شناسه واحد را دارد.

پارامترهای ورودی (JSON Body)

{
  "branch": 101,
  "type": "merge_doc",    // نوع کانکشن
  "id": 500,              // شناسه آبجکت اصلی (Object ID)
  "items": [
    { "id": 101, "type": "pay" },
    { "id": 205, "type": "check" },
    { "id": 12, "type": "fitem" }
  ]
}

خروجی (Response)

موفق (Success)

{
  "status": true,
  "time": 1715780023
}

خطا (Error)

مدیریت خطای خاصی پیاده‌سازی نشده است. اگر دیتابیس خطا دهد (مثلاً ID اشتباه باشد یا اتصال قطع شود)، خطای استاندارد لاراول (500) باز میگردد.

POST /v2/accounting/connections/update

Route Info

شرح عملکرد (Functionality)

این متد برای ویرایش یک Connection موجود استفاده می‌شود. نوع عملیات وابسته به دو آرایه است:

برای هر آیتم، فیلد relationship در جدول مربوطه یا به مقدار connection_id آپدیت می‌شود یا null می‌گردد.

نوع هر آیتم، جدول مقصد را تعیین می‌کند:

پارامترهای ورودی (JSON Body)

{
  "connection_id": 42,
  "items_add": [
    { "type": "pay", "id": 1001 },
    { "type": "check", "id": 55 },
    { "type": "fitem", "id": 990 }
  ],
  "items_remove": [
    { "type": "financial_past", "id": 81 },
    { "type": "pay", "id": 402 }
  ]
}

فیلدهای اجباری:

خروجی (Response)

موفق (Success)

{
  "status": true,
  "time": 1718450000
}

خطا (Error)

اینجا هیچ مدیریت خطا، اعتبارسنجی یا کنترل وجود ندارد. اگر:

باز هم متد بدون هیچ هشدار یا Exception، پاسخ موفق بازمی‌گرداند. (Silent Failure)

POST /v2/accounting/connections/trash

Route Info

شرح عملکرد (Functionality)

این متد برای حذف نرم (Soft Delete) یک Connection استفاده می‌شود. در این عملیات:

این عملیات هیچ رکوردی را حذف نمی‌کند و فقط ارتباط آن‌ها با Connection را قطع می‌کند.

پارامترهای ورودی (JSON Body)

{
  "connection_id": 42
}

خروجی (Response)

موفق (Success)

{
  "status": true,
  "time": 1718450000
}

خطاها (Errors)

برای این مسیر مدیریت خطای اختصاصی پیاده‌سازی نشده است.

POST /v2/accounting/connections/trash

Route Info

شرح عملکرد (Functionality)

این متد برای حذف نرم (Soft Delete) یک Connection استفاده می‌شود. در این عملیات:

این عملیات هیچ رکوردی را حذف نمی‌کند و فقط ارتباط آن‌ها با Connection را قطع می‌کند.

پارامترهای ورودی (JSON Body)

{
  "connection_id": 42
}

خروجی (Response)

موفق (Success)

{
  "status": true,
  "time": 1718450000
}

خطاها (Errors)

برای این مسیر مدیریت خطای اختصاصی پیاده‌سازی نشده است.

POST /v2/accounting/connections/view

Route Info

شرح عملکرد (Functionality)

این مسیر برای نمایش جزئیات کامل یک Connection استفاده می‌شود. در این متد، نوع اتصال بررسی می‌شود و در صورتی که اتصال از نوع leger_account باشد، عملیات زیر انجام می‌شود:

خروجی شامل لیست نهایی اسناد (Bills) است که برای نمایش جزئیات دفاتر حسابداری استفاده می‌شود.

پارامترهای ورودی (JSON Body)

{
  "connection_id": 42
}

خروجی (Response)

موفق (Success)

{
  "status": true,
  "time": 1718450000,
  "data": [
     { ... ledger items ... }
  ]
}

فیلد data شامل آرایه‌ای از تمام آیتم‌های دفتر حساب (Ledger) است. هر آیتم شامل فیلدهای:

خطاها (Errors)

این مسیر مدیریت خطای اختصاصی ندارد.

POST /v2/accounting/connections/merge

Route Info

شرح عملکرد (Functionality)

این مسیر برای ادغام دو Connection مورد استفاده قرار می‌گیرد. عملیات به این صورت انجام می‌شود:

در نهایت، مسیر صرفاً تأیید انجام عملیات را بازمی‌گرداند و اطلاعات اضافی ارسال نمی‌شود.

پارامترهای ورودی (JSON Body)

{
  "connection_last_id": 14,
  "connection_current_id": 7
}

خروجی (Response)

موفق (Success)

{
  "status": true,
  "time": 1718450000
}

خطاها (Errors)

این مسیر مدیریت خطای اختصاصی ندارد.

POST /v2/accounting/connections/list

Route Info

شرح عملکرد (Functionality)

این مسیر برای دریافت لیست Connections فعال استفاده می‌شود. امکان اعمال دو نوع فیلتر ورودی وجود دارد:

پس از اعمال فیلترها، فقط رکوردهایی با status = 1 بازگردانده می‌شوند. در مرحله بعد، برای هر Connection یک ساختار خروجی شامل id، شماره سریال محاسبه‌شده و عنوان تولید می‌شود.

شماره سریال نهایی با افزودن 1000 به مقدار اصلی تولید می‌شود.

پارامترهای ورودی (JSON Body)

همه پارامترها اختیاری هستند.

{
  "search": "123",     // اختیاری - جستجو بر اساس serial
  "id": "45"           // اختیاری - فیلتر بر اساس object id
}

خروجی (Response)

موفق (Success)

{
  "status": true,
  "time": 1718450000,
  "data": [
    {
      "id": 12,
      "serial": 1123,
      "title": "ارتباط 1123"
    },
    ...
  ]
}

خطاها (Errors)

این مسیر مدیریت خطای اختصاصی ندارد.

POST /v2/accounting/account/update

Route Info

شرح عملکرد (Functionality)

این مسیر برای ایجاد (store) یا ویرایش (update) اطلاعات حساب‌های درخت حسابداری مورد استفاده قرار می‌گیرد. در این متد سه نوع ساختار حسابداری پشتیبانی می‌شود:

نوع عملیات از طریق پارامتر action مشخص می‌شود:

ورودی‌ها در کلید data قرار می‌گیرند و بر اساس نوع حساب (type) عمل درج یا ویرایش روی یکی از جداول زیر انجام می‌شود:

در صورت بروز خطا، پیام و Trace کامل استثنا بازگردانده می‌شود.

پارامترهای ورودی (JSON Body)

ساختار کلی ورودی

{
  "action": "store | update",
  "id": 12,                   // فقط در حالت update
  "data": {
    "type": "group | general | moeen",
    "code": "112",
    "title_fa": "عنوان فارسی",
    "title_en": "English Title",
    "nature": 1,
    "status": 1,
    "...": "سایر فیلدهای ویژه نوع حساب"
  }
}

فیلدهای تکمیلی برای نوع General

فیلدهای تکمیلی برای نوع Moeen

خروجی موفق (Success Response)

{
  "status": true,
  "time": 1718450000
}

خروجی خطا (Error Response)

در صورت بروز خطا (مانند خطای دیتابیس)، ساختار زیر بازگردانده می‌شود:

{
  "status": false,
  "time": 1718450000,
  "code": 5005,
  "message": "Exception message...",
  "trace": [ ... ]
}

GET /v2/accounting/account/get

Route Info

شرح عملکرد (Functionality)

این مسیر برای دریافت جزئیات یک حساب درخت حسابداری استفاده می‌شود. با توجه به پارامتر type که می‌تواند یکی از سه مقدار group، general یا moeen باشد، اطلاعات از جداول مرتبط استخراج شده و ساختار داده متناسب بازگردانده می‌شود.

اطلاعات بازگشتی شامل:

پارامترهای ورودی (Query Params)

/v2/accounting/account/get?type=TYPE&id=ID

خروجی موفق (Success Response)

نمونه پاسخ برای نوع Group

{
  "status": true,
  "time": 1718449999,
  "data": {
    "id": 3,
    "type": "group",
    "code": "11",
    "public_code": "11",
    "title_fa": "دارایی",
    "title_en": "Assets",
    "nature": 1,
    "status": 1
  }
}

نمونه پاسخ برای نوع General

{
  "status": true,
  "time": 1718449999,
  "data": {
    "parent": {
      "type": "group",
      "code": "11",
      "public_code": "11",
      "id": 3,
      "title": { "fa": "دارایی", "en": "Assets" }
    },
    "id": 18,
    "type": "general",
    "code": "02",
    "public_code": "1102",
    "title_fa": "موجودی کالا",
    "title_en": "Inventory",
    "nature": 1,
    "status": 1
  }
}

نمونه پاسخ برای نوع Moeen

{
  "status": true,
  "time": 1718449999,
  "data": {
    "parent": {
      "type": "general",
      "code": "02",
      "public_code": "1102",
      "id": 18,
      "title": { "fa": "موجودی کالا", "en": "Inventory" }
    },
    "id": 51,
    "type": "moeen",
    "code": "005",
    "public_code": "1102005",
    "title_fa": "موجودی انبار مرکزی",
    "title_en": "Main Warehouse",
    "nature": 1,
    "nature_check": 1,
    "currency": 1,
    "aggregation": 0,
    "bill": [ ... ],
    "detailed_first": null,
    "detailed_second": null,
    "detailed_third": null,
    "detailed_fourth": null,
    "status": 1
  }
}

خروجی خطا (Error Response)

در صورت بروز خطا مانند عدم یافتن رکورد یا خطای دیتابیس:

{
  "status": false,
  "time": 1718449999,
  "code": 5005,
  "message": "Error message...",
  "trace": [ ... ]
}

POST /v2/manual-document/update

Route Info

شرح عملکرد (Functionality)

این مسیر برای ایجاد (add) یا ویرایش (update) یک سند دستی (Manual Document) استفاده می‌شود. روش کار متد بطور خلاصه:

در هر دو حالت، ثبت لاگ در SystemLog انجام می‌شود.

پارامترهای ورودی (JSON Body)

ساختار کلی

{
  "action": "add | update",
  "id": 15,                     // فقط در حالت update
  "date": "1403-05-20",
  "description": "سند دستی",
  "status": 3,
  "currency": 1,
  "currency_fee": 0,
  "sub_serial": null,
  "data": [
    {
      "preference": "colleague-42",
      "moeen": "moeen-18",
      "credit": "0",
      "debit": "250000",
      "description": "توضیحات"
    }
  ],
  "data_delete": [ ... ]         // فقط در حالت update
}

توضیحات پارامترهای کلیدی

خروجی موفق (Success Response)

در حالت ایجاد (add)

{
  "status": true,
  "time": 1718450000,
  "message": "ثبت سند با موفقیت انجام شد. شماره: [3125, 3126]"
}

در حالت ویرایش (update)

{
  "status": true,
  "time": 1718450000,
  "message": "ویرایش سند با موفقیت انجام شد."
}

خروجی خطا (Error Response)

خطا در بازه زمانی بسته مالی

{
  "status": false,
  "time": 1718450000,
  "type": "danger",
  "code": 5007,
  "message": "ثبت و ویرایش سند دستی در بازه زمانی بسته شده امکان پذیر نمی‌باشد..."
}

خطاهای دیتابیس (Insert/Update)

{
  "status": false,
  "time": 1718450000,
  "code": 5006,
  "message": "SQL error message...",
  "trace": [ ... ]
}

DELETE /v2/manual-document

Route Info

شرح عملکرد (Functionality)

این مسیر جهت حذف نرم (Soft Delete) یک سند دستی (Manual Document) استفاده می‌شود. فرآیند عملکرد به صورت زیر است:

ورودی‌ها (Request Inputs)

Body Parameters (JSON/Form):

{
  "id": 1542
}

خروجی موفق (Success Response)

در صورت موفقیت عملیات، پاسخ بدون بدنه با کد 204 بازگردانده می‌شود:

HTTP 204 No Content

خطاها (Error Responses)

۱) سند داخل دوره مالی بسته شده باشد

{
  "status": false,
  "time": 1718450000,
  "type": "danger",
  "code": 5007,
  "message": "حذف سند دستی در بازه زمانی بسته شده امکان پذیر نمی‌باشد. حساب ها تا تاریخ YYYY/MM بسته شده‌ است."
}

۲) عدم ارسال شناسه معتبر

{
  "error": {
    "code": 1000,
    "message": "شناسه سند ارسالی صحیح نمی باشد"
  },
  "meta": {
    "timestamp": 1718450000
  }
}

نکات داخلی (Internal Logic Notes)

POST /v2/manual-document/list

Route Info

شرح عملکرد (Functionality)

این مسیر برای لیست‌گیری، جستجو، فیلتر و صفحه‌بندی اسناد دستی در جدول manual_documents استفاده می‌شود. عملکرد متد به صورت زیر است:

پارامترهای ورودی (JSON Body)

Body Parameter: کل ورودی در فیلد json ارسال می‌شود

{
  "start": 0,
  "length": 20,
  "draw": 1,
  "search": {
    "from": "1403-01-01",
    "to": "1403-01-30",
    "year": "",
    "from_document": "",
    "to_document": ""
  }
}

خروجی موفق (Success Response)

{
  "status": true,
  "time": 1718450000,
  "draw": 1,
  "recordsTotal": 152,
  "recordsFiltered": 20,
  "data": [
    {
      "serial": 3125,
      "system_serial": 125,
      "type": "manual",
      "title": "سند شماره 3125 | 1403/01/25 | دستی - توضیحات",
      "date": "14030125",
      "manual_serial": false,
      "sub_serial": false,
      "description": "توضیحات سند",
      "status": "تائید نهایی",
      "financial": {
        "debit_financial_past": 0,
        "credit_financial_past": 0,
        "debit_start_period": 0,
        "credit_start_period": 0,
        "debit_during_period": 1500000,
        "credit_during_period": 900000,
        "debit_balance": 600000,
        "credit_balance": 0
      }
    }
  ]
}

خروجی خطا (Error Response)

در صورت بروز خطای دیتابیس یا Exception:

{
  "status": false,
  "time": 1718450000,
  "code": 5005,
  "message": "SQL error message...",
  "trace": [ ... ]
}

نکات داخلی (Internal Logic Notes)

POST /v2/manual-document/view

Route Info

شرح عملکرد (Functionality)

این مسیر برای نمایش جزئیات کامل یک سند دستی (Manual Document) استفاده می‌شود. پس از دریافت شناسه سند:

پارامترهای ورودی (Request Inputs)

Body (JSON یا Form-Data):

{
  "id": 1524
}

خروجی موفق (Success Response)

ساختار خروجی شامل:

{
  "status": true,
  "time": 1718450000,
  "data": [
    {
      "moeen": {
        "id": 1102,
        "title": "بانک ملت"
      },
      "preference": {
        "id": "colleague-5421",
        "title": "علی رضایی"
      },
      "preference_2": false,
      "preference_3": false,
      "preference_4": false,
      "description": "سند دستی 3125 | پرداخت نقدی",
      "credit": 0,
      "debit": 2500000
    }
  ],
  "balance": {
    "debit_financial_past": 0,
    "credit_financial_past": 0,
    "debit_start_period": 0,
    "credit_start_period": 0,
    "debit_during_period": 2500000,
    "credit_during_period": 0,
    "debit_finish_period": 2500000,
    "credit_finish_period": 0,
    "debit_balance": 2500000,
    "credit_balance": 0
  }
}

خروجی خطا (Error Response)

در صورت وقوع هرگونه Exception، ساختار خطا به شکل زیر بازگردانده می‌شود:

{
  "status": false,
  "time": 1718450000,
  "code": 5005,
  "message": "Error message ...",
  "trace": [ ... ]
}

خلاصه منطق داخلی getManualDocumentDetails

بسته به نوع سند:

در پایان:

POST /v2/manual-document/get

Route Info

شرح عملکرد (Functionality)

این مسیر جهت دریافت تمامی جزئیات یک سند دستی و تمام ردیف‌های وابسته به آن استفاده می‌شود.

فرآیند متد:

پارامترهای ورودی (JSON Body)

Body:

{
  "id": 1524
}

خروجی موفق (Success Response)

خروجی شامل سه بخش اصلی است:

{
  "items": [
    {
      "id": 980211,
      "serial": 1452,
      "moeen": {
        "id": 1102,
        "serial": 220,
        "group": 4,
        "details": { ... },
        "type": { "fa": "معین", "en": "moeen" },
        "title": {
          "fa": { "simple": "بانک ملت", "html": "بانک ملت" }
        }
      },
      "preference": {
        "id": "colleague-5421",
        "serial": 5421,
        "title": "علی رضایی"
      },
      "preference_2": {
        "id": 1452,
        "title": 1452
      },
      "preference_3": false,
      "preference_4": false,
      "description": "واریز نقدی",
      "credit": 0,
      "debit": 850000
    }
  ],
  "payload": {
    "document": {
      "serial": 3125,
      "system_serial": 1524,
      "title": "سند شماره 3125 | دستی - توضیحات"
    },
    "system_serial": 1524,
    "serial": 3125,
    "type": "manual",
    "title": "سند شماره 3125 | دستی - توضیحات",
    "date": "1403/01/25",
    "manual_serial": false,
    "sub_serial": false,
    "description": "توضیحات سند",
    "total": {
      "count": 4,
      "debit": 3200000,
      "credit": 2400000
    },
    "status": 1
  },
  "meta": {
    "timestamp": 1718450000
  }
}

خروجی خطا (Error Response)

در صورت بروز Exception:

{
  "status": false,
  "time": 1718450000,
  "code": 5005,
  "message": "Error message...",
  "trace": [ ... ]
}

نکات داخلی اجرای متد

POST /v2/manual-document/list/{type}

Route Info

شرح عملکرد (Functionality)

این مسیر برای دریافت لیست ۵۰تایی اسناد دستی، افتتاحیه یا اختتامیه استفاده می‌شود. فیلتر جستجو از طریق پارامتر json اعمال می‌شود و خروجی شامل سریال نمایشی (+1000)، شماره سیستمی، و عنوان نهایی سند است.

پارامترهای مسیر (Path Parameters)

پارامترهای ورودی (JSON Body)

Body:

{
  "json": "{\"search\": {\"value\": \"1403/01\"}}",
  "branch": 1
}

خروجی موفق (Success Response)

خروجی نهایی شامل آرایه‌ای از اسناد فرمت‌شده است:

{
  "status": true,
  "time": 1718451600,
  "data": [
    {
      "serial": 3125,
      "system_serial": 1524,
      "title": "سند شماره 3125 | 1403/01/21 | دستی - هزینه دفتر"
    },
    {
      "serial": 3101,
      "system_serial": 1512,
      "title": "سند شماره 3101 | افتتاحیه - افتتاح سال 1403"
    }
  ]
}

خروجی خطا (Error Response)

در صورت رخ دادن استثناء عمومی:

{
  "status": false,
  "time": 1718451600,
  "code": 5005,
  "message": "Exception message...",
  "trace": [ ... ]
}

الگوی ساخت عنوان سند (getManualDocumentTitle)

الگوی خروجی عنوان براساس نوع سند:

در این Route فقط سه نوع زیر بازگردانده می‌شود:

POST /v2/manual-document/preferences/list/details

Route Info

شرح عملکرد (Functionality)

این مسیر برای دریافت جزئیات کامل معین (Moeen) و تفصیل (Preference) استفاده می‌شود. ورودی شامل آرایه‌ای از رکوردها است که هر کدام شامل:

این متد با منطق زیر کار می‌کند:

پارامترهای ورودی (JSON Body)

Body:

{
  "data": [
    {
      "moeen": "110203",
      "preference": 120000145
    }
  ],
  "branch": 1
}

خروجی موفق (Success Response)

در صورت موفقیت، خروجی شامل آرایه‌ای از آیتم‌های پردازش شده:

{
  "items": [
    {
      "moeen": {
        "id": 25,
        "serialId": 25,
        "details": {
          "aggregation": 1
        },
        "code": "110203",
        "text": "110203 - فروش | فروش داخلی"
      },
      "preference": {
        "id": "title-15",
        "code": 120000145,
        "table": "title",
        "text": "هزینه تعمیرات",
        "financial": false
      }
    }
  ],
  "meta": {
    "timestamp": 1718453500
  }
}

خطاهای اعتبارسنجی (Error Response 422)

اگر هر بخش از گروه، کل یا معین وجود نداشته باشد:

{
  "error": {
    "code": 1000,
    "message": "گروه حسابداری با کد 11 در معین 110203 وجود ندارد"
  },
  "meta": {
    "timestamp": 1718453500
  }
}

اگر تفصیل وجود نداشته باشد:

{
  "error": {
    "code": 1000,
    "message": "تفصیل با کد 120000999 وجود ندارد"
  },
  "meta": {
    "timestamp": 1718453500
  }
}

ساختار استخراج کد معین (Moeen Code Structure)

برای هر کد ۶ رقمی مثلاً 110203:

این ۳ بخش به‌ترتیب روی جداول زیر اعتبارسنجی می‌شوند:

تشخیص نوع تفصیل بر اساس ۲ رقم اول کد

نمونه خروجی تفصیل برای انواع مختلف

1 — Bank Account (prefix 10)

{
  "id": "account-12",
  "code": 100000532,
  "text": "بانک ملت شعبه مرکزی (1234567890)"
}

2 — Personnel (prefix 13)

{
  "id": "personnel-88",
  "code": 130001234,
  "text": "مهدی احمدی"
}

3 — Office (prefix 30)

{
  "id": "office-7",
  "code": 300000215,
  "text": "مرکز هزینه اداره مرکزی"
}

Meta

تمام پاسخ‌ها شامل:

GET /v2/accounting/closing

Route Info

شرح عملکرد (Functionality)

این مسیر اطلاعات مربوط به تاریخ پایان دوره مالی بسته شده را برای دفتر (Branch/Office) فعلی برمی‌گرداند. داده‌ها از جدول office_config خوانده می‌شوند و مقدار کلید END_OF_FINANCIAL_PERIOD_CLOSING_ACCOUNTS بررسی می‌شود. در صورت وجود مقدار، تنها سال و ماه از آن جدا و بازگردانده می‌شود.

تابع کمکی Functions::officeConfig($office, $key) وظیفه دارد مقدار تنظیم دفتر را از جدول office_config بخواند. اگر چیزی یافت نشود، مقدار false برمی‌گردد.

این مسیر برای کنترل دوره‌های مالی در مسیرهای دیگر (مثل ثبت یا حذف سند) کاربرد دارد تا مانع عملیات بعد از تاریخ بسته شدن شود.

فرآیند محاسباتی (Logic Steps)

پاسخ موفق (Success Response)

{
  "payload": {
    "year": "1404",
    "month": "03"
  },
  "meta": {
    "timestamp": 1733053000
  }
}

پاسخ در صورت نبود تنظیمات

اگر مقدار در جدول تنظیمات یافت نشود:

{
  "payload": null,
  "meta": {
    "timestamp": 1733053000
  }
}

وابستگی دیتابیس (Database Dependency)

توابع کمکی استفاده شده (Helper Functions)

static function officeConfig($office, $key)
{
    return DB::table('office_config')
             ->where('office', $office)
             ->where('key', strtoupper($key))
             ->value('value') ?: false;
}

اطلاعات تکمیلی (Meta)

POST /v2/accounting/closing

Route Info

شرح عملکرد (Functionality)

این مسیر برای بستن دوره مالی در یک شعبه استفاده می‌شود. قبل از اعمال بستن دوره، سیستم باید اطمینان پیدا کند که در بازه انتخاب‌شده هیچ سند قطعی‌نشده وجود ندارد. این بررسی شامل ۳ دسته سند اصلی است:

اگر هرکدام از این موارد قطعی نشده باشند، مسیر با خطای 422 و پیام مناسب بازمی‌گردد. در صورت پاک بودن همه اسناد، مقدار جدید END_OF_FINANCIAL_PERIOD_CLOSING_ACCOUNTS برای شعبه در جدول office_config ثبت یا به‌روزرسانی می‌شود.

پارامترهای ورودی (JSON Body)

{
  "year": "1404",
  "month": "03",
  "branch": 1
}

منطق بررسی اسناد قطعی‌نشده (checkDocumentsForClosingAccount)

این تابع ۳ نوع سند را بررسی می‌کند:

اسناد فروش (factors)

هر سندی که:

اسناد دریافت/پرداخت (pays)

اسناد دستی (manual_documents)

خروجی تابع:

{
  "references": true | false,
  "payments": true | false,
  "manual_documents": true | false,
  "salary": false,
  "treasury_bills": false
}

پاسخ خطا (422)

اگر هرگونه سند قطعی‌نشده وجود داشته باشد:

{
  "error": {
    "code": 1000,
    "message": "اسناد فروش روزانه | دارای سند قطعی نشده می باشد. قبل از بستن حساب ها، تمامی اسناد باید قطعی شوند."
  },
  "meta": {
    "timestamp": 1733056000
  }
}

*نوع پیام بسته به اولین پرچم فعال در خروجی checkDocumentsForClosingAccount است:

پاسخ موفق (Success Response)

اگر هیچ سندی مانع بستن دوره نباشد:

پاسخ:

Status: 204 No Content
Body: ""

وابستگی دیتابیس

META

PUT /v2/accounting/closing/definite/{type}

Route Info

شرح عملکرد (Functionality)

این مسیر برای قطعی‌کردن دسته‌ای اسناد هنگام بستن دوره مالی استفاده می‌شود. نوع سند از پارامتر {type} تعیین می‌شود و شامل موارد زیر است:

هر نوع سند با شرط‌های خاص زمانی (شمسی/میلادی) و وضعیت فعلی، به وضعیت 3 (قطعی) به‌روزرسانی می‌شود. این API بخشی از پیوستگی عملیات بستن حساب است و معمولاً پس از بررسی عدم وجود سند باز انجام می‌شود.

پارامترهای ورودی (Input)

Path Parameter

Body (JSON):

{
  "year": "1404",
  "month": "03",
  "branch": 1
}

منطق پردازش (Logic)

ابتدا سال/ماه شمسی به میلادی تبدیل می‌شوند:

قطعی‌کردن اسناد فروش روزانه (type = daily_sales)

UPDATE factors SET status = 3

قطعی‌کردن دریافت/پرداخت روزانه (type = daily_credit_debit)

UPDATE pays SET status = 3

قطعی‌کردن اسناد دستی (type = manual_documents)

UPDATE manual_documents SET status = 3

موارد رزرو (به‌صورت NO-OP)

return false

پاسخ موفق (Success Response)

اگر عملیات با موفقیت انجام شود (true):

Status: 204 No Content
Body: ""

پاسخ خطا (Invalid Type)

اگر نوع سند شناسایی نشود (false):

Status: 422 Unprocessable Entity
Body: ""

وابستگی دیتابیس

Meta

GET /v2/accounting/preference

Route Info

شرح عملکرد (Functionality)

این مسیر برای دریافت لیست نگاشت حسابداری استفاده می‌شود. اطلاعات جدول mapping_accounting_preferences را بر اساس شعبه، نوع شیء (object_type) و شناسه شیء (object) به‌صورت صفحه‌بندی شده (Paginated) برمی‌گرداند.

در صورت نبود پارامتر paginate، سیستم به‌صورت خودکار مقدار پیش‌فرض زیر را اعمال می‌کند:

محاسبه شماره صفحه بر اساس فرمول زیر انجام می‌شود:

page = (start == 0 ? length : start + length) / length

پارامترهای ورودی (Query Parameters)

پاسخ موفق (Success Response)

پاسخ شامل داده‌های صفحه‌بندی‌شده لاراول است (object کامل pagination):

{
  "payload": {
    "current_page": 1,
    "data": [
      {
        "id": 12,
        "branch": 1,
        "object_type": "customer",
        "object": 24,
        "moeen": 14,
        "created_at": "2024-07-21T10:00:00.000000Z",
        "updated_at": "2024-07-21T10:00:00.000000Z"
      }
    ],
    "first_page_url": "...",
    "from": 1,
    "last_page": 4,
    "last_page_url": "...",
    "next_page_url": "...",
    "path": "...",
    "per_page": 30,
    "prev_page_url": null,
    "to": 30,
    "total": 110
  },
  "meta": {
    "timestamp": 1733056000
  }
}

خطاها (Errors)

وابستگی دیتابیس

Meta

POST /v2/accounting/preference

Route Info

شرح عملکرد (Functionality)

این API برای ثبت نگاشت‌های حسابداری در جدول mapping_accounting_preferences استفاده می‌شود. ورودی به‌صورت مجموعه‌ای از آیتم‌ها در فیلد items ارسال می‌شود. برای هر آیتم:

در انتها، اگر هیچ خطایی وجود نداشته باشد، همه رکوردهای جدید به صورت Batch درج می‌شوند.

ورودی مورد نیاز (JSON Body)

ساختار کلی:

{
  "branch": 1,
  "items": [
    {
      "id": "customer-24",
      "text": "24 - مشتری عمده",
      "code": "110201"
    },
    {
      "id": "office-3",
      "text": "301 - دفتر مرکزی",
      "code": "880030"
    }
  ]
}

جزئیات فیلدها:

ساختاردهی رکورد درج‌شونده

برای هر آیتم غیرتکراری:

پاسخ موفق (Success Response)

در صورت عدم وجود خطا و انجام موفق درج:

{
  "payload": true,
  "error": false,
  "meta": {
    "timestamp": 1733056000
  }
}

پاسخ در صورت وجود خطا برای برخی آیتم‌ها

اگر بخشی از آیتم‌ها Duplicate باشند:

{
  "payload": true,
  "error": [
    {
      "message": "این کد قبلا ثبت شده است.",
      "code": "110201"
    }
  ],
  "meta": {
    "timestamp": 1733056000
  }
}

خطای عدم ارسال فیلد items

{
  "error": {
    "message": "The items field is required."
  },
  "meta": {
    "timestamp": 1733056000
  }
}

وابستگی دیتابیس

Meta

GET /v2/accounting/preference/{id}

Route Info

شرح عملکرد (Functionality)

این مسیر برای دریافت یک رکورد واحد از جدول mapping_accounting_preferences بر اساس شناسه ارسال شده در {id} استفاده می‌شود.

هیچ پردازش اضافی، تغییر ساختار یا اعتبارسنجی ویژه انجام نمی‌شود؛ فقط رکورد دیتابیس خوانده شده و به‌صورت مستقیم بازگردانده می‌شود.

پارامتر مسیر (Path Parameter)

پاسخ موفق (Success Response)

اگر رکورد موجود باشد:

{
  "payload": {
    "id": 12,
    "branch": 1,
    "object_type": "customer",
    "object": 24,
    "title": "مشتری عمده",
    "system_code": "24",
    "code": "110201",
    "updated_at": "2024-07-21 10:00:00"
  },
  "meta": {
    "timestamp": 1733056000
  }
}

اگر رکورد موجود نباشد، مقدار payload برابر false خواهد بود.

{
  "payload": false,
  "meta": {
    "timestamp": 1733056000
  }
}

خطاها (Errors)

وابستگی دیتابیس

Meta

PUT /v2/accounting/preference/{id}

Route Info

شرح عملکرد (Functionality)

این API برای ویرایش یک نگاشت حسابداری در جدول mapping_accounting_preferences استفاده می‌شود.

منطق مسیر شامل مراحل زیر است:

ساختار ورودی (JSON Body)

{
  "branch": 1,
  "id": "customer-24",
  "text": "24 - مشتری عمده",
  "code": "110201"
}

توضیح فیلدها

اعتبارسنجی

قبل از ذخیره، بررسی می‌شود که آیا کد جدید در همان شعبه قبلاً استفاده شده است یا خیر:

exists where:
  branch = request.branch
  code = request.code
  id != {id}

اگر رکوردی با همین کد وجود داشته باشد، به‌جای به‌روزرسانی، خطا بازگردانده می‌شود.

پاسخ موفق (Success Response)

در صورت به‌روزرسانی موفق، رکورد کامل جدید بازگردانده می‌شود:

{
  "payload": {
    "id": 12,
    "branch": 1,
    "object_type": "customer",
    "object": 24,
    "title": "مشتری عمده",
    "system_code": "24",
    "code": "110201",
    "updated_at": "2024-07-21T10:00:00.000000Z"
  },
  "meta": {
    "timestamp": 1733056000
  }
}

پاسخ خطا (Error Response)

اگر کد تکراری باشد:

{
  "error": {
    "message": "این کد قبلا ثبت شده است."
  },
  "meta": {
    "timestamp": 1733056000
  }
}

وابستگی دیتابیس

Meta

POST /v2/account-history/calculate-daily

Route Info

شرح عملکرد (Functionality)

این API برای محاسبه و ذخیره مانده‌های روزانه یک همکار (Colleague) استفاده می‌شود. فرآیند محاسبه می‌تواند:

محاسبات امکان اجرا به صورت:

نتیجه‌های محاسبه شده در Redis با TTL سی روزه ذخیره می‌شوند.

ورودی (Request Body)

{
  "colleague_id": 24,
  "year": 1403,          // optional
  "from": "1403-01-01",  // optional
  "to": "1403-12-29",    // optional
  "async": true          // optional, default = false
}

قوانین اعتبارسنجی

منطق اجرا (Execution Logic)

مشخصات Job

پاسخ موفق (Async Mode)

{
  "payload": null,
  "meta": {
    "colleague_id": 24,
    "year": 1403,
    "from": "1403-01-01",
    "to": "1403-12-29",
    "type": "daily",
    "status": "queued",
    "timestamp": "2025-12-01T10:15:00+03:30"
  }
}

پاسخ موفق (Sync Mode)

{
  "payload": {
    "1403-01-01": {
      "credit": 0,
      "debit": 1200000,
      "balance": -1200000
    },
    "1403-01-02": {
      "credit": 500000,
      "debit": 0,
      "balance": 500000
    }
  },
  "meta": {
    "colleague_id": 24,
    "from": "1403-01-01",
    "to": "1403-12-29",
    "total_days": 365,
    "timestamp": "2025-12-01T10:15:00+03:30"
  }
}

پاسخ‌های خطا (Error Responses)

اعتبارسنجی (400)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "colleague_id is required"
  },
  "meta": {
    "timestamp": "2025-12-01T10:18:00+03:30"
  }
}

تاریخ آینده مجاز نیست (400)

{
  "error": {
    "code": "FUTURE_DATE_NOT_ALLOWED",
    "message": "Cannot calculate for future dates."
  },
  "meta": {
    "colleague_id": 24,
    "to": "1404-01-01",
    "timestamp": "2025-12-01T10:18:00+03:30"
  }
}

خطای داخلی (500)

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Unexpected error..."
  },
  "meta": {
    "colleague_id": 24,
    "timestamp": "2025-12-01T10:20:00+03:30"
  }
}

Meta

POST /v2/account-history/calculate-monthly

Route Info

شرح عملکرد (Functionality)

این API وظیفه محاسبه و ذخیره مانده‌های ماهانه برای یک همکار (Colleague) را دارد. محاسبه می‌تواند بر اساس:

محاسبات می‌توانند به صورت:

در حالت async، عملیات توسط CalculateAccountHistoryJob با type = "monthly" انجام می‌شود.

ورودی (Request Body)

{
  "colleague_id": 108,
  "year": 1403,           // optional
  "from": "1403-01-01",   // optional
  "to": "1403-12-29",     // optional
  "async": false          // optional (default=false)
}

قوانین اعتبارسنجی

منطق اجرا (Execution Logic)

مشخصات Job

پاسخ موفق (Async Mode)

{
  "payload": null,
  "meta": {
    "colleague_id": 108,
    "year": 1403,
    "from": "1403-01-01",
    "to": "1403-12-29",
    "type": "monthly",
    "status": "queued",
    "timestamp": "2025-12-01T12:35:00+03:30"
  }
}

پاسخ موفق (Sync Mode)

{
  "payload": {
    "1403-01": { "credit": 0, "debit": 900000, "balance": -900000 },
    "1403-02": { "credit": 500000, "debit": 0, "balance": 500000 }
  },
  "meta": {
    "colleague_id": 108,
    "year": 1403,
    "total_months": 12,
    "timestamp": "2025-12-01T12:35:00+03:30"
  }
}

پاسخ‌های خطا (Error Responses)

اعتبارسنجی (400)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "colleague_id field is required"
  },
  "meta": {
    "timestamp": "2025-12-01T12:40:00+03:30"
  }
}

تاریخ آینده مجاز نیست (400)

{
  "error": {
    "code": "FUTURE_DATE_NOT_ALLOWED",
    "message": "Cannot calculate for future dates."
  },
  "meta": {
    "colleague_id": 108,
    "to": "1405-01-01",
    "timestamp": "2025-12-01T12:40:00+03:30"
  }
}

خطای داخلی (500)

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Unexpected error..."
  },
  "meta": {
    "colleague_id": 108,
    "timestamp": "2025-12-01T12:41:00+03:30"
  }
}

Meta

POST /v2/account-history/calculate-complete

Route Info

شرح عملکرد (Functionality)

این API برای محاسبه کامل مانده‌ها استفاده می‌شود؛ یعنی:

محاسبه‌ها می‌توانند بر اساس:

روش اجرا:

هر دو محاسبه از طریق سرویس AccountHistoryService انجام می‌شوند.

ورودی (Request Body)

{
  "colleague_id": 108,
  "year": 1403,           // optional
  "from": "1403-01-01",   // optional
  "to": "1403-12-29",     // optional
  "async": true           // optional (default = true)
}

قوانین اعتبارسنجی

منطق اجرا (Execution Logic)

مشخصات Job

پاسخ موفق (Async Mode)

{
  "payload": null,
  "meta": {
    "colleague_id": 108,
    "year": 1403,
    "from": "1403-01-01",
    "to": "1403-12-29",
    "jobs": ["daily", "monthly"],
    "status": "queued",
    "timestamp": "2025-12-01T14:20:00+03:30"
  }
}

پاسخ موفق (Sync Mode)

{
  "payload": {
    "daily": {
      "1403-01-01": { "credit": 0, "debit": 1200000, "balance": -1200000 },
      "1403-01-02": { "credit": 500000, "debit": 0, "balance": 500000 }
    },
    "monthly": {
      "1403-01": { "credit": 0, "debit": 900000, "balance": -900000 },
      "1403-02": { "credit": 500000, "debit": 0, "balance": 500000 }
    }
  },
  "meta": {
    "colleague_id": 108,
    "year": 1403,
    "from": "1403-01-01",
    "to": "1403-12-29",
    "daily_meta": { "...": "..." },
    "monthly_meta": { "...": "..." },
    "timestamp": "2025-12-01T14:20:00+03:30"
  }
}

پاسخ‌های خطا (Error Responses)

اعتبارسنجی (400)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "colleague_id is required"
  },
  "meta": {
    "timestamp": "2025-12-01T14:25:00+03:30"
  }
}

تاریخ آینده مجاز نیست (400)

{
  "error": {
    "code": "FUTURE_DATE_NOT_ALLOWED",
    "message": "Cannot calculate for future dates."
  },
  "meta": {
    "colleague_id": 108,
    "to": "1404-01-01",
    "timestamp": "2025-12-01T14:25:00+03:30"
  }
}

خطای محاسباتی یکی از دو عملیات (400)

{
  "error": {
    "code": "CALCULATION_ERROR",
    "message": "Error in one or both calculations",
    "details": {
      "daily": null,
      "monthly": {
        "code": "INTERNAL_ERROR",
        "message": "..."
      }
    }
  },
  "meta": {
    "colleague_id": 108,
    "timestamp": "2025-12-01T14:26:00+03:30"
  }
}

خطای داخلی (500)

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Unexpected exception..."
  },
  "meta": {
    "colleague_id": 108,
    "timestamp": "2025-12-01T14:26:00+03:30"
  }
}

Meta

GET /v2/account-history/daily

Route Info

شرح عملکرد (Functionality)

این API صرفاً برای خواندن سریع اطلاعات محاسبه‌شده از قبل استفاده می‌شود.

ورودی (Query Parameters)

پارامترها به صورت Query String ارسال می‌شوند:

?colleague_id=108&year=1403&date=1403-01-05

قوانین اعتبارسنجی (Validation Rules)

منطق اجرا (Execution Logic)

پاسخ موفق (200 OK)

{
  "payload": {
    "credit": 0,
    "debit": 1500000,
    "balance": -1500000
  },
  "meta": {
    "colleague_id": 108,
    "year": 1403,
    "date": "1403-01-05",
    "source": "cache",
    "timestamp": "2025-12-01T15:30:00+03:30"
  }
}

پاسخ‌های خطا (Error Responses)

خطای اعتبارسنجی (400)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The date does not match the format Y-m-d."
  },
  "meta": {
    "timestamp": "2025-12-01T15:30:00+03:30"
  }
}

داده یافت نشد / محاسبه نشده (404)

{
  "error": {
    "code": "NOT_FOUND",
    "message": "No data found for this date. Please calculate first."
  },
  "meta": {
    "timestamp": "2025-12-01T15:31:00+03:30"
  }
}

خطای سرور (500)

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Redis connection failed..."
  },
  "meta": {
    "colleague_id": 108,
    "timestamp": "2025-12-01T15:32:00+03:30"
  }
}

توضیحات فنی (Meta)

GET /v2/account-history/monthly

Route Info

شرح عملکرد (Functionality)

این API برای دریافت مانده حساب ماهانه طراحی شده است و دارای مکانیزم هوشمند (Read-Through Cache) است:

توجه: اگر کش خالی باشد، پاسخ این سرویس ممکن است کمی طول بکشد (به اندازه زمان محاسبه مانده سالانه)

ورودی (Query Parameters)

?colleague_id=108&year=1403&month=2

قوانین اعتبارسنجی (Validation Rules)

منطق اجرا (Execution Logic)

پاسخ موفق (200 OK)

حالت ۱: داده در کش موجود بود (Cache Hit)

{
  "payload": {
    "credit": 500000,
    "debit": 0,
    "balance": 500000
  },
  "meta": {
    "colleague_id": 108,
    "year": 1403,
    "month": "02",
    "cached": true,
    "timestamp": "2025-12-01T16:00:00+03:30"
  }
}

حالت ۲: داده محاسبه شد (Cache Miss -> Calculated)

{
  "payload": {
    "credit": 500000,
    "debit": 0,
    "balance": 500000
  },
  "meta": {
    "colleague_id": 108,
    "year": 1403,
    "month": "02",
    "cached": false,
    "calculated": true,
    "timestamp": "2025-12-01T16:00:05+03:30"
  }
}

پاسخ‌های خطا (Error Responses)

خطای اعتبارسنجی (400)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The month must be at least 1."
  },
  "meta": { ... }
}

خطای عدم یافتن/محاسبه (404)

زمانی رخ می‌دهد که حتی پس از تلاش برای محاسبه، داده‌ای در کش ذخیره نشود.

{
  "error": {
    "code": "CACHE_MISS",
    "message": "Balance not found in cache and calculation failed"
  },
  "meta": {
    "colleague_id": 108,
    "year": 1403,
    "month": "02",
    "cached": false,
    "timestamp": "..."
  }
}

خطای سرور (500)

{
  "error": {
    "code": "INTERNAL_ERROR",

GET /v2/account-history/all-daily

Route Info

شرح عملکرد (Functionality)

این API برای دریافت یکجای تمام سوابق روزانه یک سال خاص استفاده می‌شود (مثلاً برای رسم نمودار تغییرات موجودی در طول سال).

ورودی (Query Parameters)

?colleague_id=108&year=1403

قوانین اعتبارسنجی (Validation Rules)

منطق اجرا (Execution Logic)

پاسخ موفق (200 OK)

توجه کنید که کلیدهای آبجکت payload همان تاریخ‌ها هستند.

{
  "payload": {
    "1403-01-01": {
      "credit": 0,
      "debit": 100000,
      "balance": -100000,
      "date": "1403-01-01"
    },
    "1403-01-02": {
      "credit": 50000,
      "debit": 0,
      "balance": -50000,
      "date": "1403-01-02"
    },
    "1403-05-20": {
      "credit": 200000,
      "debit": 0,
      "balance": 150000,
      "date": "1403-05-20"
    }
  },
  "meta": {
    "colleague_id": 108,
    "year": 1403,
    "total_days": 3,
    "cached": true,
    "timestamp": "2025-12-01T16:15:00+03:30"
  }
}

پاسخ‌های خطا (Error Responses)

خطای اعتبارسنجی (400)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The year must be between 1300 and 1500."
  },
  "meta": { ... }
}

خطای سرور (500)

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Redis connection failed"
  },
  "meta": { ... }
}

توضیحات فنی (Meta)

GET /v2/account-history/all-monthly

Route Info

شرح عملکرد (Functionality)

این API برای دریافت یکجای تمام مانده‌های ماهانه یک سال مشخص استفاده می‌شود.

ورودی (Query Parameters)

?colleague_id=108&year=1403

قوانین اعتبارسنجی (Validation Rules)

منطق اجرا (Execution Logic)

پاسخ موفق (200 OK)

خروجی به صورت Map (Dictionary) است که کلیدهای آن شماره ماه (معمولاً دو رقمی مثل "01") هستند.

{
  "payload": {
    "01": {
      "credit": 1000000,
      "debit": 500000,
      "balance": 500000
    },
    "02": {
      "credit": 200000,
      "debit": 0,
      "balance": 700000
    },
    "12": {
      "credit": 0,
      "debit": 100000,
      "balance": 600000
    }
  },
  "meta": {
    "colleague_id": 108,
    "year": 1403,
    "total_months": 3,
    "cached": true,
    "timestamp": "2025-12-01T16:30:00+03:30"
  }
}

پاسخ‌های خطا (Error Responses)

خطای اعتبارسنجی (400)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The selected colleague id is invalid."
  },
  "meta": { ... }
}

خطای سرور (500)

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Redis connection failed"
  },
  "meta": { ... }
}

توضیحات فنی (Meta)

DELETE /v2/account-history/cache

Route Info

شرح عملکرد (Functionality)

این API برای پاک‌سازی دستی کش (Invalidation) استفاده می‌شود. زمانی که داده‌های زیرساختی تغییر کرده‌اند و نیاز است محاسبات مجدداً از صفر انجام شوند، این متد صدا زده می‌شود.

ورودی‌ها (Input Parameters)

پارامترها می‌توانند در Query String یا Body (JSON) ارسال شوند.

{
  "colleague_id": 108,
  "year": 1403
}

قوانین اعتبارسنجی (Validation Rules)

منطق اجرا (Execution Logic)

پاسخ موفق (200 OK)

{
  "payload": {
    "cleared_keys": 25
  },
  "meta": {
    "colleague_id": 108,
    "year": 1403,
    "timestamp": "2025-12-01T17:05:00+03:30"
  }
}

پاسخ‌های خطا (Error Responses)

خطای سمت سرویس (500)

اگر اتصال به Redis در حین حذف قطع شود:

{
  "error": {
    "code": "CACHE_CLEAR_ERROR",
    "message": "Redis connection failed..."
  },
  "meta": { ... }
}

نکات فنی (Technical Notes)

POST /v2/redis-accounting/create-missing-documents

Route Info

شرح عملکرد (Functionality)

این API مسئول بررسی وجود اسناد مفقود و سپس ایجاد خودکار آن‌ها در سیستم است. منطق ساخت اسناد به‌طور کامل در سرویس redisAccountingService اجرا می‌شود و این روت فقط فراخوانی و مدیریت پاسخ را انجام می‌دهد.

ورودی‌ها (Input Parameters)

این روت هیچ پارامتر ورودی‌ای در Query یا Body دریافت نمی‌کند.

منطق اجرا (Execution Logic)

پاسخ موفق (200 OK)

{
  "success": true,
  "data": {
    "total_processed": 42,
    "created": 42,
    "existing": 0
  },
  "message": "پردازش کامل شد. 42 سند ایجاد شد."
}

پاسخ‌های خطا (Error Responses)

خطای سمت سرویس (500)

در صورت بروز Exception در سرویس:

{
  "success": false,
  "message": "خطا در ایجاد اسناد: Redis connection failed"
}

نکات فنی (Technical Notes)

POST /v2/redis-accounting/create-missing-documents

Redis Accounting Sync

مستندات فنی سرویس حسابداری - نسخه 2.0

مسیر پردازش داده (Data Flow)

Header Requirements

نمونه پاسخ‌ها (Responses)

{
    "success": true,
    "data": {
        "total_scanned": 1540,
        "total_processed": 12,
        "details": [
            "Document #8891 synced from Redis."
        ]
    },
    "message": "پردازش کامل شد. 12 سند ایجاد شد."
}

{
    "success": false,
    "message": "خطا در ایجاد اسناد: Redis connection timed out."
}

POST /v2/redis-accounting/create-missing-documents

Create Missing Documents

این اندپوینت در سرویس Redis Accounting وظیفه دارد همه مدارکی که باید وجود داشته باشند اما در Redis ثبت نشده‌اند را شناسایی و ایجاد کند. این عملیات معمولاً در موارد زیر استفاده می‌شود:

Request Overview

Request Body Schema

Request Example

{
  "organization_id": 1204,
  "sync_mode": "delta",
  "dry_run": false
}
  

Response Schema

Response Example

{
  "status": "success",
  "created_count": 32,
  "missing_ids": [
    "redis:doc:93422",
    "redis:doc:93424",
    "redis:doc:93455"
  ],
  "execution_time_ms": 128
}
  

Process Flow

POST /v2/redis-accounting/save-manual-document

Save Manual Document

این اندپوینت یک سند دستی (Manual Document) را از دیتابیس بارگذاری کرده و ردیف‌های آن را در Redis ذخیره می‌کند. این عملیات زمانی استفاده می‌شود که بخواهیم وضعیت یک سند دستی در Redis بازسازی یا هماهنگ‌سازی شود.

Request Overview

Request Body Schema

Request Example

{
  "id": 9234
}
  

Response (Success)

{
  "success": true,
  "message": "Saved 3 documents to Redis",
  "data": {
    "success": true,
    "message": "Saved 3 documents to Redis",
    "manual_document_id": 9234
  }
}
  

Response (Validation Error)

{
  "success": false,
  "message": "خطا در اعتبارسنجی",
  "errors": {
    "id": [
      "The id field is required"
    ]
  }
}
  

Response (Server Error)

{
  "success": false,
  "message": "خطا در ذخیره سند: <error details>"
}
  

Process Flow

POST /v2/redis-accounting/save-document

Save Document

این اندپوینت یک سند حسابداری را در هسته حسابداری Redis ذخیره می‌کند. عملیات شامل ایجاد Hash سند، ساخت ایندکس‌های زمانی و حسابداری، و به‌روزرسانی مانده‌ها در سه سطح گروه/کل/حساب است. این متد ستون فقرات سیستم حسابداری Redis محسوب می‌شود.

Request Overview

Request Body Schema

Request Example

{
  "serial": 120,
  "description": "خرید قطعات",
  "jalaliDate": "1403-09-01",
  "debtor": 250000,
  "creditor": 0,
  "group": 10,
  "general": 101,
  "account": 1011,
  "subsidiary": 1011003
}
  

Response (Success)

{
  "status": true,
  "serial": 120,
  "id": 934221,
  "time": 1.78
}
  

Response (Validation Error)

{
  "status": false,
  "message": "خطا در اعتبارسنجی",
  "errors": {
    "jalaliDate": [
      "The jalaliDate must match YYYY-MM-DD"
    ]
  }
}
  

Response (Server Error)

{
  "status": false,
  "message": "خطا در ذخیره سند",
  "trace": [...]
}
  

Internal Redis Architecture

Process Flow

DELETE /v2/redis-accounting/delete-document

Delete Document

این اندپوینت یک سند حسابداری را از هسته Redis حذف می‌کند. عملیات شامل حذف Hash سند، حذف شناسه از تمامی ایندکس‌ها، و پاک‌سازی کامل کلیدهای بالانس مرتبط با گروه/کل/معین/تفضیلی است. توجه: در منطق فعلی سیستم، بالانس‌ها recalculate نمی‌شوند و به‌جای آن حذف کامل می‌گردند.

Request Overview

Request Body Schema

Request Example

{
  "id": 934221
}
  

Response (Success)

{
  "success": true,
  "message": "سند با موفقیت حذف شد"
}
  

Response (Validation Error)

{
  "success": false,
  "message": "خطا در اعتبارسنجی",
  "errors": {
    "id": [
      "The id field is required."
    ]
  }
}
  

Response (Server Error)

{
  "success": false,
  "message": "خطا در حذف سند: Internal server error message..."
}
  

Internal Redis Architecture

Process Flow

DELETE /v2/redis-accounting/clear-all

Clear All Documents

این اندپوینت تمام اسناد حسابداری ذخیره‌شده در Redis را حذف می‌کند. عملیات شامل حذف تمامی Hashها، پاک‌سازی کامل تمام ایندکس‌ها (Set / Sorted Set)، و حذف همه کلیدهای بالانس در سطوح گروه، کل، معین و تفضیلی است. این عملیات یک عملیات مخرب و غیرقابل بازگشت محسوب می‌شود.

Request Overview

Request Body Schema

این اندپوینت هیچ ورودی‌ای نمی‌پذیرد.

Request Example

DELETE /v2/redis-accounting/clear-all
  

Response (Success)

{
  "success": true,
  "message": "تمام اسناد از Redis حذف شدند"
}
  

Response (Server Error)

{
  "success": false,
  "message": "خطا در حذف اسناد: Internal server error..."
}
  

Internal Redis Architecture

Process Flow

GET /v2/redis-accounting/documents/subsidiary

Get Documents by Subsidiary

این اندپوینت لیست اسناد حسابداری مربوط به یک کد تفضیلی را از Redis برمی‌گرداند. دیتای خروجی شامل اسناد، مانده فعلی، تعداد کل اسناد، و در صورت درخواست، مانده تجمیعی از ابتدای سال تا تاریخ مشخص است. عملیات بر اساس ایندکس Redis accounting:docs:subsidiary:{code} انجام می‌شود.

Request Overview

Query Parameters Schema

Request Example

GET /v2/redis-accounting/documents/subsidiary?code=1011003&from_year_start=true&to_date=1403-09-15
  

Response (Success)

ساختار خروجی:

{
  "success": true,
  "data": {
    "documents": [
      [
        [1733301120.123, 1733301120.125, ...],
        [
          {
            "id": "934221",
            "date": "1403-09-01",
            "debit": "250000",
            "credit": "0",
            "group": "10",
            "general": "101",
            "account": "1011",
            "subsidiary": "1011003"
          }
        ]
      ],
      "balance": {
        "debit": 250000,
        "credit": 0,
        "remaining": 250000
      },
      "total_documents": 1,
      "year_start_balance": {
        "debit": 250000,
        "credit": 0,
        "remaining": 250000,
        "year_start": "1403-01-01",
        "to_date": "1403-09-15"
      }
    }
  }
}
  

Response (Validation Error)

{
  "success": false,
  "message": "خطا در اعتبارسنجی",
  "errors": {
    "code": [
      "The code field is required."
    ]
  }
}
  

Response (Server Error)

{
  "success": false,
  "message": "خطا در دریافت اسناد: Internal server error..."
}
  

Internal Redis Architecture

Process Flow

GET /v2/redis-accounting/documents/account

Get Documents by Account

این اندپوینت لیست اسناد حسابداری مربوط به یک کد معین را از Redis بازیابی می‌کند. خروجی شامل اسناد، مانده فعلی، تعداد اسناد، و در صورت فعال بودن، ماندهٔ تجمیعی از ابتدای سال است. عملیات بر اساس ایندکس Redis accounting:docs:account:{code} انجام می‌شود.

Request Overview

Query Parameters Schema

Request Example

GET /v2/redis-accounting/documents/account?code=1011&from_year_start=true
  

Response (Success)

ساختار خروجی:

{
  "success": true,
  "data": {
    "documents": [
      [
        [1733301120.101, 1733301120.103, ...],
        [
          {
            "id": "2210",
            "date": "1403-05-01",
            "debit": "500000",
            "credit": "0",
            "group": "10",
            "general": "101",
            "account": "1011",
            "subsidiary": "1011001"
          }
        ]
      ],
      "balance": {
        "debit": 500000,
        "credit": 0,
        "remaining": 500000
      },
      "total_documents": 2,
      "year_start_balance": {
        "debit": 500000,
        "credit": 0,
        "remaining": 500000,
        "year_start": "1403-01-01",
        "to_date": "1403-09-15"
      }
    }
  }
}
  

Response (Validation Error)

{
  "success": false,
  "message": "خطا در اعتبارسنجی",
  "errors": {
    "code": [
      "The code field is required."
    ]
  }
}
  

Response (Server Error)

{
  "success": false,
  "message": "خطا در دریافت اسناد: Internal server error..."
}
  

Internal Redis Architecture

Process Flow

GET /v2/redis-accounting/documents/general

Get Documents by General

این اندپوینت اسناد حسابداری مرتبط با یک کد کل (General Code) را از Redis بازیابی می‌کند. خروجی شامل: لیست اسناد، مانده فعلی، تعداد اسناد، و اگر درخواست شده باشد، مانده تجمیعی از ابتدای سال است. داده‌ها از ایندکس Redis با الگو accounting:docs:general:{code} استخراج می‌شوند.

Request Overview

Query Parameters

Request Example

GET /v2/redis-accounting/documents/general?code=101&from_year_start=true
  

Response (Success)

ساختار خروجی:

{
  "success": true,
  "data": {
    "documents": [
      [
        [1733301120.201, 1733301120.203, ...],
        [
          {
            "id": "88401",
            "date": "1403-03-15",
            "debit": "150000",
            "credit": "0",
            "group": "10",
            "general": "101",
            "account": "1011",
            "subsidiary": "1011001"
          }
        ]
      ],
      "balance": {
        "debit": 150000,
        "credit": 0,
        "remaining": 150000
      },
      "total_documents": 2,
      "year_start_balance": {
        "debit": 150000,
        "credit": 0,
        "remaining": 150000,
        "year_start": "1403-01-01",
        "to_date": "1403-09-15"
      }
    }
  }
}
  

Response (Validation Error)

{
  "success": false,
  "message": "خطا در اعتبارسنجی",
  "errors": {
    "code": [
      "The code field is required."
    ]
  }
}
  

Response (Server Error)

{
  "success": false,
  "message": "خطا در دریافت اسناد: Internal server error..."
}
  

Internal Redis Architecture

Process Flow

GET /v2/redis-accounting/documents/group

Get Documents by Group

این اندپوینت وظیفه دارد تمام اسناد حسابداری مرتبط با یک کد گروه (Group Code) را از Redis بازیابی کند. داده‌ها شامل اسناد، مانده فعلی، تعداد اسناد، و در صورت درخواست، مانده تجمیعی از ابتدای سال شمسی است. استخراج داده از Redis بر اساس الگوی زیر انجام می‌شود: accounting:docs:group:{code}.

Request Overview

Query Parameters

Request Example

GET /v2/redis-accounting/documents/group?code=10&from_year_start=true
  

Response (Success)

ساختار خروجی دقیقاً مطابق پیاده‌سازی فعلی RedisAccountingService است.

{
  "success": true,
  "data": {
    "documents": [
      [
        [1733301001.102, 1733301001.105, ...],
        [
          {
            "id": "88401",
            "date": "1403-03-15",
            "debit": "150000",
            "credit": "0",
            "group": "10",
            "general": "101",
            "account": "1011",
            "subsidiary": "1011001"
          }
        ]
      ],
      "balance": {
        "debit": 150000,
        "credit": 0,
        "remaining": 150000
      },
      "total_documents": 2,
      "year_start_balance": {
        "debit": 150000,
        "credit": 0,
        "remaining": 150000,
        "year_start": "1403-01-01",
        "to_date": "1403-09-15"
      }
    }
  }
}
  

Response (Validation Error)

{
  "success": false,
  "message": "خطا در اعتبارسنجی",
  "errors": {
    "code": [
      "The code field is required."
    ]
  }
}
  

Response (Server Error)

{
  "success": false,
  "message": "خطا در دریافت اسناد: Internal server error..."
}
  

Internal Redis Architecture

Process Flow

GET /v2/redis-accounting/documents/group

Get Documents by Group

این اندپوینت وظیفه دارد تمام اسناد حسابداری مرتبط با یک کد گروه (Group Code) را از Redis بازیابی کند. داده‌ها شامل اسناد، مانده فعلی، تعداد اسناد، و در صورت درخواست، مانده تجمیعی از ابتدای سال شمسی است. استخراج داده از Redis بر اساس الگوی زیر انجام می‌شود: accounting:docs:group:{code}.

Request Overview

Query Parameters

Request Example

GET /v2/redis-accounting/documents/group?code=10&from_year_start=true
  

Response (Success)

ساختار خروجی دقیقاً مطابق پیاده‌سازی فعلی RedisAccountingService است.

{
  "success": true,
  "data": {
    "documents": [
      [
        [1733301001.102, 1733301001.105, ...],
        [
          {
            "id": "88401",
            "date": "1403-03-15",
            "debit": "150000",
            "credit": "0",
            "group": "10",
            "general": "101",
            "account": "1011",
            "subsidiary": "1011001"
          }
        ]
      ],
      "balance": {
        "debit": 150000,
        "credit": 0,
        "remaining": 150000
      },
      "total_documents": 2,
      "year_start_balance": {
        "debit": 150000,
        "credit": 0,
        "remaining": 150000,
        "year_start": "1403-01-01",
        "to_date": "1403-09-15"
      }
    }
  }
}
  

Response (Validation Error)

{
  "success": false,
  "message": "خطا در اعتبارسنجی",
  "errors": {
    "code": [
      "The code field is required."
    ]
  }
}
  

Response (Server Error)

{
  "success": false,
  "message": "خطا در دریافت اسناد: Internal server error..."
}
  

Internal Redis Architecture

Process Flow

GET /v2/redis-accounting/documents/date-range

Get Documents By Date Range

این اندپوینت اسناد حسابداری را بر اساس یک بازهٔ تاریخ شمسی (Jalali) از Redis استخراج می‌کند. استخراج اسناد بر اساس ایندکس تاریخ شمسی accounting:docs:by_jalali_date انجام شده و خروجی شامل لیست اسناد، تعداد کل اسناد و اطلاعات معتبر از بازهٔ ارسال‌شده است.

Request Overview

Query Parameters

Request Example

GET /v2/redis-accounting/documents/date-range?start_date=1403-01-01&end_date=1403-03-31
  

Validation Rules

Response (Success)

ساختار خروجی بر اساس منطق RedisAccountingService است.

{
  "success": true,
  "data": {
    "documents": [
      {
        "id": "88401",
        "date": "1403-02-15",
        "debit": "450000",
        "credit": "0",
        "group": "10",
        "general": "101",
        "account": "1011",
        "subsidiary": "1011001"
      }
    ],
    "total_documents": 1,
    "date_range": {
      "start": "1403-01-01",
      "end": "1403-03-31",
      "start_shamsi": "1403/01/01",
      "end_shamsi": "1403/03/31"
    }
  }
}
  

Response (Validation Error)

{
  "success": false,
  "message": "خطا در اعتبارسنجی - تاریخ باید به صورت شمسی (YYYY-MM-DD) باشد",
  "errors": {
    "start_date": [
      "The start_date format is invalid."
    ]
  }
}
  

Response (Start > End)

{
  "success": false,
  "message": "تاریخ شروع باید کوچکتر یا مساوی تاریخ پایان باشد"
}
  

Response (Server Error)

{
  "success": false,
  "message": "خطا در دریافت اسناد: Internal server error..."
}
  

Internal Redis Architecture

Process Flow

GET /v2/redis-accounting/balance

Get Redis Balance

این اندپوینت مانده حساب را بر اساس نوع و کد حساب از Redis بازیابی می‌کند. مانده‌ها در کلیدهای balance:{type}:{code} ذخیره می‌شوند و شامل سه مقدار debit، credit و remaining هستند.

Request Overview

Query Parameters

Request Example

GET /v2/redis-accounting/balance?type=group&code=10
  

Response (Success)

{
  "success": true,
  "data": {
    "debit": 450000,
    "credit": 150000,
    "remaining": 300000
  }
}
  

No Balance Found

در صورتی که کلید balance:{type}:{code} وجود نداشته باشد، خروجی بدون ارور و به شکل زیر است:

{
  "success": true,
  "data": {
    "debit": 0,
    "credit": 0,
    "remaining": 0
  }
}
  

Response (Validation Error)

{
  "success": false,
  "message": "خطا در اعتبارسنجی",
  "errors": {
    "type": [
      "The type field is required."
    ]
  }
}
  

Response (Server Error)

{
  "success": false,
  "message": "خطا در دریافت مانده: Redis connection error..."
}
  

Internal Redis Architecture

Process Flow

GET /v2/redis-accounting/stats

Get Redis Statistics

این اندپوینت آمار کلی Redis را در حوزه سیستم حسابداری استخراج می‌کند. شامل تعداد اسناد، تعداد ایندکس‌ها، تعداد مانده‌ها و میزان حافظه مصرف شده Redis. این روت برای استفاده داخلی (Ops, Engineering, Monitoring) طراحی شده است.

Request Overview

Authentication

این اندپوینت کاملاً محافظت‌شده است. فقط کاربران احراز هویت شده و دارای JWT معتبر دسترسی دارند.

Request Parameters

بدون ورودی. این روت هیچ query یا body ندارد.

Response (Success)

{
  "success": true,
  "data": {
    "total_documents": 3412,
    "total_indexes": 128,
    "total_balances": 904,
    "memory_usage": "6.12M"
  }
}
  

Response (Server Error)

{
  "success": false,
  "message": "خطا در دریافت آمار: Redis connection lost"
}
  

Internal Architecture Notes

برای استخراج آمار، سرویس داخلی redisAccountingService از دستور Redis::keys استفاده می‌کند. این عملیات نمایی و غیرمقیاس‌پذیر است و فقط برای محیط‌های داخلی مناسب است (Production-safe only when dataset is controlled).

POST /v2/batch-accounting/process/date-range

Batch Process Documents by Date Range

این اندپوینت پردازش دسته‌ای اسناد حسابداری را در یک بازه تاریخی شمسی انجام می‌دهد. تمام اسنادی که در تاریخ مشخص‌شده قرار دارند از دیتابیس فراخوانی شده، در چانک‌های کنترل‌شده پردازش می‌شوند و داده‌های Redis Accounting شامل اسناد و مانده‌ها آپدیت می‌گردند. این عملیات برای عملیات‌های Rebuild، Sync و Mass‑Recalculate استفاده می‌شود.

Request Overview

Authentication

این اندپوینت کاملاً محافظت‌شده بوده و فقط کاربران دارای JWT معتبر می‌توانند آن را اجرا کنند. در صورت نامعتبر بودن Token، خطاهای استاندارد میدلور AuthWithJWT بازگردانده می‌شود.

Request Body Parameters

Request Example

POST /v2/batch-accounting/process/date-range
Content-Type: application/json

{
  "start_date": "1403-01-01",
  "end_date": "1403-01-31",
  "batch_size": 200
}
  

Response (Success)

{
  "success": true,
  "data": {
    "success": true,
    "total_processed": 283,
    "total_errors": 2,
    "batch_results": [
      {
        "processed": 100,
        "errors": 0
      },
      {
        "processed": 98,
        "errors": 1
      },
      {
        "processed": 85,
        "errors": 1
      }
    ],
    "date_range": {
      "start": "1403-01-01",
      "end": "1403-01-31"
    }
  },
  "message": "پردازش کامل شد. 283 سند پردازش شد."
}
  

Response (Validation Error)

{
  "success": false,
  "message": "خطا در اعتبارسنجی",
  "errors": {
    "start_date": [
      "The start_date field format is invalid."
    ]
  }
}
  

Response (Shamsi Date Middleware Error)

{
  "success": false,
  "message": "فیلد start_date باید تاریخ شمسی معتبر به فرمت YYYY-MM-DD باشد",
  "field": "start_date",
  "received_value": "2024-01-01",
  "example": "1404-05-27"
}
  

Response (Server Error)

{
  "success": false,
  "message": "خطا در پردازش: Redis connection timeout"
}
  

Internal Processing Architecture

این عملیات تمام اسناد جدول manual_documents را در بازه تاریخی مشخص دریافت می‌کند، سپس آنها را در چانک‌های کنترل‌شده پردازش می‌کند. بین هر Batch یک توقف 0.1 ثانیه‌ای برای جلوگیری از فشار Redis انجام می‌شود.

Process Flow

POST /v2/batch-accounting/process/month

Process Batch Documents By Month

این اندپوینت اسناد حسابداری را بر اساس یک ماه شمسی مشخص دریافت کرده و آن‌ها را به صورت دسته‌ای (Batch Processing) پردازش می‌کند. ابتدا از تاریخ ورودی برای تعیین محدودهٔ کامل ماه استفاده می‌شود سپس عملیات پردازش دسته‌ای بر اساس منطق processBatchByDateRange اجرا می‌گردد. خروجی شامل تعداد کل اسناد پردازش‌شده، اطلاعات هر Batch و پیام نهایی مربوط به نام فارسی ماه است.

Request Overview

Body Parameters

Request Example

POST /v2/batch-accounting/process/month

{
  "month_date": "1403-05-01",
  "batch_size": 200
}
  

Validation Rules

Response (Success)

ساختار خروجی بر اساس BatchAccountingService::processBatchByDateRange است.

{
  "success": true,
  "data": {
    "success": true,
    "total_processed": 450,
    "total_errors": 0,
    "batches_count": 3
  },
  "message": "پردازش ماه مرداد کامل شد. 450 سند پردازش شد."
}
  

Response (Validation Error)

{
  "success": false,
  "message": "خطا در اعتبارسنجی",
  "errors": {
    "month_date": [
      "The month_date format is invalid."
    ]
  }
}
  

Response (Server Error)

{
  "success": false,
  "message": "خطا در پردازش ماه: Internal server error..."
}
  

Internal Architecture

Process Flow

POST /v2/batch-accounting/process/month

Process Batch Documents By Month

این اندپوینت اسناد حسابداری را بر اساس یک ماه شمسی مشخص دریافت کرده و آن‌ها را به صورت دسته‌ای (Batch Processing) پردازش می‌کند. ابتدا از تاریخ ورودی برای تعیین محدودهٔ کامل ماه استفاده می‌شود سپس عملیات پردازش دسته‌ای بر اساس منطق processBatchByDateRange اجرا می‌گردد. خروجی شامل تعداد کل اسناد پردازش‌شده، اطلاعات هر Batch و پیام نهایی مربوط به نام فارسی ماه است.

Request Overview

Body Parameters

Request Example

POST /v2/batch-accounting/process/month

{
  "month_date": "1403-05-01",
  "batch_size": 200
}

Validation Rules

Response (Success)

ساختار خروجی بر اساس BatchAccountingService::processBatchByDateRange است.

{
  "success": true,
  "data": {
    "success": true,
    "total_processed": 450,
    "total_errors": 0,
    "batches_count": 3
  },
  "message": "پردازش ماه مرداد کامل شد. 450 سند پردازش شد."
}

Response (Validation Error)

{
  "success": false,
  "message": "خطا در اعتبارسنجی",
  "errors": {
    "month_date": [
      "The month_date format is invalid."
    ]
  }
}

Response (Server Error)

{
  "success": false,
  "message": "خطا در پردازش ماه: Internal server error..."
}

Internal Architecture

Process Flow

POST /v2/batch-accounting/process/year

Process Batch Documents By Year

این اندپوینت اسناد حسابداری را بر اساس یک سال شمسی مشخص پردازش می‌کند. ابتدا تاریخ شروع سال و پایان سال شمسی محاسبه می‌شود، سپس عملیات دسته‌ای (Batch Processing) توسط متد processBatchByDateRange اجرا می‌گردد. نتیجه نهایی شامل تعداد اسناد پردازش‌شده، تعداد خطاها و مجموع Batchهای اجرا شده است.

Request Overview

Body Parameters

Request Example

POST /v2/batch-accounting/process/year

{
  "year": 1402,
  "batch_size": 800
}
  

Validation Rules

Response (Success)

ساختار خروجی بر اساس BatchAccountingService::processBatchByYear است.

{
  "success": true,
  "data": {
    "success": true,
    "total_processed": 7800,
    "total_errors": 12,
    "batches_count": 16
  },
  "message": "پردازش سال 1402 کامل شد. 7800 سند پردازش شد."
}
  

Response (Validation Error)

{
  "success": false,
  "message": "خطا در اعتبارسنجی",
  "errors": {
    "year": [
      "The year must be between 1300 and 1500."
    ]
  }
}
  

Response (Server Error)

{
  "success": false,
  "message": "خطا در پردازش سال: Internal server error..."
}
  

Internal Architecture

Process Flow

POST /v2/batch-accounting/process/current-month

Process Batch Documents of Current Month

این اندپوینت ماه جاری شمسی را به صورت خودکار تشخیص داده و اسناد آن را با استفاده از پردازش دسته‌ای (Batch Processing) پردازش می‌کند. تاریخ روز جاری از طریق ShamsiDateHelper::today() استخراج می‌شود و سپس عملیات ماه جاری مانند متد processBatchByMonth انجام می‌گیرد. پیام نهایی شامل نام فارسی ماه جاری است.

Request Overview

Body Parameters

Request Example

POST /v2/batch-accounting/process/current-month

{
  "batch_size": 150
}
  

Validation Rules

Response (Success)

{
  "success": true,
  "data": {
    "success": true,
    "total_processed": 1120,
    "total_errors": 0,
    "batches_count": 8
  },
  "message": "پردازش آذر جاری کامل شد. 1120 سند پردازش شد."
}
  

Response (Server Error)

{
  "success": false,
  "message": "خطا در پردازش ماه جاری: Internal server error..."
}
  

Internal Architecture

Process Flow

POST /v2/batch-accounting/process/current-year

Process Batch Documents of Current Year

این اندپوینت سال جاری شمسی را به صورت خودکار تشخیص داده و اسناد آن را از طریق پردازش دسته‌ای (Batch Processing) پردازش می‌کند. سال جاری از تاریخ کامل امروز، که توسط ShamsiDateHelper::today() تولید می‌شود، استخراج شده و سپس متد processBatchByYear فراخوانی می‌شود.

Request Overview

Body Parameters

Request Example

POST /v2/batch-accounting/process/current-year

{
  "batch_size": 700
}
  

Validation Rules

Response (Success)

{
  "success": true,
  "data": {
    "success": true,
    "total_processed": 9100,
    "total_errors": 3,
    "batches_count": 20
  },
  "message": "پردازش سال 1403 کامل شد. 9100 سند پردازش شد."
}
  

Response (Server Error)

{
  "success": false,
  "message": "خطا در پردازش سال جاری: Internal server error..."
}
  

Internal Architecture

Process Flow

POST /v2/batch-accounting/rebuild-indexes

Rebuild All Redis Indexes

این اندپوینت یک عملیات بسیار سنگین و مخرب (destructive) برای بازسازی کامل تمامی ایندکس‌های Redis اجرا می‌کند. قبل از شروع، تمام داده‌های موجود در Redis شامل اسناد، ایندکس‌ها و مانده‌ها حذف می‌شوند و سپس بر اساس رکوردهای فعال جدول manual_documents، ایندکس‌ها از صفر ساخته می‌شوند. برای جلوگیری از اجرای اشتباه، فیلد confirm اجباری است.

Request Overview

Body Parameters

Request Example

POST /v2/batch-accounting/rebuild-indexes

{
  "batch_size": 300,
  "confirm": true
}
  

Validation Rules

Response (Success)

{
  "success": true,
  "data": {
    "total_documents": 12850,
    "processed_count": 12850,
    "error_count": 0,
    "duration_seconds": 14.27,
    "performance": {
      "documents_per_second": 900.32,
      "batch_size": 300
    }
  },
  "message": "بازسازی کامل انجام شد. 12850 سند در 14.27 ثانیه پردازش شد."
}
  

Response (Validation Error: 422)

{
  "success": false,
  "message": "خطا در اعتبارسنجی",
  "errors": {
    "confirm": [
      "فیلد confirm الزامی است."
    ]
  }
}
  

Response (Server Error)

{
  "success": false,
  "message": "خطا در بازسازی: Internal server error..."
}
  

Internal Architecture

Process Flow

POST /v2/batch-accounting/optimize-memory

Optimize Redis Memory

این اندپوینت عملیات بهینه‌سازی حافظه Redis را به صورت کامل و ساختاریافته انجام می‌دهد. هدف عملیات شامل: - اندازه‌گیری حافظه فعلی، - حذف کلیدهای غیرمعتبر، - اجرای فشرده‌سازی AOF از طریق bgrewriteaof, - و ارائه گزارش میزان حافظه آزادشده است. از آنجا که این عملیات می‌تواند بر عملکرد موقتی Redis اثر بگذارد، معمولاً در محیط‌های Production با احتیاط فراخوانی می‌شود.

Request Overview

Body Parameters

این اندپوینت هیچ ورودی ندارد.

Request Example

POST /v2/batch-accounting/optimize-memory
{}
  

Response (Success)

{
  "success": true,
  "data": {
    "initial_memory": 183783424,
    "final_memory": 119013376,
    "saved_memory": 64770048,
    "optimization_percentage": 35.25
  },
  "message": "بهینه‌سازی کامل شد. 35.25% حافظه آزاد شد."
}
  

Response (Server Error)

{
  "success": false,
  "message": "خطا در بهینه‌سازی: Internal server error..."
}
  

Internal Architecture

Process Flow

GET /v2/batch-accounting/report/comprehensive

Comprehensive Redis Accounting Report

این اندپوینت یک گزارش جامع (Comprehensive Report) از وضعیت کامل سیستم Redis Accounting و Batch Accounting تولید می‌کند. این گزارش شامل آمار عمومی Redis، تحلیل اسناد ماهانه، بخش‌های پرمصرف (Top Subsidiaries)، جمع‌بندی بالانس‌ها، گزارش حافظه، و متریک‌های عملکردی است. این گزارش معمولاً برای تیم‌های DevOps، Backend Engineering و تیم‌های Performance Monitoring استفاده می‌شود.

Request Overview

Query Parameters

این اندپوینت هیچ پارامتر ورودی ندارد.

Response (Success)

{
  "success": true,
  "data": {
    "general_stats": {
      "total_documents": 12850,
      "total_indexes": 5120,
      "total_balances": 740,
      "memory_usage": "148 MB"
    },
    "documents_by_month": {
      "1403-01": 1320,
      "1403-02": 1408,
      "1403-03": 960
    },
    "top_subsidiaries": [
      { "code": 21012, "documents": 482 },
      { "code": 21007, "documents": 441 }
    ],
    "balance_summary": {
      "total_debit": 483900000,
      "total_credit": 480200000,
      "difference": 3700000
    },
    "memory_info": {
      "used_memory": 183783424,
      "peak_memory": 221184000,
      "fragmentation_ratio": 1.23
    },
    "performance_metrics": {
      "avg_documents_per_batch": 280,
      "avg_processing_time_ms": 14.2,
      "throughput_docs_per_second": 905.4
    }
  },
  "message": "گزارش کامل تهیه شد"
}
  

Response (Server Error)

{
  "success": false,
  "message": "خطا در تهیه گزارش: Internal server error..."
}
  

Internal Architecture

Process Flow

POST /v2/batch-accounting/preview

Preview Batch Processing (Dry‑Run)

این اندپوینت یک پیش‌نمایش کامل از عملیات پردازش Batch را ارائه می‌دهد، بدون اینکه هیچ پردازش واقعی روی Redis یا دیتابیس انجام شود. این پیش‌نمایش برای تصمیم‌گیری مهندسی قبل از اجرای پردازش‌های سنگین استفاده می‌شود و شامل: - تعداد اسناد قابل پردازش، - تعداد Batch مورد نیاز، - زمان تخمینی، - تعداد روزهای شمسی در بازه، - و اطلاعات کامل بازه تاریخ می‌باشد.

Request Overview

Body Parameters

Validation Rules

Response (Success)

{
  "success": true,
  "data": {
    "total_documents": 1480,
    "batch_size": 100,
    "estimated_batches": 15,
    "estimated_time_seconds": 7.5,
    "estimated_time_minutes": 0.13,
    "working_days_count": 31,
    "date_range": {
      "start": "1403-01-01",
      "end": "1403-01-31",
      "start_formatted": "۱ فروردین ۱۴۰۳",
      "end_formatted": "۳۱ فروردین ۱۴۰۳"
    }
  },
  "message": "پیش‌نمایش: 1480 سند در 15 batch پردازش خواهد شد"
}
  

Response (Validation Error: 422)

{
  "success": false,
  "message": "خطا در اعتبارسنجی",
  "errors": {
    "start_date": [
      "فرمت تاریخ نامعتبر است."
    ]
  }
}
  

Response (Server Error)

{
  "success": false,
  "message": "خطا در پیش‌نمایش: Internal server error..."
}
  

Internal Architecture

Process Flow

POST /v2/core/offices/list

Core Offices List

این اندپوینت لیست کامل دفاتر (Offices) سیستم را از جدول offices بازیابی کرده و برای استفاده در پنل‌های مدیریتی Core Center برگشت می‌دهد. دسترسی به این اندپوینت کاملاً ویژه است و فقط کاربرانی که Branch آن‌ها دقیقاً مقدار "[0]" باشد می‌توانند وارد شوند.

Request Overview

Authentication

لازم است هدر زیر حتماً ارسال شود:

Authorization: Bearer <JWT_TOKEN>

میدلور AuthWithJWT موارد زیر را احراز می‌کند:

سپس میدلور group, level, operator را به درخواست اضافه می‌کند.

Authorization (Core Access)

میدلور CoreAccess سطح دسترسی را کنترل می‌کند.

در صورت عدم دسترسی خروجی زیر برگردانده می‌شود:

{
  "status": false,
  "time": 1710000000,
  "error": {
    "code": 5005,
    "message": "Access to the [core center] requires special access."
  },
  "support": {
    "phone": "021-91016838 in 121",
    "email": "ict@airplus.app",
    "panel": "helpdesk.airplus.app"
  }
}
  

Body Parameters

این اندپوینت هیچ پارامتر ورودی ندارد.

Response (Success)

خروجی شامل تمام رکوردهای جدول offices است.

{
  "status": true,
  "time": 1710000000,
  "data": [
    {
      "id": 1,
      "title_fa": "دفتر مرکزی",
      "brand_fa": "ایرپلاس",
      "city": "تهران",
      "status": 1,
      ...
    },
    ...
  ]
}
  

Response (JWT Error)

نمونه خروجی اگر توکن ارسال نشود:

{
  "status": false,
  "time": 1710000000,
  "error": {
    "code": 1005,
    "message": "Token not provided!"
  },
  "support": { ... }
}
  

Process Flow

POST /v2/core/accommodations/list

Core Accommodations List

این اندپوینت لیست اقامتگاه‌ها (هتل‌ها) را با پشتیبانی از فیلترهای پیشرفته، صفحه‌بندی پویا، بارگذاری داده‌های تکمیلی از Redis، اطلاعات جغرافیایی از دیتابیس، و استخراج Supplier Mapping برگشت می‌دهد. این سرویس صرفاً در اختیار کاربرانی قرار می‌گیرد که دسترسی Core داشته باشند (operator.branch == "[0]").

Request Overview

Authentication & Access Control

مانند سایر سرویس‌های هسته Core:

در صورت عدم دسترسی:

{
  "status": false,
  "time": 1710000000,
  "error": {
    "code": 5005,
    "message": "Access to the [core center] requires special access."
  },
  "support": { ... }
}
  

Request Body

ورودی با کلید json در Body ارسال می‌شود و توسط کد json_decode تبدیل می‌شود.

Database Query Logic

کوئری اصلی روی جدول hotels اعمال می‌شود:

paginate(
    $perPage = length,
    columns = "*",
    pageName = "hotels",
    currentPage = (start / length)
)
  

Enrichment Pipeline (per-item)

برای هر accommodation مراحل زیر اجرا می‌شود:

Response Schema

Sample Successful Response

{
  "status": true,
  "time": 1710000000,
  "draw": 3,
  "recordsTotal": 1295,
  "recordsFiltered": 20,
  "data": [
    {
      "id": 554,
      "title": "Tehran Grand Hotel",
      "title_fa": "هتل بزرگ تهران",
      "rate": 5,
      "country": {
        "id": 102,
        "fa_name": "ایران",
        "en_name": "Iran",
        "fa_nationality": "ایرانی",
        "en_nationality": "Iranian"
      },
      "state": "تهران",
      "city": "تهران",
      "location": "35.7000,51.4000",
      "address": "خیابان ولیعصر ...",
      "logo": "/media/accommodations/554/logo.png",
      "status": 1,
      "supplier": {
        "system_serial": 88,
        "serial": "C-4401"
      }
    }
  ]
}
  

Process Flow

POST /v2/core/accommodation/store

Core Accommodation Store

این اندپوینت یک اقامتگاه جدید (Hotel / Accommodation) را در سیستم ثبت می‌کند. داده‌ها از کلید data در بدنه درخواست دریافت شده و به‌صورت کامل روی جدول hotels درج می‌شوند. سپس عملیات‌های جانبی شامل ذخیره لوگو و گالری رسانه، ثبت Mapping در جدول mapping_accommodations، و اجرای سه Job (UpdateRedis، SystemLog و RunCron) در صف انجام می‌شود.

Request Overview

Access Control

دسترسی فقط در صورتی مجاز است که:

Request Body Schema

تمام ورودی‌ها داخل کلید data ارسال می‌شوند.

Core Database Insertion Logic

عملیات اصلی درج:

id = DB::table('hotels')->insertGetId([...])
  

Media Insertion Rules

هر فایل مسیر مانند

"uploads/hotels/abc.jpg"

به شکل زیر پردازش می‌شود:

Mapping Insertion

شیء mapping می‌تواند شامل کلیدهای زیر باشد. هر مقدار خالی (null / "") → در DB مقدار null ذخیره می‌شود.

در جدول mapping_accommodations فیلد accommodation = ID درج شده ذخیره می‌شود.

Background Jobs

در ادامه سه Job اجرا می‌شود:

Response (Success)

{
  "status": true,
  "time": 1710000000,
  "message": "1391 | Accommodation added!"
}
  

Response (Error)

{
  "status": false,
  "code": "1003",
  "message": "SQLSTATE... (error message)",
  "trace": [ ... ]
}
  

Flowchart

POST /v2/core/accommodation/update

Core Accommodation Update

این اندپوینت برای به‌روزرسانی اطلاعات یک اقامتگاه موجود استفاده می‌شود. رفتار اندپوینت در دو حالت انجام می‌شود:
method = "update" → به‌روزرسانی کامل رکورد اصلی (hotels)، ثبت لوگو و رسانه، به‌روزرسانی یا ایجاد Mapping، و اجرای Jobها.
method = "board" → فقط آپدیت فیلد Board و اجرای Jobهای مرتبط.

Request Overview

Access Control

Request Body Schema

در حالت method = update، ساختار data شامل تمام فیلدهای زیر است:

Update Logic (method = "update")

Media Update Rules

Mapping Logic

Update Logic (method = "board")

Background Jobs

Response (Success)

{
  "status": true,
  "time": 1710000000,
  "message": "1402 | Accommodation updated!"
}
  

Response (Error)

{
  "status": false,
  "code": "1003",
  "message": "(Exception message)",
  "trace": [...]
}
  

Flowchart

DELETE /v2/core/accommodation/delete

Core Accommodation Delete

این اندپوینت برای حذف کامل یک اقامتگاه (Hotel / Accommodation) از سیستم استفاده می‌شود. عملیات حذف فقط رکورد اصلی جدول hotels را پاک می‌کند و هیچ عمل پاکسازی روی Media یا Mapping انجام نمی‌دهد. پس از حذف، یک SystemLog با تأخیر ۱۰ دقیقه به صف snailJob ارسال می‌شود.

Request Overview

Access Control

Request Parameters

پارامتر id باید به‌صورت QueryParam یا BodyParam (بسته به ساختار درخواست) ارسال شود.

Delete Logic

SystemLog Payload

{
  "type": "DeleteAccommodation",
  "data": null,
  "goal": ,
  "by": operator.id,
  "agent": HTTP_USER_AGENT,
  "ip": client_ip,
  "datetime": now()
}
  

Response (Success)

{
  "status": true,
  "time": 1710000000,
  "message": "1402 | Accommodation deleted!"
}
  

Response (Error)

{
  "status": false,
  "code": "1003",
  "message": "(Exception message)",
  "trace": [...]
}
  

Flowchart

GET /v2/core/accommodation/view

Core Accommodation View

این اندپوینت اطلاعات کامل یک اقامتگاه را بر اساس شناسه ارسال‌شده بازگردانی می‌کند. داده‌های هتل، اطلاعات کشور/استان/شهر، مدیا (لوگو + گالری)، جزئیات، امکانات، برد، اطلاعات مدیریت و Mapping Supplierها به‌صورت کامل تجمیع و استانداردسازی می‌شود.

Request Overview

Access Control

Request Parameters

Lookup Logic

Response (Success)

{
  "status": true,
  "time": 1710000000,
  "data": {
    "title": {
      "fa": "...",
      "en": "..."
    },
    "type": "...",
    "rate": 4,
    "country": {
      "id": 118,
      "icon": "IR",
      "title": { "fa": "...", "en": "..." },
      "nationality": { "fa": "...", "en": "..." }
    },
    "state": { "id": 1, "title": { "fa": "...", "en": "..." } },
    "city":  { "id": 2, "title": { "fa": "...", "en": "..." } },

    "phone": "...",
    "mobile": "...",
    "email": "...",
    "site": "...",
    "address": "...",
    "location": "...",

    "logo": "... or false",
    "media": ["..."] or false,

    "details": {...},
    "board": [...],
    "possibilities": [...],

    "leader_name": "...",
    "leader_mobile": "...",
    "description": "...",

    "confirm_status": 1,
    "priority": 10,

    "mapping": {
      "tport": true|false,
      "sepehr": true|false,
      "snapptrip": true|false,
      "alibaba": true|false,
      "eghamat24": true|false,
      "iranhotelonline": true|false
    },

    "status": 1
  }
}
  

Response (Error)

{
  "status": false,
  "code": "1003",
  "message": "(Exception message)",
  "trace": [...]
}
  

Flowchart

POST /v2/core/accommodation/supplier/store

Core Accommodation Supplier Store

این اندپوینت برای ایجاد یک Supplier جدید (نوع colleague) و اتصال آن به یک اقامتگاه استفاده می‌شود. این عملیات شامل ایجاد رکورد جدید در جدول colleagues با سریال اختصاصی و سپس ثبت ارتباط در mapping_colleagues است.

Request Overview

Access Control

Request Body Schema

Structure of data

Insert Logic

1. ایجاد رکورد colleague

2. درج در mapping_colleagues

Serial Generation Logic (colleague)

فراخوانی زیر انجام می‌شود:

StaticController::getSerialId('colleague', 2)

منطق:

Response (Success)

{
  "status": true,
  "time": 1710000000,
  "message": "1023 | Supplier stored!"
}
  

Response (Error)

{
  "status": false,
  "code": "1003",
  "message": "(Exception message)",
  "trace": [...]
}
  

Flowchart

POST /v2/core/airlines/list

Core Airlines List

این اندپوینت لیست خطوط هوایی را با قابلیت فیلترینگ پیشرفته، Pagination سفارشی و Pull اطلاعات کشور از Redis یا Database باز می‌گرداند. منطق Pagination به صورت DataTables‑Style انجام شده و ساختار پاسخ دقیقاً با نیازهای فرانت هماهنگ است.

Request Overview

Access Control

Request Body

Structure Inside json

Pagination Logic

Filtering Logic

تمام فیلترها داخل یک Closure در where قرار گرفته‌اند:

Country Fetch Logic (Redis + DB Fallback)

Final Output Mapping

برای هر airline:

{
  "id": ...,
  "title": airline.en_title,
  "title_fa": airline.fa_title,
  "icao": airline.icao,
  "iata": airline.iata,
  "country": resolved_country_fa_name,
  "description": airline.description,
  "logo": airline.logo,
  "status": airline.status
}
  

Response (Success)

{
  "status": true,
  "time": 1710000000,
  "draw": ,
  "recordsTotal": ,
  "recordsFiltered": ,
  "data": [...]
}
  

Response (Error)

{
  "status": false,
  "code": "1003",
  "message": "(Exception message)",
  "trace": [...]
}
  

Flowchart

POST /v2/core/airports/list

Core Airports List

این اندپوینت برای دریافت لیست فرودگاه‌ها با فیلترهای پیشرفته، Pagination مشابه DataTables، و غنی‌سازی داده‌ها (Country از Redis/DB و City از DB) استفاده می‌شود. خروجی کاملاً استاندارد و سازگار با سیستم‌های مدیریت داده (DataTables‑Compatible Response) است.

Request Overview

Access Control

Request Body Schema

Structure Inside json

Pagination Logic

Filtering Logic

تمام فیلترها داخل Closure:

Country & City Enrichment

Country (Redis → DB Fallback)

City Resolution

Lookup مستقیم DB:

Final Output Mapping

{
  "id": airport.id,
  "title": airport.title,
  "title_fa": airport.title_fa,
  "iata": airport.iata,
  "country": resolved_country,
  "state": resolved_state_name,
  "city": resolved_city_name,
  "location": airport.location,
  "description": airport.description,
  "logo": airport.logo,
  "image": airport.image,
  "status": airport.status
}
  

Response (Success)

{
  "status": true,
  "time": 1710000000,
  "draw": ,
  "recordsTotal": ,
  "recordsFiltered": ,
  "data": [...]
}
  

Response (Error)

{
  "status": false,
  "code": "1003",
  "message": "(Exception message)",
  "trace": [...]
}
  

Flowchart

POST /v2/core/socket/send

Core Socket: Send Message

این اندپوینت یک پیام را از طریق سیستم Broadcasting لاراول ارسال می‌کند. پیام به Event TradeOperation پاس داده می‌شود و با toOthers() فقط به کلاینت‌های دیگر (غیر از فرستنده) Broadcast می‌شود.

Request Overview

Access Control

Request Body Schema

Broadcast Logic

پس از دریافت message:

broadcast(new TradeOperation($message))

->toOthers()

Response (Success)

{
  "status": "Message Sent!"
}
  

Response (Error)

در این نسخه از کد هندل‌کردن Exception وجود ندارد، اما در صورت بروز خطا در سطح سیستم (مثلاً عدم کارکرد Broadcast Driver)، لاراول پاسخ خطا برمی‌گرداند.

Flowchart

GET /v2/core/changelogs

Core System Changelogs

این اندپوینت وظیفه ارائه نسخه‌بندی کامل تغییرات سیستم (Change Log) را بر اساس ساختار SemVer توسعه‌یافته (major.minor.patch) بر عهده دارد. داده‌ها از جدول change_logs دریافت می‌شوند، سپس در قالب گروه‌بندی‌شده بر اساس نسخه، بازگردانده می‌شوند.

Request Overview

Access Control

Database Query Logic

دریافت تمامی لاگ‌ها از جدول change_logs با مرتب‌سازی دقیق نسخه:

DB::table('change_logs')
    ->orderBy('major', 'DESC')
    ->orderBy('minor', 'DESC')
    ->orderBy('patches', 'DESC')
    ->orderBy('created_at')
    ->get();
  

Version Grouping Logic

هر رکورد داخل گروه مخصوص نسخه قرار می‌گیرد. کلید گروه نسخه برابر است با: major . minor . patches بدون نقطه (مثلاً 231 → نسخه 02.03.01).

نسخه نهایی با صفرهای سمت چپ فرمت می‌شود:

$changeLogs[$major.$minor.$patch]['version']
    = sprintf("%02d", major)
    . '.' . sprintf("%02d", minor)
    . '.' . sprintf("%02d", patch);
  

ساختار داده هر آیتم

[
  "title"       => row.title,
  "content"     => row.content,
  "created_at"  => CalendarUtils::strftime('Y/m/d', strtotime(row.created_at)),
  "tag"         => row.tag
]
  

Response (Success)

{
  "status": true,
  "time": 1710000000,
  "data": {
    "020301": {
      "version": "02.03.01",
      "data": [
        {
          "title": "Fix Accounting Issues",
          "content": "Detail text ...",
          "created_at": "1403/07/12",
          "tag": "fix"
        },
        ...
      ]
    },
    ...
  }
}
  

Response (Error)

در این متد try/catch وجود ندارد؛ هر خطای دیتابیس یا رانتایم به‌صورت Exception خام از طرف لاراول برگشته می‌شود (HTTP 500).

Flowchart

GET /v2/core/accommodation/view

Core Accommodation: View Details

این اندپوینت برای دریافت جزئیات کامل یک هتل در سیستم Core استفاده می‌شود. داده‌ها از جداول اصلی (hotels، countries، states، cities)، جدول mapping_accommodations و جدول media بارگذاری شده و سپس در یک ساختار استاندارد و نرمال‌سازی شده بازگردانده می‌شوند.

Request Overview

Access Control

Request Query Parameters

Hotel Record Loading

جزئیات اولیه هتل از جدول hotels بارگذاری می‌شود:

$item = DB::table('hotels')
    ->where('id', request->id)
    ->first();
  

Country Resolution

کشور با شرط‌های زیر لود می‌شود:

[
  "id" => country.id,
  "icon" => country.iso,
  "title" => [
    "fa" => country.fa_name,
    "en" => country.en_name
  ],
  "nationality" => [
    "fa" => country.fa_nationality,
    "en" => country.en_nationality
  ]
]
  

State Resolution

$state = [
  "id" => state.id,
  "title" => [
    "fa" => state.title_fa,
    "en" => state.title_en
  ]
];
  

City Resolution

$city = [
  "id" => city.id,
  "title" => [
    "fa" => city.title_fa,
    "en" => city.title_en
  ]
];
  

Mapping Resolution

اگر رکورد فعال وجود داشته باشد، فیلدهای null به false تبدیل می‌شوند؛ در غیر این صورت مقدار نهایی false است.

{
  "tport": value or false,
  "sepehr": value or false,
  "snapptrip": value or false,
  "alibaba": value or false,
  "eghamat24": value or false,
  "iranhotelonline": value or false
}
  

Media Resolution

همه مدیاها با شرط‌های زیر لود می‌شوند:

ساختار خروجی نهایی مدیا:

{
  "logo": "/path/to/logo.jpg" or false,
  "media": ["/path/a.jpg","/path/b.jpg"] or false
}
  

Final Response Mapping

ساختار کلی:

{
  "title": {
    "fa": item.fa_title,
    "en": item.en_title
  },
  "type": item.type,
  "rate": item.rate,
  "country": country_object,
  "state": state_object,
  "city": city_object,
  "phone": item.phone,
  "mobile": item.mobile,
  "email": item.email,
  "site": item.site,
  "address": item.address,
  "location": item.location,
  "logo": logo or false,
  "media": media_list or false,
  "details": json_decode(item.details),
  "board": json_decode(item.board),
  "possibilities": json_decode(item.possibilities),
  "leader_name": item.leader_name,
  "leader_mobile": item.leader_mobile,
  "description": item.description,
  "confirm_status": item.confirm_status,
  "priority": item.priority,
  "mapping": mapping_object or false,
  "status": item.status
}
  

Response (Success)

{
  "status": true,
  "time": 1710000000,
  "data": { ... }
}
  

Response (Error)

{
  "status": false,
  "code": "1003",
  "message": "Exception message",
  "trace": [...]
}
  

Flowchart

POST /v2/core/system/report

Core System: Add System Report

این اندپوینت برای ثبت گزارش سیستمی (System Report) در بخش Core استفاده می‌شود. داده‌ها به متد Visa::AddSystemReport() ارسال شده و پس از ثبت، یک کد رهگیری (tracking_code) تولید و برگردانده می‌شود.

Request Overview

Access Control

Request Body Schema

Core Processing Logic

ورودی‌ها مستقیماً وارد سرویس ثبت گزارش می‌شوند:

$insert = Visa::AddSystemReport(
    $request->get('data'),
    $request->get('operator')->id
);
  

Response (Success)

کد وضعیت HTTP: 201 Created

{
  "payload": {
    "tracking_code": "ABC123456"
  },
  "meta": {
    "timestamp": 1710000000
  }
}
  

Response (Error)

در این متد هیچ try/catch وجود ندارد، بنابراین هرگونه Exception از طرف Visa::AddSystemReport یا دیتابیس → خطای 500 بازگشت داده می‌شود.

Flowchart

GET /v2/charter (Multi‑Mode Charter Loader)

Charter: Get Charter(s) Details

این اندپوینت، هسته اصلی بازیابی اطلاعات چارترهاست. بسته به ورودی، می‌تواند یک چارتر واحد را برگرداند، یا چندین چارتر را به‌صورت آرایه، و همچنین بسته به مقدار action می‌تواند چهار سطح مختلف از داده‌ها را برگرداند: all / list / base / calculations / capacity. این Endpoint از کلاس پیچیده CharterResource استفاده می‌کند که شامل غنی‌سازی بسیار سنگین دیتاست.

Request Overview

Behavior Summary

Query Parameters

Single Charter Mode

if (is_numeric($request->id)) {
    $charter = DB::table('charters')->where('id', $request->id)->first();
}
  

اگر یافت نشود:

{
  "status": false,
  "time": 1710000000,
  "message": "item not found!"
}
  

Multiple Charter Mode

$charters = DB::table('charters')->whereIn('id', $request->id)->get();
  

همه رکوردها map می‌شوند:

$charters->map(fn($item) => new CharterResource($item))
  

CharterResource Overview

این کلاس بسیار بزرگ مسئول تبدیل رکورد دیتابیس به ساختارهای کامل، شامل اطلاعات اپراتور، محاسبات، قوانین، آیتم‌ها، ظرفیت رزرو، ویژگی‌ها، و ده‌ها نوع داده متفاوت دیگر است.

Modes (action)

Shared Data Loaders (Resource Level)

sortItems() Logic

این تابع یکی از سنگین‌ترین بخش‌هاست و بسته به method/submethod آیتم دیتا را enrich می‌کند:

جزئیات شامل:

sortCalculations() Logic

این قسمت شامل:

getInformation() Logic

بسته به type → title و blocks متفاوت تولید می‌کند. مقادیر در Redis کش می‌شوند تحت کلید:

charter:{id}:information:title
  

Response Structure (Single Charter, action=all)

{
  "status": true,
  "time": 1710000000,
  "data": {
     "id": 123,
     "serial": 10000 + serial,
     "title": { fa, en },
     "type": "...",
     "subtype": "...",
     "capacity": ...,
     "buy": ...,
     "deadline": ...,
     "information": {...},
     "reservation": {...},
     "calculations": [...],
     "rules": { refund: [...], public: [...] },
     "operator": {...},
     "items": [...],
     "details": {...},
     "plan": ...,
     "slug": ...,
     "hub": ...,
     "schedule": {...} | false,
     "status": ...
  }
}
  

Error Response

{
  "status": false,
  "time": 1710000000,
  "message": "item not found!"
}
  

Flowchart

POST /v2/charter

Charter: Create Inventory (Store)

این اندپوینت قلب تپنده سیستم تعریف موجودی (Inventory) است. وظیفه آن دریافت یک الگوی زمانی و قیمتی، و تبدیل آن به صدها رکورد فیزیکی در دیتابیس است. این متد از یک Replication Engine داخلی استفاده می‌کند تا تاریخ‌های پرواز یا رزرو هتل را بر اساس الگوهای هفتگی، دوره‌ای یا تاریخ‌های خاص تولید کرده و تمام وابستگی‌های مالی و قانونی را در قالب تراکنش‌های اتمیک ذخیره کند.

Request Overview

Key Features & Behavior

Payload Schema (Root Level)

Logic 1: Route & Object Resolution

سیستم ابتدا داده‌های ورودی را نرمال‌سازی می‌کند:

IF type == 'route':
   IF subtype == 'aircraft':
       Origin/Dest IDs -> Look up 'airports' table -> Fetch City Name
   ELSE (train/bus):
       Origin/Dest IDs -> Used directly as City Name

IF type == 'accommodation':
   Object -> Hotel ID -> Look up 'hotels' table -> Fetch City Name
   Origin = Destination = City Name
   Start/End Time -> Set strictly to 00:00:00 / 23:59:59
  

Logic 2: Outbound Handling (Round Trip)

اگر در اولین آیتم آرایه items، کلید outbound وجود داشته باشد:

Logic 3: The Replication Engine

متغیر کلیدی $charterDates بر اساس آبجکت repeat پر می‌شود. این بخش هوشمند سیستم است:

Type: Dates (Manual)

{ "type": "dates", "dates": ["2024-01-01", "2024-01-05"] }
// دقیقاً برای همین تاریخ‌ها رکورد تولید می‌شود.
  

Type: Weekly (Pattern)

{
  "type": "weekly",
  "days": [1, 3, 5], // 1=شنبه, 3=دوشنبه ...
  "from": "2024-01-01",
  "to": "2024-03-01"
}
// حلقه روی بازه زمانی می‌چرخد و روزهای هفته شمسی را چک می‌کند.
  

Type: Periodic (Interval)

{
  "type": "periodic",
  "repeat_day": 2, // یک روز در میان
  "from": "...", "to": "..."
}
  

Logic 4: Financial Calculations

داده‌های مالی در جداول جداگانه بر اساس type ذخیره می‌شوند. همچنین جداول واسط زیر پر می‌شوند:

Execution Flowchart

Response Example

// Success
{
    "status": true,
    "time": 1715432100
}

// Error (Exception handled)
{
    "status": false,
    "time": 1715432105,
    "message": "SQL Error: Column 'x' not found...",
    "trace": [...]
}
  

PUT /v2/charter

Charter: Update Inventory (Operation)

این اندپوینت مسئول مدیریت تغییرات یک چارتر ثبت‌شده است. این متد یک Action Dispatcher داخلی دارد که بر اساس مقدار action درخواست را به یکی از سه رفتار مستقل هدایت می‌کند: base، calculations و copy. این عملیات‌ها اتمیک و تحت تراکنش انجام می‌شوند و سیستم از Capacity Protection برای جلوگیری از تناقض ظرفیت و فروش استفاده می‌کند.

Request Overview

Key Features & Behavior

Payload Schema (Root Level)

Logic 1: Base Operation

این حالت برای ویرایش اطلاعات عمومی چارتر استفاده می‌شود.

// Capacity Guard Example
$cap = CharterHelper::capacityItemCharter($id);
if ($new_capacity < $cap['reserved_total']) {
    throw new Exception("New capacity cannot be lower than sold seats.");
}
  

Logic 2: Calculations Operation

مدیریت کلاس‌های نرخی، قیمت‌ها، ظرفیت اتاق‌ها، مالیات‌ها و قوانین کنسلی.

{
  "action": "calculations",
  "main_id": 150,
  "items": [
    {
      "mode": "update",
      "id": 455,
      "price": 3200000,
      "capacity": 12,
      "taxes": [{ "amount": 10000, "description": "Tax" }],
      "rules": [{ "percent": 30, "from_time": 0, "to_time": 12 }]
    }
  ]
}
  

Logic 3: Copy Operation

عملیات کپی یک چارتر شامل:

{
  "action": "copy",
  "id": 150
}
  

Execution Flowchart

Response Example

// Success
{
  "status": true,
  "data": { "id": 150, "status": true }
}

// Error
{
  "status": false,
  "message": "Capacity cannot be less than sold seats"
}
  

`

PATCH /v2/charter (updateCharter)

Charter: Update Charter (Status / Sell)

این اندپوینت جهت تغییر وضعیت کلی چارتر (Status) و یا مدیریت وضعیت فروش (Sell) برای همکاران و HUB طراحی شده است. این متد برخلاف ویرایش کامل، عملیات سبک‌تری انجام می‌دهد اما قوانین سخت‌گیرانه‌ای برای حذف (Delete) دارد.

Request Overview

Access Control

Request Parameters

Logic: Action "status"

برای تغییر وضعیت چارتر (فعال/غیرفعال/حذف) استفاده می‌شود.

Logic: Action "sell"

برای کنترل سوئیچ‌های فروش استفاده می‌شود.

Response (Success)

در صورت موفقیت، هیچ محتوایی برگردانده نمی‌شود (HTTP 204).

HTTP/1.1 204 No Content
  

Response (Error)

// Error: Deletion failed due to existing reservations
{
  "error": {
    "code": 1000,
    "message": "بر روی این چارتر رزرو انجام شده است و امکان حذف وجود ندارد."
  }
}

// Error: Charter Not Found
{
  "error": {
    "code": 1000,
    "message": "چارتر مورد نظر یافت نشد."
  }
}
  

Flowchart

DELETE /v2/charter

Charter: Delete (Soft Deactivate)

این اندپوینت مسئول حذف نرم (Soft Delete) یا غیرفعال‌سازی یک چارتر است. توجه داشته باشید که این متد رکورد را از دیتابیس پاک نمی‌کند، بلکه وضعیت (Status) آن را به مقدار 2 تغییر می‌دهد (که معمولاً به معنای غیرفعال یا بایگانی است).

Request Overview

Access Control

Request Parameters

Logic Details

Response (Success)

{
  "status": true,
  "time": 1710000000
}
  

Response (Exception Error)

{
  "status": false,
  "time": 1710000000,
  "message": "SQLSTATE[...]: Integrity constraint violation...",
  "trace": [...]
}
  

Flowchart

GET /v2/charter/list

Charter: List & Search

این اندپوینت جهت دریافت لیست چارترها با قابلیت فیلتر کردن پیشرفته، جستجو بر اساس تاریخ (با منطق متفاوت برای اقامتگاه و پرواز)، مسیرهای دوطرفه و وضعیت‌های مختلف استفاده می‌شود.

Request Overview

Access Control

Request Parameters (Query String)

کلیه پارامترها به صورت Query Param ارسال می‌شوند.

Complex Logic Details

۱. منطق تاریخ (Date Logic)

۲. جستجوی دوطرفه (Roundtrip)

اگر advanced[roundtrip] برابر true باشد و مبدا و مقصد مشخص شده باشند، کوئری به صورت OR اجرا می‌شود:
(مبدا = Origin AND مقصد = Dest) یا (مبدا = Dest AND مقصد = Origin).

۳. صفحه‌بندی و مرتب‌سازی

Response (Success)

{
  "items": [
    {
      "id": 10050,
      "serial": "CHR-123",
      "type": "flight",
      "origin": "THR",
      "destination": "MHD",
      "start": "2024-05-20 10:00:00",
      "status": 1,
      // ... other resource fields
    }
  ],
  "meta": {
    "timestamp": 1715000000,
    "table": {
      "total": 150
    }
  }
}
  

Flowchart

GET /v2/charter/communications

Charter: List Communications

این اندپوینت لیست "ارتباطات" (Communications) تعریف شده بین چارترها را برمی‌گرداند. این جدول معمولاً برای تعریف مسیرهای متصل (Connecting Flights) یا ارتباط بین یک چارتر اصلی و چارترهای وابسته استفاده می‌شود. خروجی شامل دو بخش اصلی src (چارتر مبدا) و dst (چارتر مقصد/متصل) است.

Request Overview

Access Control

Request Parameters

Logic Details

۱. فیلتر هوشمند مبدا و مقصد

این متد مستقیماً روی جدول charter_communications جستجو نمی‌کند، بلکه ابتدا شناسه‌های معتبر را از جدول charters استخراج می‌کند:

۲. غنی‌سازی داده‌ها (Data Enrichment)

پس از دریافت لیست خام ارتباطات، برای هر رکورد توابع زیر صدا زده می‌شوند تا جزئیات کامل برگردانده شود:

Response Structure

{
  "items": {
    "communication": [
      {
        "id": 501,
        "title": "Tehran to Mashhad (Connection)",
        "src": {
          "main": {
             "id": 100,
             "type": "route",
             "subtype": "aircraft",
             "information": { "origin": 1, "destination": 2, ... },
             "calculations": [...]
          },
          "item": {
             "class": { "iata": "Y", "title_en": "Economy", ... }
          },
          "type": "system" // source_type
        },
        "dst": {
          "main": { ... }, // اطلاعات چارتر دوم
          "item": { ... }, // اطلاعات کلاس چارتر دوم
          "type": "charter" // destination_type
        }
      }
    ]
  },
  "meta": {
    "timestamp": 1715000000,
    "table": { "total": 10, ... }
  }
}
  

Flowchart

GET /v2/charter/reservation/{type}

Charter: List Reservations & Reports

این اندپوینت لیست رزروها را بر اساس type (نوع گزارش) فیلتر می‌کند. این متد قلب تپنده گزارش‌گیری سیستم چارتر است و حالت‌های مختلفی از جمله رزروهای قطعی، موقت (لاگین شده)، استردادی و نمای گرافیکی "Plan" (مخصوص هتل) را پوشش می‌دهد.

Request Overview

Access Control

Request Parameters

Path Parameters

Query Parameters

Logic Details

۱. منطق فیلتر Definite (رزروهای قطعی)

در این حالت، سیستم رزروهایی که refund_id ندارند و حذف نشده‌اند را برمی‌گرداند. منطق تاریخ بر اساس report_type متغیر است:

۲. منطق Temporary (رزروهای موقت)

این بخش رکوردهایی را از جدول charter_temporary_reservation می‌خواند که هنوز منقضی نشده‌اند.
شرط انقضا: created_at + duration > NOW()

۳. منطق Plan (نمای تقویم اقامتگاه)

این حالت پیچیده‌ترین بخش است و داده‌ها را از ۴ منبع تجمیع می‌کند. اگر نوع چارتر accommodation نباشد، خطای 409 برمی‌گرداند.

POST /v2/charter/reservation

Charter: Insert Bulk Reservations

این اندپوینت برای ایجاد یک یا چند رزرو به صورت همزمان طراحی شده است. ورودی اصلی آن آرایه‌ای از مسافران است. سیستم ابتدا تمام مسافران را اعتبارسنجی کرده، سپس ظرفیت را بررسی می‌کند و در نهایت رزروها را ایجاد می‌کند. این متد بین چارترهای مسیرمحور (مانند پرواز) و اقامتگاهی (هتل) تمایز قائل می‌شود.

Request Overview

Access Control

Request Body (JSON)

ساختار آبجکت Passenger

Logic Details

۱. اعتبارسنجی گسترده

پیش از هر اقدامی، سیستم تمام مسافران موجود در آرایه passengers را بررسی می‌کند. در صورت وجود اولین خطا، عملیات متوقف و کد خطای 422 Unprocessable Entity بازگردانده می‌شود.

۲. بررسی ظرفیت

پس از اعتبارسنجی، سیستم تعداد مسافران بزرگسال و کودک را شمارش کرده و با ظرفیت باقی‌مانده آیتم مقایسه می‌کند.
اگر ظرفیت کافی نباشد، عملیات متوقف و کد خطای 409 Conflict به همراه پیام "ظرفیت تکمیل است" (کد 1008) بازگردانده می‌شود.

۳. تفاوت منطق Route و Accommodation

هسته اصلی این متد بر اساس نوع چارتر عمل می‌کند:

۴. محاسبه مالی و ثبت

برای هر رزرو، اگر آبجکت financial در اطلاعات مسافر ارسال شده باشد، قیمت‌ها به صورت دستی ثبت می‌شوند. در غیر این صورت، سیستم با استفاده از financialCalculation قیمت نهایی را بر اساس قوانین قیمت‌گذاری (پله‌ای، کارمزد، مارکاپ) محاسبه می‌کند. در نهایت، برای هر رزرو موفق، یک PNR محلی و یک شناسه یکتا تولید و در دیتابیس ذخیره می‌شود.

Response Structure

پاسخ موفق

در صورت موفقیت، کد 201 Created به همراه آرایه‌ای از نتایج بازگردانده می‌شود. این آرایه می‌تواند شامل آیتم‌های موفق و ناموفق (مثلاً مسافر تکراری) باشد.

{
  "items": [
    {
      "status": true,
      "pnr": {
        "local": "XG7H5A2B", // PNR مشترک برای این بچ
        "original": "K9L4M1N0", // Slug یکتای این رزرو
        "id": 10845        // شناسه رزرو + 10000
      },
      // این بخش فقط برای رزرو اقامتگاه وجود دارد
      "accommodation_rooms": [
        {
          "reservation_id": 10845,
          "room_id": 10021,
          "date": "2025-12-25",
          "number": "205"
        }
      ]
    },
    {
      "status": false,
      "item_id": 45,
      "details": "0012345678",
      "code": 1010,
      "message": "برای این مسافر قبلا این آیتم خریداری شده است.",
      "solution": "..."
    }
  ],
  "meta": { "timestamp": 1715000000 }
}
  

Flowchart

PUT /v2/charter/reservation

Charter: Update Reservation(s)

این اندپوینت دو قابلیت مجزا اما مرتبط را فراهم می‌کند. بسته به پارامتر apply_all، می‌توان یک رزرو خاص را با تمام جزئیاتش به‌روزرسانی کرد، یا فقط اطلاعات مالی (مبلغ) را برای تمام رزروهای فعال یک چارتر به صورت یکجا تغییر داد. این متد برای اصلاح اطلاعات مسافر یا اعمال تغییرات قیمت کلی بسیار کاربردی است.

Request Overview

Access Control

Request Body (JSON)

ساختار بدنه درخواست بسته به مقدار فیلد apply_all متفاوت است.

Logic Details

این متد بر اساس فیلد apply_all به دو شاخه منطقی اصلی تقسیم می‌شود:

۱. حالت به‌روزرسانی تکی (apply_all: false)

این حالت پیش‌فرض است و برای ویرایش جزئیات یک رزرو مشخص به کار می‌رود.

۲. حالت به‌روزرسانی گروهی (apply_all: true)

این حالت برای تغییر یکپارچه قیمت تمام رزروهای یک چارتر استفاده می‌شود.

Response Structure

پاسخ موفق

در صورت موفقیت‌آمیز بودن هر یک از دو حالت، سرور یک پاسخ خالی با کد وضعیت 204 No Content باز می‌گرداند که به معنای انجام موفقیت‌آمیز عملیات بدون نیاز به بازگرداندن محتوا است.

پاسخ‌های خطا

Flowchart

DELETE /v2/charter/reservation

Charter: Soft Delete Reservation(s)

این اندپوینت برای حذف نرم (soft delete) یک یا چند رزرو به صورت همزمان طراحی شده است. عملیات حذف به صورت فیزیکی رکوردها را از پایگاه داده پاک نمی‌کند، بلکه وضعیت (status) آن‌ها را به 2 (حذف شده) تغییر داده و فیلد deleted_at را با زمان فعلی پر می‌کند. این متد همچنین رزرو اتاق‌های مرتبط با چارترهای اقامتی را نیز مدیریت می‌کند.

Request Overview

Access Control

Request Body (JSON)

Logic Details

فرآیند حذف در دو مرحله کلیدی انجام می‌شود تا از هماهنگی داده‌ها اطمینان حاصل شود:

۱. به‌روزرسانی جدول اصلی رزروها

ابتدا، سیستم با استفاده از پارامتر type، نام جدول مربوط به رزروها (مثلاً charter_reservation_route) را از طریق متد getTableCharter به دست می‌آورد. سپس یک دستور UPDATE گروهی اجرا می‌کند که تمام رکوردهای موجود در آرایه reserves_id را پیدا کرده و فیلدهای زیر را در آن‌ها به‌روزرسانی می‌کند:

۲. به‌روزرسانی جدول اتاق‌های اقامتی

بلافاصله پس از مرحله اول، یک دستور UPDATE دیگر بر روی جدول charter_reservation_accommodation_rooms اجرا می‌شود. این عملیات نیز تمام رکوردهایی را که reservation_id آن‌ها در آرایه reserves_id وجود دارد، پیدا کرده و آن‌ها را نیز به صورت نرم حذف می‌کند (status=2 و deleted_at=now()).

نکته مهم: این مرحله دوم همیشه اجرا می‌شود، حتی اگر نوع چارتر route باشد. در این حالت، چون هیچ رکوردی در جدول اتاق‌ها با شناسه‌های رزرو پرواز مطابقت ندارد، این دستور تأثیری نخواهد داشت، اما وجود آن برای مدیریت صحیح رزروهای اقامتی ضروری است.

Response Structure

پاسخ موفق

اگر هر دو عملیات به‌روزرسانی با موفقیت انجام شوند، سرور یک پاسخ خالی با کد وضعیت 204 No Content باز می‌گرداند. این نشان می‌دهد که درخواست با موفقیت پردازش شده و نیازی به بازگرداندن محتوا نیست.

پاسخ خطا

در صورت بروز هرگونه استثنا (Exception) در حین اجرای عملیات پایگاه داده، سرور با کد 400 Bad Request پاسخ می‌دهد. بدنه پاسخ شامل یک آبجکت خطا با جزئیاتی مانند کد خطا، پیام و ردپای آن (trace) برای کمک به فرآیند اشکال‌زدایی خواهد بود.

Flowchart

PATCH /v2/charter/reservation/undo

Charter: Undo Reservation Deletion

این اندپوینت برای بازگردانی یک رزرو که قبلاً به صورت نرم (soft delete) حذف شده است، استفاده می‌شود. عملیات اصلی، تغییر وضعیت (status) رزرو از 2 (حذف شده) به 1 (قطعی) و پاک کردن مقدار فیلد deleted_at است. نکته بسیار مهم در این فرآیند، بررسی مجدد ظرفیت خالی قبل از بازگردانی است که دارای منطق متفاوتی برای مسافران نوزاد و غیرنوزاد می‌باشد.

Request Overview

Access Control

Request Body (JSON)

Logic Details

فرآیند بازگردانی با یک بررسی ظرفیت حیاتی همراه است تا از فروش بیش از حد جلوگیری شود.

۱. یافتن رزرو و بررسی اولیه

ابتدا سیستم با استفاده از main_id و reserves_id، رکورد رزرو حذف شده را از جدول مربوطه پیدا می‌کند. اگر رکوردی یافت نشود، یک خطای عمومی رخ داده و پاسخ 400 بازگردانده می‌شود.

۲. بررسی ظرفیت (Capacity Check)

این مهم‌ترین بخش منطق است. سیستم متد ReservationController::capacityItemCharter را فراخوانی می‌کند تا ظرفیت باقی‌مانده واقعی را محاسبه کند. این متد با کسر کردن رزروهای قطعی، گارانتی و قفل‌های موقت از ظرفیت کل، عدد نهایی را به دست می‌آورد. سپس، یک شرط بر اساس نوع مسافر اعمال می‌شود:

۳. عملیات پایگاه داده

 

 

Response Structure

پاسخ موفق

اگر بازگردانی با موفقیت انجام شود، سرور یک پاسخ خالی با کد وضعیت 204 No Content ارسال می‌کند.

پاسخ‌های خطا

Flowchart

PUT /v2/charter/reservation/transfer

Charter: Transfer Reservations

این اندپوینت یک قابلیت مدیریتی قدرتمند برای انتقال یک یا چند رزرو از یک چارتر/آیتم به چارتر/آیتم دیگر فراهم می‌کند. فرآیند انتقال تنها در صورتی انجام می‌شود که چارتر مقصد ظرفیت کافی برای پذیرش تمام رزروهای درخواستی را داشته باشد. این عملیات برای جابجایی مسافران بین پروازها یا اتاق‌های مختلف بسیار کاربردی است.

Request Overview

Access Control

Request Body (JSON)

Logic Details

منطق اصلی این اندپوینت بر پایه یک بررسی ظرفیت و سپس اجرای یک سری به‌روزرسانی‌های متوالی استوار است.

۱. بررسی ظرفیت مقصد

اولین و مهم‌ترین گام، فراخوانی متد ReservationController::capacityItemCharter برای چارتر و آیتم مقصد (goal.main_id و goal.item_id) است. این متد ظرفیت کل را محاسبه کرده و تعداد رزروهای قطعی، گارانتی و قفل‌های موقت را از آن کم می‌کند تا ظرفیت باقی‌مانده واقعی (balance) را به دست آورد.

۲. تصمیم‌گیری بر اساس ظرفیت

سپس، سیستم ظرفیت باقی‌مانده ($capacity['balance']) را با تعداد رزروهایی که قرار است منتقل شوند (count($request->items)) مقایسه می‌کند.

Response Structure

پاسخ موفق

در صورتی که ظرفیت کافی باشد و تمام عملیات‌های به‌روزرسانی با موفقیت انجام شوند، سرور یک پاسخ خالی با کد وضعیت 204 No Content باز می‌گرداند.

پاسخ‌های خطا

Flowchart

PATCH /character/reservation/refund

Charter: Process Reservation Refund

این اندپوینت برای پردازش بازپرداخت (Refund) برای یک یا چند رزرو قطعی (`status=1`) طراحی شده است. فرآیند شامل محاسبه جریمه (به صورت درصدی یا مبلغ ثابت)، به‌روزرسانی اطلاعات مالی رزرو، ثبت رکورد بازپرداخت در جدول مجزا، و در نهایت تغییر وضعیت رزرو به "مسترد شده" (`status=3`) است. این عملیات به صورت دسته‌ای (batch) برای لیستی از رزروها قابل اجراست.

Request Overview

Access Control

Request Body (JSON)

Logic Details

منطق این اندپوینت در دو فاز اصلی اجرا می‌شود: فاز اعتبارسنجی و آماده‌سازی، و فاز اجرای تغییرات در پایگاه داده.

فاز ۱: اعتبارسنجی و محاسبه جریمه (در یک حلقه)

سیستم در یک حلقه، هر شناسه رزرو ارسال شده در آرایه items را پردازش می‌کند:

نکته مهم: اعتبارسنجی به صورت متوالی انجام می‌شود. در صورت بروز خطا برای هر یک از آیتم‌ها، کل فرآیند متوقف شده و هیچ تغییری در پایگاه داده اعمال نمی‌گردد.

فاز ۲: اجرای تغییرات در پایگاه داده

اگر فاز اول برای تمام آیتم‌ها بدون خطا به پایان برسد و حداقل یک آیتم معتبر برای استرداد وجود داشته باشد، سیستم وارد این فاز می‌شود:

Response Structure

پاسخ موفق

در صورتی که تمام عملیات با موفقیت انجام شود (حتی اگر هیچ آیتم معتبری برای استرداد وجود نداشته باشد)، سرور یک پاسخ خالی با کد وضعیت 204 No Content باز می‌گرداند.

پاسخ‌های خطا

Flowchart

PATCH /v2/charter/reservation/refund/undo

Charter: Undo Reservation Refund

این اندپوینت برای لغو عملیات استرداد یک رزرو خاص و بازگرداندن آن به وضعیت "قطعی" (`status = 1`) استفاده می‌شود. قبل از بازگردانی، سیستم ظرفیت آیتم مربوطه (پرواز یا اتاق) را بررسی می‌کند. یک منطق خاص برای نوزادان (infant) وجود دارد که بازگردانی رزرو آن‌ها تنها در صورت وجود حداقل یک ظرفیت خالی امکان‌پذیر است، در حالی که برای بزرگسالان و کودکان این بررسی ظرفیت اعمال نمی‌شود.

Request Overview

Access Control

Request Body (JSON)

Logic Details

فرآیند لغو استرداد شامل سه گام اصلی است: دریافت اطلاعات، بررسی ظرفیت، و اجرای به‌روزرسانی‌ها.

۱. دریافت اطلاعات رزرو

با استفاده از main_id و reserve_id ارسالی، سیستم ابتدا رکورد کامل رزرو مورد نظر را از جدول مربوطه (charter_route_reservations یا charter_accommodation_reservations) استخراج می‌کند. اگر رزرو یافت نشود، یک استثنا (Exception) رخ داده و عملیات متوقف می‌شود.

۲. بررسی ظرفیت (Capacity Check)

این مهم‌ترین بخش منطق است.

۳. اجرای عملیات

Response Structure

پاسخ موفق

در صورتی که عملیات با موفقیت انجام شود، سرور یک پاسخ خالی با کد وضعیت 204 No Content باز می‌گرداند.

پاسخ‌های خطا

Flowchart

DELETE /v2/charter/reservation/temporary

Charter: Soft Delete Temporary Reservation

این اندپوینت برای حذف نرم (soft-delete) یک رزرو موقت از سیستم استفاده می‌شود. رزروهای موقت در جدول جداگانه‌ای به نام charter_temporary_reservation نگهداری می‌شوند. این عملیات رکورد را به طور کامل از پایگاه داده حذف نمی‌کند، بلکه فقط ستون status آن را به مقدار 2 (به معنای لغو شده یا حذف شده) تغییر می‌دهد تا در پردازش‌های بعدی نادیده گرفته شود.

Request Overview

Access Control

Request Parameters

شناسه رزرو موقت باید به عنوان یک پارامتر کوئری (Query Parameter) در URL ارسال شود.

Example URL

Logic Details

فرآیند این اندپوینت بسیار ساده و سرراست است و در یک بلوک try...catch برای مدیریت خطاهای احتمالی پایگاه داده محصور شده است.

۱. اجرای عملیات حذف نرم (Soft Delete)

۲. مدیریت خطا

Response Structure

برخلاف بسیاری از اندپوینت‌های RESTful که در پاسخ به متد DELETE موفق، کد وضعیت 204 No Content را برمی‌گردانند، این اندپوینت همیشه یک بدنه پاسخ (JSON) با کد وضعیت 200 OK باز می‌گرداند. وضعیت موفقیت یا شکست عملیات از طریق فیلد status در بدنه JSON مشخص می‌شود.

پاسخ موفق

در صورتی که کوئری UPDATE بدون خطا اجرا شود (حتی اگر هیچ رکوردی برای به‌روزرسانی پیدا نشود)، پاسخ زیر بازگردانده می‌شود.

پاسخ خطا

در صورت بروز هرگونه استثنا (Exception) در سطح پایگاه داده، پاسخ زیر بازگردانده می‌شود.

Flowchart

POST /v2/charter/reservation/temporary

Charter: Create Temporary Reservation (Lock)

این اندپوینت برای ایجاد یک "رزرو موقت" یا "قفل" روی ظرفیت یک آیتم چارتر (مانند صندلی پرواز یا اتاق هتل) برای یک مدت زمان مشخص (به دقیقه) طراحی شده است. هدف اصلی آن جلوگیری از فروش همزمان یک ظرفیت توسط چند کاربر است. منطق این اندپوینت بر اساس نوع چارتر (`type`) به دو شاخه اصلی تقسیم می‌شود: اقامتگاهی (`accommodation`) و غیر اقامتگاهی (مانند مسیر `route`).

Request Overview

Access Control

Request Body (JSON)

ساختار بدنه درخواست شامل اطلاعات عمومی قفل و دو شیء کلیدی requester و capacity است که ساختار capacity بسته به نوع چارتر متفاوت است.

ساختار شیء `capacity`

- برای چارترهای غیر اقامتگاهی (`route`, ...):

{
  "capacity": {
    "adult": 2,
    "child": 1,
    "infant": 0
  }
}

- برای چارترهای اقامتگاهی (`accommodation`):

{
  "capacity": {
    "room": 3
  }
}

Logic Details

پس از دریافت درخواست، سیستم ابتدا نوع چارتر را با کوئری زدن به جدول charters از روی main_id تشخیص می‌دهد. سپس منطق بر اساس نوع چارتر اجرا می‌شود.

۱. منطق برای چارتر اقامتگاهی (Accommodation)

این حالت پیچیده‌تر است و نیازمند بررسی دقیق ظرفیت اتاق‌ها در بازه زمانی مشخص است.

۲. منطق برای چارتر غیر اقامتگاهی (Route)

این حالت بسیار ساده‌تر است و مبتنی بر اعتماد به درخواست‌دهنده است.

Response Structure

مشابه اندپوینت قبلی، این API نیز در همه موارد (موفقیت یا شکست) کد وضعیت 200 OK را به همراه یک بدنه JSON برمی‌گرداند.

پاسخ موفق (چارتر اقامتگاهی)

پاسخ موفق (چارتر غیر اقامتگاهی)

پاسخ خطا (ظرفیت ناکافی در چارتر اقامتگاهی)

پاسخ خطا (استثنای عمومی)

Flowchart

POST /v2/charter/reservation/plan/update

Charter: Update Accommodation Reservation Room Plan

این اندپوینت برای تغییر چینش اتاق‌های تخصیص داده شده به یک رزرو اقامتگاهی موجود استفاده می‌شود. کاربرد اصلی آن این است که به اپراتور اجازه می‌دهد اتاق فیزیکی (`room_id`) مربوط به یک یا چند تاریخ (`date`) خاص از یک رزرو (`reservation_id`) را تغییر دهد. برای مثال، اگر یک رزرو برای سه شب در اتاق ۱۰۱ ثبت شده، می‌توان با استفاده از این اندپوینت، شب دوم اقامت را به اتاق ۱۰۵ منتقل کرد.
نکته مهم تجاری: شناسه‌های ورودی (id و room_id) شناسه‌های عمومی هستند و سیستم به صورت داخلی عدد 10,000 را از آن‌ها کم می‌کند تا به شناسه‌های واقعی در پایگاه داده دسترسی پیدا کند.

Request Overview

Access Control

Request Body (JSON)

بدنه درخواست باید شامل یک فیلد data باشد که آرایه‌ای از اشیاء است. هر شیء در این آرایه نشان‌دهنده یک تغییر در تخصیص اتاق برای یک تاریخ مشخص است.

ساختار شیء در آرایه `data`

Example Request Body

در مثال زیر، برای رزرو با شناسه عمومی 10123، اتاق تخصیص داده شده برای تاریخ 2025-10-20 به اتاقی با شناسه عمومی 10055 تغییر می‌کند. همچنین برای همین رزرو، اتاق تاریخ 2025-10-21 به اتاق 10056 منتقل می‌شود.

{
  "data": [
    {
      "id": 10123,
      "date": "2025-10-20",
      "room_id": 10055
    },
    {
      "id": 10123,
      "date": "2025-10-21",
      "room_id": 10056
    }
  ]
}

Logic Details

فرآیند در یک بلوک try...catch برای مدیریت خطاها اجرا می‌شود.

۱. اعتبارسنجی ورودی

۲. پردازش حلقه به‌روزرسانی

۳. مدیریت خطا

Response Structure

پاسخ موفق

در صورتی که تمام دستورات به‌روزرسانی با موفقیت اجرا شوند، سرور یک پاسخ 200 OK با ساختار زیر بازمی‌گرداند.

پاسخ خطا (ورودی نامعتبر)

اگر فیلد data در درخواست ارسال نشود یا خالی باشد.

پاسخ خطا (استثنای عمومی)

در صورت بروز هرگونه خطای پایگاه داده یا خطای دیگر در حین اجرا.

Flowchart

GET /v2/charter/financial

Charter: Get Financial Report

این اندپوینت یک گزارش مالی جامع و تجمیع‌شده برای یک چارتر خاص (با شناسه main_id) تولید می‌کند. هدف اصلی آن، ارائه یک دید کلی از وضعیت فروش، درآمد، هزینه‌ها و بدهی‌ها با سه دسته‌بندی مجزا است:

 

Request Overview

Access Control

Query Parameters

Example Request

GET /v2/charter/financial?id=451

Logic Details

فرآیند تولید گزارش در چندین مرحله و با تجمیع داده‌ها از جداول مختلف انجام می‌شود.

۱. شناسایی جداول و واکشی داده‌های اولیه

۲. ساخت نقشه قیمت خرید (Buy Price Map)

۳. حلقه اصلی و تجمیع داده‌ها

سیستم یک حلقه بر روی تمام رزروهای واکشی شده (`reserves`) اجرا می‌کند و در هر تکرار، عملیات زیر را انجام می‌دهد:

۴. خروجی نهایی

Response Structure

پاسخ موفق

در صورت موفقیت، سرور یک پاسخ 200 OK با ساختار پیچیده زیر بازمی‌گرداند. این ساختار شامل سه بخش اصلی `classes`, `pledgers`, و `warranties` است.

پاسخ خطا

در صورت بروز هرگونه خطا (مانند عدم یافتن چارتر یا خطای دیتابیس) سرور یک پاسخ 400 Bad Request بازمی‌گرداند.

Helper Functions

دو تابع کمکی نقش کلیدی در منطق این اندپوینت دارند:

Functions::getClassName($class, $lang)

این تابع یک کد کلاس پروازی تک حرفی (مانند 'Y', 'C') را به نام کامل و خوانای آن در زبان‌های مختلف (en, fa, ar) تبدیل می‌کند.

ReservationController::priceHandle($price, $values)

این تابع برای محاسبه مقدار پولی مالیات، کمیسیون یا مارکاپ استفاده می‌شود. ورودی آن مبلغ پایه (`price`) و آرایه‌ای از قوانین (`values`) است. هر قانون می‌تواند بر اساس درصد (`percent`) یا یک مبلغ ثابت (`currency`) باشد. تابع مجموع مقادیر محاسبه شده را بازمی‌گرداند.

 0 && $values) {
        foreach ($values as $value) {
            if ($value && isset($value['value'])) { // Direct value structure
                if ($value['value'] > 0) {
                    if ($value['value_type'] == 'percent') {
                        $return += ($price * $value['value']) / 100;
                    } else if ($value['value_type'] == 'currency') {
                        $return += $value['value'];
                    }
                }
            } else { // Nested structure
                foreach ($value as $item) {
                    if (isset($item['value']) && $item['value']) {
                        if ($item['value_type'] == 'percent') {
                            $return += ($price * $item['value']) / 100;
                        } else if ($item['value_type'] == 'currency') {
                            $return += $item['value'];
                        }
                    }
                }
            }
        }
    }
    return $return;
}
  ?>

Flowchart

GET /v2/charter/financial/completion

Charter: Get Completion Financial Report

این اندپوینت برای ارائه یک گزارش تکمیل مالی و تحلیلی از یک چارتر طراحی شده است. این گزارش فراتر از تجمیع ساده داده‌های فروش رفته و با محاسبه شاخص‌های کلیدی عملکرد (KPIs) مانند هزینه کل خرید ظرفیت (Paid)، سود یا زیان (Profit)، و هزینه ظرفیت فروخته‌نشده (Burned)، یک دید ۳۶۰ درجه از وضعیت مالی چارتر ارائه می‌دهد.
خروجی این اندپوینت در چهار بخش اصلی سازماندهی شده است:

 

Request Overview

Access Control

Query Parameters

Example Request

GET /v2/charter/financial/completion?id=451

Logic Details

منطق این اندپوینت در دو فاز اصلی اجرا می‌شود: فاز اول تجمیع داده‌های اولیه و فاز دوم محاسبه شاخص‌های مالی پیشرفته.

فاز اول: واکشی و تجمیع داده‌های اولیه

فاز دوم: محاسبه شاخص‌های سود و زیان ( حلقه دوم)

پس از اتمام حلقه اول و تجمیع داده‌های پایه، یک حلقه دوم روی آرایه تجمیع‌شده return['classes'] اجرا می‌شود تا محاسبات پیشرفته برای هر آیتم انجام شود:

محاسبه نهایی

Response Structure

پاسخ موفق

پاسخ موفق 200 OK حاوی یک شیء `payload` با ساختاری بسیار غنی است که شامل بخش `total` در کنار سه بخش دیگر می‌باشد.

پاسخ خطا

در صورت بروز خطا، پاسخ 400 Bad Request با جزئیات استثنا بازگردانده می‌شود.

Helper Functions

این اندپوینت از همان توابع کمکی اندپوینت قبلی برای ترجمه نام کلاس و محاسبه مقادیر درصدی/ثابت استفاده می‌کند.

Functions::getClassName($class, $lang)

ReservationController::priceHandle($price, $values)

Flowchart

PATCH /v2/charter/financial/completion

Charter: Finalize Completion Financial Report

این اندپوینت برای نهایی‌سازی (Finalization) گزارش مالی تکمیلی یک چارتر طراحی شده است. پس از اینکه یک چارتر به پایان می‌رسد و تمام داده‌های فروش و هزینه‌ها مشخص می‌شود، این اندپوینت فراخوانی می‌شود تا یک "اسنپ‌شات" (Snapshot) از وضعیت مالی نهایی (شامل سود، زیان، هزینه سوخت‌شده و...) تهیه و آن را در پایگاه داده ثبت کند. این عمل معادل "بستن گزارش مالی" برای آن چارتر است و معمولاً پس از آن، امکان تغییر در رزروها یا داده‌های مالی مرتبط با آن چارتر محدود یا مسدود می‌شود.

Request Overview

Access Control

Request Body

برای مشخص کردن اینکه کدام چارتر باید نهایی شود، شناسه اصلی آن باید در بدنه درخواست ارسال گردد.

Example Request

{
  "main_id": 451
}

Logic Details

نکته مهم: کد ارائه شده صرفاً یک ساختار اولیه است. منطق واقعی این اندپوینت بسیار پیچیده‌تر بوده و شامل مراحل زیر خواهد بود:

Response Structure

پاسخ موفق

یک پاسخ موفق به این معنی است که گزارش مالی با موفقیت تولید و بایگانی شده است. طبق استاندارد REST، برای عملیات PATCH یا PUT که منجر به به‌روزرسانی موفقی شده اما بدنه پاسخی برای برگرداندن ندارد، از کد وضعیت 204 استفاده می‌شود.

پاسخ‌های خطا

خطاهای مختلفی ممکن است در این فرآیند رخ دهد:

PHP Implementation

کد زیر یک ساختار اولیه برای این اندپوینت است. منطق اصلی که در بخش "Logic Details" تشریح شد، باید در بلوک try پیاده‌سازی شود.

public function setCompletionFinancialCharter(Request $request)
{
    // Validate that 'main_id' exists in the request body.
    $validated = $request->validate([
        'main_id' => 'required|integer|exists:charter_main,id',
    ]);

    $mainId = $validated['main_id'];

    try {
        // 1. Check if the charter is already finalized.
        $charter = DB::table('charter_main')->where('id', $mainId)->first();
        if ($charter->finalized_at) {
            return response()->json([
                "message" => "Financial report for this charter has already been finalized."
            ], 409); // 409 Conflict
        }

        // 2. Generate the financial completion report data internally.
        // This would call the same logic as the getCompletionFinancialCharter() method.
        $reportData = $this->generateFinancialData($mainId); // Hypothetical internal method

        // 3. Store the snapshot.
        DB::table('charter_financial_snapshots')->insert([
            'charter_main_id' => $mainId,
            'snapshot_data' => json_encode($reportData),
            'finalized_by' => auth()->id(), // Get user ID from JWT
            'created_at' => now(),
            'updated_at' => now()
        ]);

        // 4. Update the main charter record to mark it as finalized.
        DB::table('charter_main')->where('id', $mainId)->update([
            'finalized_at' => now()
        ]);

        // 5. Return success response.
        return response('', 204);

    } catch (Exception $exception) {
        return response()->json([
            "message" => $exception->getMessage(),
            "trace" => $exception->getTrace()
        ], 400);
    }
}
  

POST /v2/charter/warranty

Charter: Manage Warranties (Batch Operation)

این اندپوینت به عنوان یک ابزار مدیریتی جامع برای گارانتی‌های یک چارتر عمل می‌کند. با استفاده از متد POST، این اندپوینت قادر است در یک فراخوانی، لیستی از عملیات ایجاد، به‌روزرسانی و حذف را بر روی گارانتی‌ها انجام دهد. این رویکرد دسته‌ای، نیاز به ارسال درخواست‌های متعدد را از بین برده و مدیریت گارانتی‌ها را بسیار کارآمد می‌کند.
این اندپوینت به خصوص برای چارترهای اقامتگاهی، دارای منطق‌های اعتبارسنجی پیچیده‌ای است تا از تداخل گارانتی با رزروهای موجود جلوگیری کند.

Request Overview

Access Control

Request Body Structure

بدنه درخواست از سه بخش اصلی تشکیل شده است: main_id برای شناسایی چارتر، آرایه warranties برای عملیات ایجاد و به‌روزرسانی، و آرایه deleted برای عملیات حذف.

Structure of a Warranty Object (inside `warranties` array)

Example Request (Create, Update & Delete)

{
  "main_id": 451,
  "warranties": [
    {
      "id": "temp-12345", // CREATE new warranty
      "item_id": 101,
      "guarantor": { "id": 25 },
      "warranty": {
        "adult": { "number": 10, "price": 1200000 },
        "child": { "number": 5, "price": 900000 }
      },
      "status": 1
    },
    {
      "id": 88, // UPDATE existing warranty
      "guarantor": { "id": 26 },
      "warranty": {
        "adult": { "number": 2, "price": 2500000 },
        "child": { "number": 0, "price": 0 }
      },
      "start_date": "2025-12-10",
      "end_date": "2025-12-15",
      "room_id": [ // Add this new room
        { "room_id": 305, "number": "305" }
      ],
      "deleted_room_id": [ // Remove this old room
        { "room_id": 301, "number": "301" }
      ],
      "status": 1
    }
  ],
  "deleted": [92, 95] // DELETE these two warranties
}

Logic Details

منطق این اندپوینت به سه بخش اصلی تقسیم می‌شود که به ترتیب اجرا می‌شوند:

1. پردازش آرایه `warranties` (ایجاد و به‌روزرسانی)

سیستم روی هر آیتم در آرایه warranties حلقه می‌زند و بر اساس وجود یا عدم وجود id عددی، تصمیم به ایجاد یا به‌روزرسانی می‌گیرد.

2. پردازش آرایه `deleted` (حذف)

Response Structure

پاسخ موفق

اگر تمام عملیات‌ها (ایجاد، به‌روزرسانی، حذف) بدون خطا انجام شوند، پاسخ 204 No Content بازگردانده می‌شود.

پاسخ‌های خطا (Conflict)

GET /v2/charter/warranty

Charter: List Warranties

این اندپوینت برای بازیابی لیستی کامل از تمام گارانتی‌های مرتبط با یک چارتر مشخص (main_id) استفاده می‌شود. به ازای هر گارانتی، اطلاعات تکمیلی شامل جزئیات گارانتی‌کننده (همکار) و لیست اتاق‌های اختصاص‌داده‌شده (برای چارترهای اقامتگاهی) نیز بازگردانده می‌شود. این اندپوینت از یک مکانیزم کش (Caching) با استفاده از Redis برای بهینه‌سازی و افزایش سرعت دریافت اطلاعات همکاران بهره می‌برد.

Request Overview

Access Control

Request Parameters (Query String)

این اندپوینت اطلاعات مورد نیاز خود را از طریق Query String دریافت می‌کند.

Example Request

GET /v2/charter/warranty?id=451

Logic Details

فرآیند پردازش درخواست به شرح زیر است:

Response Structure

پاسخ موفق (Success)

در صورت موفقیت، پاسخ 200 OK به همراه یک ساختار JSON استاندارد حاوی لیست گارانتی‌ها بازگردانده می‌شود.

{
  "status": true,
  "time": 1733271000, // Unix Timestamp
  "data": [
    {
      "id": 99,
      "item_id": 102, // شناسه آیتم (مثلا نوع اتاق)
      "guarantor": { // اطلاعات کامل همکار از کش یا دیتابیس
        "id": 25,
        "title_fa": "آژانس مسافرتی بهار",
        "title_en": "Bahar Agency",
        "first_name": "علی",
        "last_name": "رضایی",
        "credit_amount": 50000000,
        "status": 1
      },
      "warranty": {
        "adult": {
          "number": 2,
          "price": 2500000
        },
        "child": {
          "number": 1,
          "price": 1800000
        },
        "infant": {
          "number": 0,
          "price": 0
        }
      },
      "room_id": [ // لیست اتاق های این گارانتی
        {
          "id": 210,
          "warranty_id": 99,
          "room_id": 305
        },
        {
          "id": 211,
          "warranty_id": 99,
          "room_id": 306
        }
      ],
      "sank_cost": 0,
      "service_price": 150000,
      "start_date": "2025-12-10",
      "end_date": "2025-12-15",
      "status": 1
    },
    {
      "id": 88,
      "item_id": 101, // شناسه آیتم (مثلا کلاس پروازی)
      "guarantor": { ... },
      "warranty": { ... },
      "room_id": false, // این گارانتی اقامتگاهی نیست یا اتاقی ندارد
      "sank_cost": 500000,
      "service_price": 0,
      "start_date": null,
      "end_date": null,
      "status": 1
    }
  ]
}

پاسخ خطا (Error)

در صورت بروز هرگونه استثناء (Exception) در سرور، یک پاسخ با ساختار زیر و کد وضعیت (معمولا 200 OK به دلیل مدیریت خطا در کد) بازگردانده می‌شود.
توجه: نمایش trace خطا در محیط پروداکشن توصیه نمی‌شود.

{
    "status": false,
    "time": 1733271000,
    "message": "Error message from the exception.",
    "trace": [ ... ] // Stack trace of the error
}

GET /v2/charter/services/list

Charter: List Service Categories & Services

این اندپوینت برای دریافت لیست دسته‌بندی‌های خدمات چارتر به‌همراه سرویس‌های زیرمجموعه هر دسته استفاده می‌شود. داده‌ها از جداول charter_service_categories و charter_services بارگذاری شده و فقط مواردی که status = 1 دارند بازگردانده می‌شوند.

Request Overview

Access Control

Query Parameters

این اندپوینت هیچ پارامتر ورودی (Query / Body) ندارد.

Response Structure

خروجی موفق شامل کلیدهای زیر است:

Category Object Schema

Service Object Schema

Core Processing Logic

$categories = DB::table('charter_service_categories')
    ->select('id','title_fa','title_en')
    ->where('status', 1)
    ->get();

foreach ($categories as $category) {
    $services = DB::table('charter_services')
        ->select('id','title','type','description')
        ->where('category', $category->id)
        ->where('status', 1)
        ->get();
}
  

Response (Success)

{
  "status": true,
  "time": 1710000000,
  "data": [
    {
      "id": 1,
      "title": {
        "fa": "عنوان فارسی",
        "en": "English Title"
      },
      "services": [
        {
          "id": 100,
          "title": "VIP Lounge",
          "type": "lounge",
          "description": "Access to VIP lounge"
        }
      ]
    }
  ]
}
  

Response (Error)

در صورت Exception (به دلیل وجود try/catch):

{
  "status": false,
  "time": 1710000000,
  "message": "Exception message here",
  "trace": [ ... ]
}
  

Flowchart

GET /v2/charter/flight-rate

Charter: Get Approved Flight Rate

این اندپوینت نرخ مصوب (Approved Flight Rate) میان دو فرودگاه را بر اساس جدول approved_flight_rate بازیابی می‌کند. سیستم ابتدا دقیقاً مسیر origin → destination را جستجو می‌کند و در صورت نبود، مسیر destination → origin را نیز بررسی می‌کند. در صورت نیافتن رکورد، خروجی با مقدارهای پیش‌فرض (0) برگردانده می‌شود.

Request Overview

Access Control

Query Parameters

Database Table Reference

اطلاعات نرخ‌های مصوب از جدول زیر خوانده می‌شود:

Core Processing Logic

$result = DB::table('approved_flight_rate')
    ->where(function ($q) use ($request) {
        $q->where('origin', $request->get('origin'))
          ->where('destination', $request->get('destination'));
    })
    ->orWhere(function ($q) use ($request) {
        $q->where('origin', $request->get('destination'))
          ->where('destination', $request->get('origin'));
    })
    ->first();
  

Response (Success — Found)

در صورتی که رکورد واقعی در جدول موجود باشد:

{
  "status": true,
  "time": 1710000000,
  "data": {
    "origin": 1,
    "destination": 2,
    "least": 850000,
    "most": 1350000,
    "updated_at": "2024-09-12 16:40:55"
  }
}
  

Response (Success — Not Found)

اگر ریتی برای این مسیر ثبت نشده باشد:

{
  "status": true,
  "time": 1710000000,
  "data": {
    "origin": 1,
    "destination": 2,
    "least": 0,
    "most": 0,
    "updated_at": "2025-02-12 14:10:21"
  }
}
  

Response (Error)

در صورت بروز Exception:

{
  "status": false,
  "time": 1710000000,
  "message": "SQLSTATE[HY000]: ...",
  "trace": [ ... ]
}
  

Flowchart

GET /v2/charter/pledger

Charter: List Branch Pledgers

این اندپوینت لیست ضامنین (Pledgers) یک شعبه را از جدول charter_pledgers به همراه اطلاعات همکار (colleague) بازیابی می‌کند. داده‌ها با join روی جدول colleagues enrich شده و خروجی نهایی یک آرایه items با ساختار title.fa و title.en بازمی‌گرداند.

Request Overview

Query Parameters

Database Tables

Table: charter_pledgers

Table: colleagues

Core Processing Logic

$pledgers = DB::table('charter_pledgers')
    ->select(
        'charter_pledgers.id',
        'colleagues.id as colleague_id',
        'colleagues.first_name',
        'colleagues.last_name',
        'colleagues.office',
        'colleagues.office_en',
        'colleagues.status'
    )
    ->where('charter_pledgers.branch', $request->get('branch'))
    ->where('charter_pledgers.status', 1)
    ->where('colleagues.status', 1)
    ->leftJoin('colleagues', 'charter_pledgers.colleague_id', 'colleagues.id')
    ->orderBy('charter_pledgers.id', 'DESC')
    ->get();
  

Output Mapping Logic

$return = $pledgers->map(function ($pledger) {
    return [
        'id' => $pledger->id,
        'colleague_id' => $pledger->colleague_id,
        'title' => [
            'fa' => $pledger->office .
                   ($pledger->last_name != '' 
                     ? ' ' . $pledger->first_name . ' ' . $pledger->last_name 
                     : ""),
            'en' => $pledger->office_en
        ]
    ];
});
  

ساختار title.fa مطابق الگوی زیر ساخته می‌شود:

Response (Success)

{
  "items": [
    {
      "id": 18,
      "colleague_id": 92,
      "title": {
        "fa": "آژانس هرمس علی کاظمی",
        "en": "Hermes Agency"
      }
    }
  ],
  "meta": { "timestamp": 1710000000 }
}
  

Response (Error)

{
  "message": "SQLSTATE[HY000]: ...",
  "trace": [...]
}
  

Flowchart

POST /v2/charter/pledger

pledger: storePledgerCharter

این اندپوینت یک ضامن جدید (Pledger) را برای یک شعبه در جدول charter_pledgers ثبت می‌کند. در صورت موفقیت مقدار خاصی برنمی‌گرداند و تنها وضعیت 201 Created داده می‌شود.

Request Body

Controller Logic

public function storePledgerCharter(Request $request)
{
    try {
        $insert = [
            'branch' => $request->get('branch'),
            'colleague_id' => $request->colleague_id,
        ];

        DB::table('charter_pledgers')->insert($insert);

        return response('', 201);

    } catch (Exception $exception) {
        return response()->json([
            "message" => $exception->getMessage(),
            "trace" => $exception->getTrace()
        ], 400);
    }
}
  

Table: charter_pledgers

Success Response

Status: 201 Created
Body:   (empty)
  

Error Response

Status: 400 Bad Request

{
  "message": "SQLSTATE[23000]: ...",
  "trace": [...]
}
  

Flowchart

POST /v2/charter/accommodation/rooms

rooms: getCharterAccommodationRooms

این اندپوینت برای دریافت لیست اتاق‌های اقامتگاه (Accommodation Rooms) مرتبط با یک محاسبه calculation_id استفاده می‌شود. مقدار calculation_id ابتدا اصلاح شده و از جدول مرتبط واکشی می‌گردد. فقط زمانی پاسخ معتبر برگردانده می‌شود که چارتر از نوع accommodation باشد.

Request Body

Controller Logic

static function getCharterAccommodationRooms(Request $request)
{
    try {
        if (isset($request->calculation_id) && $request->calculation_id) {

            $calculationId = $request->calculation_id - 10000;

            $calculation = DB::table('charter_calculations_accommodation')
                ->select('main_id')
                ->find($calculationId);

            if ($calculation) {

                $charter = DB::table('charters')
                    ->select('type')
                    ->find($calculation->main_id);

                if ($charter && $charter->type == 'accommodation') {

                    $accommodationRooms = DB::table('charter_accommodation_rooms')
                        ->where('calc_id', $calculationId)
                        ->get();

                    return response()->json([
                        'items' => $accommodationRooms,
                        'meta' => ['timestamp' => time()]
                    ]);

                } else {
                    return response()->json([
                        'error' => ['message' => 'charter not found.'],
                        'meta' => ['timestamp' => time()]
                    ], 400);
                }

            } else {
                return response()->json([
                    'error' => ['message' => 'calculation not found.'],
                    'meta' => ['timestamp' => time()]
                ], 400);
            }

        } else {
            return response()->json([
                'error' => ['message' => 'The calculation_id field is required.'],
                'meta' => ['timestamp' => time()]
            ], 400);
        }

    } catch (Exception $exception) {
        return response()->json([
            'error' => [
                'code' => $exception->getCode(),
                'message' => $exception->getMessage(),
                'trace' => $exception->getTrace()
            ]
        ], 400);
    }
}
  

Possible Errors

Success Response

Status: 200 OK

{
  "items": [
    {
      "id": 12,
      "calc_id": 1033,
      "room_title": "...",
      "capacity": 3,
      "price": 1250000,
      ...
    },
    ...
  ],
  "meta": {
    "timestamp": 1730000000
  }
}
  

Error Response

Status: 400 Bad Request

{
  "error": {
    "message": "calculation not found."
  },
  "meta": {
    "timestamp": 1730000000
  }
}
  

Flowchart

POST /v2/charter/accommodation/rooms/access

Charter: Access Accommodation Rooms

این اندپوینت برای «از دسترس خارج کردن» یا «بازگرداندن به دسترس» یک اتاق اقامتگاهی استفاده می‌شود. رفتار اندپوینت بر اساس ارسال یا عدم ارسال start_date و end_date دو حالت مختلف دارد: در حالت بازه‌دار روی تاریخ‌ها عمل می‌کند و در حالت بدون بازه روی وضعیت عمومی اتاق.

Request Body

Controller Logic

static function accessCharterAccommodationRooms(Request $request)
{
    try {
        $roomId = $request->room_id - 10000;
        $delete = false;

        if (isset($request->delete) && $request->delete) {
            $delete = filter_var($request->delete, FILTER_VALIDATE_BOOLEAN);
        }

        if ((isset($request->start_date) && $request->start_date) && isset($request->end_date) && $request->end_date) {

            $startDate = Carbon::createFromFormat('Y-m-d', $request->start_date);
            $endDate = Carbon::createFromFormat('Y-m-d', $request->end_date)->subDay();
            $period = CarbonPeriod::create($startDate, $endDate);

            if ($delete) {

                foreach ($period as $date) {
                    $dateString = $date->toDateString();

                    DB::table('charter_reservation_accommodation_rooms')
                        ->where([
                            ['type', '=', 'disable'],
                            ['room_id', '=', $roomId],
                            ['date', '=', $dateString],
                        ])
                        ->delete();
                }

            } else {

                $allReservations = DB::table('charter_reservation_accommodation_rooms')
                    ->where('date', '>=', $startDate->toDateString())
                    ->where('date', '<=', $endDate->toDateString())
                    ->where('room_id', $roomId)
                    ->exists();

                if (!$allReservations) {

                    foreach ($period as $date) {
                        $dateString = $date->toDateString();

                        DB::table('charter_reservation_accommodation_rooms')->insertGetId([
                            'type' => 'disable',
                            'room_id' => $roomId,
                            'date' => $dateString,
                        ]);
                    }

                } else {

                    return response()->json([
                        'error' => [
                            'message' =>
                                'این اتاق در بازه درخواستی شما دارای رزرو میباشد و از دسترس خارج کردن اتاق امکان پذیر نمی باشد.',
                        ],
                        'meta' => ['timestamp' => time()]
                    ], 400);

                }
            }

        } else {

            if ($delete) {

                DB::table('charter_accommodation_rooms')
                    ->where('id', $roomId)
                    ->update(['status' => 1]);

            } else {

                $allReservations = DB::table('charter_reservation_accommodation_rooms')
                    ->where('date', '>', Carbon::today())
                    ->where('room_id', $roomId)
                    ->exists();

                if (!$allReservations) {

                    DB::table('charter_accommodation_rooms')
                        ->where('id', $roomId)
                        ->update(['status' => 2]);

                } else {

                    return response()->json([
                        'error' => [
                            'message' =>
                                'این اتاق در بازه درخواستی شما دارای رزرو می باشد و از دسترس خارج کردن اتاق امکان پذیر نمی باشد.',
                        ],
                        'meta' => ['timestamp' => time()]
                    ], 400);

                }
            }
        }

        return response()->json([
            "payload" => true,
            'meta' => ['timestamp' => time()]
        ]);

    } catch (Exception $exception) {
        return response()->json([
            'error' => [
                'code' => $exception->getCode(),
                'message' => $exception->getMessage(),
                'trace' => $exception->getTrace()
            ]
        ], 400);
    }
}
  

Possible Errors

Success Response

Status: 200 OK

{
  "payload": true,
  "meta": {
    "timestamp": 1730000000
  }
}
  

Flowchart

GET /v2/academy/categories/view

Academy: View Categories

این اندپوینت برای دریافت لیست دسته‌بندی‌های فعال آکادمی استفاده می‌شود. تنها رکوردهایی که status = 1 دارند واکشی می‌شوند و داده‌ها در ساختار استاندارد شامل فیلدهای id، slug، flag، title، description و status بازگردانده می‌شوند.

Request

این اندپوینت هیچ پارامتر اجباری یا اختیاری دریافت نمی‌کند.

Controller Logic

public function viewCategories(Request $request)
{
    $resultCategories = DB::table('academy_categories')->where("status", 1)->get();
    $categories = [];

    foreach ($resultCategories as $category) {
        $categories[] = [
            "id" => $category->id,
            "slug" => $category->slug,
            "flag" => $category->flag,
            "title" => [
                "fa" => $category->title_fa,
                "en" => $category->title_en
            ],
            "description" => $category->description,
            "status" => $category->status
        ];
    }

    return [
        "status" => true,
        "time" => time(),
        "data" => $categories
    ];
}
  

Response Structure

Category Object

Example Response

Status: 200 OK

{
  "status": true,
  "time": 1730000000,
  "data": [
    {
      "id": 4,
      "slug": "frontend",
      "flag": "fe",
      "title": {
        "fa": "فرانت‌اند",
        "en": "Frontend"
      },
      "description": "دسته‌بندی آموزش‌های تخصصی فرانت‌اند",
      "status": 1
    },
    ...
  ]
}
  

Flowchart

GET /v2/academy/courses/view

Academy: View Courses

این اندپوینت لیست دوره‌های آموزشی آکادمی را با امکان فیلتر بر اساس دسته‌بندی بازمی‌گرداند. داده‌ها شامل اطلاعات کامل دوره، اطلاعات دسته‌بندی مرتبط، وضعیت کاربر در دوره (progress)، تعداد کل مراحل و وضعیت نمایش (featured) است. تنها دوره‌هایی که وضعیت آن‌ها 1 یا 3 باشد در خروجی قرار می‌گیرند.

Query Parameters

Controller Logic

// Filter: category_id (optional)
// Only show courses with status IN (1,3)
// Join with academy_categories for category details
// For each course: find progress, total steps, progress completed

$resultCourses = DB::table('academy_courses')
    ->select([...])
    ->where(function ($q) use ($request) {
        if ($request->has('category_id') && $request->get('category_id')) {
            $q->where('academy_courses.category', $request->get('category_id'));
        }
    })
    ->whereIn("academy_courses.status", [1, 3])
    ->leftJoin("academy_categories", "academy_categories.id", "academy_courses.category")
    ->get();

foreach ($resultCourses as $course) {

    $resultCompleted = DB::table('academy_course_completed')
        ->select('completed', 'current_step')
        ->where('course', $course->id)
        ->where('student', $request->get('operator')->id)
        ->first();

    if (!$resultCompleted) {
        $stepCompleted = 0;
        $currentStep = 1;
    } else {
        $stepCompleted = $resultCompleted->completed;
        $currentStep = $resultCompleted->current_step;
    }

    $courseCount = DB::table('academy_course_steps')
        ->where('course', $course->id)
        ->count();

    $courses[] = [
        "id" => $course->id,
        "slug" => $course->slug,
        "branch" => !is_null($course->branch) ? $course->branch : false,
        "price" => !is_null($course->price) ? $course->price : 'free',
        "necessary" => !is_null($course->necessary) ? json_decode($course->necessary) : false,
        "title" => [...],
        "category" => [...],
        "progress" => [
            "current_step" => (int)$currentStep,
            "completed" => (int)$stepCompleted
        ],
        "duration" => $course->duration,
        "total_steps" => $courseCount,
        "featured" => $course->featured,
        "description" => $course->description,
        "status" => $course->status,
        "created_at" => $course->created_at,
        "updated_at" => $course->updated_at
    ];
}

return [
    "status" => true,
    "time" => time(),
    "data" => $courses
];
  

Course Object Structure

Example Response

Status: 200 OK

{
  "status": true,
  "time": 1730000000,
  "data": [
    {
      "id": 21,
      "slug": "advanced-react",
      "branch": false,
      "price": "free",
      "necessary": false,
      "title": {
        "fa": "ری‌اکت پیشرفته",
        "en": "Advanced React"
      },
      "category": { ... },
      "progress": { "current_step": 1, "completed": 0 },
      "duration": 180,
      "total_steps": 12,
      "featured": 1,
      "description": "دوره کامل React برای توسعه‌دهندگان پیشرفته",
      "status": 1,
      "created_at": "2024-04-02 11:30:00",
      "updated_at": "2024-04-20 19:12:00"
    }
  ]
}
  

Flowchart

GET /v2/academy/course/steps/view

Academy: View Course Steps

این اندپوینت اطلاعات کامل یک دوره آموزشی به‌همراه تمام مراحل (steps) آن را برمی‌گرداند. همچنین وضعیت پیشرفت کاربر (current_step و completed) را به‌روزرسانی و بازگردانی می‌کند. منطق این API بر اساس آخرین مرحله (آخرین رکورد step) داده دریافت شده بنا شده است و اطلاعات دوره نیز عمداً از همان آخرین step استخراج می‌شود (طبق رفتار فعلی سیستم).

Query Parameters

Controller Logic

// 1. Fetch all steps of this course (optional filtering by step_id)
// 2. LEFT JOIN course + category info inside each step row
// 3. Load or create progress record in academy_course_completed
// 4. Update progress (completed / current_step)
// 5. Build steps[]
// 6. Build final course object based on the LAST step (intentional behavior)

$resultCourseSteps = DB::table('academy_course_steps')
    ->select([... course + step + category fields ...])
    ->where('academy_course_steps.course', $request->get('course_id'))
    ->where(function ($q) {
        if ($request->has('step_id')) $q->where('academy_course_steps.id', $request->get('step_id'));
    })
    ->leftJoin("academy_courses", ...)
    ->leftJoin("academy_categories", ...)
    ->orderBy('order')->orderBy('id')
    ->get();

$resultStep = DB::table('academy_course_completed')
    ->where('course', $request->get('course_id'))
    ->where('student', $request->get('operator')->id)
    ->first();

$courseCount = total number of steps in academy_course_steps;

// Progress Update Logic
if (!$resultStep) create new record with defaults;
else update based on current_step rules;

// Build steps[]
foreach (... each step ...) { ... }

// IMPORTANT: course info is taken from LAST step (as user confirmed)
$return = [
   "id" => $step->course_id,
   ...
   "steps" => $steps
];

return [...];
  

Step Object Structure

Course Object Structure (Extracted From Last Step)

Important Note

اطلاعات دوره از **آخرین step** استخراج می‌شود. این رفتار در کد وجود دارد و توسط کاربر (علیرضا) تأیید شده‌است. اگر steps خالی باشد، `$step` undefined شده و سیستم خطا خواهد داد.

Example Response

Status: 200 OK

{
  "status": true,
  "time": 1730000000,
  "data": {
    "id": 21,
    "slug": "advanced-react",
    "branch": false,
    "price": "free",
    "necessary": false,
    "title": { "fa": "ری‌اکت پیشرفته", "en": "Advanced React" },
    "category": {
      "id": 3,
      "flag": "frontend",
      "title": { "fa": "فرانت‌اند", "en": "Frontend" }
    },
    "progress": { "current_step": 2, "completed": 1 },
    "total_steps": 12,
    "duration": 180,
    "featured": 1,
    "created_at": "2024-04-02 11:30:00",
    "updated_at": "2024-04-20 19:12:00",
    "status": 1,
    "steps": [
      {
        "id": 10,
        "title": { "fa": "آشنایی", "en": "Introduction" },
        "subtitle": { "fa": "مقدمه", "en": "Intro" },
        "content": "...",
        "order": 1,
        "status": 1,
        "created_at": "2024-04-02 11:30:00",
        "updated_at": "2024-04-02 11:30:00"
      },
      ...
    ]
  }
}
  

Flowchart

POST /v2/academy/course/steps/update

Academy: Update / Store / Delete Course Steps

این اندپوینت سه عملیات روی مراحل دوره (Course Steps) انجام می‌دهد: ایجاد (store)، ویرایش (update) و حذف (delete). نوع عملیات از طریق پارامتر action مشخص می‌شود. همه عملیات‌ها روی جدول academy_course_steps انجام می‌شود و در صورت خطا، پاسخ استاندارد شامل پیام خطا بازگردانده می‌شود.

Body Parameters

Controller Logic

action = $request->get('action');
data = $request->data;

try {

  // ---------- UPDATE ----------
  if (action == 'update') {
      update academy_course_steps where id = data['step_id']
      set:
        course = data['course']
        title_fa = data['title_fa']
        title_en = data['title_en'] == '' ? null : data['title_en']
        subtitle_fa = data['subtitle_fa']
        subtitle_en = data['subtitle_en'] == '' ? null : data['subtitle_en']
        content = data['content']
        order = data['order']
        updated_at = now()

      return status=true, time

  // ---------- STORE ----------
  } else if (action == 'store') {
      insert into academy_course_steps:
        course = data['course']
        title_fa = data['title_fa']
        title_en = data['title_en'] == '' ? null : data['title_en']
        subtitle_fa = data['subtitle_fa']
        subtitle_en = data['subtitle_en'] == '' ? null : data['subtitle_en']
        content = data['content']
        order = data['order']
        created_at = now()
        updated_at = now()

      return status=true, time

  // ---------- DELETE ----------
  } else if (action == 'delete') {
      delete from academy_course_steps where id = data['step_id']
      return status=true, time
  }

} catch (Exception $e) {
    return status=false, time, message=$e->getMessage();
}
  

Important Notes

Example Requests

1. Update Step

POST /v2/academy/course/steps/update
{
  "action": "update",
  "data": {
    "step_id": 12,
    "course": 4,
    "title_fa": "ویرایش شده",
    "title_en": "",
    "subtitle_fa": "ساب جدید",
    "subtitle_en": "",
    "content": "

New HTML

",
    "order": 3
  }
}
  

2. Store New Step

POST /v2/academy/course/steps/update
{
  "action": "store",
  "data": {
    "course": 4,
    "title_fa": "مرحله جدید",
    "title_en": "New Step",
    "subtitle_fa": "ساب",
    "subtitle_en": "",
    "content": "

Hello

",
    "order": 5
  }
}
  

3. Delete Step

POST /v2/academy/course/steps/update
{
  "action": "delete",
  "data": {
    "step_id": 12
  }
}
  

Flowchart

GET /v2/mail/servers/list

Mail: Get Server List

این اندپوینت لیستی از سرورهای ایمیل فعال (Status = 1) را برای یک شعبه (Branch) خاص بازیابی می‌کند.
خروجی شامل اطلاعات پیکربندی سرویس و محدودیت‌های ماهانه هر سرور است که برای مدیریت ارسال ایمیل‌ها استفاده می‌شود.

Request Overview

Access Control

Query Parameters

Example Request

GET /v2/mail/servers/list?branch=10

Logic Details

فرآیند پردازش در متد mailServer به صورت زیر است:

Response Structure

پاسخ موفق

در صورت موفقیت، لیست سرورها در آرایه data قرار می‌گیرد.

پاسخ خطا

در صورت بروز هرگونه خطا (Exception) در طول پردازش، کد وضعیت 400 بازگردانده می‌شود.

Flowchart

GET /v2/mail/address/list

Mail: Get Address List

این اندپوینت لیستی از آدرس‌های ایمیل تعریف شده روی یک سرور خاص را برمی‌گرداند.
نکته کلیدی در این اندپوینت، سیستم دسترسی است: تنها آدرس‌هایی بازگردانده می‌شوند که شناسه اپراتور درخواست‌دهنده در لیست کاربران مجاز آن آدرس (`users` JSON column) وجود داشته باشد. همچنین آدرس نهایی با ترکیب نام کاربری و دامنه سرور ساخته می‌شود.

Request Overview

Access Control

Query Parameters

Example Request

GET /v2/mail/address/list?server=5

Logic Details

مراحل پردازش در متد mailAddress به شرح زیر است:

Response Structure

پاسخ موفق

لیست آدرس‌های مجاز به همراه آدرس کامل ساخته شده بازگردانده می‌شود.

پاسخ خطا

در صورت بروز خطا (مثلاً سرور یافت نشود یا خطای دیتابیس)، پاسخ 400 بازگردانده می‌شود.

Flowchart

POST /v2/mail/address/store

Mail: Create Address

این اندپوینت برای ایجاد یک حساب ایمیل جدید استفاده می‌شود.
این متد یک فرآیند دو مرحله‌ای دارد: ابتدا درخواست ساخت اکانت را به سرویس‌دهنده خارجی (External API) ارسال می‌کند و در صورت موفقیت، اطلاعات آن را در دیتابیس محلی ذخیره کرده و به اپراتور درخواست‌دهنده تخصیص می‌دهد.

Request Overview

Access Control

Body Parameters

Logic Details

فرآیند متد mailAddressStore به شرح زیر است:

Response Structure

پاسخ موفق (Created)

حساب کاربری هم در سرویس خارجی و هم در دیتابیس داخلی ایجاد شده است.

پاسخ ناموفق (API Reject)

سرویس خارجی درخواست ساخت اکانت را رد کرده است (مثلاً نام کاربری تکراری است).

پاسخ خطا (Exception)

Flowchart

GET /v2/mail/{type}/list

Mail: Get Mailbox List

این اندپوینت چندمنظوره برای دریافت لیست ایمیل‌ها بر اساس دسته‌بندی‌های مختلف استفاده می‌شود.
بسته به پارامتر type در آدرس، سیستم می‌تواند صندوق ورودی، صندوق ارسال، پیش‌نویس‌ها، یا ایمیل‌های فیلتر شده بر اساس تگ و لیبل را بازگرداند.

Request Overview

Access Control

Path Parameters

Query Parameters

Logic Details

منطق این متد بر اساس type به سه شاخه اصلی تقسیم می‌شود:

Response Structure

پاسخ موفق

خروجی آرایه‌ای از اشیاء ایمیل است. بسته به نوع (دریافتی/ارسالی) فیلد sender یا recipients وجود خواهد داشت.

Flowchart

POST /v2/mail/{type}/update

Mail: Update Attributes

این اندپوینت یک متد عمومی و داینامیک برای ویرایش ویژگی‌های یک ایمیل است.
با استفاده از این متد می‌توان وضعیت‌هایی مانند "خوانده شده" (`read_at`)، برچسب‌ها (`label`)، تگ‌ها (`tag`) یا هر ستون دیگری از ایمیل را در صندوق ورودی یا ارسالی تغییر داد.

Request Overview

Access Control

Path Parameters

Body Parameters

Logic Details

منطق این متد بسیار مستقیم است:

Response Structure

پاسخ موفق

پاسخ خطا

در صورت بروز خطا (مثلاً نام ستون اشتباه باشد):

Flowchart

POST /v2/mail/attachments/download

Mail: Download Attachment

این اندپوینت وظیفه دریافت لینک دانلود فایل‌های پیوست ایمیل را بر عهده دارد.
برای ایمیل‌های ورودی (Inbox)، از استراتژی Lazy Download استفاده می‌شود: فایل ابتدا روی سرور ایمیل خارجی است؛ اگر اولین بار باشد که درخواست می‌شود، فایل دانلود شده، در S3 ذخیره می‌شود و لینک آن در دیتابیس ثبت می‌گردد. در درخواست‌های بعدی، لینک مستقیم S3 بازگردانده می‌شود.

Request Overview

Access Control

Body Parameters

Logic Details

منطق پردازش به شرح زیر است:

Response Structure

پاسخ موفق

Flowchart

GET /v2/mail/sent/get

Mail: Get Sent Details

این اندپوینت برای دریافت جزئیات کامل یک ایمیل ارسال شده استفاده می‌شود.
برخلاف لیست‌ها که اطلاعات خلاصه‌ای ارائه می‌دهند، این متد متن کامل بدنه ایمیل (`content`)، لیست کامل گیرندگان (CC/BCC) و آرایه کامل فایل‌های پیوست را باز می‌گرداند.

Request Overview

Access Control

Query Parameters

Logic Details

فرآیند واکشی اطلاعات به صورت زیر است:

Response Structure

پاسخ موفق

Flowchart

POST /v2/mail/sent/store

Mail: Store & Send Email

این اندپوینت وظیفه ذخیره‌سازی و ارسال ایمیل را بر عهده دارد.
عملکرد این متد وابسته به پارامتر type است: اگر outbox باشد، ایمیل علاوه بر ذخیره شدن در دیتابیس، با استفاده از تنظیمات SMTP پویا (Dynamic SMTP) بلافاصله ارسال می‌شود. در غیر این صورت (مثلاً پیش‌نویس)، صرفاً ذخیره می‌شود.

Request Overview

Access Control

Body Parameters

Logic Details

منطق پردازش به شرح زیر است:

Response Structure

پاسخ موفق

Flowchart

DELETE /v2/mail/sent/trash

Mail: Move Sent to Trash

این اندپوینت برای انتقال یک ایمیل ارسال شده به "زباله‌دان" (Trash) استفاده می‌شود.
این عملیات یک حذف نرم (Soft Delete) است؛ رکورد فیزیکی از دیتابیس پاک نمی‌شود، بلکه فیلد type آن به trash تغییر می‌کند تا در لیست‌های عادی نمایش داده نشود.

Request Overview

Access Control

Body/Query Parameters

Logic Details

منطق پردازش بسیار ساده است:

Response Structure

پاسخ موفق

Flowchart

GET /v2/mail/inbox/get

Mail: Get Inbox Details

این اندپوینت برای دریافت جزئیات کامل یک ایمیل ورودی (Inbox) استفاده می‌شود.
اطلاعات شامل متن کامل ایمیل، فایل‌های پیوست، امتیاز اسپم و متادیتای فرستنده است.

Request Overview

Access Control

Query Parameters

Logic Details

فرآیند واکشی اطلاعات به صورت زیر است:

Response Structure

پاسخ موفق

Flowchart

GET /v2/mail/inbox/get

Mail: Get Inbox Details

این اندپوینت برای دریافت جزئیات کامل یک ایمیل ورودی (Inbox) استفاده می‌شود.
اطلاعات شامل متن کامل ایمیل، فایل‌های پیوست، امتیاز اسپم و متادیتای فرستنده است.

Request Overview

Access Control

Query Parameters

Logic Details

فرآیند واکشی اطلاعات به صورت زیر است:

Response Structure

پاسخ موفق

Flowchart

DELETE /v2/mail/inbox/trash

Mail: Move Inbox to Trash

این اندپوینت برای انتقال یک ایمیل ورودی (Inbox) به "زباله‌دان" (Trash) استفاده می‌شود.
مشابه اندپوینت بخش ارسالی‌ها، این عملیات نیز یک حذف نرم (Soft Delete) است و رکورد فیزیکی از دیتابیس پاک نمی‌شود؛ تنها فیلد type آن به trash تغییر می‌کند.

Request Overview

Access Control

Body/Query Parameters

Logic Details

مراحل پردازش:

Response Structure

پاسخ موفق

Flowchart

DELETE /v2/mail/trash/delete

Mail: Permanent Delete (Trash)

این اندپوینت برای حذف فیزیکی و دائمی یک ایمیل استفاده می‌شود.
معمولاً زمانی فراخوانی می‌شود که کاربر بخواهد آیتمی را از پوشه "زباله‌دان" (Trash) به طور کامل پاک کند. برخلاف اندپوینت‌های قبلی که فقط برچسب (Type) را تغییر می‌دادند، این متد رکورد را از دیتابیس حذف می‌کند (Hard Delete).

Request Overview

Access Control

Body/Query Parameters

Logic Details

مراحل پردازش به شرح زیر است:

Response Structure

پاسخ موفق

پاسخ خطا

Flowchart

GET /v2/modules/lottery/registrations

Module: Lottery Registrations List

این اندپوینت برای دریافت لیست ثبت‌نام‌کنندگان در ماژول قرعه‌کشی (Lottery) استفاده می‌شود.
این سرویس لیست فاکتورهایی را برمی‌گرداند که شامل آیتم خدمات با شناسه خاص (۱۷) هستند و محاسبات مالی سنگینی (سود، زیان، تراز دریافتی و پرداختی) برای هر ردیف انجام می‌دهد.

Request Overview

Access Control

Query Parameters

توجه: پارامترها به صورت آرایه `json` و پارامتر مجزای `branch` ارسال می‌شوند.

Logic Details

فرآیند تولید گزارش به شرح زیر است:

Response Structure

پاسخ موفق

{
  "status": true,
  "time": 1715000000,
  "draw": 1,
  "recordsTotal": 50,
  "data": [
    {
      "id": 101,                  // شناسه آیتم فاکتور
      "system_id": 5050,          // شناسه فاکتور
      "serial": 1001,             // سریال خام دیتابیس
      "details": {                // جزئیات سرویس قرعه‌کشی
        "id": 17,
        "name": "Lottery Name"
      },
      "customer_id": 200,
      "sale": 5000000,
      "discount": false,          // یا آبجکت تخفیف
      "status": 1,
      "description": "توضیحات فاکتور",
      "financial": {              // خروجی تابع Financial با فرمت snake_case
        "operator": {
          "title": "Admin User",
          "id": 1
        },
        "leader": {
          "id": 200,
          "title_fa": "علی محمدی",
          "mobile": "0912..."
        },
        "financial": {
          "sum_passenger": 1,
          "sum_buy": 4000000,
          "sum_sale": 5000000,
          "sum_receive": 5000000,
          "balance_received": 0,  // تراز مالی مسافر (0 یعنی تسویه)
          "balance_paid": -4000000, // تراز مالی تامین کننده
          "profit": 1000000,      // سود خالص
          "percent_profit": 25
        },
        "suppliers": { ... },     // لیست تامین‌کنندگان
        "serial_id": 11001        // سریال نمایشی (10000 + serial)
      }
    }
  ]
}

Flowchart

POST /v2/trade/tickets

Trade: Tickets & Vouchers Data

این اندپوینت وظیفه استخراج اطلاعات کامل بلیت‌ها، واچرها و فاکتورها را برای نمایش یا چاپ بر عهده دارد.
این سرویس منطق پیچیده‌ای برای گردآوری اطلاعات مسافران، تامین‌کنندگان، وضعیت آیتم‌ها (عادی یا استردادی) و تنظیمات نمایش قیمت دارد.

Request Overview

Access Control

Body Parameters

Logic Details

منطق پردازش این سرویس شامل مراحل زیر است:

Response Structure

نکته مهم: در کد فعلی، حتی در صورت موفقیت‌آمیز بودن عملیات و بازگشت دیتا، مقدار status برابر با false و کد 5008 برگردانده می‌شود (احتمالاً یک استاندارد داخلی یا لگاسی کد).

{
  "status": false,  // ! توجه: طبق کد موجود فالس برمی‌گرداند
  "code": 5008,
  "data": [
    {
      "confirmation": 1,
      "serial_id": 100500,
      "track_code": "09-1200", // فرمت: ماه-سریال
      "print": {
        "id": 1,
        "title": { "fa": "مشاهده بدون قیمت", "en": "view without price" }
      },
      "internal": true,
      "contact_information": {
        "logo": "url...",
        "address": "Tehran...",
        "phone": "021..."
      },
      "operator": {
        "first_name": "Admin",
        "last_name": "User",
        "mobile": "0912..."
      },
      "leader": {
        "firstname_fa": "علی",
        "lastname_fa": "علوی",
        "mobile": "0912..."
      },
      "data": {
        // آرایه‌ای از آیتم‌ها گروه‌بندی شده بر اساس شناسه آیتم/مسافر
        "route_123": [
           {
             "serial_id": 50,
             "action": "route",
             "passenger": { ... }, // آبجکت کامل مسافر
             "sell": false,        // یا مبلغ اگر print=2 باشد
             "route": { ... }      // جزئیات پرواز
           }
        ]
      },
      "created": "2024-05-10 10:00:00"
    }
    // ممکن است شامل آبجکت‌های خطا هم باشد اگر یکی از فاکتورها مشکل داشته باشد
    // { "status": false, "code": 5006, "message": "..." }
  ]
}

Flowchart

POST /v2/trade/contract

Trade: Contract Generation

این اندپوینت وظیفه تولید متن کامل قرارداد را بر عهده دارد.
سیستم با استفاده از قالب‌های HTML ذخیره شده در دیتابیس و ترکیب آن‌ها با اطلاعات پویای فاکتور (مسافران، خدمات، قیمت‌ها)، خروجی نهایی قرارداد را برای نمایش یا چاپ آماده می‌کند.

Request Overview

Access Control

Body Parameters

Logic Details

فرآیند تولید قرارداد شامل مراحل زیر است:

Response Structure

در صورت موفقیت، کد HTML قرارداد در فیلد contract و متادیتای مورد نیاز در data قرار می‌گیرد.

{
  "status": true,
  "time": 1715001200,
  "contract": "... HTML CONTENT ...",
  "data": {
    "confirmation": "2024-05-10 12:30:00", // زمان تایید یا null
    "serial_id": 1500,       // شناسه اصلی دیتابیس
    "internal": true,        // وضعیت داخلی/خارجی بودن مسیر
    "leader": {
      "id": 105,
      "firstname_en": "Ali",
      "lastname_en": "Rezaei",
      "firstname_fa": "علی",
      "lastname_fa": "رضایی",
      "mobile": "09121234567"
    },
    "slug": "xYz123",
    "track_code": "02-2500", // فرمت: ماه - (سریال + اکستنشن)
    "created": "2024-05-10 10:00:00"
  }
}

پاسخ‌های خطا

// خطای عدم وجود یا وضعیت نامعتبر
{
  "status": false,
  "code": 5001,
  "message": "قرارداد یافت نشد" 
}
// خطای غیرقابل چاپ بودن
{
  "status": false,
  "code": 5006,
  "message": "رفرنس مورد نظر قابلیت چاپ ندارد."
}

Flowchart

POST /v2/trade/confirmation

Trade: Contract Confirmation

این اندپوینت جهت تایید نهایی قرارداد (فاکتور) توسط اپراتور استفاده می‌شود.
با فراخوانی این سرویس، فیلد تاییدیه در دیتابیس با زمان جاری مقداردهی شده و در صورت درخواست، پیامک اطلاع‌رسانی حاوی لینک قرارداد دیجیتال برای مسافر (سرگروه) ارسال می‌شود.

Request Overview

Access Control

Body Parameters

Logic Details

فرآیند تایید شامل مراحل زیر است:

Response Structure

پاسخ موفق

{
  "status": true,
  "time": 1715001200
}

پاسخ خطا

{
  "status": false,
  "code": 5007,
  "message": "خطا در ارسال اطلاعات.",
  "trace": [ ... ]
}

Flowchart

POST /v2/credit-card

Credit Card: Issue Request

این اندپوینت وظیفه احراز هویت پیشرفته و صدور کارت اعتباری برای مسافر را بر عهده دارد.
در این فرآیند، اطلاعات هویتی و مالکیتی سیم‌کارت از طریق سرویس‌های شاهکار و ثبت‌احوال (Jibit) استعلام شده و در صورت تأیید، یک کارت بانکی مجازی با الگوریتم استاندارد بانکی تولید و ۵۰,۰۰۰ ریال از کیف پول اپراتور کسر می‌گردد.

Request Overview

Access Control

Body Parameters

Logic Details

فرآیند صدور کارت دارای منطق پیچیده اعتبارسنجی به شرح زیر است:

Response Structure

پاسخ موفق

پاسخ‌های خطا (نمونه)

{
  "error": {
    "code": 1000, // یا کدهای خطای جیبیت
    "message": "اطلاعات هویتی مسافر با اطلاعات هویتی موجود در سیستم ثبت احوال مطابقت ندارد."
  },
  "meta": {
    "timestamp": 1715001200
  }
}

کدهای وضعیت HTTP:

Flowchart

GET /v2/credit-card/index

Credit Card: List & Index

این اندپوینت وظیفه واکشی و نمایش لیست کارت‌های اعتباری صادر شده را بر عهده دارد.
مهم‌ترین ویژگی این بخش، اعمال لایه‌ی امنیتی روی شماره کارت‌ها (Masking) جهت حفاظت از داده‌های حساس و همچنین فیلترینگ هوشمند بر اساس دسترسی شعبه (Branch Access) می‌باشد.

Request Overview

Access Control

Query Parameters

Logic Details

منطق پردازش لیست شامل مراحل امنیتی و محاسباتی زیر است:

Response Structure

پاسخ موفق

{
  "items": [
    {
      "id": 105,
      "status": 1, // 1: Active, 0: Inactive
      "card": {
        "number": "6219********4321", // Masked for security
        "withdrawal_limit": false,      // false if null
        "blocked_amount": 500000
      },
      "passenger": {
        "id": 2045,
        "first_name": "علی",
        "last_name": "محمدی"
      }
    }
    // ... more items
  ],
  "meta": {
    "timestamp": 1715005000,
    "table": {
      "total": 50,
      "per_page": 10,
      "current_page": 1,
      "last_page": 5,
      "from": 1,
      "to": 10
    }
  }
}

مدیریت خطا

در صورت بروز خطای دیتابیس یا منطقی، ساختار زیر برای دیباگ برگردانده می‌شود:

{
  "error": {
    "code": "HY000",
    "message": "SQLSTATE[HY000]: General error: ...",
    "file": "/app/Http/Controllers/V2/CreditCards.php",
    "line": 85
  },
  "meta": { "timestamp": 1715005123 }
}

Flowchart

GET /v2/credit-card

Credit Card: Show Details

این اندپوینت برای مشاهده جزئیات یک کارت اعتباری خاص استفاده می‌شود.
ویژگی منحصر‌به‌فرد این متد، حساسیت به مالکیت (Ownership Awareness) است. سیستم بررسی می‌کند که آیا درخواست‌کننده (Operator) همان صاحب کارت است یا خیر. اگر مالک باشد، اطلاعات محرمانه (CVV2، تاریخ انقضا و شماره کامل) نمایش داده می‌شود؛ در غیر این صورت، داده‌ها ماسک می‌شوند.

Request Overview

Access Control

Query Parameters

* توجه: اگرچه پارامترها اختیاری (Optional) تعریف شده‌اند، اما برای دریافت خروجی معتبر باید حداقل یکی از آن‌ها ارسال شود تا کوئری نتیجه‌ای برگرداند.

Logic Details & Security

منطق پردازش شامل مراحل زیر است:

Response Structure

حالت اول: پاسخ به مالک کارت (Owner View)

{
  "payload": {
    "id": 105,
    "status": 1,
    "card": {
      "number": "6219861012345678", // Full Number
      "withdrawal_limit": false,
      "blocked_amount": false,
      "cvv2": "452",              // Visible
      "expire_date": "1405/02"    // Visible
    },
    "passenger": {
      "id": 2045,
      "first_name": "علی",
      "last_name": "محمدی"
    }
  },
  "meta": { "timestamp": 1715005000 }
}

حالت دوم: پاسخ به سایرین (Admin/Public View)

{
  "payload": {
    "id": 105,
    "status": 1,
    "card": {
      "number": "6219********5678", // Masked Number
      "withdrawal_limit": false,
      "blocked_amount": false
      // CVV2 and Expire Date are OMITTED
    },
    "passenger": {
      "id": 2045,
      "first_name": "علی",
      "last_name": "محمدی"
    }
  },
  "meta": { "timestamp": 1715005000 }
}

خطای ۴۲۲ (پیدا نشد)

اگر با پارامترهای ارسالی کارتی پیدا نشود:

{
  "error": {
    "code": 1000,
    "message": "کارت اعتباری پیدا نشد."
  },
  "meta": { ... }
}

Flowchart

POST /v2/articles/{id}/views

Article: Increment Views

این اندپوینت وظیفه افزایش شمارنده بازدید یک مقاله خاص را بر عهده دارد.
این متد معمولاً زمانی فراخوانی می‌شود که کاربر وارد صفحه جزئیات مقاله (Single Page) می‌شود. عملیات افزایش بازدید به صورت مستقیم روی دیتابیس (Atomic) انجام شده و تعداد جدید بازدیدها بلافاصله برگردانده می‌شود.

Request Overview

Access Control

Path Parameters

Logic Details

روند پردازش به شرح زیر است:

Response Structure

پاسخ موفق (200 OK)

{
  "status": true,
  "time": 1715006000,
  "views": 1543 // تعداد بازدید جدید پس از افزایش
}

خطای یافت نشد (404 Not Found)

اگر شناسه مقاله در دیتابیس موجود نباشد (توسط findOrFail):

{
  "message": "No query results for model [App\\Models\\Article] 9999"
  // یا ساختار استاندارد خطای لاراول بسته به تنظیمات Exception Handler
}

Flowchart

RESOURCE /v2/articles

Article Resource Management

این بخش شامل ۵ اندپوینت استاندارد برای مدیریت کامل مقالات (Articles) می‌باشد.
ویژگی‌های کلیدی این کنترلر شامل فیلترینگ پیشرفته در لیست‌گیری (بر اساس دسته‌بندی، تگ و مکان) و مدیریت روابط متا تگ‌ها (PageMetatags) هنگام ساخت و ویرایش است.

1. List Articles (Index)

پارامترهای فیلترینگ (Query Params)

مثال پاسخ (Response)

{
  "status": true,
  "time": 1715008000,
  "data": [
    { "id": 10, "title": "...", "views": 150, ... } // ArticleResource Object
  ],
  "links": {
    "first": "...",
    "last": "...",
    "prev": null,
    "next": "..."
  }
}

2. Create Article (Store)

یک مقاله جدید ایجاد می‌کند. همزمان اگر آرایه metatags ارسال شود، رکوردهای مربوطه در جدول page_metatags ساخته می‌شوند.
فیلد operator به صورت خودکار از توکن کاربر احراز هویت شده برداشته می‌شود.

بدنه درخواست (Body Parameters)

3. Show Article (Show)

جزئیات کامل یک مقاله را برمی‌گرداند. از Route Model Binding لاراول استفاده می‌کند (اگر پیدا نشود ۴۰۴ می‌دهد).

4. Update Article

اطلاعات مقاله را ویرایش می‌کند.
منطق هوشمند متاتگ‌ها: در آرایه metatags، اگر آیتمی دارای id باشد، آن رکورد در دیتابیس آپدیت می‌شود. اگر فاقد ID باشد، به عنوان یک متاتگ جدید برای این مقاله ایجاد می‌شود.

5. Delete Article

مقاله را حذف می‌کند. متاتگ‌های وابسته (اگر Cascade در دیتابیس تنظیم شده باشد) حذف می‌شوند، در غیر این صورت فقط رکورد مقاله حذف می‌شود.

{
    "status": true,
    "time": 1715009000
}

RESOURCE /v2/categories

Category Resource Management

این بخش شامل مدیریت کامل دسته‌بندی‌ها (Categories) است.
این کنترلر به طور پیش‌فرض در متد لیست‌گیری، فقط دسته‌بندی‌های اصلی (بدون والد) را برمی‌گرداند. همچنین از فیلترهای مکان و نوع پشتیبانی می‌کند.

1. List Categories (Index)

نکته مهم: این اندپوینت دارای فیلتر سخت‌گیرانه whereNull('main') است. یعنی فقط دسته‌بندی‌هایی که فیلد main آن‌ها خالی است (دسته‌بندی‌های والد) در خروجی ظاهر می‌شوند.

پارامترهای فیلترینگ (Query Params)

مثال پاسخ

{
  "status": true,
  "time": 1715011000,
  "data": [
    {
      "id": 5,
      "title": "تکنولوژی",
      "slug": "tech",
      "image": "https://...",
      "main": null, // همیشه null است در این لیست
      "places": "[1, 2]" // JSON String
    }
  ],
  "links": { ... }
}

2. Create Category (Store)

یک دسته‌بندی جدید ایجاد می‌کند.

بدنه درخواست (Body Parameters)

3. Show Category

مشاهده جزئیات یک دسته‌بندی خاص.

4. Update Category

ویرایش اطلاعات دسته‌بندی. ورودی‌ها دقیقاً مشابه متد Store هستند.

{
    "status": true,
    "time": 1715012000
}

5. Delete Category

حذف کامل دسته‌بندی.

Index Logic Flowchart

RESOURCE /v2/tags

Tag Resource Management

این بخش شامل مدیریت کامل تگ‌ها (Tags) است که برای برچسب‌گذاری روی مقالات و سایر محتواها استفاده می‌شود.
این کنترلر از ساختار استاندارد Resource در لاراول پیروی می‌کند.

1. List Tags (Index)

لیست تگ‌ها را به صورت صفحه‌بندی شده (۱۵ آیتم در هر صفحه) برمی‌گرداند.

مثال پاسخ

{
  "status": true,
  "time": 1715015000,
  "data": [
    {
      "id": 1,
      "title": "Laravel",
      "slug": "laravel",
      "description": "PHP Framework"
    }
  ],
  "links": {
    "first": "http://.../v2/tags?page=1",
    "last": "http://.../v2/tags?page=5",
    "prev": null,
    "next": "http://.../v2/tags?page=2"
  }
}

2. Create Tag (Store)

یک تگ جدید ایجاد می‌کند. پارامتر branch به صورت خودکار از درخواست (احتمالاً از توکن کاربر یا میدل‌ور) دریافت و ثبت می‌شود.

بدنه درخواست (Body Parameters)

مثال پاسخ موفق

{
  "status": true,
  "time": 1715015100,
  "data": {
      "id": 12,
      "title": "New Tag",
      "slug": "new-tag",
      "description": "..."
  }
}

3. Show Tag

مشاهده جزئیات یک تگ خاص بر اساس ID.

4. Update Tag

ویرایش اطلاعات تگ. فیلدها مشابه متد Store هستند.

{
    "status": true,
    "time": 1715015200
}

5. Delete Tag

حذف تگ از سیستم.

RESOURCE /v2/landing_pages

Landing Page Management

این بخش شامل مدیریت کامل صفحات فرود (Landing Pages) است.
این صفحات معمولاً برای کمپین‌های خاص یا صفحات ایستا استفاده می‌شوند و شامل مدیریت سئو (Meta Tags) به صورت تودرتو هستند.

1. List Landing Pages (Index)

توجه: در این متد از صفحه‌بندی (Pagination) استفاده نشده و تمام رکوردهای موجود در جدول برگردانده می‌شوند.

مثال پاسخ

{
  "status": true,
  "time": 1715016000,
  "data": [
    {
      "id": 1,
      "title": "Black Friday Sale",
      "slug": "black-friday",
      "image": "https://...",
      "published_at": "2024-11-20 00:00:00"
    },
    {
      "id": 2,
      "title": "Norouz Campaign",
      "slug": "norouz-1404",
      "image": "https://...",
      "published_at": "2025-03-20 00:00:00"
    }
  ]
}

2. Create Landing Page (Store)

ایجاد صفحه فرود جدید به همراه متاتگ‌های سئو.

بدنه درخواست (Body Parameters)

رفتار سیستمی: متاتگ‌های ارسالی در آرایه metatags با تایپ landing_page در دیتابیس ذخیره می‌شوند.

3. Show Landing Page

دریافت جزئیات کامل یک صفحه فرود.

4. Update Landing Page

ویرایش اطلاعات صفحه فرود و مدیریت هوشمند متاتگ‌ها.

منطق آپدیت متاتگ‌ها (Metatags Logic)

هنگام ارسال آرایه metatags، سیستم روی هر آیتم پیمایش می‌کند:

5. Delete Landing Page

حذف صفحه فرود (و احتمالاً متاتگ‌های وابسته اگر Cascade در دیتابیس تنظیم شده باشد).

RESOURCE /v2/page_metatags

Page Metatag Management (Direct)

این بخش شامل مدیریت مستقیم و مستقل متاتگ‌های سئو (Meta Tags) است.
معمولاً متاتگ‌ها همراه با مقاله یا صفحه فرود ویرایش می‌شوند، اما این اندپوینت‌ها برای اصلاحات سریع یا مدیریت سیستمی کاربرد دارند.

1. List All Metatags (Index)

هشدار عملکردی: این متد از PageMetatag::all() استفاده می‌کند و تمام رکوردهای جدول را بدون صفحه‌بندی برمی‌گرداند. در صورت زیاد بودن داده‌ها، پاسخ سنگین خواهد بود.

مثال پاسخ

{
  "status": true,
  "time": 1715018000,
  "data": [
    {
      "id": 101,
      "page_id": 5,
      "type": "article",
      "key": "keywords",
      "body": "news, tech, ai",
      "details": null,
      "status": 1,
      "created_at": "...",
      "updated_at": "..."
    }
  ]
}

2. Create Metatag (Store)

ایجاد یک متاتگ جدید و انتساب آن به یک صفحه یا مقاله.

بدنه درخواست (Body Parameters)

3. Show Metatag

مشاهده جزئیات یک متاتگ خاص.

4. Update Metatag

ویرایش کامل یک متاتگ. ورودی‌ها دقیقاً مشابه متد Store هستند.

{
    "status": true,
    "time": 1715018200
}

5. Delete Metatag

حذف متاتگ از دیتابیس.

RESOURCE /v2/places

Article Places Management

این بخش مربوط به مدیریت مکان‌های نمایش (Places) مقالات است.
مکان‌ها احتمالاً نواحی خاصی در سایت هستند (مثل "اسلایدر اصلی"، "اخبار فوری") که مقالات یا دسته‌بندی‌ها به آن‌ها منتسب می‌شوند.

1. List Places (Index)

لیست مکان‌ها را برمی‌گرداند. برای هر مکان، دسته‌بندی‌های متصل به آن نیز (که در جدول articles_categories تعریف شده‌اند) واکشی و ضمیمه می‌شوند.

فیلترها و منطق کوئری

ساختار پاسخ (Different Response Structure)

توجه کنید که آرایه اصلی در کلید items قرار دارد.

{
  "items": [
    {
      "id": 1,
      "title": "Home Slider",
      "type": "slider",
      "branch": 0,
      "status": 1,
      "categories": [
        {
          "id": 5,
          "title": "Top News",
          "places": "[1, 2]" 
        }
      ]
    }
  ],
  "meta": {
    "total": 1,
    "time": 1715020000
  }
}

2. Create Place (Store)

ایجاد یک مکان جدید در جدول articles_places.

بدنه درخواست (Body Parameters)

3. Show Place

نمایش جزئیات یک مکان خاص.
در اینجا نیز کوئری دوم اجرا می‌شود تا تمام دسته‌بندی‌هایی که این مکان در فیلد places (JSON) آن‌ها وجود دارد، پیدا شده و به خروجی اضافه شوند.

4. Update Place

ویرایش اطلاعات مکان. پارامترها مشابه متد Store است.

{
    "status": true,
    "time": 1715020500
}

5. Delete Place

حذف رکورد از جدول articles_places.

RESOURCE /v2/media

Media Management (File Storage)

این ماژول وظیفه مدیریت فایل‌ها و رسانه‌های سیستم را بر عهده دارد.
برخلاف ذخیره‌سازی محلی، این کنترلر مستقیماً با فضای ذخیره‌سازی ابری (Liara Object Storage) در ارتباط است. فایل‌ها بر اساس نوع، شعبه، سال و ماه در پوشه‌بندی‌های منظم ذخیره شده و متادیتای آن‌ها (شامل سایز، مسیر و ارتباط با سایر موجودیت‌ها) در دیتابیس نگهداری می‌شود.

1. Upload File (Store)

Body Parameters

Upload Logic Details

Flowchart (Upload Process)

2. List Media (Index)

لیست فایل‌های آپلود شده به صورت صفحه‌بندی شده (۱۵ تایی).

فیلترهای جستجو (Query Params)

3. Update Media Status

توجه: در متد آپدیت، فایل فیزیکی یا مسیر آن تغییر نمی‌کند. تنها می‌توان وضعیت (Status) فایل را تغییر داد.

{
  "status": 0 // غیرفعال کردن فایل
}

4. Delete Media

عملیات حذف دومرحله‌ای:

GET /v2/travel_requests

Travel Requests List

این اندپوینت لیست درخواست‌های سفر (مانند پرواز، هتل، قطار و ...) را با قابلیت‌های پیشرفته فیلترینگ و غنی‌سازی (Data Enrichment) بازمی‌گرداند.
نکته متمایز این کنترلر، منطق Scoping (تعیین سطح دسترسی بر اساس گروه کاربری) و همچنین اتصال به چندین جدول (Operators, Customers, Colleagues, Cities, Factors) و دیتابیس Redis برای ساخت یک آبجکت پاسخ کامل است.

List Requests (Index)

Query Parameters

Logic Details

Flowchart (Request Processing)

Response Structure

{
  "items": [
    {
      "id": 123,
      "branch": 1,
      "requester_id": { "id": 50, "first_name": "...", "last_name": "..." }, // Object (Customer or Colleague)
      "origin": { "id": 1, "fa_name": "تهران", "en_name": "Tehran" },
      "destination": { "id": 2, "fa_name": "مشهد", "en_name": "Mashhad" },
      "reference": {
         "id": 99,
         "serial": 10055, // Original + 10000
         "title": "تور مشهد" // From Redis
      },
      "accommodation": {
         "title": { "fa": "هتل درویشی" },
         "category": { "title": "hotel", "subtitle": false }
      },
      "title": "تهران به مشهد هتل درویشی از 1403/01/01 تا 1403/01/04", // Generated String
      "details": { ... } // Decoded JSON
      // ... other fields
    }
  ],
  "meta": {
    "timestamp": 1715000000,
    "table": {
      "total": 100,
      "per_page": 30,
      "current_page": 1,
      "last_page": 4,
      "from": 1,
      "to": 30,
      "next_page": 2
    }
  }
}

POST /v2/travel_requests/status/{id}

Change Request Status

این اندپوینت برای تغییر وضعیت یک درخواست سفر و همچنین تخصیص اپراتور مسئول استفاده می‌شود.
نکته مهم در این متد، منطق شرطی برای ثبت شماره فاکتور (`reference_id`) است که تنها در وضعیت خاصی (وضعیت ۴) اعمال می‌شود.

Update Status & Assign Operator

Body Parameters

Logic Details

Flowchart (Status Change Logic)

Response Example

{
  "payload": {
    "status": true
  },
  "meta": {
    "timestamp": 1715000000
  }
}

RESOURCE /v2/accommodation/facilities

Accommodation Facilities CRUD

این کنترلر وظیفه مدیریت امکانات اقامتگاه‌ها (Facilities) را بر عهده دارد.
ویژگی بارز این پیاده‌سازی، استفاده مستقیم از Query Builder لاراول (`DB::table`) به جای Eloquent Models برای تمامی عملیات‌ها (خواندن، نوشتن، ویرایش و حذف) است که باعث افزایش پرفورمنس در کوئری‌های ساده می‌شود.

List All Facilities

دریافت لیست کامل امکانات بدون هیچ‌گونه فیلترینگ یا صفحه‌بندی.

Response Example

{
  "status": true,
  "time": 1715000000,
  "data": [
    {
      "id": 1,
      "category_id": 5,
      "title_en": "Free WiFi",
      "title_fa": "اینترنت رایگان",
      "icon": "wifi-icon.svg",
      "description": "High speed internet",
      "branch": 1,
      "status": 1
    }
  ]
}

Create Facility

Body Parameters

Implementation Note

سیستم از DB::table('facilities')->insertGetId() برای درج رکورد و دریافت همزمان ID استفاده می‌کند. سپس بلافاصله یک کوئری `SELECT` اجرا می‌شود تا آبجکت کامل ساخته شده را در پاسخ بازگرداند.

Show Facility Details

نمایش جزئیات یک رکورد خاص بر اساس ID.

Update Facility

Body Parameters

Delete Facility

حذف فیزیکی رکورد از دیتابیس (Hard Delete) با استفاده از دستور delete() کوئری بیلدر.

RESOURCE /v2/accommodation/facilities_category

Accommodation Facility Categories

این کنترلر وظیفه مدیریت دسته‌بندی‌های امکانات (Facility Categories) را بر عهده دارد (مانند: تفریحی، بهداشتی، عمومی و ...).
مشابه کنترلر Facilities، این بخش نیز برای افزایش سرعت و کارایی از Query Builder لاراول (`DB::table`) استفاده می‌کند.

List Categories

دریافت لیست کامل دسته‌بندی‌ها بدون فیلترینگ و صفحه‌بندی.

Response Example

{
  "status": true,
  "time": 1715000000,
  "data": [
    {
      "id": 1,
      "title_en": "General",
      "title_fa": "عمومی",
      "icon": "general.svg",
      "description": "General amenities",
      "branch": 1,
      "status": 1
    }
  ]
}

Create Category

Body Parameters

Show Category

نمایش تکی یک دسته‌بندی بر اساس ID.

Update Category

Body Parameters

Delete Category

حذف فیزیکی رکورد از جدول facilities_category.

RESOURCE /v2/accommodation/rules

Accommodation Rules CRUD

این کنترلر وظیفه مدیریت قوانین اقامتگاه (Accommodation Rules) را بر عهده دارد (مانند: قوانین کنسلی، ساعت ورود/خروج، ممنوعیت حیوانات خانگی و ...).
داده‌ها مستقیماً در جدول accommodation_rules ذخیره می‌شوند و برای تمام عملیات دیتابیس از Query Builder استفاده شده است.

List All Rules

دریافت لیست کامل قوانین ثبت شده بدون فیلترینگ یا صفحه‌بندی.

Response Example

{
  "status": true,
  "time": 1715000000,
  "data": [
    {
      "id": 1,
      "accommodation": 105,
      "title_en": "No Smoking",
      "title_fa": "استعمال دخانیات ممنوع",
      "description": "Smoking is strictly prohibited inside the rooms.",
      "status": 1
    }
  ]
}

Create Rule

Body Parameters

Show Rule Details

نمایش جزئیات یک قانون خاص بر اساس شناسه.

Update Rule

Body Parameters

Delete Rule

حذف فیزیکی رکورد از جدول accommodation_rules.

GET /v2/comments

Comments: List & Filter

این اندپوینت برای دریافت لیستی از نظرات (Comments) با قابلیت‌های فیلترینگ و مرتب‌سازی پیشرفته طراحی شده است.
این پیاده‌سازی از Eloquent ORM و API Resources لاراول بهره می‌برد و نتایج را به صورت صفحه‌بندی شده (15 آیتم در هر صفحه) بازمی‌گرداند.

List All Comments

Query Parameters

این اندپوینت از پارامترهای زیر برای فیلتر و مرتب‌سازی پشتیبانی می‌کند:

Response Structure

خروجی این اندپوینت شامل آبجکت‌های data (آرایه‌ای از نظرات)، links (لینک‌های صفحه‌بندی) و meta (اطلاعات متا صفحه‌بندی) است.

Response Example

{
    "status": true,
    "time": 1715000000,
    "data": [
        {
            "id": 10,
            "operatorId": 5,
            "contentId": 152,
            "category": "article",
            "branch": 1,
            "commentText": "مطلب بسیار مفیدی بود، ممنون.",
            "status": "approved",
            "isFlagged": false,
            "replyTo": null,
            "createdAt": "2024-10-22T14:30:00.000000Z"
        }
    ],
    "links": {
        "first": "http://your.api/v2/comments?page=1",
        "last": "http://your.api/v2/comments?page=5",
        "prev": null,
        "next": "http://your.api/v2/comments?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 5,
        "path": "http://your.api/v2/comments",
        "per_page": 15,
        "to": 15,
        "total": 75
    }
}

GET /v2/comments/{id}

Show Comment Details

این اندپوینت جزئیات کامل یک نظر خاص را برمی‌گرداند.
در این متد از قابلیت Route Model Binding لاراول استفاده شده است؛ به این معنی که اگر شناسه‌ی ارسال شده در URL در دیتابیس وجود نداشته باشد، فریم‌ورک به صورت خودکار خطای 404 برمی‌گرداند.

Get Single Comment

Path Parameters

Response Logic

خروجی از طریق CommentResource فرمت‌دهی شده و در قالب استاندارد شامل وضعیت و زمان سرور بازگردانده می‌شود.

Response Example

{
    "status": true,
    "time": 1715000000,
    "data": {
        "id": 10,
        "operatorId": 5,
        "contentId": 152,
        "category": "article",
        "branch": 1,
        "commentText": "مطلب بسیار مفیدی بود، ممنون.",
        "status": "approved",
        "isFlagged": false,
        "replyTo": null,
        "createdAt": "2024-10-22T14:30:00.000000Z",
        "updatedAt": "2024-10-22T14:30:00.000000Z"
    }
}

DELETE /v2/comments/{id}

Delete Comment

این اندپوینت برای حذف یک نظر مشخص از دیتابیس استفاده می‌شود.
این متد نیز از قابلیت Route Model Binding لاراول بهره می‌برد؛ به این معنی که ابتدا مدل Comment متناظر با شناسه ارسالی را پیدا کرده و سپس آن را حذف می‌کند. اگر شناسه نامعتبر باشد، به طور خودکار پاسخ 404 (Not Found) بازگردانده می‌شود.

Delete a Single Comment

Path Parameters

Response on Success

در صورت موفقیت‌آمیز بودن عملیات حذف، یک پاسخ ساده با status: true بازگردانده می‌شود و هیچ داده‌ای در بدنه پاسخ وجود ندارد.

Response Example

{
    "status": true,
    "time": 1715000000
}

POST /v2/comments

Create Comment

این اندپوینت برای ثبت یک نظر جدید در سیستم طراحی شده است. فرآیند ارسال داده به این اندپوینت به دلیل ملاحظات امنیتی، پیچیدگی خاصی دارد.
داده‌های اصلی نظر ابتدا باید به صورت یک آبجکت JSON ساخته شده، سپس با استفاده از کلید عمومی (Public Key) مربوط به هر شعبه رمزنگاری (Encrypt) شوند و در نهایت به صورت Base64 در یک فیلد به نام data به سرور ارسال گردند.

Request Flow and Encryption

Create a New Comment

Request Body Structure (Before Encryption)

آبجکت JSON که باید رمزنگاری و ارسال شود، باید شامل فیلدهای زیر باشد:

Request Examples

مرحله ۱: ساختار JSON خام (قبل از رمزنگاری)

{
    "content_id": 152,
    "category": "article",
    "content": "این یک تست برای ثبت کامنت است.",
    "name": "کاربر تست",
    "email": "test@example.com",
    "phone": "09120000000",
    "status": 0,
    "reply_to": null
}

مرحله ۲: بدنه نهایی درخواست (بعد از رمزنگاری و Base64)

{
    "data": "eyB...[Encrypted & Base64 Encoded String]...SIn0="
}

Server-Side Logic

پس از رمزگشایی موفق، کنترلر به صورت خودکار اطلاعات زیر را به داده‌های دریافتی اضافه کرده و در دیتابیس ذخیره می‌کند:

 

Success Response

در صورت موفقیت، سرور یک پاسخ با کد 200 و حاوی آبجکت نظر جدید که از طریق CommentResource فرمت‌دهی شده، برمی‌گرداند.

{
    "status": true,
    "time": 1715000000,
    "data": {
        "id": 11,
        "operatorId": 5,
        "contentId": 152,
        "category": "article",
        "branch": 1,
        "commentText": "این یک تست برای ثبت کامنت است.",
        "status": "pending",
        "isFlagged": false,
        "replyTo": null,
        "createdAt": "2024-10-23T10:00:00.000000Z",
        "updatedAt": "2024-10-23T10:00:00.000000Z"
    }
}

PUT /v2/comments/{id}

Update Comment

این اندپوینت برای به‌روزرسانی اطلاعات یک نظر موجود استفاده می‌شود. همانند اندپوینت ایجاد نظر، داده‌های ارسالی برای به‌روزرسانی نیز باید ابتدا رمزنگاری شده و سپس ارسال شوند.
این متد از قابلیت Route Model Binding لاراول استفاده می‌کند. به این معنی که لاراول ابتدا به صورت خودکار مدل Comment مربوط به {id} ارسالی در URL را پیدا می‌کند و سپس عملیات به‌روزرسانی را روی آن انجام می‌دهد. اگر شناسه نامعتبر باشد، پاسخ 404 بازگردانده می‌شود.

Encryption Flow

فرآیند رمزنگاری و ارسال داده‌ها برای این اندپوینت دقیقاً مشابه اندپوینت ایجاد نظر (Create Comment) است. خلاصه‌ی مراحل به شرح زیر است:

 

Update an Existing Comment

Path Parameters

Request Body Structure (Before Encryption)

آبجکت JSON که باید رمزنگاری و در فیلد data ارسال شود، می‌تواند شامل فیلدهای زیر باشد. تمام فیلدها اختیاری هستند و فقط فیلدهایی که قصد تغییر آن‌ها را دارید، ارسال کنید.

Request Examples

مرحله ۱: ساختار JSON خام (قبل از رمزنگاری)

{
    "content": "متن ویرایش شده نظر.",
    "status": 1,
    "flagged": false
}

مرحله ۲: بدنه نهایی درخواست (بعد از رمزنگاری و Base64)

{
    "data": "AbC...[Encrypted & Base64 Encoded String]...dEfG=="
}

Success Response

در صورت موفقیت‌آمیز بودن عملیات، یک پاسخ با کد 200 و وضعیت true بازگردانده می‌شود. برخلاف متد store، در پاسخ این متد، آبجکت داده وجود ندارد.

{
    "status": true,
    "time": 1715000000
}

Error Responses

POST /v2/comments/{commentId}/{action}

Like or Dislike a Comment

این اندپوینت برای ثبت لایک یا دیسلایک برای یک نظر مشخص استفاده می‌شود. عملیات مورد نظر (لایک یا دیسلایک) از طریق پارامتر action در URL تعیین می‌گردد.
این متد به صورت اتمیک عمل نمی‌کند، اما شمارنده‌های likes و dislikes را در مدل Comment یک واحد افزایش می‌دهد.

Increment Like/Dislike Counter

Path Parameters

Request Body

این اندپوینت به هیچ داده‌ای در بدنه درخواست (Request Body) نیاز ندارد.

Server-Side Logic

 

 

Success Response

در صورت موفقیت‌آمیز بودن عملیات، سرور یک پاسخ با کد 200 به همراه مقادیر به‌روز شده‌ی شمارنده‌های likes و dislikes برمی‌گرداند.

{
    "status": true,
    "time": 1715000000,
    "data": {
        "likes": 25,
        "dislikes": 3
    }
}

Error Response

DELETE /v2/comments/{commentId}/{action}

Remove a Like or Dislike from a Comment

این اندپوینت برای کاهش (حذف) یک لایک یا دیسلایک از یک نظر مشخص استفاده می‌شود. این عملیات، معکوس اندپوینت POST برای افزودن لایک/دیسلایک است و به کاربر اجازه می‌دهد تا رأی خود را پس بگیرد.

Decrement Like/Dislike Counter

Path Parameters

Request Body

این اندپوینت به هیچ داده‌ای در بدنه درخواست (Request Body) نیاز ندارد.

فلوچارت منطق سرور (Server Logic Flow)

روند پردازش درخواست در سمت سرور به شرح زیر است:

Success Response

در صورت موفقیت‌آمیز بودن عملیات، سرور یک پاسخ با کد 200 به همراه مقادیر به‌روز شده‌ی شمارنده‌های likes و dislikes برمی‌گرداند.

{
    "status": true,
    "time": 1715000000,
    "data": {
        "likes": 24,
        "dislikes": 2
    }
}

Error Response

POST /v2/invoice/process

Hub: Create Payment Invoice

این اندپوینت برای ایجاد یک صورت‌حساب قابل پرداخت طراحی شده است.
فرآیند شامل ثبت یک "قبض" (Bill)، یافتن یک درگاه پرداخت فعال، تولید یک فاکتور منحصر به فرد با اسلاگ (Slug) یکتا، و در نهایت بازگرداندن یک لینک پرداخت برای کاربر است.

Request Overview

Access Control

Body Parameters

Logic Details

فرآیند ایجاد لینک پرداخت دارای چندین مرحله کلیدی است:

Response Structure

پاسخ موفق

{
    "payload": {
        "status": "payment_link",
        "amount": 50000,
        "url": "https://ipg.airplus.app/invoice/payment/aB3xZ7cR"
    },
    "meta": {
        "timestamp": 1715001200
    }
}

پاسخ‌های خطا (نمونه)

{
  "error": {
    "code": 1000,
    "message": "درگاه پرداخت فعال یافت نشد"
  }
}

Flowchart

POST /v2/invoice/payment/details

Hub: Get Invoice Payment Details

این اندپوینت برای استعلام وضعیت و دریافت جزئیات تراکنش یک فاکتور خاص استفاده می‌شود.
معمولاً پس از بازگشت کاربر از درگاه بانک، کلاینت با ارسال slug فاکتور به این اندپوینت، وضعیت نهایی پرداخت (موفق یا ناموفق)، شماره پیگیری، شماره کارت و علت خطا (در صورت شکست) را دریافت می‌کند.

Request Overview

Access Control

Body Parameters

Logic Details

فرآیند استعلام شامل مراحل دقیق زیر است:

Response Structure

پاسخ موفق (پرداخت تایید شده)

{
    "payload": {
        "type": "hotel",
        "amount": 1500000,
        "tracking_code": "17459821",
        "drive": "sep",
        "datetime": "2024-05-18 14:30:00",
        "card": "610433******1234",
        "return_url": "https://client-app.com/callback"
    },
    "meta": {
        "timestamp": 1716025200
    }
}

پاسخ ناموفق (خطای پرداخت یا یافت نشدن)

{
    "payload": {
        "type": "flight",
        "amount": 5000000,
        "tracking_code": null,
        "drive": "behpardakht",
        "datetime": "2024-05-18 14:35:00",
        "card": null,
        "return_url": null
    },
    "meta": {
        "timestamp": 1716025500
    },
    "error": {
        "code": 1000,
        "message": "خطای مربوط به پرداخت"
    }
}

Flowchart

POST /v2/invoice/payment/wallet

Hub: Pay using Wallet

این اندپوینت یک فرآیند پرداخت ترکیبی را مدیریت می‌کند که به کاربر اجازه می‌دهد از کیف پول داخلی شعبه برای تسویه حساب استفاده کند.
این مسیر دو سناریوی اصلی دارد:
۱. موجودی کافی: مبلغ کامل از کیف پول کسر شده و تراکنش با موفقیت ثبت می‌شود.
۲. موجودی ناکافی: موجودی کیف پول به طور کامل مصرف شده و برای باقیمانده مبلغ، یک لینک پرداخت آنلاین (از طریق اندپوینت createInvoice) ایجاد می‌شود.

Request Overview

Access Control

Body Parameters

Logic Details

این اندپوینت فرآیند پیچیده‌ای را دنبال می‌کند که به دو شاخه اصلی تقسیم می‌شود:

Response Structure

پاسخ موفق (پرداخت کامل از کیف پول)

{
    "payload": {
        "status": "succeed",
        "id": 542,
        "datetime": "2024-05-18 15:00:00"
    },
    "meta": {
        "timestamp": 1716027000
    }
}

پاسخ موفق (پرداخت ترکیبی - موجودی ناکافی)

{
    "payload": {
        "status": "payment_link",
        "amount": 450000,
        "url": "https://ipg.airplus.app/invoice/payment/kL9sW1aP"
    },
    "meta": {
        "timestamp": 1716027100
    }
}

پاسخ‌های خطا

{
  "error": {
    "code": 1000,
    "message": "صورتحساب یافت نشد."
  },
  "meta": {
    "timestamp": 1716027200
  }
}

Flowchart

GET /v2/core/bill/{type}

Hub: Get Branch Bills

این اندپوینت برای دریافت لیست صورتحساب‌های پرداخت نشده (`status = 1`) یک شعبه خاص طراحی شده است.
کلاینت می‌تواند با ارسال نوع سرویس (مانند `hotel`, `flight` و...)، فقط صورتحساب‌های مربوط به آن سرویس را فیلتر و دریافت کند. خروجی شامل جزئیات کامل هر صورتحساب به همراه مبلغ نهایی قابل پرداخت است.

Request Overview

Access Control

URL Parameters

Logic Details

فرآیند دریافت صورتحساب‌ها به شرح زیر است:

Response Structure

پاسخ موفق (در صورت یافتن صورتحساب)

{
    "items": [
        {
            "id": 101,
            "details": {
                "month_title": "آذر ماه"
            },
            "description": "بابت رزرو هتل اسپیناس پالاس",
            "amount": 5000000,
            "tax": 450000,
            "discount": 0,
            "markup": 0,
            "total": 5450000,
            "created_at": "2025-12-09 10:00:00",
            "updated_at": "2025-12-09 10:00:00",
            "expired_at": "2025-12-11 10:00:00"
        }
    ],
    "meta": {
        "timestamp": 1733735400
    }
}

پاسخ موفق (در صورت عدم وجود صورتحساب)

{
    "items": false,
    "meta": {
        "timestamp": 1733735400
    }
}

Flowchart

GET /v2/core/hub/information

Hub: Get Basic Information

این اندپوینت به عنوان یک مسیر عمومی برای دریافت اطلاعات پایه‌ای و مرکزی (Hub Information) عمل می‌کند. رفتار این اندپوینت بر اساس پارامتر action که در کوئری استرینگ ارسال می‌شود، تغییر می‌کند.
در حال حاضر، این مسیر تنها برای دریافت لیست تمام دفاتر (Offices) پیاده‌سازی شده است.

Request Overview

Access Control

Query Parameters

Logic Details

منطق این اندپوینت کاملاً به پارامتر action وابسته است:

Response Structure

پاسخ موفق (برای action=offices)

{
    "items": [
        {
            "id": 25,
            "title": {
                "fa": "10025 - آژانس تابان",
                "en": "10025 - Taban Agency"
            }
        },
        {
            "id": 26,
            "title": {
                "fa": "10026 - آژانس سپهر",
                "en": "10026 - Sepehr Agency"
            }
        }
    ],
    "meta": {
        "timestamp": 1733736000
    }
}

پاسخ برای سایر مقادیر action (یا عدم ارسال آن)

{
    "items": null,
    "meta": {
        "timestamp": 1733736100
    }
}

Flowchart

GET /v2/core/hub/analyze

Hub: Flight Reservation Analysis

این اندپوینت یک گزارش تحلیلی جامع از تمام رزروهای پرواز آنلاین (`product='online'`, `byproduct='aircraft'`) ارائه می‌دهد. داده‌ها بر اساس سال شمسی، تأمین‌کننده (Supplier)، و تأمین‌کننده سیستمی (System Supplier) دسته‌بندی و agregare می‌شوند. خروجی شامل تعداد کل رزروها و مجموع مبالغ خرید در هر دسته‌بندی است.

Request Overview

Access Control

Logic Details

فرآیند تحلیل داده‌ها در این اندپوینت طی چندین مرحله پیچیده انجام می‌شود:

Response Structure

پاسخ موفق

{
    "payload": {
        "years": {
            "1404": { // سال شمسی
                "suppliers": {
                    "55": { // شناسه Supplier
                        "id": 55,
                        "title": "Ghasreshirin", // نام استخراج شده از جدول colleagues
                        "total": {
                            "count": 10, // کل رزروها از این Supplier در سال 1404
                            "paid": 95000000 // مجموع خرید از این Supplier در سال 1404
                        },
                        "months": {
                            "08": { // ماه شمسی
                                "total": {
                                    "count": 4,
                                    "paid": 38000000
                                }
                            },
                            "09": {
                                "total": {
                                    "count": 6,
                                    "paid": 57000000
                                }
                            }
                        }
                    }
                },
                "system_suppliers": {
                    "10": { // شناسه SystemSupplier
                        "id": 10,
                        "title": "Parsian System",
                        "total": {
                            "count": 10, // کل رزروها از این SystemSupplier در سال 1404
                            "paid": 95000000
                        },
                        "months": {
                            "08": { /* ... */ },
                            "09": { /* ... */ }
                        }
                    }
                },
                "total": { // مجموع کل برای سال 1404
                    "count": 10,
                    "paid": 95000000
                }
            }
        },
        "total": { // مجموع کل در تمام سال‌ها
            "count": 10,
            "paid": 95000000
        }
    },
    "meta": {
        "timestamp": 1733736600
    }
}

Flowchart

GET /v2/core/hub/reservation

Hub: Get Master Reservation List

این اندپوینت یک لیست جامع و صفحه‌بندی شده از تمام رزروهای ثبت شده در سیستم مرکزی (Hub) را برمی‌گرداند. برای هر رزرو، اطلاعات از جداول مختلفی مانند offices، factor_items، colleagues، و wallet استخراج و با داده‌های اصلی ادغام می‌شود تا یک خروجی کامل و غنی‌شده ارائه دهد.

Request Overview

Access Control

Query Parameters (Custom Pagination)

این اندپوینت از یک ساختار صفحه‌بندی سفارشی استفاده می‌کند که معمولاً توسط کتابخانه‌های جدولی مانند (jQuery DataTables) ارسال می‌شود. پارامترها باید در یک آبجکت به نام paginate ارسال شوند.

Example URL: /v2/core/hub/reservation?paginate[length]=15&paginate[start]=0

Logic Details

فرآیند دریافت و پردازش رزروها بسیار گسترده است و شامل مراحل زیر می‌شود:

Response Structure

پاسخ موفق

{
    "items": [
        {
            "id": 12345,
            "branch": "آژانس تابان", // از جدول offices
            "item_id": 54321,
            "operator": { // از متد getOperators
                "id": 101,
                "text": "1100 - علی اکبری",
                "query": { /* ... details ... */ }
            },
            "service": "Ghasreshirin", // نام تبدیل شده
            "sub_service": "Parsian System", // نام تبدیل شده
            "supplier_details": { /* آبجکت JSON */ },
            "details": { /* آبجکت JSON */ },
            "status": "issued",
            "created_at": "2025-12-09T12:00:00.000000Z",
            
            // --- Fields added in the loop ---
            "title_item": "هواپیما تهران به مشهد | ۱۴۰۴/۰۹/۱۸ ۱۲:۳۰ | W5065 | ماهان", // از getReferenceItemTitle
            "item": { // آبجکت کامل از factor_items
                "id": 54321,
                "product": "online",
                "byproduct": "aircraft",
                "details": { /* ... */ },
                "buy": 5400000,
                "sell": 5500000
                /* ... */
            },
            "refund": { // یا false اگر وجود نداشته باشد
                "id": 789,
                "credit": 5000000,
                "description": "استرداد بابت کنسلی پرواز"
            }
        }
    ],
    "meta": {
        "timestamp": 1733737200,
        "table": {
            "total": 500,
            "per_page": 15,
            "current_page": 1,
            "last_page": 34,
            "from": 1,
            "to": 15
        }
    }
}

Flowchart

POST /v2/core/hub/reservation

Hub: Create Manual Wallet Transaction

این اندپوینت برای ثبت دستی یک تراکنش مالی (سند) در کیف پول (`wallet`) استفاده می‌شود. اگرچه URL به "رزرو" اشاره دارد، اما عملکرد اصلی آن ایجاد یک رکورد بدهکار (`debit`) یا بستانکار (`credit`) برای یک شعبه خاص است. این عملیات معمولاً توسط مدیران هاب برای اصلاح حساب یا ثبت سند دستی انجام می‌شود.

Request Overview

Access Control

Request Body Parameters

Logic Details

فرآیند ثبت در کنترلر به صورت زیر است:

Response Structure

پاسخ موفق

پاسخ خطا

{
    "error": {
        "code": 1000,
        "message": "SQLSTATE[23000]: Integrity constraint violation..." // پیام خطا
    },
    "meta": {
        "timestamp": 1733737200
    }
}

Flowchart

PATCH /v2/core/hub/reservation/refund

Hub: Process Reservation Refund

این اندپوینت برای انجام عملیات استرداد (Refund) یک رزرو ثبت‌شده در سیستم هاب استفاده می‌شود. فرآیند شامل محاسبه مبلغ جریمه (به صورت درصدی یا مبلغ ثابت)، ثبت مبلغ قابل بازگشت به عنوان یک تراکنش بستانکار در کیف پول شعبه، و در نهایت به‌روزرسانی وضعیت رزرو به "استرداد شده" است.

Request Overview

Access Control

Request Body Parameters

Logic Details

فرآیند استرداد در کنترلر به صورت گام‌به‌گام زیر انجام می‌شود:

Response Structure

پاسخ موفق

پاسخ خطا

{
    "error": {
        "code": 1000,
        "message": "رزرو یافت نشد."
    }
}

Flowchart

PATCH /v2/core/hub/reservation/refund/undo

Hub: Undo Reservation Refund

این اندپوینت برای لغو یک عملیات استرداد (Refund) که قبلاً انجام شده، استفاده می‌شود. فرآیند شامل پیدا کردن تراکنش بستانکاری مربوط به استرداد، بررسی کافی بودن موجودی کیف پول شعبه برای بازگرداندن آن مبلغ، ایجاد یک تراکنش بدهکاری جدید برای خنثی کردن تراکنش قبلی، و در نهایت بازگرداندن وضعیت رزرو به حالت اولیه (فعال) است.

Request Overview

Access Control

Request Body Parameters

Logic Details

فرآیند لغو استرداد به صورت گام‌به‌گام زیر است:

Response Structure

پاسخ موفق

پاسخ‌های خطا

۱. تراکنش استرداد یافت نشد:

{
    "error": {
        "code": 1000,
        "message": "استرداد یافت نشد"
    }
}

۲. موجودی کیف پول ناکافی است:

{
    "error": {
        "code": 1000,
        "message": "موجودی کیف پول جهت برگشت این آیتم کافی نیست."
    },
    "meta": {
        "timestamp": 1733737200
    }
}

۳. بروز خطای عمومی (Exception):

{
    "error": {
        "code": 1000,
        "message": "General exception message..."
    },
    "meta": {
        "timestamp": 1733737200
    }
}

Flowchart

POST /v2/flights/ticket/information/{type}

L. Flight Ticket Information (Nira)

این اندپوینت برای استعلام اطلاعات دقیق بلیط‌های صادر شده از طریق سیستم تامین‌کننده نیرا (Nira) استفاده می‌شود. این سرویس قابلیت جستجو بر اساس "شماره بلیط" یا "PNR" را دارد و به صورت هوشمند وضعیت استرداد (Refund) بلیط را بررسی کرده و در صورت نیاز، جزئیات مالی استرداد (جریمه و مبلغ پرداختی) را از سیستم نیرا استخراج می‌کند.

Request Overview

Access Control

Path Parameters

Request Body Parameters

Logic Details

منطق پردازش در کنترلر به شرح زیر است:

Response Structure

پاسخ موفق (200 OK)

{
    "items": [
        {
            "TicketNo": "096-23651478",
            "PassengerName": "TEST USER",
            "StatusCode": "R",  // وضعیت استرداد
            "RefundData": {     // داده‌های استخراج شده استرداد
                "RefundDate": "14DEC2025",
                "Penalty": 500000,
                "RefundedAmount": 4500000
            },
            // ... سایر اطلاعات بلیط
        }
    ],
    "meta": {
        "timestamp": 1733738000
    }
}

پاسخ خطا

Flowchart

POST /v2/flights/routes/update

M. Update Airline Active Routes (Manual Trigger)

این اندپوینت برای بروزرسانی دستی جدول مسیرهای فعال (Airline Active Routes) استفاده می‌شود. سیستم با فراخوانی این سرویس، موجودی پروازها را برای ۷ روز آینده (از فردا) به تفکیک روزهای هفته بررسی کرده و در دیتابیس ذخیره می‌کند. این فرآیند با ارسال درخواست‌های متوالی به وب‌سرویس تامین‌کننده (Nira) انجام می‌شود.

Request Overview

Access Control

Request Body Parameters

Logic Details

منطق پردازش در CronController بسیار پیچیده است و شامل مراحل زیر می‌باشد:

Response Structure

پاسخ موفق (200 OK)

{
    "payload": {
        "Status": true,
        "Time": 1733738500
    },
    "meta": {
        "timestamp": 1733738500
    }
}

Flowchart

POST /v2/flights/routes/min_price

N. Flight Route Min Price (Cache)

این اندپوینت برای دریافت حداقل قیمت پرواز در یک مسیر خاص (مبدا و مقصد) استفاده می‌شود. داده‌های این سرویس مستقیماً از Redis Cache خوانده می‌شوند و دو حالت عملکرد دارد: دریافت قیمت برای یک تاریخ خاص، یا دریافت لیست تمام قیمت‌های موجود (Calendar View) برای آن مسیر.

Request Overview

Access Control

Request Body Parameters

Logic Details

منطق کنترلر بر اساس وجود یا عدم وجود پارامتر date به دو شاخه تقسیم می‌شود:

Response Structure

حالت ۱: پاسخ موفق (تاریخ مشخص)

{
    "payload": {
        "origin": "MHD",
        "destination": "THR",
        "date": "2025-12-10",
        "min_price": 1500000
    },
    "meta": {
        "timestamp": 1733739000
    }
}

حالت ۲: پاسخ موفق (لیست کلی)

{
    "items": [
        {
            "origin": "MHD",
            "destination": "THR",
            "date": "2025-12-10",
            "min_price": 1500000
        },
        {
            "origin": "MHD",
            "destination": "THR",
            "date": "2025-12-11",
            "min_price": 1450000
        }
    ],
    "meta": {
        "timestamp": 1733739000
    }
}

پاسخ خطا (یافت نشد)

فقط در حالت "تک تاریخ" رخ می‌دهد:

{
    "error": {
        "code": 404,
        "message": "not found."
    },
    "meta": {
        "timestamp": 1733739000
    }
}

Flowchart

GET /v2/core/application_interface

O. List Application Interfaces (Core)

این اندپوینت برای دریافت لیست رابط‌های نرم‌افزاری (Application Interfaces) استفاده می‌شود. خروجی این سرویس لیستی از شعب (Offices) است که تنظیمات و دسترسی‌های مربوطه (مانند APIهای ایرلاین‌ها، دسترسی همکاران و...) به عنوان زیرمجموعه آن‌ها گروه‌بندی شده‌اند. همچنین امکان دریافت مانده حساب کیف پول هر شعبه نیز به صورت اختیاری وجود دارد.

Request Overview

Access Control

Query Parameters (Filters)

Logic Details

فرآیند پردازش داده‌ها شامل مراحل زیر است:

Response Structure

نمونه پاسخ موفق (JSON)

{
    "items": [
        {
            "id": 1,
            "title_fa": "دفتر مرکزی",
            "title_en": "Headquarters",
            "brand_fa": "برند نمونه",
            "items": [
                {
                    "id": 105,
                    "branch": 1,
                    "service": { "id": "nira", "title": "nira" },
                    "type": { "id": "api", "title": "api" },
                    "object_type": { "id": "colleague", "title": "colleague" },
                    "object": {
                        "id": 50,
                        "first_name": "Ali",
                        "last_name": "Rezaei",
                        "serial": "12345"
                    },
                    "status": 1
                }
            ],
            "balance": {
                "credit": 1000000,
                "debit": 200000,
                "balance": 800000,
                "diagnosis": "creditor"
            }
        }
    ],
    "meta": {
        "timestamp": 1733745000
    }
}

Flowchart

GET /v2/core/application_interface/{id}

P. Show Application Interface (Single Item)

این اندپوینت برای دریافت جزئیات کامل یک رابط نرم‌افزاری خاص استفاده می‌شود. با ارسال شناسه (ID) رکورد، سیستم اطلاعات آن را از دیتابیس استخراج کرده و پس از استانداردسازی فیلدها و غنی‌سازی اطلاعات (مانند اطلاعات همکار)، خروجی را بازمی‌گرداند.

Request Overview

Access Control

Path Parameters

Logic Details

منطق پردازش این متد به شرح زیر است:

Response Structure

نمونه پاسخ موفق (200 OK)

{
    "payload": {
        "id": 105,
        "branch": 1,
        "service": {
            "id": "nira",
            "title": "nira"
        },
        "type": {
            "id": "api",
            "title": "api"
        },
        "object_type": {
            "id": "colleague",
            "title": "colleague"
        },
        "object": {
            "id": 50,
            "first_name": "Ali",
            "last_name": "Rezaei",
            "office": 1,
            "status": 1,
            "serial": "12345"
        },
        "status": 1,
        "created_at": "2024-01-01 12:00:00"
    },
    "meta": {
        "timestamp": 1733748000
    }
}

Flowchart

DELETE /v2/core/application_interface/{id}

Q. Delete Application Interface (Core)

این اندپوینت برای حذف یک رابط نرم‌افزاری از سیستم استفاده می‌شود. عملیات حذف به صورت مستقیم بر روی دیتابیس انجام شده و غیرقابل بازگشت است (Hard Delete).

Request Overview

Access Control

Path Parameters

Logic Details

منطق پردازش این متد بسیار ساده و مستقیم است:

Response Structure

نمونه پاسخ موفق (JSON)

در این نمونه، عدد 1 نشان‌دهنده حذف موفقیت‌آمیز یک رکورد است.

{
    "payload": 1,
    "meta": {
        "timestamp": 1733751000
    }
}

Flowchart

POST /v2/core/application_interface

Store Application Interface (Create New)

این اندپوینت برای ایجاد یک رابط نرم‌افزاری جدید در سیستم استفاده می‌شود. نکته حائز اهمیت در این متد، نحوه ارسال پارامترهای دسته‌بندی است؛ فیلدهایی مانند نوع و سرویس باید به صورت آبجکت ارسال شوند تا سیستم بتواند عنوان (Title) آن‌ها را استخراج و ذخیره کند.

Request Overview

Access Control

Body Parameters

پارامترهای زیر باید در بدنه درخواست (Body) به صورت JSON ارسال شوند:

Logic Details

فرآیند ذخیره‌سازی به شرح زیر است:

Response Structure

نمونه Body ارسالی (Request)

{
    "branch": 1,
    "type": { "id": "api", "title": "api" },
    "service": { "id": "nira", "title": "nira" },
    "object_type": { "id": "colleague", "title": "colleague" },
    "object": { "id": 50, "name": "Ali..." },
    "url": "https://api.example.com",
    "username": "user1",
    "password": "pass123",
    "data": "API_KEY_STRING",
    "priority": 0,
    "status": 1
}

نمونه پاسخ موفق (200 OK)

{
    "payload": {
        "id": 106,
        "branch": 1,
        "type": "api",
        "service": "nira",
        "object_type": "colleague",
        "object": 50,
        "url": "https://api.example.com",
        "username": "user1",
        "password": "pass123",
        "data": "API_KEY_STRING",
        "priority": 0,
        "status": 1,
        "created_at": null,
        "updated_at": null
    },
    "meta": {
        "timestamp": 1733752000
    }
}

Flowchart

PUT /v2/core/application_interface/{id}

Update Application Interface

این اندپوینت برای ویرایش اطلاعات یک رابط نرم‌افزاری موجود استفاده می‌شود. با ارسال شناسه رکورد و داده‌های جدید، سیستم رکورد را بروزرسانی می‌کند. همانند متد ثبت، پارامترهای دسته‌بندی باید به صورت آبجکت ارسال شوند تا سیستم بتواند مقادیر مورد نیاز (Title یا ID) را از آن‌ها استخراج کند.

Request Overview

Access Control

Path Parameters

Body Parameters

ساختار بادی درخواست مشابه متد ثبت (Store) است:

Logic Details

فرآیند بروزرسانی به شرح زیر است:

Response Structure

نمونه Body ارسالی (JSON)

{
    "branch": 1,
    "type": { "id": "api", "title": "api" },
    "service": { "id": "parto", "title": "parto" },
    "object_type": { "id": "branch", "title": "branch" },
    "object": { "id": 2 },
    "url": "https://new-api.com",
    "username": "admin",
    "password": "newpass",
    "data": "{}",
    "priority": 5,
    "status": 1
}

نمونه پاسخ موفق (200 OK)

{
    "payload": {
        "id": 105,
        "branch": 1,
        "type": "api",
        "service": "parto",
        "object_type": "branch",
        "object": 2,
        "url": "https://new-api.com",
        "username": "admin",
        "password": "newpass",
        "data": "{}",
        "priority": 5,
        "status": 1,
        "created_at": "2024-01-01...",
        "updated_at": null
    },
    "meta": {
        "timestamp": 1733753000
    }
}

Flowchart

GET /v2/core/application_interface_types

List Application Interface Types

این اندپوینت لیست ثابت و از پیش تعریف‌شده‌ای از انواع (Types) قابل قبول برای رابط‌های نرم‌افزاری را بازمی‌گرداند. این لیست معمولاً برای پر کردن Dropdown‌ها در فرم‌های ایجاد یا ویرایش (اندپوینت‌های R و S) استفاده می‌شود تا کاربر یکی از مقادیر مجاز را انتخاب کند.

Request Overview

Access Control

Logic Details

این متد هیچ پردازش دیتابیسی انجام نمی‌دهد و یک آرایه استاتیک از مقادیر زیر را برمی‌گرداند:

Response Structure

نمونه پاسخ موفق (200 OK)

{
    "items": [
        { "id": "recaptcha", "title": "recaptcha" },
        { "id": "sms", "title": "sms" },
        { "id": "ami", "title": "ami" },
        { "id": "ftp", "title": "ftp" },
        { "id": "support", "title": "support" },
        { "id": "api", "title": "api" },
        { "id": "smtp", "title": "smtp" }
    ],
    "meta": {
        "timestamp": 1733754000
    }
}

Flowchart

GET /v2/core/application_interface_services

List Application Interface Services

این اندپوینت لیست ثابت و از پیش تعریف‌شده‌ای از سرویس‌ها (Services) قابل انتخاب برای رابط‌های نرم‌افزاری را بازمی‌گرداند. این مقادیر مشخص می‌کنند که یک رابط خاص (مثلاً یک API Key) مربوط به کدام سرویس‌دهنده یا پلتفرم خارجی است.

Request Overview

Access Control

Logic Details

این متد هیچ پردازش دیتابیسی انجام نمی‌دهد و یک آرایه استاتیک شامل لیست سرویس‌دهندگان پشتیبانی شده را برمی‌گرداند:

Response Structure

نمونه پاسخ موفق (200 OK)

{
    "items": [
        { "id": "airplus", "title": "airplus" },
        { "id": "google", "title": "google" },
        { "id": "ami", "title": "ami" },
        { "id": "gmini", "title": "gmini" },
        { "id": "irnoti", "title": "irnoti" },
        { "id": "issabel", "title": "issabel" },
        { "id": "goftino", "title": "goftino" },
        { "id": "navasan", "title": "navasan" },
        { "id": "ravis", "title": "ravis" },
        { "id": "sepehr", "title": "sepehr" },
        { "id": "nira", "title": "nira" },
        { "id": "liara", "title": "liara" },
        { "id": "tport", "title": "tport" },
        { "id": "sepehr_hotel", "title": "sepehr_hotel" },
        { "id": "jibit", "title": "jibit" },
        { "id": "snapptrip_hotel", "title": "snapptrip_hotel" }
    ],
    "meta": {
        "timestamp": 1733754000
    }
}

Flowchart

GET /v2/core/application_interface_object_types

List Application Interface Object Types

این اندپوینت لیست ثابت انواع موجودیت‌های (Object Types) قابل اتصال به رابط‌های نرم‌افزاری را بازمی‌گرداند. این فیلد تعیین می‌کند که شناسه موجود در فیلد object به کدام جدول دیتابیس (مثلاً جدول همکاران) اشاره دارد.

Request Overview

Access Control

Logic Details

این متد در حال حاضر تنها یک مقدار ثابت را بازمی‌گرداند که نشان‌دهنده اتصال رابط به موجودیت «همکار» است:

Response Structure

نمونه پاسخ موفق (200 OK)

{
    "items": [
        {
            "id": "colleague",
            "title": "colleague"
        }
    ],
    "meta": {
        "timestamp": 1733754000
    }
}

Flowchart

PUT /v2/core/application_interface/status/{id}

Update Application Interface Status

این اندپوینت به منظور تغییر سریع وضعیت (Status) یک رابط نرم‌افزاری استفاده می‌شود. برخلاف متد ویرایش کلی، این متد تنها فیلد status را در دیتابیس بروزرسانی می‌کند.

Request Overview

Access Control

Parameters

Logic Details

عملیات به صورت مستقیم روی دیتابیس انجام می‌شود:

Response Structure

نمونه پاسخ موفق (200 OK)

{
    "payload": {
        "id": 15,
        "branch_id": 1,
        "type": "sms",
        "service": "irnoti",
        "object_type": "colleague",
        "object": 102,
        "settings": "{\"apiKey\":\"...\"}",
        "status": "inactive",
        "created_at": "2023-01-01 12:00:00",
        "updated_at": "2023-12-09 14:30:00"
    },
    "meta": {
        "timestamp": 1733754000
    }
}

Flowchart

RESOURCE /v2/scrumboard/boards

List Scrum Boards

این اندپوینت لیست بوردهای اسکرام را بازیابی می‌کند. نتایج شامل بوردهایی است که کاربر جاری یا سازنده (Owner) آن‌هاست و یا به عنوان عضو (Member) به آن‌ها دعوت شده است.

Parameters

Logic Details

سیستم پردازش‌های زیر را هنگام دریافت لیست انجام می‌دهد:

Success Response

{
    "items": [
        {
            "id": 10,
            "title": "پروژه توسعه",
            "operator_id": 55,
            "members": [
                { "id": 60, "first_name": "Ali", "last_name": "Rezaei", "avatar": "..." }
            ],
            "lists": [
                { "id": 1, "title": "درحال انجام", "priority": 2 }
            ],
            "labels": [
                { "id": 5, "title": "فوری" }
            ]
        }
    ],
    "meta": { "timestamp": 1733754000 }
}

Create Scrum Board

این اندپوینت یک بورد اسکرام جدید ایجاد می‌کند. نکته مهم در این متد، ایجاد خودکار لیست‌ها و لیبل‌های پیش‌فرض همزمان با ساخت بورد است تا بورد بلافاصله قابل استفاده باشد.

Parameters

Logic Details (Default Data)

پس از درج بورد، سیستم موارد زیر را به صورت خودکار ایجاد می‌کند:

Success Response

{
    "payload": {
        "id": 12,
        "title": "New Board",
        "lists": [ ... ],
        "labels": [ ... ]
    },
    "meta": { "timestamp": 1733754000 }
}

Show Scrum Board

دریافت اطلاعات کامل یک بورد خاص شامل اعضا، لیست‌ها و لیبل‌ها. دسترسی به داده‌های خروجی این متد محدود به سازنده یا اعضای آن بورد است.

Path Parameters

Logic Details

این متد چک می‌کند که آیا کاربر درخواست کننده (`operator`) یا سازنده بورد است و یا شناسه او در فیلد JSON `members` وجود دارد. در غیر این صورت (یا اگر بورد وجود نداشته باشد)، نتیجه خالی برمی‌گرداند.

Success Response

{
    "payload": {
        "id": 12,
        "title": "Board Title",
        "members": [...],
        "lists": [...],
        "labels": [...]
    },
    "meta": { "timestamp": 1733754000 }
}

Update Scrum Board

بروزرسانی اطلاعات بورد. نکته امنیتی مهم این است که برخلاف نمایش، فقط سازنده بورد (Operator ID منطبق) اجازه ویرایش را دارد.

Parameters

Error Response (Forbidden)

اگر کاربر جاری سازنده بورد نباشد:

{
    "error": {
        "code": 1001,
        "message": "You do not have permission to edit this scrum board."
    },
    "meta": { "timestamp": 1733754000 }
}

Success Response

{
    "payload": { "id": 12, "title": "Updated Title", ... },
    "meta": { "timestamp": 1733754000 }
}

Delete Scrum Board

حذف کامل بورد از دیتابیس. این عملیات نیز مانند ویرایش، تنها توسط سازنده بورد قابل انجام است.

Logic Details

ابتدا مالکیت بورد بررسی می‌شود. اگر کاربر جاری سازنده نباشد، خطای کد 1001 بازگردانده می‌شود. در صورت موفقیت، رکورد از جدول scrumboard_boards حذف می‌شود.

Success Response

{
    "payload": 1, // تعداد رکوردهای حذف شده
    "meta": {
        "timestamp": 1733754000
    }
}

RESOURCE /v2/scrumboard/lists

Deep Hydration Logic Flow

منطق غنی‌سازی عمیق (Deep Hydration) که در اکثر متدها (Index, Store, Show, Update) اجرا می‌شود تا ساختار درختی کامل بورد را بسازد:

Get Board Lists

دریافت تمام لیست‌های (ستون‌های) مربوط به یک بورد خاص به همراه تمام کارت‌ها و جزئیات آن‌ها.

Parameters

Response Structure

{
    "items": [
        {
            "id": 1,
            "board_id": 10,
            "title": "To Do",
            "priority": 2,
            "cards": [
                {
                    "id": 101,
                    "title": "Task 1",
                    "members": [ { "id": 1, "first_name": "Ali", ... } ],
                    "labels": [ { "id": 5, "title": "Bug", "color": "red" } ],
                    "comments": [ ... ],
                    "checklists": [ ... ],
                    "attachments": [ ... ],
                    "sprints": [ ... ]
                }
            ]
        }
    ],
    "meta": { "timestamp": 1733754000 }
}

Create List

ایجاد یک لیست (ستون) جدید در بورد. بلافاصله پس از ایجاد، رکورد بازیابی شده و فرآیند Hydration روی آن اجرا می‌شود.

Parameters

Success Response

{
    "payload": {
        "id": 5,
        "title": "New Column",
        "cards": [],
        "created_at": "..."
    },
    "meta": { "timestamp": 1733754000 }
}

Show List

دریافت اطلاعات یک لیست خاص با شناسه ID. این متد نیز تمامی کارت‌ها و وابستگی‌های آن‌ها را بارگذاری می‌کند.

Path Parameters

Update List

ویرایش اطلاعات یک لیست.

Parameters

Success Response

{
    "payload": {
        "id": 5,
        "title": "Edited Title",
        "priority": 10,
        "cards": [ ... ]
    },
    "meta": { "timestamp": 1733754000 }
}

Delete List

حذف کامل یک لیست از دیتابیس.

Success Response

{
    "payload": 1, // تعداد ردیف‌های حذف شده
    "meta": {
        "timestamp": 1733754000
    }
}

RESOURCE /v2/scrumboard/labels

Label Logic Flow

منطق پردازش ساده برای مدیریت لیبل‌ها (برچسب‌ها) که مستقیماً با دیتابیس در تعامل است:

Get Board Labels

دریافت لیست تمامی لیبل‌های تعریف شده برای یک بورد خاص.

Parameters

Response Structure

نکته: اگر داده‌ای یافت نشود، مقدار items برابر با false خواهد بود.

{
    "items": [
        {
            "id": 1,
            "board_id": 10,
            "title": "Bug Fix",
            "status": 1,
            "created_at": "2023-12-01 10:00:00",
            "updated_at": "2023-12-01 10:00:00"
        }
    ],
    "meta": { "timestamp": 1733754000 }
}

Create Label

ایجاد یک لیبل جدید برای بورد.

Parameters

Success Response

{
    "payload": {
        "id": 5,
        "board_id": 10,
        "title": "Urgent",
        "created_at": "...",
        "updated_at": "..."
    },
    "meta": { "timestamp": 1733754000 }
}

Show Label

دریافت جزئیات یک لیبل خاص.

Path Parameters

Response

اگر لیبل یافت نشود، مقدار payload برابر با false خواهد بود.

{
    "payload": {
        "id": 5,
        "board_id": 10,
        "title": "Urgent",
        "status": 1,
        ...
    },
    "meta": { "timestamp": 1733754000 }
}

Update Label

ویرایش نام، وضعیت یا انتقال لیبل به بورد دیگر.

Parameters

Success Response

{
    "payload": {
        "id": 5,
        "board_id": 10,
        "title": "New Title",
        "status": 1,
        "updated_at": "..."
    },
    "meta": { "timestamp": 1733754000 }
}

Delete Label

حذف لیبل از دیتابیس.

Success Response

{
    "payload": 1, // تعداد ردیف‌های حذف شده
    "meta": {
        "timestamp": 1733754000
    }
}

RESOURCE /v2/scrumboard/checklists

Checklist Hydration Logic

در تمامی متدها (لیست، ایجاد، نمایش، ویرایش)، داده‌های خام دیتابیس قبل از ارسال به کلاینت پردازش می‌شوند. فیلد `checkitems` از رشته JSON به آرایه تبدیل شده و شناسه `operator` به آبجکت کامل اپراتور تبدیل می‌گردد.

Get Card Checklists

دریافت لیست تمامی چک‌لیست‌های متصل به یک کارت (Card) مشخص. آیتم‌های داخلی چک‌لیست و اطلاعات اپراتور مسئول به صورت خودکار بارگذاری می‌شوند.

Parameters

Response Structure

{
    "items": [
        {
            "id": 1,
            "card_id": 101,
            "title": "QA Testing",
            "checkitems": [
                { "text": "Test Login", "done": true },
                { "text": "Test Logout", "done": false }
            ],
            "operator": {
                "id": 5,
                "first_name": "Ali",
                "last_name": "Rezaei",
                "avatar": "path/to/img.jpg"
                ...
            },
            "duration": "2h",
            "status": 1,
            "created_at": "..."
        }
    ],
    "meta": { "timestamp": 1733754000 }
}

Create Checklist

ایجاد یک چک‌لیست جدید. کلاینت می‌تواند آرایه‌ای از آیتم‌ها (`checkitems`) را ارسال کند که در سمت سرور به JSON تبدیل و ذخیره می‌شود.

Parameters

Success Response

{
    "payload": {
        "id": 15,
        "title": "Deployment Steps",
        "checkitems": [ ... ], // آرایه دیکد شده
        "operator": { ... },   // آبجکت اپراتور (اگر ارسال شده باشد)
        "created_at": "..."
    },
    "meta": { "timestamp": 1733754000 }
}

Show Checklist

دریافت جزئیات یک چک‌لیست خاص با شناسه ID.

Path Parameters

Response

اگر یافت نشود، payload: false برمی‌گرداند.

{
    "payload": {
        "id": 15,
        "title": "Deployment Steps",
        "checkitems": [],
        "operator": null,
        ...
    },
    "meta": { "timestamp": 1733754000 }
}

Update Checklist

ویرایش اطلاعات چک‌لیست. این متد معمولاً برای تغییر عنوان، وضعیت، تغییر مسئول (`operator`) یا به‌روزرسانی محتوای آیتم‌های داخلی (`checkitems`) استفاده می‌شود.

Parameters

Success Response

{
    "payload": {
        "id": 15,
        "title": "Updated Title",
        "checkitems": [ ... ],
        "operator": { ... },
        "updated_at": "..."
    },
    "meta": { "timestamp": 1733754000 }
}

Delete Checklist

حذف چک‌لیست از دیتابیس.

Success Response

{
    "payload": 1, // تعداد ردیف‌های حذف شده
    "meta": {
        "timestamp": 1733754000
    }
}

RESOURCE /v2/scrumboard/comments

Comment Operator Hydration

در تمامی متدها (لیست، ثبت، نمایش و ویرایش)، سیستم پس از دریافت اطلاعات کامنت از جدول `scrumboard_comments`، به صورت دستی اطلاعات اپراتور (نویسنده کامنت) را از جدول `operators` استخراج کرده و به پاسخ اضافه می‌کند.

Get Card Comments

دریافت لیست نظرات ثبت شده برای یک کارت (Card). این متد امکان فیلتر کردن بر اساس اپراتور و وضعیت را نیز دارد.

Parameters

Response Structure

{
    "items": [
        {
            "id": 10,
            "card_id": 55,
            "operator_id": 3,
            "message": "This needs to be fixed ASAP.",
            "ip_address": "192.168.1.5",
            "status": 1,
            "created_at": "2024-01-01 12:00:00",
            "updated_at": "2024-01-01 12:00:00",
            "operator": {
                "id": 3,
                "first_name": "John",
                "last_name": "Doe",
                "first_name_en": "John",
                "last_name_en": "Doe",
                "avatar": "path/to/avatar.jpg"
            }
        }
    ],
    "meta": { "timestamp": 1733754000 }
}

Create Comment

ثبت یک نظر جدید برای یک کارت. آدرس IP کاربر به صورت خودکار توسط سیستم (`getIP()`) ذخیره می‌شود.

Parameters

Success Response

{
    "payload": {
        "id": 12,
        "card_id": 55,
        "operator_id": 3,
        "ip_address": "127.0.0.1",
        "message": "Task completed.",
        "created_at": "...",
        "updated_at": "...",
        "operator": {
            "id": 3,
            "first_name": "John",
            "last_name": "Doe",
            ...
        }
    },
    "meta": { "timestamp": 1733754000 }
}

Show Comment

مشاهده جزئیات یک نظر خاص با استفاده از شناسه آن.

Path Parameters

Response

در صورت عدم یافتن رکورد، مقدار payload: false بازگردانده می‌شود.

{
    "payload": {
        "id": 10,
        "message": "Specific comment details...",
        "operator": { ... },
        ...
    },
    "meta": { "timestamp": 1733754000 }
}

Update Comment

ویرایش متن، وضعیت و یا حتی انتقال نظر به کارت/اپراتور دیگر.

Parameters

Success Response

{
    "payload": {
        "id": 10,
        "message": "Updated message text",
        "status": 1,
        "updated_at": "...",
        "operator": { ... }
    },
    "meta": { "timestamp": 1733754000 }
}

Delete Comment

حذف دائمی یک نظر از دیتابیس.

Success Response

{
    "payload": 1, // تعداد ردیف‌های حذف شده
    "meta": {
        "timestamp": 1733754000
    }
}

RESOURCE /v2/scrumboard/cards

Card Deep Hydration Logic

کارت‌ها قلب سیستم اسکرام هستند. در تمامی متدها (Index, Store, Show, Update)، پس از دریافت اطلاعات خام کارت، یک فرآیند سنگین برای بارگذاری تمام وابستگی‌ها اجرا می‌شود. این فرآیند شامل دیکد کردن JSONها و کوئری‌های متعدد به جداول مختلف است.

Get Cards List

دریافت لیست کارت‌های موجود در یک لیست (ستون) خاص. تمامی اطلاعات وابسته (اعضا، لیبل‌ها، پیوست‌ها و...) به همراه کارت برگردانده می‌شوند.

Parameters

Response Structure

{
    "items": [
        {
            "id": 101,
            "list_id": 5,
            "title": "Fix Login Bug",
            "description": "User cannot login with email...",
            "members": [
                { "id": 1, "first_name": "Ali", "avatar": "..." }
            ],
            "labels": [
                { "id": 2, "title": "Bug", "color": "#ff0000" }
            ],
            "comments": [ ... ], // لیست کامل نظرات با اطلاعات نویسنده
            "checklists": [ ... ], // لیست چک‌لیست‌ها با آیتم‌ها
            "attachments": [ ... ], // مدیاهای متصل
            "sprints": [ ... ], // اسپرینت‌های مرتبط
            "created_at": "..."
        }
    ],
    "meta": { "timestamp": 1733754000 }
}

Create Card

ایجاد یک کارت جدید ساده. پس از ایجاد، کارت بلافاصله بازیابی شده و ساختار کامل (با آرایه‌های خالی برای وابستگی‌ها) برگردانده می‌شود.

Parameters

Success Response

{
    "payload": {
        "id": 102,
        "title": "New Feature",
        "members": [],
        "labels": [],
        "comments": [],
        "checklists": [],
        "attachments": [],
        "sprints": [],
        ...
    },
    "meta": { "timestamp": 1733754000 }
}

Show Card Details

دریافت جزئیات کامل یک کارت با شناسه مشخص.

Response

اگر کارت پیدا نشود، payload: false برمی‌گرداند.

{
    "payload": {
        "id": 101,
        "title": "Fix Login Bug",
        "members": [ ... ],
        "checklists": [
            {
                "id": 5,
                "title": "QA",
                "checkitems": [{ "text": "Test A", "done": true }],
                "operator": { ... }
            }
        ],
        ...
    },
    "meta": { "timestamp": 1733754000 }
}

Update Card & Sub-Resources

این متد علاوه بر آپدیت فیلدهای اصلی کارت، قابلیت مدیریت تو‌در‌توی (Nested Management) برای comments و checklists را نیز دارد. شما می‌توانید همزمان با ویرایش کارت، یک کامنت یا چک‌لیست را ایجاد، ویرایش یا حذف کنید.

Basic Parameters

Advanced Parameters (Nested Actions)

ارسال این پارامترها اختیاری است و برای عملیات سریع روی زیرمجموعه‌ها استفاده می‌شود.

1. مدیریت کامنت (پارامتر comment)

2. مدیریت چک‌لیست (پارامتر checklist)

Success Response

{
    "payload": {
        "id": 101,
        // کارت آپدیت شده به همراه تمام تغییرات اعمال شده در کامنت‌ها/چک‌لیست‌ها
        "comments": [ ... ], 
        "checklists": [ ... ],
        ...
    },
    "meta": { "timestamp": 1733754000 }
}

Delete Card

حذف کارت از دیتابیس. توجه: طبق کد فعلی، وابستگی‌ها (مثل کامنت‌ها) به صورت Cascade در کد PHP حذف نمی‌شوند مگر اینکه در سطح دیتابیس تنظیم شده باشد.

Success Response

{
    "payload": 1, // 1: موفق، 0: ناموفق
    "meta": { "timestamp": 1733754000 }
}

RESOURCE /v2/scrumboard/sprints

Sprint Hydration Logic

اسپرینت‌ها ظروف نگهداری کارت‌ها در بازه‌های زمانی مشخص هستند. منطق Hydration در اینجا بسیار سنگین است زیرا با دریافت اسپرینت، سیستم به صورت خودکار تمام کارت‌های داخل آن را واکشی کرده و فرآیند "Card Deep Hydration" را برای تک تک آن‌ها اجرا می‌کند.

Get Sprints List

دریافت لیست اسپرینت‌های یک بورد. هر آیتم در لیست شامل آرایه‌ای کامل از کارت‌های داخل آن اسپرینت است.

Parameters

Response Structure

{
    "items": [
        {
            "id": 10,
            "board_id": 1,
            "title": "Sprint #4 - Login Refactor",
            "goal": "Improve security",
            "duration": "2 weeks",
            "status": 1,
            "created_at": "...",
            // گزارش‌های اسپرینت
            "reports": [
                { "id": 1, "note": "Daily meeting...", "operator": { ... } }
            ],
            // کارت‌های داخل اسپرینت (کاملاً Hydrate شده)
            "cards": [
                {
                    "id": 101,
                    "title": "Login API",
                    "members": [...],
                    "labels": [...],
                    "comments": [...],
                    "checklists": [...],
                    "attachments": [...]
                }
            ]
        }
    ],
    "meta": { "timestamp": 1733754000 }
}

Create Sprint

ایجاد یک اسپرینت جدید. می‌توان در لحظه ایجاد، لیست کارت‌های مرتبط را نیز تعیین کرد.

Body Parameters

Success Response

{
    "payload": {
        "id": 11,
        "title": "New Sprint",
        "cards": [], // یا شامل آبجکت‌های کارت اگر در ورودی ارسال شده باشد
        "reports": [],
        ...
    },
    "meta": { "timestamp": 1733754000 }
}

Show Sprint Details

مشاهده جزئیات یک اسپرینت خاص به همراه تمامی وابستگی‌ها (کارت‌ها و گزارش‌ها).

Update Sprint

به‌روزرسانی اطلاعات اسپرینت. مهم: اگر پارامتر cards ارسال شود، لیست کارت‌های اسپرینت با لیست جدید جایگزین می‌شود (Sync).

Body Parameters

Success Response

{
    "payload": {
        "id": 11,
        "title": "Updated Title",
        "cards": [ ... ], // لیست جدید کارت‌ها با جزئیات کامل
        ...
    },
    "meta": { "timestamp": 1733754000 }
}

Delete Sprint

حذف اسپرینت از دیتابیس. این عملیات کارت‌ها را حذف نمی‌کند، بلکه فقط ارتباط اسپرینت را از بین می‌برد (مگر اینکه در دیتابیس تنظیمات دیگری اعمال شده باشد).

Response

{
    "payload": 1, // تعداد رکوردهای حذف شده
    "meta": { "timestamp": 1733754000 }
}

RESOURCE /v2/scrumboard/sprint_reports

Sprint Report Hydration Logic

گزارش‌های اسپرینت، زیرمجموعه‌ای از اسپرینت‌ها هستند و منطق Hydration ساده‌ای دارند. در تمام متدها، پس از دریافت داده‌های گزارش، سیستم فقط اطلاعات اپراتور (نویسنده) را از جدول `operators` بارگذاری می‌کند.

Get Sprint Reports List

دریافت لیست گزارش‌های ثبت شده برای یک اسپرینت مشخص.

Parameters

Response Structure

در صورت عدم وجود گزارش، مقدار items: false برگردانده می‌شود.

{
    "items": [
        {
            "id": 1,
            "sprint_id": 10,
            "title": "Daily Stand-up - Day 3",
            "description": "Discussed blocker on API endpoint...",
            "issued_at": "2025-12-08 09:00:00",
            "status": 1,
            "operator": {
                "id": 5,
                "first_name": "Reza",
                "last_name": "Ahmadi",
                "avatar": "..."
            },
            "created_at": "..."
        }
    ],
    "meta": { "timestamp": 1733754000 }
}

Create Sprint Report

ایجاد یک گزارش جدید برای یک اسپرینت. شناسه اپراتور (نویسنده) به صورت خودکار از توکن کاربر احراز هویت شده (`authWithJwt`) استخراج و ثبت می‌شود.

Body Parameters

Success Response

{
    "payload": {
        "id": 2,
        "sprint_id": 10,
        "title": "Sprint Review Notes",
        ...
        "operator": {
            "id": 1, 
            "first_name": "Admin",
            ...
        }
    },
    "meta": { "timestamp": 1733754000 }
}

Show Sprint Report Details

مشاهده جزئیات یک گزارش خاص با شناسه آن.

Response

در صورت پیدا نشدن گزارش، payload: false برمی‌گردد.

{
    "payload": {
        "id": 1,
        "title": "Daily Stand-up - Day 3",
        "operator": { ... },
        ...
    },
    "meta": { "timestamp": 1733754000 }
}

Update Sprint Report

به‌روزرسانی اطلاعات یک گزارش. توجه داشته باشید که نویسنده (operator) قابل تغییر نیست.

Body Parameters

Success Response

{
    "payload": {
        "id": 1,
        "title": "Updated report title",
        ...
    },
    "meta": { "timestamp": 1733754000 }
}

Delete Sprint Report

حذف یک گزارش از سیستم.

Response

{
    "payload": 1, // 1 برای موفقیت، 0 برای عدم موفقیت
    "meta": { "timestamp": 1733754000 }
}

RESOURCE /v2/cartable/letters

Letter & Workflow Logic

ماژول کارتابل دارای یک منطق گردش کار (Workflow) است. زمانی که یک نامه ایجاد می‌شود، سیستم به صورت خودکار اولین مرحله (Step) آن فرآیند را ایجاد می‌کند. همچنین زمانی که وضعیت یک مرحله به "انجام شده" تغییر می‌کند، سیستم به صورت هوشمند مرحله بعدی را تشخیص داده و ایجاد می‌کند.

Get Letters List

دریافت لیست نامه‌های موجود در کارتابل. این متد از یک سیستم صفحه‌بندی (Pagination) خاص استفاده می‌کند که پارامترهای `length` و `start` را به شماره صفحه لاراول تبدیل می‌کند.

Query Parameters

Response Structure

خروجی توسط LetterResource فرمت‌دهی می‌شود.

{
    "items": [
        {
            "id": 50,
            "serial": "LET-1402-001",
            "subject": { "id": 1, "title": "Leave Request" },
            "requester": { "id": 10, "name": "Ali..." },
            "current_step": { "id": 205, "status": "pending" },
            "created_at": "..."
        }
    ],
    "meta": { "timestamp": 1733754000 }
}

Create Letter

ایجاد یک نامه جدید.
نکته مهم: پس از ایجاد نامه، سیستم به جدول `cartable_subjects` مراجعه کرده و لیست مراحل تعریف شده برای آن موضوع (`subject`) را می‌خواند و به صورت خودکار اولین مرحله را در جدول `cartable_letter_steps` برای این نامه ثبت می‌کند.

Body Parameters

Success Response

{
    "payload": {
        "id": 51,
        "serial": "100-2569",
        "subject": 5,
        "steps": [ ... ] // شامل اولین مرحله ایجاد شده
    },
    "meta": { "timestamp": 1733754000 }
}

Show Letter Details

مشاهده جزئیات کامل یک نامه. اگر نامه حذف شده باشد (`deleted_at` داشته باشد) یا وجود نداشته باشد، خطای 404 برمی‌گرداند.

Update Letter

ویرایش اطلاعات عمومی نامه (عنوان، گیرنده، توضیحات و...). این متد مراحل گردش کار را تغییر نمی‌دهد.

Body Parameters

Delete Letter

حذف نرم (Soft Delete) نامه. فیلد deleted_at با زمان فعلی مقداردهی می‌شود.

Update Step & Advance Workflow

توجه: این متد در کنترلر وجود دارد اما روت آن در اسنیپت ارائه شده نیست (احتمالاً روت سفارشی دارد).
این متد برای تغییر وضعیت یک مرحله (Step) استفاده می‌شود.
منطق هوشمند: اگر وضعیت ارسالی برابر با 3 (انجام شده) باشد، سیستم به صورت خودکار مرحله بعدی فرآیند را از تنظیمات موضوع (`subject steps`) پیدا کرده و آن را ایجاد می‌کند.

Body Parameters

RESOURCE /v2/cartable/subjects

Subject & Workflow Configuration Logic

این کنترلر وظیفه مدیریت "موضوعات نامه" را بر عهده دارد. اهمیت اصلی این بخش در فیلد steps است.
فیلد steps یک آرایه JSON است که "نقشه راه" یا "گردش کار" (Workflow) یک نامه را تعریف می‌کند. وقتی نامه‌ای با موضوع خاصی ایجاد می‌شود، سیستم از این تنظیمات برای تولید مراحل (`cartable_letter_steps`) استفاده می‌کند.

List Subjects

دریافت لیست تمام موضوعات تعریف شده. برخلاف نامه‌ها، در اینجا فعلاً صفحه‌بندی (Pagination) وجود ندارد و همه رکوردها بر اساس فیلترها بازگردانده می‌شوند.

Query Parameters

Response Structure

{
    "items": [
        {
            "id": 1,
            "branch": 101,
            "department": 5,
            "title": "درخواست مرخصی",
            "steps": "[{\"order\":1, \"role\":\"manager\"}, ...]", // JSON String
            "created_at": "...",
            "updated_at": "..."
        }
    ],
    "meta": { "timestamp": 1733758000 }
}

Create Subject & Workflow

تعریف یک موضوع جدید به همراه مراحل گردش کار آن.
نکته فنی: آرایه `steps` به صورت `json_encode` شده در دیتابیس ذخیره می‌شود.

Body Parameters

Success Response

{
    "payload": {
        "id": 12,
        "title": "New Workflow",
        "steps": "[\"step1\", \"step2\"]",
        "created_at": "..."
    },
    "meta": { "timestamp": 1733758000 }
}

Show Subject Details

مشاهده جزئیات یک موضوع.

Update Subject

ویرایش تنظیمات موضوع.
نکته: طبق کد، فیلد `branch` در متد Update قابل ویرایش نیست (فقط department, title, steps).

Body Parameters

Delete Subject

حذف فیزیکی (Hard Delete) یک موضوع از دیتابیس.
هشدار: این عملیات Soft Delete نیست و رکورد کاملاً پاک می‌شود.

RESOURCE /v2/cartable/subject_steps

Subject Steps Management Logic

این کنترلر وظیفه مدیریت مراحل پیش‌فرض (Step Templates) را بر عهده دارد.
این جدول (`cartable_subject_steps`) به عنوان یک بانک اطلاعاتی از مراحل عمل می‌کند که شامل یک عنوان (`title`) و یک اپراتور مسئول (`operator`) است. این مراحل مستقل هستند اما می‌توانند هنگام تعریف گردش کار (Workflow) در بخش Subjectها مورد استفاده قرار گیرند.

List Step Definitions

دریافت لیست مراحل تعریف شده. این لیست بر اساس تاریخ ایجاد (نزولی) مرتب شده است.

Query Parameters

Response Structure

{
    "items": [
        {
            "id": 10,
            "operator": 105,
            "title": "بررسی مالی",
            "created_at": "...",
            "updated_at": "..."
        }
    ],
    "meta": { "timestamp": 1733760000 }
}

Create Step Definition

ایجاد یک تعریف مرحله جدید (Template).

Body Parameters

Success Response

{
    "payload": {
        "id": 15,
        "operator": 105,
        "title": "تایید نهایی",
        "created_at": "...",
        "updated_at": "..."
    },
    "meta": { "timestamp": 1733760000 }
}

Show Step Details

مشاهده جزئیات یک مرحله خاص.

Response Structure

{
    "payload": {
        "id": 15,
        "operator": 105,
        "title": "تایید نهایی",
        "created_at": "...",
        "updated_at": "..."
    },
    "meta": { "timestamp": 1733760000 }
}

Update Step Definition

ویرایش اطلاعات اپراتور یا عنوان مرحله.

Body Parameters

Success Response

{
    "payload": {
        "id": 15,
        "operator": 200, // Updated
        "title": "تایید مدیریت ارشد", // Updated
        "created_at": "...",
        "updated_at": "..."
    },
    "meta": { "timestamp": 1733760000 }
}

Delete Step Definition

حذف فیزیکی (Hard Delete) یک مرحله از دیتابیس.
هشدار: اگر این مرحله در Subjectها استفاده شده باشد، ممکن است باعث ناهماهنگی در تنظیمات شود (بسته به منطق فرانت‌اند). در اینجا حذف کامل انجام می‌شود.

Success Response

{
    "payload": 1, // تعداد رکوردهای حذف شده
    "meta": { "timestamp": 1733760000 }
}

RESOURCE /v2/cartable/recipients

Department Recipients Management Logic

این کنترلر وظیفه مدیریت لیست "گیرندگان" (`recipients`) را در سطح دپارتمان‌ها بر عهده دارد.
این جدول (`cartable_department_recipients`) عناوین شغلی یا واحدهایی را نگهداری می‌کند که در یک شعبه و دپارتمان خاص مجاز به دریافت نامه هستند (مانند: "دبیرخانه"، "مدیریت مالی" و ...).

List Recipients

دریافت لیست تمام گیرندگان تعریف شده. این لیست بر اساس تاریخ ایجاد (نزولی) مرتب شده است.

Query Parameters

Response Structure

{
    "items": [
        {
            "id": 10,
            "department": 5,
            "branch": 101,
            "title": "دبیرخانه مرکزی",
            "created_at": "...",
            "updated_at": "..."
        }
    ],
    "meta": { "timestamp": 1733762000 }
}

Create Recipient

تعریف یک گیرنده جدید برای یک شعبه و دپارتمان خاص.

Body Parameters

Success Response

{
    "payload": {
        "id": 12,
        "department": 5,
        "branch": 101,
        "title": "حسابداری",
        "created_at": "...",
        "updated_at": "..."
    },
    "meta": { "timestamp": 1733762000 }
}

Show Recipient Details

مشاهده جزئیات یک گیرنده خاص.

Response Structure

{
    "payload": {
        "id": 12,
        "department": 5,
        "branch": 101,
        "title": "حسابداری",
        "created_at": "...",
        "updated_at": "..."
    },
    "meta": { "timestamp": 1733762000 }
}

Update Recipient

ویرایش اطلاعات گیرنده.
نکته مهم: طبق منطق کد، فیلد `branch` در متد Update قابل تغییر نیست و فقط `department` و `title` بروزرسانی می‌شوند.

Body Parameters

Success Response

{
    "payload": {
        "id": 12,
        "department": 6, // Changed
        "branch": 101,
        "title": "حسابداری ارشد", // Changed
        "created_at": "...",
        "updated_at": "..."
    },
    "meta": { "timestamp": 1733762000 }
}

Delete Recipient

حذف فیزیکی (Hard Delete) یک گیرنده از سیستم.

Success Response

{
    "payload": 1, // تعداد رکوردهای حذف شده
    "meta": { "timestamp": 1733762000 }
}

RESOURCE /v2/cartable/operator_role

Operator Role & Signature Logic

این کنترلر برای انتساب یک "عنوان" (`title`) به یک "اپراتور" (`operator`) و مهم‌تر از آن، ذخیره **تصویر امضای دیجیتال** (`signature_file`) استفاده می‌شود.
فایل‌های آپلود شده در فضای ذخیره‌سازی ابری (دیسک `liara`) با ساختار پوشه‌بندی بر اساس شناسه شعبه (`branch`) و تاریخ ذخیره می‌شوند.

List Operator Roles

دریافت لیست نقش‌ها و امضاهای تعریف شده.

Query Parameters

Response Structure

{
    "items": [
        {
            "id": 5,
            "operator": 105,
            "title": "مدیر فنی",
            "signature_file": "uploads/100/cartable/signatures/2024/12/example.png",
            "created_at": "...",
            "updated_at": "..."
        }
    ],
    "meta": { "timestamp": 1733764000 }
}

Create Role & Upload Signature

تعریف نقش جدید و آپلود تصویر امضا.
نکته مهم: این درخواست باید به صورت multipart/form-data ارسال شود.

Body Parameters (Multipart)

Success Response

{
    "payload": {
        "id": 8,
        "operator": 105,
        "title": "رئیس هیئت مدیره",
        "signature_file": "uploads/101/cartable/signatures/2025/12/sig-123.png",
        "created_at": "...",
        "updated_at": "..."
    },
    "meta": { "timestamp": 1733764000 }
}

Show Role Details

مشاهده جزئیات یک نقش خاص.

Response Structure

{
    "payload": {
        "id": 8,
        "operator": 105,
        "title": "رئیس هیئت مدیره",
        "signature_file": "uploads/101/cartable/signatures/2025/12/sig-123.png",
        "created_at": "...",
        "updated_at": "..."
    },
    "meta": { "timestamp": 1733764000 }
}

Update Role & Signature

ویرایش عنوان یا جایگزینی فایل امضا.
اگر فایل جدیدی ارسال شود، آپلود شده و مسیر آن در دیتابیس جایگزین می‌شود.
توجه: در لاراول برای ارسال فایل در متد PUT معمولاً باید از `_method: PUT` در یک درخواست POST استفاده کنید.

Body Parameters

Success Response

{
    "payload": {
        "id": 8,
        "operator": 105,
        "title": "عنوان ویرایش شده",
        "signature_file": "uploads/101/cartable/signatures/2025/12/new-sig.png",
        "updated_at": "..."
    },
    "meta": { "timestamp": 1733764000 }
}

Delete Role

حذف نقش و امضا.
پاکسازی فایل: این متد علاوه بر حذف رکورد از دیتابیس، فایل امضای مربوطه را نیز از فضای ابری (Liara) پاک می‌کند.

Success Response

{
    "payload": 1, // 1 for success
    "meta": { "timestamp": 1733764000 }
}

PUT /v2/cartable/letters/step/{id}

Workflow Progression Logic

این متد یک مرحله خاص (`cartable_letter_steps`) از یک نامه را بروزرسانی می‌کند.
جادوی گردش کار: اگر وضعیت ارسالی برابر با 3 (انجام شده) باشد، سیستم به صورت خودکار پیکربندی "موضوع نامه" (`subject->steps`) را بررسی کرده و مرحله بعدی را در دیتابیس ایجاد می‌کند.

Update Letter Step

تغییر وضعیت یک مرحله، ثبت توضیحات و (در صورت اتمام) ارجاع خودکار به مرحله بعد.

URL Parameters

Body Parameters

Logic Details (Backend)

Success Response

{
    "payload": 1, // نشان دهنده موفقیت آمیز بودن عملیات (تعداد ردیف تغییر کرده)
    "meta": {
        "timestamp": 1733765000
    }
}

Visual Logic Flow

POST /v2/ai/chat/completions

AI Financial Analysis Logic

این اندپوینت داده‌های خام مالی (شامل خرید، فروش، سود و زیان) را دریافت کرده و آن را به یک گزارش متنی/بصری تبدیل می‌کند.
نقش سیستم: سیستم به عنوان یک مدیر مالی هوشمند برای نرم‌افزار AirPlus عمل می‌کند.
فرمت خروجی: پرامپت سیستم به گونه‌ای تنظیم شده که خروجی نهایی صرفاً کد HTML Body باشد تا در فرانت‌اند مستقیماً داخل یک تگ div نمایش داده شود.

Generate AI Report

ارسال داده‌های JSON مالی و دریافت تحلیل متنی به همراه جداول HTML.
در این فرآیند نام آژانس (`branch`) از دیتابیس خوانده شده و در متن گزارش استفاده می‌شود تا تحلیل شخصی‌سازی شده باشد.

Body Parameters

Default Prompt Structure

اگر پارامتر prompt ارسال نشود، سیستم دستورالعمل زیر را به AI می‌دهد:

Success Response Example

{
    // خروجی بسته به کلاینت AI متفاوت است اما محتوا HTML است
    "content": "

گزارش عملکرد آژانس تعطیلات رویایی

بر اساس داده‌های دریافتی...

..."
}

Visual Logic Flow

POST /v2/trade/reference/type

Global Reference Search

این متد به عنوان یک جستجوگر چندمنظوره (Poly-morphic Search) عمل می‌کند. فرانت‌اند با ارسال پارامتر goal مشخص می‌کند که به دنبال چه نوع داده‌ای است (مثلاً مسافر، حساب بانکی، یا ایرلاین) و سیستم با جستجو در جداول مربوطه، لیست استاندارد شده‌ای شامل id و text برمی‌گرداند.

Search Entities (Autocomplete)

جستجو و واکشی اطلاعات برای ورودی‌های Select و Autocomplete در سراسر سیستم.

Request Parameters

Goal Codes (Magic Numbers) & Logic

Success Response Example

{
    "total_count": 10,
    "incomplete_results": false,
    "results": [
        {
            "id": 105,
            "text": "1205 - هتل داریوش (کیش)"
        },
        {
            "id": "account-50", // در صورت فعال بودن separator
            "text": "1050 - صندوق ریالی (Main Branch)"
        }
    ],
    "pagination": {
        "more": false
    }
}

POST /v2/base/reference

Base System References

این اندپوینت دقیقاً همان موتور جستجوی مرکزی (Global Search) است که در ماژول Trade استفاده می‌شد، اما با آدرس base برای استفاده‌های عمومی در کل سیستم (مانند فرم‌های تنظیمات، داشبورد و غیره) در دسترس قرار گرفته است.
وظیفه آن تبدیل کدهای موجودیت (Goals) به لیست‌های استاندارد برای Dropdownها است.

General Reference Lookup

جستجوی تمامی موجودیت‌های پایه سیستم (کاربران، شیفت‌ها، دپارتمان‌ها، حساب‌ها و...) برای استفاده در کامپوننت‌های Select2.

Request Parameters

Reference Codes (Goal Dictionary)

Example Request (Shift Works)

{
    "goal": "shift_works",
    "branch": 1,
    "details": true
}

Success Response

{
    "total_count": 5,
    "incomplete_results": false,
    "results": [
        {
            "id": 1,
            "text": "شیفت صبح",
            "query": {
                "id": 1,
                "title": "شیفت صبح",
                "start_time": "08:00",
                "end_time": "16:00"
            }
        }
    ],
    "pagination": {
        "more": false
    }
}

Technical Logic Flow

POST /v2/config

System Configuration & Tenant Init

این متد حیاتی‌ترین اندپوینت برای راه‌اندازی اولیه اپلیکیشن (Bootstrapping) است.
سیستم بر اساس هدر Domain تشخیص می‌دهد که کاربر مربوط به کدام شعبه (Office) است و تنظیمات ظاهری، مالی، حقوقی و ماژول‌های فعال آن شعبه را برمی‌گرداند.

Get Office Configuration

Headers (Required)

Response Structure (JSON)

خروجی شامل چندین بخش اصلی است:

Example Response

{
    "office_id": 1001,
    "title": {
        "fa": "آژانس مسافرتی نمونه",
        "en": "Sample Travel Agency"
    },
    "brand": {
        "fa": "برند نمونه",
        "en": "Sample Brand"
    },
    "short_domain": "smpl",
    "expiration": "2026-01-01",
    "communicational": {
        "phone": "02188888888",
        "mobile": "09120000000",
        "email": "info@example.com",
        "site": "example.com",
        "address": {
            "fa": "تهران، خیابان ولیعصر...",
            "en": "Tehran, Valiasr St..."
        }
    },
    "design": {
        "login_text": "Welcome to Automation",
        "logo": "https://liara.../logo.png",
        "base_color": "#3b82f6",
        "theme": "light"
    },
    "services": ["flight", "hotel", "train"],
    "details": {
        "financial_debt": false,
        "financial": {
            "value_added": 9 
        },
        "official": {
            "calendar_limit": {
                "leave": {
                    "1": { "overtime": -60, "substitute": true },
                    "2": { "overtime": -60, "substitute": false }
                }
            }
        },
        "config": {
            "allow_negative_stock": "0",
            "print_footer_text": "Thanks for your purchase"
        }
    }
}

Technical Logic Flow

GET /v2/config

Initial System Configuration

این متد نقطه شروع (Entry Point) اپلیکیشن است. فرانت‌اند قبل از هر کاری باید این اندپوینت را صدا بزند.
سیستم با بررسی هدر Domain، شعبه (Office) مورد نظر را پیدا کرده و تمام تنظیمات حیاتی شامل رنگ‌بندی، لوگو، اطلاعات تماس، قوانین مالی و وضعیت بدهی را برمی‌گرداند.

Get Tenant Config

Headers (الزامی)

Response Structure

Example Response

{
    "office_id": 1005,
    "title": {
        "fa": "آژانس مسافرتی آسمان",
        "en": "Aseman Travel Agency"
    },
    "brand": {
        "fa": "آسمان",
        "en": "Aseman"
    },
    "short_domain": "aseman",
    "expiration": "2025-12-29",
    "communicational": {
        "phone": "021-44444444",
        "mobile": "09121234567",
        "address": {
            "fa": "تهران، میدان آزادی...",
            "en": "Tehran, Azadi Sq..."
        },
        "location": "35.6892,51.3890"
    },
    "design": {
        "login_text": "به سیستم اتوماسیون خوش آمدید",
        "logo": "https://storage.../logo.png",
        "base_color": "#ff5722",
        "theme": "dark"
    },
    "support_online": {
        "service": "raychat",
        "code": "e45-fgh-789"
    },
    "details": {
        "financial_debt": false,
        "financial": {
            "value_added": 9
        },
        "official": {
            "calendar_limit": {
                "leave": {
                    "1": { "overtime": -60, "substitute": true },
                    "2": { "overtime": -60, "substitute": false }
                }
            }
        },
        "config": {
            "print_header": "1",
            "currency_default": "IRR"
        }
    }
}

Logic Flow

GET /b2c/v1/config

B2C Frontend Configuration

این اندپوینت مخصوص وب‌سایت‌های فروش آنلاین (White-label B2C) است.
سیستم با بررسی هدر Domain، آدرس سایت مشتری را در ستون b2c_domains جستجو می‌کند و تنظیمات ظاهری، بنرها، مجوزهای نماد اعتماد و پیکربندی ماژول‌های فروش را برمی‌گرداند.

Get B2C Config

Headers (الزامی)

Response Structure

Example Response

{
    "office_id": 1025,
    "title": { "fa": "سفر آنلاین", "en": "Safar Online" },
    "brand": { "fa": "سفر24", "en": "Safar24" },
    "short_domain": "s24",
    "erp_domain": "admin.safar24.ir",
    "communicational": {
        "phone": "02199999999",
        "whatsapp": "989120000000",
        "social_media": { "instagram": "safar24_inst" },
        "certificates": [
            {
                "title": "Enamad",
                "content": ""
            }
        ]
    },
    "design": {
        "logo": "https://storage.../logo_b2c.png",
        "theme": "minimal-light-1",
        "advertisement": [
            {
                "id": 55,
                "title": "تور نوروزی استانبول",
                "image": "https://storage.../banner1.jpg",
                "link": "/tours/istanbul"
            }
        ]
    },
    "hub": {
        "services": ["flight", "hotel"],
        "theme": "minimal",
        "palette": "1",
        "slogan": "سفری خاطره‌انگیز با ما",
        "modules": {
            "flight_domestic": true,
            "train": false
        },
        "authentication": "otp_mobile"
    },
    "cache": {
        "update": "Tue, 09 Dec 2025 10:30:00 +0330"
    }
}

Technical Logic

POST /b2c/v1/auth/otp

B2C Customer Authentication (OTP)

این اندپوینت وظیفه مدیریت ورود و ثبت‌نام کاربران در وب‌سایت‌های فروش (B2C) را بر عهده دارد.
سیستم از مکانیزم رمز یکبار مصرف (OTP) استفاده می‌کند. نکته کلیدی این است که اگر شماره موبایل در سیستم وجود نداشته باشد، کاربر به صورت خودکار (Auto-Register) ثبت‌نام شده و شناسه مسافر (`passenger_id`) ایجاد می‌گردد.

Request OTP / Login

Body Parameters (الزامی)

Response Structure

Example Responses

۱. موفقیت آمیز (201 Created):

{
    "status": true,
    "time": 1702134567,
    "data": {
        "passenger_id": 5421
    },
    "message": "OTP با موفقیت ارسال گردید."
}

۲. خطای محدودیت ارسال (422 Unprocessable Entity - Code 1204):

{
    "status": false,
    "code": 1204,
    "message": "تعداد درخواست های کاربر بیش از حد مجاز بوده است. لطفا 3 ساعت دیگر اقدام نمائید."
}

۳. خطای پنل پیامک (422 Unprocessable Entity - Code 1202):

{
    "status": false,
    "code": 1202,
    "message": "پیامک OTP ارسال نشد. مشکلی رخ داده است. لطفا دوباره تلاش کنید",
    "trace": { ... }
}

Technical Logic

POST /b2c/v1/auth/submit

B2C Verify OTP & Login

این اندپوینت مرحله نهایی احراز هویت است.
کلاینت کد دریافتی (OTP) را به همراه شناسه مسافر ارسال می‌کند. سیستم کد را در جدول otp_requests اعتبارسنجی کرده (بررسی انقضا و عدم استفاده قبلی) و در صورت صحت، وضعیت کد را به "استفاده شده" تغییر می‌دهد و یک JWT Token با اعتبار ۷ روز برای کاربر صادر می‌کند.

Submit OTP

Headers (الزامی)

Body Parameters (الزامی)

Response Structure

Example Responses

۱. موفقیت آمیز (Login Success):

{
    "status": true,
    "user": {
        "uuid": 5421,
        "from": "user",
        "role": "passenger",
        "type": "passenger",
        "level": 1,
        "data": {
            "title": {
                "fa": "محمد محمدی",
                "en": "Mohammad Mohammadi"
            },
            "sex": "male",
            "first_name": "Mohammad",
            "last_name": "Mohammadi",
            "first_name_fa": "محمد",
            "last_name_fa": "محمدی",
            "mobile": "09121234567",
            "national_code": "0012345678"
        }
    },
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

۲. خطای نامعتبر بودن کد (422 Unprocessable Entity - Code 1209):

{
    "status": false,
    "code": 1209,
    "message": "رمز یکبار مصرف وارد شده معتبر نمی باشد."
}

Technical Logic

POST /b2c/v1/auth/basic

B2C Colleague Authentication (Basic)

این اندپوینت جهت ورود همکاران و آژانس‌های طرف قرارداد (Colleagues) طراحی شده است.
سیستم با دریافت نام کاربری و رمز عبور، اعتبار حساب را در جدول colleague_auth بررسی کرده و در صورت فعال بودن حساب و عدم انقضای قرارداد، یک توکن JWT صادر می‌کند. همچنین جزئیات سقف اعتبار و اطلاعات تماس همکار نیز بازگردانده می‌شود.

Colleague Login

Headers (الزامی)

Body Parameters (الزامی)

Response Structure (Success)

Example Responses

۱. موفقیت آمیز (Login Success):

{
    "user": {
        "uuid": 105,
        "from": "colleague",
        "type": "agency",
        "role": "partner",
        "data": {
            "id": 88,
            "title": {
                "fa": "آژانس مسافرتی آسمان",
                "en": "Aseman Travel Agency"
            },
            "subtitle": {
                "fa": "user123 - علی رضایی",
                "en": "Aseman Travel Agency"
            },
            "additional": false,
            "avatar": "logo_105.jpg",
            "sex": "male",
            "first_name": "Ali",
            "last_name": "Rezaei",
            "first_name_fa": "علی",
            "last_name_fa": "رضایی",
            "mobile": "09121111111",
            "phone": "02188888888",
            "national_code": "0055555555"
        },
        "level": 2,
        "ceiling": {
            "amount": 50000000,
            "deadline": 1
        },
        "expired_at": null
    },
    "access_token": "eyJ0eXAiOiJjb2xsZWFndWUiLCJhbGciOiJIUzI1NiJ9..."
}

۲. خطا - اطلاعات نادرست (Invalid Credentials):

{
    "error": {
        "type": "username",
        "message": "اطلاعات وارد شده همخوانی ندارد."
    }
}

۳. خطا - حساب غیرفعال (Inactive Account):

{
    "error": {
        "type": "username",
        "message": "وضعیت شما بصورت غیرفعال می باشد."
    }
}

Technical Logic

POST /b2c/v1/get_country

Get Nationalities List

این اندپوینت لیست کشورهای فعال که دارای عنوان «ملیت» (Nationality) تعریف شده هستند را باز می‌گرداند.
از این داده‌ها معمولاً در فرم‌های ورود اطلاعات مسافر جهت انتخاب ملیت/تابعیت (مثلاً: ایرانی، آلمانی و...) استفاده می‌شود. لیست خروجی تنها شامل رکوردهایی است که وضعیت آن‌ها فعال (`status = 1`) باشد.

Fetch Country/Nationality Data

Parameters

این درخواست نیاز به پارامتر ورودی (Body Parameters) ندارد.

Response Structure

Example Responses

۱. موفقیت آمیز (200 OK):

{
    "status": true,
    "time": 1702138899,
    "data": {
        "countries": [
            {
                "id": 105,
                "iso": "IR",
                "fa_nationality": "ایرانی",
                "en_nationality": "Iranian"
            },
            {
                "id": 220,
                "iso": "TR",
                "fa_nationality": "ترک",
                "en_nationality": "Turkish"
            },
            {
                "id": 68,
                "iso": "DE",
                "fa_nationality": "آلمانی",
                "en_nationality": "German"
            }
        ]
    }
}

۲. خطای سرور (400 Bad Request):

{
    "status": false,
    "error": "Database connection error..."
}

Technical Logic

GET /b2c/v1/user/passengers

Get User Passengers List

این اندپوینت لیست تمامی مسافران مرتبط با حساب کاربری فعلی را باز می‌گرداند.
سیستم لیست مسافران را از دو منبع استخراج می‌کند:

 

Fetch Passengers

Headers (الزامی)

Response Structure

Example Responses

۱. موفقیت آمیز (200 OK):

{
    "status": true,
    "time": 1702145000,
    "data": [
        {
            "id": 501,
            "first_name": "Saeed",
            "last_name": "Mohammadi",
            "first_name_fa": "سعید",
            "last_name_fa": "محمدی",
            "national_code": "0077777777",
            "gender": 1,
            "birthday": "1990-05-20",
            "passport_number": "A12345678",
            "relationship": 105,
            "created_at": "2023-01-01 12:00:00"
        },
        {
            "id": 890,
            "first_name": "Sara",
            "last_name": "Tehrani",
            "first_name_fa": "سارا",
            "last_name_fa": "تهرانی",
            "national_code": "0088888888",
            "gender": 0,
            "birthday": "1995-10-10",
            "passport_number": null,
            "relationship": null, 
            "note": "Fetched from history"
        }
    ]
}

Technical Logic

GET /b2c/v1/office/users

Get Office/Company Users

این اندپوینت جهت دریافت لیست تمامی کاربران (Users) تعریف شده در زیرمجموعه یک شرکت یا آژانس (Colleague) استفاده می‌شود.
نکته مهم: دسترسی به این متد محدود است و تنها کاربرانی که سطح دسترسی آن‌ها مدیریت (Management) باشد مجاز به فراخوانی آن هستند. در غیر این صورت خطای 406 بازگردانده می‌شود.

Fetch Sub-Users

Headers (الزامی)

Response Structure (Success)

Example Responses

۱. موفقیت آمیز (مدیر):

{
    "items": [
        {
            "id": 10,
            "colleague": 55, 
            "username": "admin_agency",
            "category": "management",
            "level": 1,
            "ceiling": {
                "amount": false,
                "deadline": false
            },
            "expired_at": false,
            "created_at": "2023-01-01 10:00:00",
            "updated_at": "2023-05-20 14:30:00",
            "status": 1
        },
        {
            "id": 12,
            "colleague": 55,
            "username": "sales_counter",
            "category": "sales",
            "level": 2,
            "ceiling": {
                "amount": 5000000,
                "deadline": 1
            },
            "expired_at": "2024-12-29",
            "created_at": "2023-02-15 09:00:00",
            "updated_at": "2023-02-15 09:00:00",
            "status": 1
        }
    ],
    "meta": {
        "timestamp": 1702150000
    }
}

۲. خطا - عدم دسترسی (کاربر عادی):

{
    "error": {
        "code": 1000,
        "message": "دسترسی فقط برای سطح مدیریت"
    },
    "meta": {
        "timestamp": 1702150005
    }
}

Technical Logic

GET /b2c/v1/cost-center/list/form

Get Cost Centers List (Form)

این اندپوینت جهت دریافت لیست مراکز هزینه (Cost Centers) برای فرم‌ها استفاده می‌شود.
محدودیت دسترسی: این سرویس صرفاً مخصوص کاربران B2B (همکاران) است که شرکت آن‌ها در سطح هلدینگ (Category 7) تعریف شده باشد. هلدینگ‌ها از این طریق لیست زیرمجموعه‌های خود (که فیلد relationship آن‌ها برابر با شناسه هلدینگ است) را دریافت می‌کنند.

Fetch Cost Centers

Headers (الزامی)

Response Structure (Success)

Example Responses

۱. موفقیت آمیز (کاربر هلدینگ):

{
    "items": [
        {
            "id": 205,
            "title": {
                "fa": "دپارتمان مالی - علی رضایی",
                "en": "Finance Department"
            }
        },
        {
            "id": 208,
            "title": {
                "fa": "شعبه شمال تهران", 
                "en": "North Branch"
            }
        }
    ],
    "meta": {
        "timestamp": 1702155000
    }
}

۲. خطا - عدم دسترسی (کاربر معمولی یا شرکت غیر هلدینگ):

{
    "error": {
        "code": 1000,
        "message": "دسترسی فقط برای همکاران سطح هلدینگ امکانپذیر است."
    },
    "meta": {
        "timestamp": 1702155005
    }
}

Technical Logic

GET /b2c/v1/credit-card

Get Credit Card Detail

این اندپوینت برای دریافت اطلاعات یک کارت اعتباری خاص استفاده می‌شود.
ویژگی امنیتی (Security Masking): سیستم به طور خودکار بررسی می‌کند که آیا کاربر درخواست‌دهنده (`operator`) همان مالک کارت (`passenger_id`) است یا خیر:

 

Fetch Credit Card

Headers (الزامی)

Query Parameters (فیلترها)

Response Structure

Example Responses

۱. موفقیت آمیز - مالک کارت (نمایش کامل):

{
    "payload": {
        "id": 101,
        "status": 1,
        "card": {
            "number": "6037991122334455",
            "withdrawal_limit": 50000000,
            "blocked_amount": 0,
            "cvv2": "1234",           // موجود است
            "expire_date": "04/05"    // موجود است
        },
        "passenger": {
            "id": 55,
            "first_name": "علی",
            "last_name": "محمدی"
        }
    },
    "meta": {
        "timestamp": 1702160000
    }
}

۲. موفقیت آمیز - غیر مالک (اطلاعات امنیتی مخفی):

{
    "payload": {
        "id": 101,
        "status": 1,
        "card": {
            "number": "6037********4455", // ماسک شده
            "withdrawal_limit": false,
            "blocked_amount": false
            // فیلدهای cvv2 و expire_date وجود ندارند
        },
        "passenger": {
            "id": 55,
            "first_name": "علی",
            "last_name": "محمدی"
        }
    },
    "meta": {
        "timestamp": 1702160010
    }
}

۳. خطا - یافت نشد:

{
    "error": {
        "code": 1000,
        "message": "کارت اعتباری پیدا نشد."
    },
    "meta": {
        "timestamp": 1702160020
    }
}

Technical Logic

POST /b2c/v1/media/upload/s3

Upload Media to S3

این اندپوینت جهت آپلود فایل‌ها (تصاویر، اسناد و ...) بر روی فضای ذخیره‌سازی ابری (S3 Compatible / Liara) استفاده می‌شود.
انعطاف‌پذیری: کلاینت می‌تواند محدودیت‌های حجم، فرمت فایل و مسیر ذخیره‌سازی را در درخواست تعیین کند. در غیر این صورت، مقادیر پیش‌فرض سیستم اعمال می‌شوند.

Upload File

Body Parameters (Multipart/Form-Data)

Response Structure

Example Responses

۱. آپلود موفق (Success - 201):

{
    "status": true,
    "file": "b2c/uploads/1001/avatar/2023/12/custom-name.jpg"
}

۲. خطای اعتبارسنجی (Validation Error - 422):

{
    "message": "The file must be a file of type: jpeg, png, jpg, gif, pdf, webp.",
    "errors": {
        "file": [
            "The file must be a file of type: jpeg, png, jpg, gif, pdf, webp."
        ]
    }
}

۳. خطای سرور/آپلود (Error - 400):

{
    "status": false,
    "time": 1702165000
}

Technical Logic

GET /b2c/v1/base/data

Get Base Data (Cities, Trains, Configs)

این اندپوینت مرکزی برای دریافت داده‌های پایه (Base Data) و لیست‌های انتخابی (Select Options) در سیستم استفاده می‌شود.
عملکرد داینامیک: خروجی این سرویس کاملاً وابسته به پارامتر ورودی subject است. این متد برای پر کردن لیست شهرها، ایستگاه‌های قطار، فرودگاه‌ها و تنظیمات هتل کاربرد دارد.

Fetch Base Data

Query Parameters (پارامترهای ورودی)

Response Structure

ساختار پاسخ بسته به subject متفاوت است، اما به طور کلی در فرمت زیر است:

{
    "items": [ ...Array of Data... ],
    "meta": {
        "timestamp": 1702123456
    }
}

Examples per Subject (مثال‌ها بر اساس موضوع)

۱. شهرها (subject=cities):

{
    "items": [
        {
            "id": 10,
            "title": { "fa": "تهران", "en": "Tehran" },
            "category": {
                "id": 5,
                "title": { "fa": "تهران", "en": "Tehran" } // نام استان
            }
        }
    ],
    "meta": { ... }
}

۲. انواع قطار (subject=train_types):

{
    "items": [
        {
            "id": 1,
            "title": { "fa": "4 ستاره اتوبوسی", "en": false },
            "details": {
                "type": "bus",
                "star": 4
            }
        }
    ],
    "meta": { ... }
}

۳. نرخ/دید اتاق (subject=room_rate / room_view):

{
    "items": [
        {
            "title": { "fa": "برد", "en": "Board" },
            "status": "1",
            "selected": "0"
        }
    ],
    "meta": { ... }
}

۴. حالت خاص فرودگاه (action=airports):

اگر پارامتر action=airports ارسال شود، ساختار پاسخ متفاوت است:

{
    "status": true,
    "time": 1702123456,
    "data": {
        "titles": [
            {
                "id": 1,
                "iata": "MHD",
                "title": "Mashhad",
                "title_fa": "مشهد",
                "country": 1,
                "group_by": "ایران",
                "state": "خراسان رضوی"
                ...
            }
        ]
    }
}

Technical Logic

GET /b2c/v1/base/accommodations/list

Search Accommodations & Cities

این اندپوینت برای "Autocomplete" یا جستجوی اولیه در بخش هتل استفاده می‌شود.
ورودی کاربر را گرفته و به صورت همزمان در لیست شهرها و اقامتگاه‌ها (هتل، آپارتمان و...) جستجو می‌کند.

Get Accommodation List

Query Parameters (پارامترهای ورودی)

Business Logic (منطق تجاری)

Response Structure

{
    "status": true,
    "time": 1702123456,
    "data": {
        "cities": [ ...Array of Cities OR false... ],
        "accommodation": [ ...Array of Hotels OR false... ]
    }
}

1. ساختار آبجکت شهر (Inside `cities` array)

{
    "id": 10,
    "title": {
        "fa": "تهران",
        "en": "Tehran"
    },
    "country": {
        "fa": "ایران",
        "en": "Iran"
    },
    "state": {
        "fa": "تهران",
        "en": "Tehran"
    },
    "category": {
        "title": "شهر",
        "subtitle": false
    }
}

2. ساختار آبجکت اقامتگاه (Inside `accommodation` array)

{
    "id": 505,
    "en_title": "Espinas Palace",
    "fa_title": "هتل اسپیناس پالاس",
    "type": "هتل",  // Translated value
    "category": {
        "title": "هتل",
        "subtitle": false
    },
    "order": 1,
    // ... سایر فیلدهای بازگردانده شده از Redis/StaticController ...
}

Accommodation Types Mapping

مقادیر فیلد type در خروجی اقامتگاه‌ها به صورت خودکار به فارسی ترجمه می‌شوند:

GET /b2c/v1/base/suggestions/items/{type}

Get Suggestions & Featured Items

این اندپوینت لیستی از آیتم‌های پیشنهادی (Featured) را برای نمایش در صفحه اصلی یا لندینگ پیج‌ها بازمی‌گرداند.
نکته مهم: طبق کد فعلی، داده‌های این سرویس به صورت Hardcoded (ثابت) در کنترلر تعریف شده‌اند و برای شعب خاص (Branch IDs: 2, 4) شخصی‌سازی شده‌اند.

Fetch Suggestion Items

Parameters (پارامترها)

Response Structure

{
    "items": [
        // ... Array of Suggestion Objects ...
    ],
    "meta": {
        "timestamp": 1702123456
    }
}

Item Object Examples (نمونه خروجی آیتم‌ها)

ساختار آبجکت‌های داخل آرایه items بسته به type درخواستی متفاوت است:

۱. نوع تور (type = tour)

{
    "type": "tour",
    "vehicle": "train", // یا aircraft
    "cover": "https://storage.../image.jpg",
    "link": "/search/route-accommodation?origin=37&destination=396...", // لینک فرانت‌اند
    "title": {
        "fa": "تور چهارشب فول برد",
        "en": "4 nights full boards"
    },
    "accommodation": {
        "title": {
            "fa": "هتل آوازه مشهد",
            "en": "Avazeh Hotel"
        },
        "star": 2
    },
    "origin": "اصفهان",
    "destination": "مشهد",
    "price": 96000000,
    "nights": 4
}

۲. نوع بلیط (type = train / aircraft)

{
    "type": "ticket",
    "vehicle": "aircraft", // یا train
    "link": "/search/flights?origin=IFN&destination=MHD",
    "title": { // ممکن است در برخی موارد ارسال نشود
         "fa": "بلیت مشهد قطار",
         "en": "Mashhad ticket"
    },
    "origin": "اصفهان",
    "destination": "مشهد",
    "price": 33990000
}

۳. نوع اقامتگاه (type = accommodation)

{
    "type": "accommodation",
    "cover": "https://storage.../hotel.jpg",
    "link": "/search/accommodations?destination=335&action=accommodation",
    "title": {
        "fa": "اتاق دوتخته فول برد",
        "en": ""
    },
    "accommodation": {
        "title": {
            "fa": "هتل آوازه مشهد",
            "en": "Avazeh Hotel"
        },
        "star": 2
    },
    "destination": "مشهد",
    "price": 12000000
}

Logic & Constraints

GET /b2c/v1/trade/list

User Trade History (List Orders)

این اندپوینت لیست تمامی سفارشات و فاکتورهای کاربر (B2C) یا همکار (B2B) را بازمی‌گرداند.
اطلاعات مالی، وضعیت پرداخت و جزئیات محصول (پرواز، هتل و...) برای هر سفارش محاسبه و ارسال می‌شود.

List User Trades

Business Logic (منطق تجاری)

Response Structure

{
    "status": true,
    "time": 1702123456,
    "data": [
        {
            "method": "flight",       // نوع محصول (flight, train, hotel, ...)
            "submethod": false,       // زیر مجموعه (در صورت وجود)
            "title": "پرواز تهران به مشهد - ماهان", // عنوان فارسی (از کش)
            "details": {
                // تمام فیلدهای سفارش (id, created_at, status, ...)
                "id": 10250,
                "status": 1,
                "created_at": "2024-01-01 12:00:00",
                "financial": {
                    "sum_sale": 15000000,         // مبلغ کل فروش
                    "sum_return_sale": 0,         // مبلغ استرداد شده به مشتری
                    "sum_penalty_sale": 0,        // جریمه کنسلی کسر شده
                    "sum_receive": 15000000,      // مبلغ دریافت شده از مشتری
                    "balance_received": 0         // مانده حساب (بدهی/بستانکاری)
                }
            }
        },
        {
            "method": "hotel",
            "submethod": false,
            "title": 10249, // حالت Fallback: اگر عنوان در کش نباشد، ID برمی‌گردد
            "details": false // در صورت نبودن در کش، جزئیات مالی محاسبه نمی‌شود
        }
    ]
}

Financial Fields Description

POST /b2c/v1/trade/store

Store Trade / Payment Initiation

این اندپوینت برای ثبت نهایی درخواست و انجام عملیات مالی استفاده می‌شود.
سیستم ابتدا وضعیت و قیمت محصول را چک می‌کند. اگر تغییری نباشد، بسته به انتخاب کاربر (کیف پول یا درگاه)، یا تراکنش را آنی انجام می‌دهد و یا لینک پرداخت تولید می‌کند.

Submit Order & Pay

Request Body Parameters

ساختار `requests[pay]`

Business Logic Scenarios

۱. سناریوی تغییر قیمت/وضعیت (Price/Status Changed)

قبل از هر اقدامی، متد statusItemProgress اجرا می‌شود. اگر قیمت یا ظرفیت محصول تغییر کرده باشد:

۲. پرداخت با کیف پول (Wallet Payment)

اگر drive = 'wallet' باشد:

۳. پرداخت آنلاین (Online Gateway)

اگر drive != 'wallet' باشد:

Response Examples

حالت اول: تولید موفق لینک پرداخت (Online)

{
    "payload": {
        "payment_link": "https://airplus.app/p/a1b2c3d4",
        "temporary_id": 12345, // شناسه رزرو موقت
        "status_data": {
            "changed": false // یعنی قیمت تغییر نکرده است
        }
    },
    "meta": {
        "timestamp": 1702123456
    }
}

حالت دوم: خرید موفق با کیف پول (Wallet)

{
    "payload": {
        "payment_id": 9876,
        "reference_id": 500120 // شماره فاکتور نهایی (رزرو قطعی)
    },
    "meta": {
        "timestamp": 1702123456
    }
}

حالت سوم: تغییر قیمت (نیاز به تایید کاربر)

{
    "payload": {
        "payment_link": null,
        "temporary_id": false,
        "status_data": {
            "changed": true,
            "message": "قیمت پرواز تغییر کرده است...",
            "new_price": 15500000
        }
    },
    "meta": {
        "timestamp": 1702123456
    }
}

حالت چهارم: خطای موجودی ناکافی

{
    "error": {
        "code": 1001,
        "message": "اعتبار شما برای این خرید کافی نمی باشد. لطفا قبل از انجام این عملیات موجودی حساب خود را افزایش دهید."
    },
    "meta": {
        "timestamp": 1702123456
    }
}

POST /b2c/v1/trade/completion

Trade Completion & Issuance

این اندپوینت برای تکمیل فرآیند خرید استفاده می‌شود.
زمانی که پرداخت (آنلاین یا کیف پول) تایید شد، این متد برای صدور فاکتور (Factor)، بروزرسانی اطلاعات مسافران، ثبت تراکنش‌های مالی (Pledgers/Pays) و ارسال SMS نهایی به کاربر فراخوانی می‌گردد.

Finalize Order

Request Body Parameters

این متد یک آبجکت JSON پیچیده شامل اطلاعات پرداخت و جزئیات درخواست را دریافت می‌کند.

Step-by-Step Logic Breakdown

۱. ایجاد فاکتور (Factor Creation)

یک رکورد در جدول factors ایجاد می‌شود:

۲. مدیریت مسافران (Passengers Upsert)

سیستم روی آرایه request['passengers'] حلقه می‌زند:

۳. مدیریت مالی و تعهدات (Pledgers & Pays)

این بخش مشخص می‌کند "چه کسی پول را می‌دهد":

۴. پردازش آیتم‌ها (Items Processing)

بر اساس نوع سرویس (aircraft, train, accommodation):

۵. ارسال اعلان (Notification)

اگر notices: true باشد:

Response Examples

پاسخ موفق (Success - 200 OK)

{
    "status": true,
    "time": 1702123456,
    "payment": {
        "amount": 15000000,
        "method": "wallet"
    },
    "reference_id": "8XKA9L2P", // شناسه فاکتور (Factor Slug)
    "details": false // یا آرایه‌ای از خطاها در صورت وجود مشکل جزئی
}

پاسخ موفق همراه با هشدار (Success with Warnings)

اگر خرید کلی انجام شود اما برخی آیتم‌ها (مثلاً یکی از پروازها) رزرو نشوند:

{
    "status": true,
    "time": 1702123456,
    "reference_id": "8XKA9L2P",
    "details": [
        {
            "local_id": 101,
            "message": "ظرفیت این کلاس پروازی تکمیل شده است."
        }
    ]
}

پاسخ خطا (Failure)

{
    "status": false,
    "code": "1004-500",
    "message": "1004-500 : خطای داخلی سرور در هنگام ثبت رکورد",
    "trace": "..."
}

POST /b2c/v1/online/search/{type}

Search Flights & Trains

این اندپوینت برای جستجوی بلیط‌های سفر استفاده می‌شود.
سیستم به صورت هوشمند بر اساس نوع درخواست (قطار یا پرواز)، ورودی‌ها را اعتبارسنجی کرده، اطلاعات تکمیلی مبدا/مقصد را از دیتابیس یا کش Redis استخراج می‌کند و نتایج جستجو را از سرویس‌های تجمیع‌کننده (Aggregators) بازمی‌گرداند.

Route Search

Path Parameters

Request Body Parameters

پارامترهای مشترک (Common)

اگر type = 'train' باشد:

اگر type != 'train' (پرواز) باشد:

Business Logic Details

۱. احراز هویت اختیاری (Optional Pipeline Auth)

حتی اگر روت عمومی باشد، کد چک می‌کند اگر هدر Authorization وجود داشته باشد، درخواست را از پایپ‌لاین AuthWithJWT عبور می‌دهد. این کار برای اعمال تخفیف‌های خاص یا دسترسی‌های سطح کاربر (Level) انجام می‌شود.

۲. اعتبارسنجی قطار (Train Validation)

برای جستجوی قطار اعتبارسنجی سخت‌گیرانه‌تری روی تاریخ‌ها انجام می‌شود:

۳. غنی‌سازی اطلاعات مبدا/مقصد (Metadata Enrichment)

سیستم قبل از پاسخ‌دهی، اطلاعات کامل شهر یا فرودگاه را به پاسخ اضافه می‌کند:

۴. فراخوانی سرویس پایه (Base Service)

Response Examples

پاسخ جستجوی قطار (Train Response)

ساختار پاسخ قطار شامل payload و meta است.

{
    "payload": [
        // لیست قطارهای یافت شده از سرویس
        {
            "id": 105,
            "price": 2500000,
            "provider": "raja",
            "capacity": 4
        }
    ],
    "meta": {
        "search": {
            "origin": {
                "id": 37,
                "title": {"fa": "اصفهان", "en": "Isfahan"},
                "category": {"id": 5, "title": {"fa": "اصفهان", "en": "Isfahan"}}
            },
            "destination": {
                "id": 396,
                "title": {"fa": "مشهد", "en": "Mashhad"},
                "category": {"id": 10, "title": {"fa": "خراسان رضوی", "en": "Razavi Khorasan"}}
            },
            "departure": "2025-12-10",
            "returning": false
        },
        "timestamp": 1702123456
    }
}

پاسخ جستجوی پرواز (Flight Response)

ساختار پاسخ پرواز کمی متفاوت است و مستقیماً آرایه برمی‌گرداند.

{
    "search": {
        "origin": {
            "id": 1,
            "iata": "MHD",
            "title": "فرودگاه هاشمی نژاد",
            "country": { "id": 100, "title_fa": "ایران" },
            "city": { "id": 396, "title_fa": "مشهد" }
        },
        "destination": {
            "id": 2,
            "iata": "THR",
            "title": "فرودگاه مهرآباد",
            "city": { "id": 1, "title_fa": "تهران" }
        },
        "departure_date": "2025-12-10",
        "returning_date": null
    },
    "data": [
        // لیست پروازهای یافت شده
        {
            "flight_id": "WS-123",
            "airline": "Mahan",
            "price": 15000000
        }
    ]
}

خطای اعتبارسنجی تاریخ (Train Error)

{
    "error": {
        "code": 1000,
        "message": "تاریخ شروع و پایان جستجو معتبر نمی باشد"
    }
}

POST /b2c/v1/online/{type}/lock

Lock Item (Pre-Booking)

این متد برای "قفل کردن" یا "اعتبارسنجی نهایی" یک آیتم انتخابی (مانند یک پرواز یا بلیط قطار) قبل از ورود اطلاعات مسافران استفاده می‌شود.
در این مرحله، سیستم با تامین‌کننده ارتباط برقرار کرده، تغییرات احتمالی قیمت را بررسی می‌کند و یک رکورد در جدول رزروهای موقت ایجاد می‌کند.

Lock Selection

Path Parameters

Request Body Parameters

Business Logic Details

۱. احراز هویت و زمینه (Auth Context)

این متد توسط میدل‌ور authWithJwt محافظت می‌شود. این میدل‌ور اطلاعات کاربر (`operator`) و شعبه (`branch`) را به آبجکت $request تزریق می‌کند.

۲. فراخوانی سرویس پایه (BaseService Call)

متد BaseService::lockItemProgress با پارامترهای زیر فراخوانی می‌شود:

۳. ثبت در رزروهای موقت (Temporary Reservation)

نتیجه‌ی عملیات به همراه اطلاعات ورودی در جدول temporary_reservations ذخیره می‌شود:

شناسه این رکورد (`LockId`) تولید شده و در پاسخ بازگردانده می‌شود. این شناسه کلید اصلی برای مرحله بعد (ثبت مسافر و پرداخت) است.

۴. مدیریت خطا (Exception Handling)

اگر سرویس خارجی خطا دهد یا آیتم موجود نباشد (Exception)، سیستم:

Response Examples

مثال درخواست (Request)

{
    "data": {
        "flight_id": "WS-5050",
        "provider_key": "some_encrypted_key_from_search_result",
        "price": 1500000,
        "class": "Economy"
    }
}

پاسخ موفق (Success - 200 OK)

{
    "status": true,
    "time": 1702123456,
    "lock_id": 9852,
    "data": {
        "status": "confirmed",
        "new_price": 1500000,
        "token": "reservation_token_12345",
        "expiration": "20 mins"
    }
}

نکته: مقدار lock_id (در این مثال 9852) باید توسط کلاینت ذخیره شده و در اندپوینت خرید (`trade/store`) ارسال شود.

پاسخ خطا (Error - 400 Bad Request)

{
    "status": false,
    "time": 1702123499,
    "error": {
        "code": 1002,
        "message": "ظرفیت پرواز تکمیل شده است یا قیمت تغییر کرده است.",
        "trace": [ ... ]
    },
    "support": {
        "phone": "021-91016838 in 121",
        "email": "ict@airplus.app",
        "panel": "helpdesk.airplus.app"
    }
}

POST /b2c/v1/online/{type}/penalty

Refund Penalty Calculation

این اندپوینت برای محاسبه جریمه استرداد رزرو یا بلیط آنلاین طراحی شده است.
سیستم با توجه به نوع سرویس ({type}) و شعبه ارسال‌کننده، میزان جریمه، مبلغ قابل استرداد و قوانین مربوط به لغو رزرو را محاسبه می‌کند.

Calculate Refund Penalty

Path Parameters

Request Body Parameters

Response Structure

Example Response - Success

{
    "items": [
      {
        "provider": "Mahan Air",
        "ticket_number": "WS5050",
        "original_price": 15000000,
        "penalty_amount": 3000000,
        "refundable_amount": 12000000,
        "currency": "IRR",
        "rule": "لغو تا ۳ ساعت مانده به پرواز با جریمه ۲۰٪"
      }
    ],
    "meta": {
      "timestamp": 1733739501
    }
}

Error Response (400 Bad Request)

{
    "status": false,
    "time": 1733739501,
    "error": {
      "code": 1002,
      "message": "Invalid booking data format or provider error.",
      "trace": [ ... ]
    },
    "support": {
      "phone": "021-91016838 in 121",
      "email": "ict@airplus.app",
      "panel": "helpdesk.airplus.app"
    }
}

Technical Logic

POST /b2c/v1/online/{type}/refund

Refund Request Operation

این اندپوینت جهت ثبت و پردازش عملیات درخواست استرداد (Refund) برای بلیط یا رزرو آنلاین ایجاد شده است. پس از ارسال اطلاعات رزرو، توضیحات کاربر و مشخصات شعبه، فرآیند استرداد از طریق سرویس اصلی BaseService::refundItemProgress اجرا می‌شود. پاسخ شامل اطلاعات تراکنش استرداد و وضعیت نهایی عملیات خواهد بود.

Refund Item Progress

Path Parameters

Request Body Parameters

Response Structure

Example Response — Success

{
  "items": {
    "reference": "RFD-83234",
    "status": "accepted",
    "refund_amount": 1200000,
    "currency": "IRR",
    "provider": "Mahan Airlines",
    "description": "لغو پرواز توسط مسافر",
    "processed_at": "2025-12-09T17:40:22Z"
  },
  "meta": {
    "timestamp": 1733739622
  }
}

Example Response — Error (400)

{
  "status": false,
  "time": 1733739622,
  "error": {
    "code": 1002,
    "message": "Refund process failed: invalid ticket reference",
    "trace": [ ... ]
  },
  "support": {
    "phone": "021-91016838 in 121",
    "email": "ict@airplus.app",
    "panel": "helpdesk.airplus.app"
  }
}

Technical Logic

GET /b2c/v1/online/accommodation/list

List Accommodation Items

این اندپوینت فهرستی از اقامتگاه‌ها (هتل‌ها) را بر اساس شهر، IATA، یا شناسه‌ی مستقیم هتل بازیابی می‌کند. امکان اعمال فیلترهای متنوع شامل ستاره، نوع، نام، سرویس‌دهنده‌ها و محدوده‌ی تاریخی رزرو وجود دارد. در صورت انتخاب only_charters=true، نتایج محدود به هتل‌های دارای چارتر فعال در بازه‌ی داده‌شده خواهند بود.

Endpoint Info

Query Parameters

Response Structure

Example Response (Success)

{
  "Status": true,
  "Time": 1733742000,
  "Search": {
    "city": {
      "id": 396,
      "title": {"fa": "مشهد", "en": "Mashhad"},
      "country": {"fa": "ایران", "en": "Iran"},
      "category": {"title": "شهر"}
    }
  },
  "Data": [
    {
      "id": 2652,
      "fa_title": "اکسلسیور کیش",
      "en_title": "Excelsior Kish Hotel",
      "rate": 5,
      "type": "hotel",
      "city": "مشهد",
      "priority": 0,
      "mapping": {"airplus": true, "snapptrip": true}
    }
  ],
  "Table": {
    "total": 250,
    "per_page": 30,
    "current_page": 1,
    "last_page": 9,
    "from": 1,
    "to": 30,
    "next_page": 2
  }
}

Example Response (Error)

{
  "status": false,
  "time": 1733742053,
  "error": {
    "code": 1002,
    "message": "Invalid city or date format.",
    "trace": [ ... ]
  },
  "support": {
    "phone": "021-91016838 in 121",
    "email": "ict@airplus.app",
    "panel": "helpdesk.airplus.app"
  }
}

Technical Flow (Logic Overview)

GET /b2c/v1/online/accommodation/get_min_prices

Get Accommodation Minimum Prices

این اندپوینت حداقل قیمت (Minimum Price) اقامتگاه‌ها را در بازه‌ای از تاریخ ارائه می‌دهد. داده‌ها از چند سرویس خارجی شامل AirPlus، Sepehr، Tport و SnappTrip واکشی می‌شوند. نتایج هر اقامتگاه به‌صورت cache شده در Redis با TTL دینامیک نگهداری می‌شود تا بار API کاهش پیدا کند.

Endpoint Info

Query Parameters

Response Structure

Example Response (Success)

{
  "Status": true,
  "Time": 1733743200,
  "Data": {
    "2137": {
      "id": 2137,
      "min_price": 4800000,
      "min_original_price": 5500000
    },
    "2652": {
      "id": 2652,
      "min_price": 3600000,
      "min_original_price": 4100000
    }
  }
}

Example Response (Error)

{
  "status": false,
  "time": 1733743300,
  "error": {
    "code": 1002,
    "message": "Invalid accommodations parameter.",
    "trace": [ ... ]
  },
  "support": {
    "phone": "021-91016838 in 121",
    "email": "ict@airplus.app",
    "panel": "helpdesk.airplus.app"
  }
}

Logic Flow

Expiration (Redis TTL Rules)

GET /b2c/v1/online/accommodation/get_room_type_prices

Get Room Type Prices

این اندپوینت کلیهٔ قیمت‌های مرتبط با نوع اتاق (RoomType) را از سرویس‌دهندگان مختلف واکشی و تجمیع می‌کند. پس از محاسبهٔ قیمت خالص (Net)، قیمت اصلی (Board)، و ماکاپ‌ها برای هر تأمین‌کننده، نتیجه‌ی مرتب‌شده و کمترین قیمت محاسبه‌شده در Redis ذخیره می‌شود. این ورودی، موتور قیمت‌گذاری اصلی صفحه هتل در B2C است.

Endpoint Info

Query Parameters

Logical Flow

Redis Cache Logic

Response Structure

نمونه خروجی موفق

{
  "Status": true,
  "Time": 1733744200,
  "Data": [
    {
      "id": 10502,
      "fa_title": "اتاق دوتخته فول برد",
      "purchase_capacity": 3,
      "board_type_list": [
        {
          "service": "airplus",
          "financial_total": {
            "board_price": 4860000,
            "net_price": 4500000,
            "markup": 0.07
          },
          "supplier": { "id": 28, "title_fa": "AirPlus Hub" }
        }
      ]
    }
  ]
}

GET /b2c/v1/online/accommodation/get_details

Get Accommodation Details

این اندپوینت تمام جزئیات مربوط به یک اقامتگاه (هتل) را بر اساس شناسه ورودی برمی‌گرداند. جزئیات شامل اطلاعات عمومی هتل، رسانه‌ها (تصاویر، ویدیو، لوگو)، امکانات گروه‌بندی‌شده، سیاست‌ها، قوانین عمومی و قوانین استرداد می‌باشد. در صورت وجود چارتر فعال برای آن هتل، اطلاعات انتقال (Transfer) نیز به سیاست‌ها افزوده می‌شود.

Endpoint Info

Query Parameters

Logic Flow

Response Structure

AccommodationResource شامل فیلدهای زیر است:

Example Response (Success)

{
  "Status": true,
  "Time": 1733744800,
  "Data": {
    "id": 2137,
    "fa_title": "هتل بزرگ شیراز",
    "en_title": "Grand Hotel Shiraz",
    "rate": 5,
    "city": "شیراز",
    "address": "بلوار قرآن، نرسیده به دروازه قرآن",
    "logo": "https://storage.service01.ir/media/accommodations/2025/logo/grand-shiraz.png",
    "media": {
      "images": [{ "path": "https://storage.../1.jpg" }],
      "videos": false
    },
    "facility_categories": [
      {
        "id": 3,
        "title": "امکانات رفاهی",
        "facilities": [
          { "id": 12, "title": "استخر سرپوشیده" },
          { "id": 24, "title": "سونا و جکوزی" }
        ]
      }
    ],
    "rules": {
      "cancellation": [
        { "id": 1, "hours_before": 48, "percent": 10 }
      ],
      "public": [
        { "id": 2, "rule": "ورود حیوانات خانگی ممنوع است" }
      ],
      "policies": {
        "checkin": "14:00",
        "checkout": "12:00",
        "welcome_transfer": 1,
        "return_transfer": 0
      }
    }
  }
}

Example Response (Not Found)

{
  "Status": false,
  "Time": 1733744801,
  "Message": "Accommodation not found."
}

GET /b2c/v1/online/flight/class/{calculation_id}

Get Flight Class Data

این اندپوینت برای واکشی اطلاعات کامل یک کلاس پروازی از روی شناسه محاسبه (`calculation_id`) طراحی شده است. داده بازگشتی شامل جزئیات فنی، مالی، مارکاپ‌ها و تخفیف‌ها برای سنین مختلف (Adult/Child/Infant) است. درصورت معتبر بودن شناسه، داده از سرویس AirPlusApi با متد search واکشی می‌شود و پس از بررسی فیلترهای application_filter و پردازش مارکاپ‌ها توسط LibBaseService::checkSearchFlightItem() به صورت JSON بازگردانده می‌شود.

Endpoint Info

Path Parameters

Query Parameters

Logic Flow

Response Samples

✅ موفق (پردازش کلاس‌های پروازی)

{
  "payload": {
    "Airline": { "iata": "W5", "title": "Mahan Air" },
    "Origin": { "iata": "THR" },
    "Destination": { "iata": "MHD" },
    "FlightNumber": "W51234",
    "FlightType": "Charter",
    "Classes": [
      {
        "CabinType": "Economy",
        "Financial": {
          "Adult": {
            "BaseFare": 950000,
            "Tax": 50000,
            "Payable": 1000000,
            "Markup": {
              "percent": 10,
              "price": 100000,
              "final": 1100000,
              "discount": { "percent": 0, "price": 0 }
            }
          }
        },
        "AvailableSeat": 4,
        "Remarks": {
          "Inbound": { "Special": 0, "TourRequirement": false }
        }
      }
    ]
  },
  "meta": { "timestamp": 1733750500 }
}

❌ خطا – آیتم یافت نشد

{
  "error": {
    "code": 1001,
    "message": ".آیتم مورد نظر یافت نشد"
  },
  "meta": { "timestamp": 1733750510 }
}

Technical Notes

GET /b2c/v1/online/payment/flight/tracking

Tracking Payment Flight

اندپوینت زیر برای بررسی وضعیت پرداخت و رزرو پرواز از روی کد ملی و شماره رفرنس طراحی شده است. این متد با اتصال داخلی به V2TradeController::operationTrade() وضعیت فاکتور، اطلاعات پرواز و مسافران را بازیابی کرده و داده‌های حساس مالی را از خروجی حذف می‌کند.

Endpoint Info

Query Parameters

Logic Flow

Response Samples

✅ موفق - فاکتور یافت شد

{
  "payload": {
    "serial_id": 26789,
    "data": [
      {
        "serial_id": 26790,
        "title": "تهران → مشهد",
        "status": 3,
        "departure_datetime": "2025-12-09 10:15",
        "arrival_datetime": "2025-12-09 11:45",
        "airline_code": "W5",
        "aircraft": "Airbus A321",
        "cabin": "Economy"
      }
    ],
    "passengers": [
      { "name_fa": "علیرضا رضایی", "sex": "male", "national_code": "1234567890" }
    ],
    "leader": { "name_fa": "علیرضا رضایی", "mobile": "09121234567" }
  },
  "meta": { "timestamp": 1733750909 }
}

❌ خطا – مشتری یافت نشد

{
  "error": {
    "code": 1001,
    "message": ".مسافر مورد نظر یافت نشد"
  },
  "meta": { "timestamp": 1733750915 }
}

❌ خطا – فاکتور یافت نشد

{
  "error": {
    "code": 1001,
    "message": ".رفرنس مورد نظر یافت نشد"
  },
  "meta": { "timestamp": 1733750921 }
}

Technical Notes

GET /b2c/v1/financial/list

List Financial History

این اندپوینت برای نمایش لیست تراکنش‌های مالی کاربران طراحی شده است و بسته به نوع گروه کاربری (b2c یا b2b/ colleague) داده‌ها از جداول متفاوتی واکشی می‌گردند. برای کاربران B2C، از جداول factor_items، factors و pays اطلاعات استخراج می‌شود و برای کاربران B2B/Colleague از جدول wallet.

Endpoint Info

Query Parameters

Logic Flow

Response Sample

{
  "status": true,
  "time": 1733751800,
  "data": [
    {
      "serial": 19087,
      "type": "receive",
      "type_pay": "reference",
      "deadline": "20251209",
      "currency": "IRR",
      "fee": 0,
      "amount": 2500000,
      "tracking_code": "TRX-19572",
      "description": {
        "reason": "پرداخت بابت فاکتور 17894",
        "gateway": "Parsian",
        "invoice": "Ref#X20991"
      }
    },
    {
      "serial": 26789,
      "type": "payment",
      "type_pay": "wallet",
      "deadline": "20251209",
      "currency": "IRR",
      "fee": 0,
      "amount": 1200000,
      "tracking_code": 26789,
      "description": "بابت هزینه خدمات هاب با عطف 2851"
    }
  ]
}

Technical Notes

GET /b2c/v1/passengers/previous

List Previous Passengers

این اندپوینت جهت واکشی لیست مسافرانی که پیش‌تر در رزروهای کاربر (یا همکار) شرکت داشته‌اند طراحی شده است. اطلاعات از جدول customers واکشی شده و شامل جزئیات هویتی، ملیتی، گذرنامه و تماس فرد می‌باشد.

Endpoint Info

Query Parameters (from JWT + Request)

Logic Flow

Response Samples

✅ موفق - لیست مسافران قبلی

{
  "items": [
    {
      "id": 1547,
      "gender": 1,
      "fullname": {
        "first_name": { "fa": "علیرضا", "en": "Alireza" },
        "last_name": { "fa": "رضایی", "en": "Rezaei" }
      },
      "email": "alireza@example.com",
      "mobile": "09123456789",
      "birth": "13721021",
      "identity": {
        "id": "1234567890",
        "nationality": {
          "id": 118,
          "iso": "IR",
          "title": { "fa": "ایران", "en": "Iran" },
          "nationality": { "fa": "ایرانی", "en": "Iranian" }
        }
      },
      "passport": {
        "id": "P98651234",
        "expire_at": "20270930"
      }
    }
  ],
  "meta": { "timestamp": 1733752711 }
}

❌ خطا – Passenger ID خالی

{
  "error": {
    "message": "Passenger ID is required",
    "code": "passenger_id_required"
  },
  "meta": { "timestamp": 1733752715 }
}

Technical Notes

GET /b2c/v1/gateway/details

Payment Gateway Details

این اندپوینت جزئیات تراکنش از درگاه بانکی (Payment Gateway) را بر اساس serial_id برمی‌گرداند. در صورتی‌که وضعیت تراکنش موفق (status=3) باشد، اطلاعات کارت و کد رهگیری نمایش داده می‌شود؛ در غیر این صورت، پیام خطا و جزئیات تراکنش ناموفق بازگردانده می‌شود.

Endpoint Info

Query Parameters

Logic Flow

SELECT payment_gateway.*, gateways.drive as drive_title
FROM payment_gateway
JOIN gateways ON payment_gateway.drive = gateways.id
WHERE payment_gateway.serial_id = :serial_id

Response Samples

🎯 پرداخت موفق (درگاه Behpardakht)

{
  "payload": {
    "drive": "behpardakht",
    "amount": 1250000,
    "card": "610433******8124",
    "datetime": "2025-12-09T10:12:35",
    "tracking_code": "74632159"
  },
  "meta": { "timestamp": 1733749500 }
}

⚠️ پرداخت ناموفق (درگاه Behpardakht)

{
  "error": {
    "code": 1000,
    "message": "پرداخت ناموفق | تراکنش توسط دارنده کارت لغو شد"
  },
  "meta": {
    "timestamp": 1733749600,
    "data": {
      "message": "تراکنش توسط دارنده کارت لغو شد",
      "datetime": "2025-12-09T10:12:35",
      "tracking_code": "69854172"
    }
  }
}

❌ پرداختی یافت نشد

{
  "error": {
    "code": 1000,
    "message": "پرداختی با این مشخصات یافت نشد."
  },
  "meta": { "timestamp": 1733749700 }
}

Technical Notes

GET /b2c/v1/discount/submit

Submit Discount Code

این اندپوینت برای بررسی و اعمال کد تخفیف‌های فعال هر branch (دفتر عامل) طراحی شده است. کد تخفیف فقط در صورتی قابل استفاده است که هنوز منقضی نشده باشد، محدودیت استفاده آن تمام نشده باشد و در صورت تعریف کاربر خاص، توسط همان کاربر ارسال شود.

Endpoint Info

Query Parameters

Logic Flow

SELECT * FROM payment_discount
WHERE branch = :branch
  AND status = 1
  AND type = :type
  AND code = LOWER(:code)
LIMIT 1;

status = 3, limit = 0

Response Samples

✅ تخفیف معتبر

{
  "status": true,
  "time": 1733756000,
  "data": {
    "id": 47,
    "title": "تخفیف ویژه پرواز نوروزی",
    "type": "percent",
    "value": 10
  }
}

❌ کد تخفیف منقضی شده

{
  "status": false,
  "time": 1733756005,
  "message": "کد تخفیف وارد شده منقضی شده است."
}

❌ کد تخفیف برای کاربر دیگری است

{
  "status": false,
  "time": 1733756010,
  "message": "کد تخفیف وارد شده برای کاربر دیگری می باشد."
}

❌ کد تخفیف پیدا نشد

{
  "status": false,
  "time": 1733756020,
  "message": "کد تخفیف وارد شده معتبر نمی باشد."
}

Technical Notes

GET /b2c/v1/discount/unsubmit

Unsubmit Discount Code

این اندپوینت برای بازگرداندن ظرفیت یا اعتبار مصرف‌شده‌ی یک کد تخفیف در سیستم B2C طراحی شده است. در واقع، اگر کد تخفیف اشتباهی استفاده یا تراکنش مربوط به آن لغو شود، با این درخواست می‌توان مقدار limit آن را افزایش داد و status را در حالت فعال (1) قرار داد.

Endpoint Info

Query Parameters

Logic Flow

Response Samples

✅ بازگردانی موفق اعتبار

{
  "status": true,
  "time": 1733758800
}

❌ کد تخفیف یافت نشد

{
  "status": false,
  "time": 1733758810,
  "message": "کد تخفیف معتبر نمی باشد."
}

Technical Notes

GET /b2c/v1/wallet/ballance

Wallet Balance

این اندپوینت برای واکشی موجودی کیف‌پول کاربر در سیستم B2C طراحی شده است. بر اساس group (مقدار JWT احراز هویت)، نوع کاربر بین B2C و B2B (colleague) تشخیص داده می‌شود و سپس موجودی کیف پول از جدول wallet با استفاده از کنترلر مالی اصلی (AccountingController) فراخوانی می‌گردد.

Endpoint Info

Query Parameters (JWT‑required)

Logic Flow

{
  "error": {
    "code": 1000,
    "message": "گروه کاربری یافت نشد"
  },
  "meta": { "timestamp": 1733763100 }
}

Response Samples

✅ پاسخ موفق (کاربر B2C)

{
  "payload": {
    "ceiling": 2000000,
    "deadline": "2025-12",
    "wallet": {
      "credit": 5000000,
      "debit": 2500000,
      "balance": 2500000,
      "diagnosis": "creditor"
    }
  },
  "meta": { "timestamp": 1733763100 }
}

✅ پاسخ موفق (کاربر colleague/B2B)

{
  "payload": {
    "ceiling": 10000000,
    "deadline": false,
    "wallet": {
      "credit": 3200000,
      "debit": 3500000,
      "balance": -300000,
      "diagnosis": "debtor"
    }
  },
  "meta": { "timestamp": 1733763120 }
}

❌ گروه اشتباه

{
  "error": {
    "code": 1000,
    "message": "گروه کاربری یافت نشد"
  },
  "meta": { "timestamp": 1733763130 }
}

Internal Logic – AccountingController::getBalanceWallet()

static function getBalanceWallet($type, $id, $method='branch') {
    // تعیین نوع اپراتور
    if ($type == 'colleague') { $type = 'b2b'; } else { $type = 'erp'; }

    // جمع مجموع بدهکار و بستانکار
    $wallet = DB::table('wallet')
      ->selectRaw('SUM(credit) as credit, SUM(debit) as debit')
      ->where(function ($q) use ($type, $id, $method) {
          if ($method == 'branch')
              $q->where('operator_type', 'erp')->where('branch', $id);
          else
              $q->where('operator_type', $type)->where('operator', $id);
      })
      ->where('status', '!=', 2)
      ->first();

    return [
      "credit" => (int)$wallet->credit,
      "debit" => (int)$wallet->debit,
      "balance" => ($wallet->credit - $wallet->debit),
      "diagnosis" => ($wallet->credit - $wallet->debit) >= 0
        ? (($wallet->credit - $wallet->debit) == 0 ? 'neutral' : 'creditor')
        : 'debtor'
    ];
  }

Technical Notes

POST /b2c/v1/wallet/credit

POST /b2c/v1/wallet/credit

این اندپوینت به کاربران B2C و همکاران (B2B/Colleague) اجازه می‌دهد تا از طریق درگاه پرداخت فعال دفتر خود، مبلغی را به کیف‌پولشان واریز کنند. نتیجه نهایی تولید لینک پرداخت منحصر‌به‌فرد با ساختار /p/{slug} است.

Endpoint Information

Request Body Parameters

Validation & Logic Flow

🎯 Response Samples

✅ موفق

{
  "payload": {
    "status": "payment_link",
    "amount": 250000,
    "url": "https://agency-domain.com/p/ABX21SD2",
    "slug": "ABX21SD2",
    "pay_id": 35876,
    "gateway_id": 44
  },
  "meta": { "timestamp": 1733765953 }
}

❌ فیلد ناقص

{
  "error": {
    "code": 1000,
    "message": "لطفا تمامی فیلد ها را پر کنید."
  },
  "meta": { "timestamp": 1733765958 }
}

❌ درگاه پیدا نشد

{
  "error": {
    "code": 1000,
    "message": "درگاه پرداخت فعال یافت نشد"
  }
}

ساختار جدول‌های مرتبط

توضیح توابع وابسته

نکات فنی

GET /b2c/v1/ledger-account

ledger-account

این اندپوینت برای واکشی حساب کل دفتر همکار (colleague) در سیستم مالی B2C به‌کار می‌رود و از داده‌های تجمیع‌شده در Redis و خروجی متد ColleaguesController::colleagueLedgerAccounts استفاده می‌کند تا هم جزئیات صورت‌حساب‌ها (ledger items) و هم مانده‌ی کل حساب را برگرداند.

Endpoint Information

پارامترهای ورودی

منطق پردازشی (Flowchart)

ساختار خروجی JSON

پاسخ موفق

{
  "items": [
    {
      "serial_id": "1404-22",
      "datetime": "1404/09/01 00:00:00",
      "credit": 500000,
      "debit": 0,
      "description": { "html": "واریز بابت فاکتور #22", "text": "واریز بابت فاکتور #22" },
      "details": { "type": { "title": "دریافت نقدی" } }
    }
  ],
  "payload": {
    "debit": 1250000,
    "credit": 500000,
    "balance": -750000,
    "diagnosis": "بدهکار",
    "documents": 17
  },
  "meta": { "timestamp": 1733768901 }
}

پاسخ بدون داده

{
  "items": [],
  "payload": {
    "debit": 0,
    "credit": 0,
    "balance": 0,
    "diagnosis": 0,
    "documents": 0
  },
  "meta": { "timestamp": 1733768903 }
}

نکات فنی و باگ‌های شناسایی‌شده

GET /b2c/v1/articles

GET /b2c/v1/articles

این اندپوینت برای دریافت فهرست مقالات در سیستم B2C استفاده می‌شود. امکان فیلتر بر اساس دسته‌بندی‌ها، تگ‌ها و موقعیت‌ها (places) و همچنین مرتب‌سازی بر اساس امتیاز (score) یا تعداد بازدید (views) فراهم شده است. در حالت عادی خروجی صفحه‌بندی‌شده برمی‌گردد، اما در حالت مرتب‌سازی خاص، داده‌ها به صورت محدود و غیر صفحه‌بندی بازگردانده می‌شوند.

Endpoint Information

پارامترهای Query قابل استفاده

منطق پردازشی و جریان داده (Flowchart)

📦 ساختار پاسخ JSON

پاسخ موفق

{
  "status": true,
  "time": 1733799551,
  "data": [
    {
      "id": 245,
      "title": "راهنمای سفر مشهد",
      "excerpt": "در این مقاله به جاذبه‌های گردشگری...",
      "cover": "https://cdn.site.com/uploads/article245.jpg",
      "views": 932,
      "score": 4.8,
      "categories": [5, 7],
      "tags": [12, 98],
      "created_at": "2025-11-22T10:00:00Z"
    },
    ...
  ],
  "links": {
    "first": "https://api.domain.com/b2c/v1/articles?page=1",
    "last": "https://api.domain.com/b2c/v1/articles?page=15",
    "prev": null,
    "next": "https://api.domain.com/b2c/v1/articles?page=2"
  }
}

🔹 پاسخ در حالت مرتب‌سازی (بدون pagination)

{
  "status": true,
  "time": 1733799553,
  "data": [ { ... }, { ... }, ... ],
  "links": false
}

نکات فنی

🚀 پیشنهادات بهبود برای توسعه آینده

GET /b2c/v1/articles/{article}

GET /b2c/v1/articles/{article}

این اندپوینت برای مشاهده جزئیات یک مقاله خاص در سامانه‌ی B2C طراحی شده است. ورودی شامل شناسه یا slug مقاله است که به‌صورت Model Binding لاراول به Article تبدیل می‌شود. نتیجه در قالب ArticleResource بازگردانده می‌شود تا داده‌ها به شکل استاندارد JSON ارائه شود.

Endpoint Information

پارامترهای مسیر (Path Parameters)

منطق اجرای متد (Flow Logic)

پاسخ موفق (Success Response)

{
  "status": true,
  "time": 1733802321,
  "data": {
    "id": 245,
    "title": "راهنمای سفر به تبریز",
    "excerpt": "بررسی بهترین جاذبه‌های گردشگری …",
    "body": "

در این مقاله به بررسی مکان‌های دیدنی ...

",
    "cover": "https://cdn.site.com/uploads/articles/245.jpg",
    "views": 537,
    "score": 4.6,
    "categories": [1, 5],
    "tags": [12, 33, 70],
    "places": [18],
    "created_at": "2025-11-29T08:00:00Z",
    "updated_at": "2025-12-05T14:10:00Z"
  }
}

خطاهای احتمالی

📘 توضیحات اجرایی برای توسعه‌دهنده (Dev Notes)

GET /b2c/v1/categories

GET /b2c/v1/categories

این اندپوینت برای دریافت فهرست دسته‌بندی‌ها (Categories) طراحی شده است. داده‌ها از جدول categories گرفته می‌شوند و امکان فیلتر بر اساس نوع (type) و شعبه (branch) وجود دارد. فقط دسته‌بندی‌های سطح اول (یعنی مواردی که main آن‌ها NULL است) بازگردانده می‌شوند.

Endpoint Information

پارامترهای ورودی (Query Parameters)

منطق پردازشی (Process Flow)

📦 ساختار پاسخ JSON

پاسخ موفق

{
  "status": true,
  "time": 1733806124,
  "data": [
    {
      "id": 12,
      "title": {
        "fa": "مقاصد محبوب",
        "en": "Popular Destinations"
      },
      "slug": "popular-destinations",
      "type": "article",
      "main": null,
      "cover": "https://cdn.site.com/uploads/categories/12.jpg",
      "created_at": "2025-11-25T07:10:00Z"
    },
    {
      "id": 13,
      "title": {
        "fa": "تورهای داخلی",
        "en": "Domestic Tours"
      },
      "slug": "domestic-tours",
      "type": "tour",
      "main": null,
      "cover": "https://cdn.site.com/uploads/categories/13.jpg"
    }
  ],
  "links": {
    "first": "https://api.domain.com/b2c/v1/categories?page=1",
    "last": "https://api.domain.com/b2c/v1/categories?page=10",
    "prev": null,
    "next": "https://api.domain.com/b2c/v1/categories?page=2"
  }
}

پاسخ خطا (نمونه)

{
  "status": false,
  "time": 1733806125,
  "message": "پارامتر branch ارسال نشده است."
}

نکات فنی و اجرایی

🚀 پیشنهاد بهبود آینده

POST /b2c/v1/articles/{id}/views

POST /b2c/v1/articles/{id}/views

این اندپوینت برای افزایش شمارش بازدید مقاله استفاده می‌شود. هنگام نمایش جزئیات مقاله در سمت کاربر (مانند صفحه‌ی article detail)، فرانت‌اند می‌تواند پس از بارگذاری موفق مقاله، این متد را برای ثبت بازدید فراخوانی کند. افزایش بازدید مستقیماً در دیتابیس انجام می‌شود و مقدار جدید بازگردانده می‌شود.

Endpoint Information

پارامترهای مسیر (Path Parameter)

بدنه درخواست (Request Body)

{}  
// بدون نیاز به بدنه خاص؛ صرفاً فراخوانی ساده POST کافی است.

خروجی موفق (Success Response)

{
  "status": true,
  "time": 1733810253,
  "views": 121
}

در صورت بروز خطا (Error Response)

{
  "message": "No query results for model [App\\Models\\Article] 9999",
  "exception": "Symfony\\Component\\HttpKernel\\Exception\\NotFoundHttpException",
  "status_code": 404
}

فلوچارت منطق عملکرد (Flowchart)

نکات فنی برای توسعه‌دهنده (Developer Notes)

RESOURCE /b2c/v1/travel_requests

Travel Requests API

مجموعه اندپوینت‌های /b2c/v1/travel_requests برای ثبت، مشاهده، و مدیریت درخواست‌های سفر طراحی شده است. این مجموعه از ساختار Route::resource لاراول استفاده می‌کند و زیر مجموعه‌ای از کنترلر TravelRequestsController می‌باشد. تمام مسیرها از طریق middleware: authWithJwt محافظت می‌شوند.

Endpoints Overview

۱. لیست درخواست‌ها — GET /b2c/v1/travel_requests

پاسخ نمونه

{
  "items": [
    {
      "id": 45,
      "title": "اصفهان به مشهد هتل آوازه مشهد از ‎2025/12/14‎ تا ‎2025/12/18‎",
      "method": "accommodation",
      "budget": 5000000,
      "status": 1,
      "operator_group": "b2c",
      "origin": { "id": 37, "fa_name": "اصفهان", "en_name": "Isfahan" },
      "destination": { "id": 396, "fa_name": "مشهد", "en_name": "Mashhad" },
      "accommodation": { "title": { "fa": "هتل آوازه مشهد" }, "category": { "title": "hotel" } },
      "details": { "rooms": 2, "adults": 3 },
      "requester_id": { "id": 12, "first_name": "علیرضا", "last_name": "احمدی" }
    }
  ],
  "meta": {
    "timestamp": 1733821800,
    "table": { "total": 25, "per_page": 30, "current_page": 1, "last_page": 1 }
  }
}

۲. ایجاد درخواست — POST /b2c/v1/travel_requests

در این درخواست، اپراتور با استفاده از JWT خود به عنوان operator، رکوردی جدید در جدول travel_requests ایجاد می‌کند.

پارامترهای ورودی (JSON Body)

{
  "method": "accommodation",
  "origin": {"id": 37},
  "destination": {"id": 396},
  "accommodation": {"id": 52, "type": "accommodation"},
  "from_date": "2025-12-14",
  "to_date": "2025-12-18",
  "budget": 5000000,
  "cost_center": 8,
  "trip_type": "business",
  "description": "سفر کاری به مشهد",
  "details": { "adults": 3, "children": 1 }
}

خروجی موفق (201 Created)

{
  "payload": {
    "id": 45,
    "title": "اصفهان به مشهد هتل آوازه مشهد از ‎2025/12/14‎ تا ‎2025/12/18‎",
    "budget": 5000000,
    "method": "accommodation"
  },
  "meta": { "timestamp": 1733821800 }
}

۳. مشاهده جزئیات — GET /b2c/v1/travel_requests/{id}

کلیه روابط مرتبط (origin، destination، accommodation، requester و غیره) از جداول مجزا خوانده می‌شوند.

۴. ویرایش — PUT /b2c/v1/travel_requests/{id}

پاسخ نمونه

{
  "payload": {
    "id": 45,
    "status": 3,
    "payment_status": 1,
    "title": "اصفهان به مشهد هتل آوازه مشهد از ‎2025/12/14‎ تا ‎2025/12/18‎"
  },
  "meta": { "timestamp": 1733821880 }
}

۵. حذف — DELETE /b2c/v1/travel_requests/{id}

درخواست با شناسه مشخص حذف می‌شود و مقدار حذف (true/false) بازگردانده می‌شود.

۶. تغییر وضعیت — POST /b2c/v1/travel_requests/{id}/change-status

{
  "operator_id": 5,
  "status": 4,
  "reference_id": 999
}

خروجی موفق

{
  "payload": { "status": true },
  "meta": { "timestamp": 1733821930 }
}

نکات فنی و عملکردی