# RESOURCE /b2c/v1/travel_requests

## Travel Requests API

مجموعه اندپوینت‌های `/b2c/v1/travel_requests` برای ثبت، مشاهده، و مدیریت درخواست‌های سفر طراحی شده است. این مجموعه از ساختار `Route::resource` لاراول استفاده می‌کند و زیر مجموعه‌ای از کنترلر `TravelRequestsController` می‌باشد. تمام مسیرها از طریق `middleware: authWithJwt` محافظت می‌شوند.

<div class="api-docs" id="bkmrk-">---

</div>### Endpoints Overview

<div class="api-docs" id="bkmrk-method-endpoint-acti"><table class="schema-table" dir="rtl"><thead><tr><th>Method</th><th>Endpoint</th><th>Action</th><th>Description</th></tr></thead><tbody><tr><td>GET</td><td>/b2c/v1/travel\_requests</td><td>index</td><td>لیست درخواست‌های سفر با فیلتر و صفحه‌بندی</td></tr><tr><td>POST</td><td>/b2c/v1/travel\_requests</td><td>store</td><td>ثبت درخواست جدید سفر</td></tr><tr><td>GET</td><td>/b2c/v1/travel\_requests/{id}</td><td>show</td><td>دریافت جزئیات یک درخواست مشخص</td></tr><tr><td>PUT/PATCH</td><td>/b2c/v1/travel\_requests/{id}</td><td>update</td><td>ویرایش اطلاعات درخواست</td></tr><tr><td>DELETE</td><td>/b2c/v1/travel\_requests/{id}</td><td>destroy</td><td>حذف درخواست</td></tr><tr><td>POST</td><td>/b2c/v1/travel\_requests/{id}/change-status</td><td>changeStatus</td><td>تغییر وضعیت (status) با امکان ثبت reference</td></tr></tbody></table>

---

</div>### ۱. لیست درخواست‌ها — `GET /b2c/v1/travel_requests`

<div class="api-docs" id="bkmrk-%D8%B5%D9%81%D8%AD%D9%87%E2%80%8C%D8%A8%D9%86%D8%AF%DB%8C%3A-%D8%AF%D8%B1-%D9%81%DB%8C%D9%84%D8%AF-p">- صفحه‌بندی: در فیلد `paginate.length` (پیش‌فرض 30)، `paginate.start` (پیش‌فرض 0)
- فیلترهای پشتیبانی‌شده: 
    - `method` (accommodation, flight, tour...)
    - `submethod`
    - `status`
    - `payment_status`
    - `operator_id`
- دسترسی به داده‌ها محدود به گروه کاربر است: 
    - **B2C/Agent:** فقط درخواست‌های خودش
    - **B2B/Colleague:** درخواست‌های اپراتور جاری
    - **Base/B2E:** از فیلد `requester_id` در ورودی

</div>#### پاسخ نمونه

```json
{
  "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 }
  }
}
```

<div class="api-docs" id="bkmrk--1">---

</div>### ۲. ایجاد درخواست — `POST /b2c/v1/travel_requests`

در این درخواست، اپراتور با استفاده از JWT خود به عنوان `operator`، رکوردی جدید در جدول `travel_requests` ایجاد می‌کند.

#### پارامترهای ورودی (JSON Body)

```json
{
  "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 }
}
```

<div class="api-docs" id="bkmrk-method-%D8%A7%D9%84%D8%B2%D8%A7%D9%85%DB%8C-%D8%A7%D8%B3%D8%AA-%28%D9%85">- `method` الزامی است (مانند accommodation, flight, tour).
- اگر فیلد `accommodation.type = "destination"` باشد، مقدار آن جایگزین مقصد می‌شود.
- در تمام حالات، branch و group از JWT استخراج می‌شوند.

</div>#### خروجی موفق (201 Created)

```json
{
  "payload": {
    "id": 45,
    "title": "اصفهان به مشهد هتل آوازه مشهد از ‎2025/12/14‎ تا ‎2025/12/18‎",
    "budget": 5000000,
    "method": "accommodation"
  },
  "meta": { "timestamp": 1733821800 }
}
```

