#P1791
POST /b2c/v1/trade/store
Store Trade / Payment Initiation
این اندپوینت برای ثبت نهایی درخواست و انجام عملیات مالی استفاده میشود.
سیستم ابتدا وضعیت و قیمت محصول را چک میکند. اگر تغییری نباشد، بسته به انتخاب کاربر (کیف پول یا درگاه)، یا تراکنش را آنی انجام میدهد و یا لینک پرداخت تولید میکند.
Submit Order & Pay
URL:
/b2c/v1/trade/storeMethod: POST
Controller: V1TradeController@storeTradeBeforePay
Middleware:
authWithJwt (Required)Request Body Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| branch | Integer | Yes | شناسه شعبه (Branch ID). |
| group | String | Yes | نوع گروه کاربری: b2c (مسافر) یا colleague (همکار/B2B). |
| requests[pay] | Object | Yes | آبجکت تنظیمات پرداخت (جزئیات در جدول زیر). |
| ...product_data | Mixed | Yes | سایر اطلاعات مربوط به محصول (لیست مسافران، شناسه پرواز/هتل و...) که برای رزرو ضروری است. (این اطلاعات مستقیماً به سرویس رزرو ارسال میشود). |
ساختار `requests[pay]`
| Key | Type | Description |
|---|---|---|
| amount | Integer | مبلغ قابل پرداخت (ریال). |
| drive | String | روش پرداخت:
|
| return | String | لینک بازگشت (Callback URL) پس از پرداخت موفق در درگاه بانکی. |
Business Logic Scenarios
۱. سناریوی تغییر قیمت/وضعیت (Price/Status Changed)
قبل از هر اقدامی، متد statusItemProgress اجرا میشود. اگر قیمت یا ظرفیت محصول تغییر کرده باشد:
- عملیات متوقف میشود.
- کد وضعیت 201 برمیگردد.
- در پاسخ،
status_data['changed'] = trueخواهد بود. کلاینت باید قیمت جدید را به کاربر نمایش دهد.
۲. پرداخت با کیف پول (Wallet Payment)
اگر drive = 'wallet' باشد:
- بررسی موجودی: سیستم فرمول زیر را چک میکند:
(Wallet Credit - Wallet Debit) + Ceiling Amount >= Pay Amount - خطای موجودی: اگر موجودی کافی نباشد، خطای 402 بازگردانده میشود.
- موفقیت: مبلغ از حساب کسر شده، رکورد در جدول
walletثبت میشود و خرید نهایی میشود (Reference ID تولید میشود).
۳. پرداخت آنلاین (Online Gateway)
اگر drive != 'wallet' باشد:
- متد
paymentInvoiceOperationاجرا میشود. - یک رکورد در جدول
payment_gatewayبا یک Slug یکتا ایجاد میشود. - لینک پرداخت به فرمت
https://{short_domain}/p/{slug}تولید و برگردانده میشود. - یک رزرو موقت (Temporary Reservation) ایجاد میشود.
Response Examples
حالت اول: تولید موفق لینک پرداخت (Online)
Status: 201 Created
{
"payload": {
"payment_link": "https://airplus.app/p/a1b2c3d4",
"temporary_id": 12345, // شناسه رزرو موقت
"status_data": {
"changed": false // یعنی قیمت تغییر نکرده است
}
},
"meta": {
"timestamp": 1702123456
}
}حالت دوم: خرید موفق با کیف پول (Wallet)
Status: 201 Created
{
"payload": {
"payment_id": 9876,
"reference_id": 500120 // شماره فاکتور نهایی (رزرو قطعی)
},
"meta": {
"timestamp": 1702123456
}
}حالت سوم: تغییر قیمت (نیاز به تایید کاربر)
Status: 201 Created
{
"payload": {
"payment_link": null,
"temporary_id": false,
"status_data": {
"changed": true,
"message": "قیمت پرواز تغییر کرده است...",
"new_price": 15500000
}
},
"meta": {
"timestamp": 1702123456
}
}حالت چهارم: خطای موجودی ناکافی
Status: 402 Payment Required
{
"error": {
"code": 1001,
"message": "اعتبار شما برای این خرید کافی نمی باشد. لطفا قبل از انجام این عملیات موجودی حساب خود را افزایش دهید."
},
"meta": {
"timestamp": 1702123456
}
}