Skip to main content
#P1792

POST /b2c/v1/trade/completion


Trade Completion & Issuance

این اندپوینت برای تکمیل فرآیند خرید استفاده می‌شود.
زمانی که پرداخت (آنلاین یا کیف پول) تایید شد، این متد برای صدور فاکتور (Factor)، بروزرسانی اطلاعات مسافران، ثبت تراکنش‌های مالی (Pledgers/Pays) و ارسال SMS نهایی به کاربر فراخوانی می‌گردد.



Finalize Order

URL: /b2c/v1/trade/completion
Method: POST
Controller: V1TradeController@storeTradeAfterPay
Middleware: authWithJwt (Required)
Transaction: Atomic (DB::transaction)

Request Body Parameters

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

Parameter Type Required Description
branch Integer Yes شناسه شعبه (Branch ID) برای تعیین تنظیمات مالی و اعتباری.
payment Object Yes اطلاعات مربوط به پرداخت انجام شده (مبلغ، درگاه و...).
request Object Yes شامل جزئیات اصلی سفارش:
  • passengers: لیست کامل مسافران برای آپدیت در DB.
  • data: لیست آیتم‌های خریداری شده (پرواز، هتل، قطار).
  • pledgers: (اختیاری) لیست متعهدان مالی (برای B2B).
  • notices: (بولین) آیا SMS ارسال شود؟
  • income_id: شناسه درآمد.

Step-by-Step Logic Breakdown

۱. ایجاد فاکتور (Factor Creation)

یک رکورد در جدول factors ایجاد می‌شود:

  • Serial: تولید سریال یکتا بر اساس شعبه.
  • Slug: شناسه یکتای 8 کاراکتری برای پیگیری (Reference ID).
  • Status: وضعیت پیش‌فرض 3 (صادر شده/موفق) تنظیم می‌شود.
  • Colleague Auth: اگر کاربر B2B باشد، شناسه همکار ثبت می‌شود.

۲. مدیریت مسافران (Passengers Upsert)

سیستم روی آرایه request['passengers'] حلقه می‌زند:

  • اطلاعات هویتی (نام، نام خانوادگی، کد ملی، پاسپورت، تاریخ انقضا و...) در جدول customers بروزرسانی (Update) می‌شوند.
  • تاریخ تولد و انقضای پاسپورت استانداردسازی می‌شود (حذف کاراکترهای اضافی).
  • رابطه (Relationship) بین مسافر اصلی و همراهان تنظیم می‌شود.

۳. مدیریت مالی و تعهدات (Pledgers & Pays)

این بخش مشخص می‌کند "چه کسی پول را می‌دهد":

  • حالت B2B (همکار): اگر pledgers ارسال شده باشد، رکوردهایی در جدول pledgers و pays (نوع contract) ثبت می‌شود تا بدهی همکار مشخص شود.
  • حالت B2C (عادی): اگر متعهدی نباشد، خودِ اپراتور/کاربر جاری به عنوان متعهد (type='operator') در نظر گرفته می‌شود.

۴. پردازش آیتم‌ها (Items Processing)

بر اساس نوع سرویس (aircraft, train, accommodation):

  • Aircraft: وضعیت بلیط بررسی شده، سن مسافر (برای تشخیص Infant) محاسبه می‌شود و آیتم در factor_items درج می‌شود.
  • Hub Reservation: اگر سرویس از نوع airplusHub باشد، درخواست به جدول hub_reservation اضافه شده و مبلغ خرید به عنوان Debit (بدهی) در جدول wallet شعبه ثبت می‌شود.
  • Train/Hotel: مشابه پرواز، اطلاعات رزرو پردازش و ذخیره می‌شوند.
  • Temporary Update: وضعیت رزرو موقت (در جدول temporary_reservations) به تکمیل شده تغییر می‌کند.

۵. ارسال اعلان (Notification)

اگر notices: true باشد:

  • یک متن پیامک (Magic Text) به صورت تصادفی انتخاب می‌شود (مثلاً: "سفری هیجان انگیز").
  • لینک فاکتور (/f/{slug}) تولید می‌شود.
  • جاب SendNotification به صف fastJob ارسال می‌شود.
  • لاگ سیستمی در snailJob ثبت می‌گردد.

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": "..."
}
Back to top