<div class="api-docs" id="bkmrk--2">---

</div>### ۳. مشاهده جزئیات — `GET /b2c/v1/travel_requests/{id}`

کلیه روابط مرتبط (origin، destination، accommodation، requester و غیره) از جداول مجزا خوانده می‌شوند.

<div class="api-docs" id="bkmrk-%D8%AF%D8%B1%D8%AE%D9%88%D8%A7%D8%B3%D8%AA%E2%80%8C%DA%A9%D9%86%D9%86%D8%AF%D9%87-%28b2c-%E2%86%92">- درخواست‌کننده (B2C → customers، B2B → colleagues).
- رفرنس فاکتور در صورت اتصال به `factors` با offest +10000 بازگردانده می‌شود.
- عنوان اصلی مبتنی بر مسیر + تاریخ + اقامتگاه تولید می‌شود.

---

</div>### ۴. ویرایش — `PUT /b2c/v1/travel_requests/{id}`

<div class="api-docs" id="bkmrk-%D8%AA%D9%85%D8%A7%D9%85%DB%8C-%D9%81%DB%8C%D9%84%D8%AF%D9%87%D8%A7-%D9%85%D8%B4%D8%A7%D8%A8%D9%87-s">- تمامی فیلدها مشابه Store هستند؛ فقط نیاز به شناسه مسیر دارد.
- در بروزرسانی، `status` و `payment_status` نیز می‌توانند تغییر کنند.

</div>#### پاسخ نمونه

```json
{
  "payload": {
    "id": 45,
    "status": 3,
    "payment_status": 1,
    "title": "اصفهان به مشهد هتل آوازه مشهد از ‎2025/12/14‎ تا ‎2025/12/18‎"
  },
  "meta": { "timestamp": 1733821880 }
}
```

<div class="api-docs" id="bkmrk--3">---

</div>### ۵. حذف — `DELETE /b2c/v1/travel_requests/{id}`

درخواست با شناسه مشخص حذف می‌شود و مقدار حذف (true/false) بازگردانده می‌شود.

<div class="api-docs" id="bkmrk--4">---

</div>### ۶. تغییر وضعیت — `POST /b2c/v1/travel_requests/{id}/change-status`

<div class="api-docs" id="bkmrk-%D8%A8%D8%B1%D8%A7%DB%8C-%D8%A8%D9%87%E2%80%8C%D8%B1%D9%88%D8%B2%D8%B1%D8%B3%D8%A7%D9%86%DB%8C-%D8%B3%D8%B1%DB%8C">- برای به‌روزرسانی سریع وضعیت (status) و تخصیص اپراتور یا فاکتور مرجع به کار می‌رود.
- اگر مقدار `status = 4` و `reference_id` ارسال شود → فاکتور مرتبط ثبت می‌شود.

</div>```json
{
  "operator_id": 5,
  "status": 4,
  "reference_id": 999
}
```

#### خروجی موفق

```json
{
  "payload": { "status": true },
  "meta": { "timestamp": 1733821930 }
}
```

<div class="api-docs" id="bkmrk--5">---

</div>### نکات فنی و عملکردی

<div class="api-docs" id="bkmrk-%D8%B9%D9%86%D9%88%D8%A7%D9%86-%D8%AA%D8%B1%DA%A9%DB%8C%D8%A8%DB%8C-%D8%A7%D8%B2-%D9%85%D8%A8%D8%AF%D8%A3">- عنوان ترکیبی از مبدأ، مقصد، اقامتگاه و بازه تاریخ به‌شکل داینامیک ساخته می‌شود.
- روابط داده‌ای: 
    - Customers ↔ Requester (برای B2C)
    - Colleagues ↔ Requester (برای B2B)
    - Cities ↔ Origin/Destination
    - Hotels ↔ Accommodation
- تمامی تاریخ‌ها در فرمت شمسی-لاتین با `LTR Markers` جلوگیری از بهم‌ریختگی نمایش دارند.
- فیلد `details` به‌صورت JSON ذخیره و در خروجی decode م‌شود.

</div>