# GET /b2c/v1/online/payment/flight/tracking

## Tracking Payment Flight

اندپوینت زیر برای بررسی وضعیت پرداخت و رزرو پرواز از روی کد ملی و شماره رفرنس طراحی شده است. این متد با اتصال داخلی به `V2TradeController::operationTrade()` وضعیت فاکتور، اطلاعات پرواز و مسافران را بازیابی کرده و داده‌های حساس مالی را از خروجی حذف می‌کند.

<div class="api-docs" id="bkmrk-"><div class="endpoint-section">  
</div>---

</div>### Endpoint Info

<div class="api-docs" id="bkmrk-url%3A-%2Fb2c%2Fv1%2Fonline%2F"><div class="endpoint-info"><div>**URL:** `/b2c/v1/online/payment/flight/tracking`</div><div>**Method:** <span class="method-get">GET</span></div><div>**Controller:** `V1OnlineController@trackingPaymentFlight`</div><div>**Auth:** Public (بدون نیاز به JWT)</div></div>---

</div>### Query Parameters

<div class="api-docs" id="bkmrk-%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1-%D9%86%D9%88%D8%B9-%D8%A7%D8%AC%D8%A8%D8%A7%D8%B1%DB%8C-%D8%AA"><table class="schema-table" dir="rtl"><thead><tr><th>پارامتر</th><th>نوع</th><th>اجباری</th><th>توضیح</th></tr></thead><tbody><tr><td>special\_code</td><td>string</td><td>✅</td><td>کد ملی مسافر یا شناسه ویژه ثبت شده در سیستم مشتریان (`customers.national_code`)</td></tr><tr><td>reference</td><td>integer</td><td>✅</td><td>شماره فاکتور یا رفرنس پرداخت (با offset داخلی `-10000` هنگام مقایسه در جدول فاکتورها)</td></tr><tr><td>branch</td><td>integer</td><td>✅</td><td>شناسهٔ شعبه‌ای که پرداخت در آن انجام شده است</td></tr></tbody></table>

---

</div>### Logic Flow

<div class="api-docs" id="bkmrk-%F0%9F%93%A5-%D8%AF%D8%B1%DB%8C%D8%A7%D9%81%D8%AA-%D9%88%D8%B1%D9%88%D8%AF%DB%8C%E2%80%8C%D9%87%D8%A7%DB%8C-s"><div class="flowchart" dir="rtl"><div class="flow-item">📥 دریافت ورودی‌های `special_code` و `reference`</div><div class="flow-arrow">↓</div><div class="flow-item-process">**۱. بررسی مشتری با کد ملی:**  
جستجو در جدول `customers` برای یافتن رکوردی با `national_code = special_code`.  
اگر یافت نشود، پاسخ خطا با کد 404 و پیام "مسافر مورد نظر یافت نشد" برگردانده می‌شود.</div><div class="flow-arrow">↓</div><div class="flow-item-process">**۲. بررسی وجود فاکتور:**  
در جدول `factors` فیلدهای زیر بررسی می‌شوند:  
- `serial = reference - 10000`
- `branch = branch_id`
- `customer = customer.id`

اگر رکوردی یافت شود، ادامه می‌دهد؛ در غیر این صورت پاسخ خطا با پیام "رفرنس مورد نظر یافت نشد" برمی‌گردد.</div><div class="flow-arrow">↓</div><div class="flow-item-process">**۳. آماده‌سازی درخواست برای TradeController:**  
افزودن پارامتر `id = reference` به درخواست.  
تنظیم اپراتور فرضی: `{ id: 12, access: ... }` برای اجرای تابع `operationTrade`.</div><div class="flow-arrow">↓</div><div class="flow-item-process">**۴. اجرای Trade Operation:**  
ساخت شیء `V2TradeController` و اجرای متد `operationTrade($request)`.  
دادهٔ بازگشتی (JSON) شامل فاکتور و اقلام تراکنش واکشی می‌شود.</div><div class="flow-arrow">↓</div><div class="flow-item-process">**۵. پاک‌سازی داده‌ها:**  
در آرایهٔ خروجی `data`، فیلدهای محرمانه حذف می‌شوند:  
`[buy, value_added, serial, provider, currency, deadline, failure_bill]`  
و فیلدها به شکل زیر اصلاح می‌شوند:  
`serial_id = serial_id + 10000`</div><div class="flow-arrow">↓</div><div class="flow-item-success">✅ خروجی نهایی شامل اطلاعات کامل فاکتور و مسافران است و در قالب کلید `payload` برمی‌گردد.</div></div>---

</div>### Response Samples

#### ✅ موفق - فاکتور یافت شد

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

#### ❌ خطا – مشتری یافت نشد

```json
{
  "error": {
    "code": 1001,
    "message": ".مسافر مورد نظر یافت نشد"
  },
  "meta": { "timestamp": 1733750915 }
}
```

#### ❌ خطا – فاکتور یافت نشد

```json
{
  "error": {
    "code": 1001,
    "message": ".رفرنس مورد نظر یافت نشد"
  },
  "meta": { "timestamp": 1733750921 }
}
```

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

</div>### Technical Notes

<div class="api-docs" id="bkmrk-%D8%AA%D8%A7%D8%A8%D8%B9-operationtrade%28">- تابع `operationTrade()` از مسیر داخلی `/v2/trade/operation` فراخوانی شده و مسئول واکشی جزئیات پرداخت است.
- در فرآیند اعتبارسنجی، شناسهٔ فاکتور با آفست **10000−** بررسی می‌شود تا با ساختار فاکتورهای داخلی سازگار گردد.
- عامل اجرای عملیات با شناسهٔ ثابت `operator.id = 12` تنظیم شده تا از سطح دسترسی سیستم مرکزی استفاده کند.
- تمام زمان‌های بازگشتی در خروجی با فرمت میلادی و فیلد `meta.timestamp` (ثانیه‌های یونیکس) اضافه می‌شوند.
- کلید `leader` فقط در صورتی وجود دارد که فاکتور دارای سرپرست یا مشتری اصلی باشد.

</div>