سفارش‌های پرواز

سفارش، رزروی است که از یک پیشنهادِ دوباره اعتبارسنجی‌شده ساخته می‌شود. آن را ایجاد می‌کنید تا صندلی‌ها نگه داشته شوند و سپس درخواست صدور بلیت می‌دهید. در این مسیر می‌توانید سفارش را بخوانید، پیش از صدور لغوش کنید، پس از صدور استردادش کنید و به آن یادداشت اضافه کنید.

چرخهٔ عمر#

هر سفارش از میان چند وضعیت محدود عبور می‌کند:

status	معنا
`held`	صندلی‌ها نگه داشته شده‌اند و بلیت هنوز صادر نشده است. قابل لغو.
`ticketing`	درخواست صدور ثبت شده و در حال انجام است.
`ticketed`	بلیت صادر شده است. به‌جای لغو، از استرداد استفاده کنید.
`cancelled`	سفارش نگه‌داشته‌شده باطل شد و مبلغ بلوکه‌شده آزاد شد.
`refunded`	بلیت صادرشده استرداد شد.

ایجاد سفارش#

POST/v3/HAPI/flights/orders

به اسکوپ flights:write نیاز دارد. ابتدا در همان نشست پیشنهاد را دوباره اعتبارسنجی کنید (دریافت پیشنهاد)؛ وگرنه خطای 409 offer_not_revalidated برمی‌گردد.

بدنه#

فیلد	نوع	الزامی	توضیح
`offer_id`	string	الزامی	شناسهٔ `ofr_` اعتبارسنجی‌شده.
`passengers`	array	الزامی	یک ورودی برای هر مسافر.
`passengers[].type`	string	الزامی	`adult`، `child` یا `infant`.
`passengers[].given_name`	string	الزامی	نام.
`passengers[].family_name`	string	الزامی	نام خانوادگی.
`passengers[].date_of_birth`	string	الزامی	`YYYY-MM-DD`.
`passengers[].gender`	string	الزامی	`male` یا `female`.
`passengers[].nationality`	string	اختیاری	کد ملیت.
`passengers[].document`	object	اختیاری	گذرنامه: `number`، `expires_on`، `country_code`، `issued_on`.
`contact.email`	string	الزامی	ایمیل تماس.
`contact.phone`	string	الزامی	تلفن تماس.
`client_reference`	string	اختیاری	شناسهٔ مرجع خودتان؛ در پاسخ برگردانده می‌شود و برای پیگیری ایدمپوتنت سفارش هم به کار می‌رود.

curl -X POST https://api.simorghapi.com/v3/HAPI/flights/orders \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f2b8c1a-3e4d-4a6b-9c7e-1d2f3a4b5c6d" \
  -d '{
    "offer_id": "ofr_dHJhdmVscGF5b3V0cz...",
    "passengers": [
      {
        "type": "adult",
        "given_name": "Jane",
        "family_name": "Doe",
        "date_of_birth": "1990-05-01",
        "gender": "female",
        "nationality": "US",
        "document": {
          "number": "X1234567",
          "expires_on": "2030-01-01",
          "country_code": "US",
          "issued_on": "2020-01-01"
        }
      }
    ],
    "contact": { "email": "jane@example.com", "phone": "+14155550100" }
  }'

پاسخ#

یک flight_order در وضعیت held همراه با مهلت صدور بلیت.

