سفارش‌های هتل

سفارش، رزروی است که از یک نرخ تأییدشده ساخته می‌شود. آن را ایجاد می‌کنید تا اتاق نگه داشته شود و سپس سفارش را نهایی می‌کنید. همچنین می‌توانید سفارش را بخوانید، جریمهٔ لغو را پیش‌نمایش و سپس لغو کنید و مهلت پرداخت را تمدید کنید.

چرخهٔ عمر#

status	معنا
`held`	اتاق تا پایان مهلت پرداخت نگه داشته شده است. قابل لغو.
`confirming`	سفارش ثبت شده و در حال نهایی‌شدن است.
`confirmed`	رزرو تأیید شده است؛ واچر و شمارهٔ تأیید صادر شده‌اند.
`cancelled`	سفارش لغو شد و مبلغ بلوکه‌شده آزاد شد.

ایجاد سفارش#

POST/v3/HAPI/hotels/orders

به اسکوپ hotels:write نیاز دارد. ابتدا در همان نشست نرخ را تأیید کنید (تأیید نرخ)؛ وگرنه خطای 409 rate_not_revalidated برمی‌گردد.

بدنه#

فیلد	نوع	الزامی	توضیح
`rate_id`	string	الزامی	شناسهٔ `hrt_` تأییدشده.
`rooms`	array	الزامی	یک ورودی برای هر اتاق، هرکدام با مهمانانش.
`rooms[].guests[].given_name`	string	الزامی	نام مهمان.
`rooms[].guests[].family_name`	string	الزامی	نام خانوادگی مهمان.
`rooms[].guests[].type`	string	اختیاری	`adult` (پیش‌فرض) یا `child`.
`rooms[].guests[].title`	string	اختیاری	`mr`، `mrs`، `ms`، `miss`.
`contact.email`	string	الزامی	ایمیل تماس.
`contact.phone`	string	الزامی	تلفن تماس.
`nationality`	string	اختیاری	ملیت سرپرست مهمانان.
`note`	string	اختیاری	یادداشتی برای هتل.
`client_reference`	string	اختیاری	شناسهٔ مرجع خودتان.

curl -X POST https://api.simorghapi.com/v3/HAPI/hotels/orders \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f2b8c1a-3e4d-4a6b-9c7e-1d2f3a4b5c6d" \
  -d '{
    "rate_id": "hrt_Ym9va2FwcDphYmMxMjM",
    "rooms": [
      { "guests": [
        { "given_name": "Jane", "family_name": "Doe", "type": "adult", "title": "ms" }
      ] }
    ],
    "contact": { "email": "jane@example.com", "phone": "+14155550100" },
    "nationality": "US"
  }'

پاسخ#

{
  "object": "hotel_order",
  "id": "hord_8f3c81d2-4a5b-4c6d-9e0f-1a2b3c4d5e6f",
  "status": "held",
  "payment_deadline": "2026-11-13T20:00:00+00:00",
  "check_in": "2026-11-14",
  "check_out": "2026-11-16",
  "nights": 2,
  "total": { "amount": "360.00", "currency": "USD" },
  "confirmation_number": null,
  "voucher_number": null,
  "hotel_pnr": null,
  "hotel": { /* … */ },
  "contact": { "phone": "+14155550100", "email": "jane@example.com" },
  "rooms": [ /* booked rooms */ ],
  "cancellation": { "non_refundable": false, "policy_text": "…", "policies": [ /* … */ ] }
}

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

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

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

به hotels:read نیاز دارد. hotel_order را برمی‌گرداند و پس از تأیید، شمارهٔ تأیید و شمارهٔ واچر را هم شامل می‌شود.

تأیید سفارش#

POST/v3/HAPI/hotels/orders/{id}/confirm

به hotels:write نیاز دارد. سفارش held را ثبت نهایی می‌کند. سفارش را آن‌قدر بخوانید (polling) تا به confirmed برسد.

لغو سفارش#

ابتدا جریمه را پیش‌نمایش کنید و سپس لغو کنید.

GET/v3/HAPI/hotels/orders/{id}/cancellation

{
  "object": "hotel_cancellation_quote",
  "order_id": "hord_8f3c81d2-…",
  "penalty": { "amount": "0.00", "currency": "USD" },
  "status": 2,
  "expires_at": "2026-11-13T21:00:00+00:00"
}

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

به hotels:write نیاز دارد. سفارش را لغو و مبلغ بلوکه‌شده را آزاد می‌کند؛ وضعیت سفارش cancelled می‌شود.

تمدید مهلت پرداخت#

POST/v3/HAPI/hotels/orders/{id}/extend-deadline

به hotels:write نیاز دارد. مهلت پرداخت یک سفارش held را عقب‌تر می‌برد.

{ "object": "hotel_order", "id": "hord_8f3c81d2-…", "payment_deadline": "2026-11-13T20:30:00+00:00" }

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