#P1739
GET /v2/core/bill/{type}
Hub: Get Branch Bills
این اندپوینت برای دریافت لیست صورتحسابهای پرداخت نشده (`status = 1`) یک شعبه خاص طراحی شده است.
کلاینت میتواند با ارسال نوع سرویس (مانند `hotel`, `flight` و...)، فقط صورتحسابهای مربوط به آن سرویس را فیلتر و دریافت کند. خروجی شامل جزئیات کامل هر صورتحساب به همراه مبلغ نهایی قابل پرداخت است.
Request Overview
URL:
/v2/core/bill/{type}Method: GET
Controller: HubController@indexBranchBill
Middleware: authWithJwt
Access Control
- نیاز به توکن احراز هویت (JWT) دارد.
- شناسه شعبه (`branch`) به صورت خودکار از توکن کاربر استخراج و در کوئری استفاده میشود.
URL Parameters
| Field | Type | Description |
|---|---|---|
| type | string | (الزامی) نوع سرویسی که صورتحساب برای آن صادر شده است. مقادیر ممکن: 'hotel', 'flight', 'tour' و غیره. |
Logic Details
فرآیند دریافت صورتحسابها به شرح زیر است:
- استخراج اطلاعات: شناسه شعبه (`branch`) از توکن JWT و نوع سرویس (`type`) از URL خوانده میشود.
- کوئری از دیتابیس:
- یک کوئری به جدول
airplus_billsارسال میشود. - این کوئری نتایج را بر اساس سه شرط اصلی فیلتر میکند:
branch: باید با شناسه شعبه کاربر لاگین کرده مطابقت داشته باشد.status: باید دقیقاً برابر با 1 باشد (فقط صورتحسابهای در انتظار پرداخت).object_type: باید با پارامترtypeارسال شده در URL مطابقت داشته باشد.
- یک کوئری به جدول
- پردازش و تبدیل دادهها (`map`):
- اگر یک یا چند صورتحساب پیدا شود، سیستم روی هرکدام از آنها یک فرآیند تبدیل اجرا میکند:
- یک فیلد جدید به نام
totalبا استفاده از فرمول `(((amount + tax) - discount) + markup)` محاسبه و به خروجی اضافه میشود. - یک آبجکت
detailsساخته میشود که حاویmonth_titleاست. این فیلد با استفاده از تابعCalendarUtils::strftimeنام فارسی ماه (مانند "آذر ماه") را از روی تاریخ ایجاد صورتحساب استخراج میکند. - ساختار نهایی هر آیتم برای خوانایی بیشتر در پاسخ API بازآرایی میشود.
- ساختار پاسخ نهایی:
- اگر هیچ صورتحسابی یافت نشود، پاسخ با کد
200 OKبازگردانده شده و مقدار فیلدitemsبرابر باfalseخواهد بود. - نکته مهم: بلوک کد مربوط به خطای
404در کنترلر به دلیل نحوه عملکرد تابعget()، عملاً اجرا نمیشود و پاسخ همیشه200است. - اگر صورتحسابها پیدا شوند، آرایهای از آبجکتهای تبدیل شده در فیلد
itemsقرار میگیرد.
- اگر هیچ صورتحسابی یافت نشود، پاسخ با کد
Response Structure
پاسخ موفق (در صورت یافتن صورتحساب)
- Status Code:
200 OK
{
"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
}
}پاسخ موفق (در صورت عدم وجود صورتحساب)
- Status Code:
200 OK - توجه کنید که در این حالت، فیلد
itemsبه جای آرایه خالی، مقدارfalseدارد.
{
"items": false,
"meta": {
"timestamp": 1733735400
}
}Flowchart
Start Request (GET /v2/core/bill/{type})
↓
Extract `branch` from JWT & `type` from URL
↓
Query `airplus_bills` WHERE:
- `branch` = user_branch
- `status` = 1
- `object_type` = {type}
- `branch` = user_branch
- `status` = 1
- `object_type` = {type}
↓
Bills Collection is Empty?
Yes
↓
Set `items` field to `false`
↓
Return 200 OK
↓ (No)
Map over results:
- Calculate `total`
- Generate `month_title`
- Format structure
- Calculate `total`
- Generate `month_title`
- Format structure
↓
Return 200 OK with `items` array