{
  "object": "flight_order",
  "id": "ord_8f3c81d2-4a5b-4c6d-9e0f-1a2b3c4d5e6f",
  "status": "held",
  "ticketing_deadline": "2026-11-13T20:00:00+00:00",
  "validating_airline": "PC",
  "total": { "amount": "412.00", "currency": "USD" },
  "base":  { "amount": "250.00", "currency": "USD" },
  "tax":   { "amount": "162.00", "currency": "USD" },
  "contact": { "email": "jane@example.com", "phone": "+14155550100" },
  "passengers": [
    { "type": "adult", "given_name": "Jane", "family_name": "Doe",
      "date_of_birth": "1990-05-01", "gender": "female", "nationality": "US",
      "document": { "number": "X1234567", "expires_on": "2030-01-01",
                    "country_code": "US", "issued_on": "2020-01-01" },
      "ticket_number": null, "pnr": null }
  ],
  "segments": [
    { "origin": "IST", "destination": "DXB",
      "departing_at": "2026-11-14T08:10:00", "arriving_at": "2026-11-14T11:15:00",
      "marketing_carrier": "PC", "flight_number": "695",
      "cabin_class": "economy", "booking_class": "Y", "stops": 0, "pnr": null }
  ],
  "notes": [],
  "price_change": false
}

وضعیت	کد	معنا
402	`insufficient_balance`	کیف پول دفتر هزینهٔ نرخ را پوشش نمی‌دهد. آن را شارژ کنید و دوباره تلاش کنید.
409	`duplicate_booking`	برای این پیشنهاد از قبل یک سفارش فعال وجود دارد.
409	`offer_not_revalidated`	پیش از ثبت سفارش، پیشنهاد را دوباره اعتبارسنجی کنید.

خواندن سفارش#

GET/v3/HAPI/flights/orders/{id}

به flights:read نیاز دارد. همان ساختار flight_order را با وضعیت فعلی برمی‌گرداند و پس از صدور، شمارهٔ بلیت‌ها و PNR را هم شامل می‌شود.

صدور بلیت#

POST/v3/HAPI/flights/orders/{id}/ticket

به flights:write نیاز دارد. سفارش held را به وضعیت ticketing می‌برد. سفارش را آن‌قدر بخوانید (polling) تا به ticketed برسد؛ در این لحظه ticket_number و pnr برای هر مسافر پر می‌شوند.

لغو سفارش#

POST/v3/HAPI/flights/orders/{id}/cancellation

به flights:write نیاز دارد. سفارش held را باطل می‌کند و مبلغ بلوکه‌شده را آزاد می‌کند. برای سفارشی که از قبل ticketed شده، خطای 409 order_ticketed برمی‌گردد؛ به‌جای آن از استرداد استفاده کنید.

استرداد سفارش#

ابتدا شرایط استرداد را پیش‌نمایش کنید و سپس درخواست استرداد بدهید.

GET/v3/HAPI/flights/orders/{id}/refund

به flights:read نیاز دارد. یک refund_quote با جریمهٔ هر بلیت برمی‌گرداند.

{
  "object": "refund_quote",
  "order_id": "ord_8f3c81d2-…",
  "refund_type": 1,
  "tickets": [
    { "ticket_number": "235-1234567890", "status": 1, "is_refunded": false,
      "non_refundable": false, "penalty": { "amount": "40.00", "currency": "USD" },
      "route": "IST-DXB", "pnr": "ABC123" }
  ]
}

POST/v3/HAPI/flights/orders/{id}/refund

به flights:write نیاز دارد. بدنهٔ اختیاری: refund_type، ticket_numbers، refund_payment_mode. در صورت موفقیت، وضعیت سفارش refunded می‌شود.

{
  "object": "refund",
  "order_id": "ord_8f3c81d2-…",
  "status": "requested",
  "refunded_tickets": ["235-1234567890"]
}

افزودن یادداشت#

POST/v3/HAPI/flights/orders/{id}/notes

به flights:write نیاز دارد. یادداشت‌های متنی آزاد را به سفارش پیوست می‌کند.

curl -X POST https://api.simorghapi.com/v3/HAPI/flights/orders/ord_8f3c81d2-.../notes \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "notes": ["Traveller requested a window seat."] }'

flight_order به‌روزشده با یادداشت‌های اضافه‌شده برگردانده می‌شود.

ویرایش این صفحه در گیت‌هابمشکلی دیدید؟ از پنل ← پشتیبانی خبرمان کنید.