رزرو تفریحات

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

چرخهٔ عمر#

status	معنا
`held`	رزرو نگه داشته شده و مبلغ آن در کیف پول شما بلوکه شده است. هنوز چیزی صادر نشده.
`confirmed`	رزرو را تأیید کرده‌اید و صدور در جریان است.
`issued`	رزرو صادر شده و واچر آماده است.
`cancelled`	رزرو لغو شد و مبلغ بلوکه‌شده آزاد شد.

ایجاد رزرو#

POST/v3/HAPI/activities/bookings

به اسکوپ activities:write نیاز دارد.

بدنه#

فیلد	نوع	الزامی	توضیح
`product_type_id`	string	الزامی	نوع محصول `apt_` که می‌خواهید رزرو کنید.
`date`	string	الزامی	تاریخ تفریح، با قالب `YYYY-MM-DD`.
`timeslot`	string	اختیاری	ساعت شروع سانس از پاسخ ظرفیت، مثلاً `09:00`.
`travelers.adults`	integer	الزامی	تعداد بزرگسالان.
`travelers.children`	integer	اختیاری	تعداد کودکان.
`travelers.seniors`	integer	اختیاری	تعداد سالمندان.
`customer.given_name`	string	الزامی	نام سرپرست.
`customer.family_name`	string	الزامی	نام خانوادگی سرپرست.
`customer.email`	string	الزامی	ایمیل تماس.
`customer.phone`	string	اختیاری	تلفن تماس.
`client_reference`	string	اختیاری	شناسهٔ مرجع خودتان.
`options`	object	شرطی	پاسخ به گزینه‌های رزرو نوع محصول. وقتی تفریح گزینهٔ `required` دارد، الزامی است.
`options.per_booking[]`	array	اختیاری	برای هر گزینهٔ سطح رزرو، یک `{ "id", "value" }`.
`options.per_pax[][]`	array	اختیاری	یک آرایه برای هر مسافر (بزرگسالان، سپس کودکان، سپس سالمندان)؛ هر آرایهٔ داخلی پاسخ‌های `{ "id", "value" }` همان مسافر را دارد.

تعریف گزینه‌ها (شناسه، نوع، الزامی‌بودن، آیتم‌های قابل‌انتخاب) را از booking_options در پاسخ ظرفیت بگیرید. id هر پاسخ همان id گزینه است و value مقداری است که مهمان وارد کرده (برای گزینهٔ فهرستی، value یکی از آیتم‌ها).

curl -X POST https://api.simorghapi.com/v3/HAPI/activities/bookings \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f2b8c1a-3e4d-4a6b-9c7e-1d2f3a4b5c6d" \
  -d '{
    "product_type_id": "apt_88213",
    "date": "2026-11-14",
    "timeslot": "09:00",
    "travelers": { "adults": 2 },
    "customer": { "given_name": "Jane", "family_name": "Doe", "email": "jane@example.com" },
    "options": {
      "per_booking": [
        { "id": "46db421e-5727-46fc-9f2c-10679e026582", "value": "EK202" }
      ],
      "per_pax": [
        [ { "id": "543f0e45-bdfe-4dc7-af73-e7fd5eda8246", "value": "zone_1" } ],
        [ { "id": "543f0e45-bdfe-4dc7-af73-e7fd5eda8246", "value": "zone_2" } ]
      ]
    }
  }'

گزینه‌های الزامی اعتبارسنجی می‌شوند. درگاه پیش از نگه‌داشتن هر چیزی، پاسخ‌های شما را با گزینه‌های رزرو نوع محصول مقایسه می‌کند. اگر یک گزینهٔ required جا افتاده باشد (از جمله گزینهٔ per_paxـی که برای همهٔ مسافران پاسخ داده نشده)، درخواست با خطای 422 و پیامی که نام گزینه را می‌گوید رد می‌شود؛ مثلاً Missing required per-guest booking option: "Full name" (traveller 2). در این حالت هیچ مبلغی در کیف پول بلوکه نمی‌شود. قیمت گزینه‌های اضافه (price یک گزینه یا آیتم) هزینه‌ای است که مهمان علاوه بر نرخ بلیت می‌پردازد.

پاسخ#

{
  "object": "activity_booking",
  "id": "abk_7Q2F9K",
  "status": "held",
  "code": "7Q2F9K",
  "product_type_id": "apt_88213",
  "title": "Old Town Walking Tour — Adult ticket",
  "date": "2026-11-14",
  "timeslot": "09:00",
  "total": { "amount": "58.00", "currency": "USD" },
  "breakdown": [
    { "category": "adult", "quantity": 2, "price": { "amount": "29.00", "currency": "USD" } }
  ],
  "customer": { "given_name": "Jane", "family_name": "Doe", "email": "jane@example.com" },
  "created_at": "2026-08-27T10:15:00Z"
}

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

خواندن رزرو#

GET/v3/HAPI/activities/bookings/{id}

به activities:read نیاز دارد. activity_booking را با وضعیت فعلی‌اش برمی‌گرداند.

تأیید رزرو#

POST/v3/HAPI/activities/bookings/{id}/confirm

به activities:write نیاز دارد. رزرو held را به سمت صدور می‌برد. رزرو را آن‌قدر بخوانید (polling) تا به issued برسد و سپس واچر را دریافت کنید.

لغو رزرو#

POST/v3/HAPI/activities/bookings/{id}/cancel

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

فهرست رزروها#

GET/v3/HAPI/activities/bookings

به activities:read نیاز دارد. رزروهای تفریحی شما را فهرست می‌کند و می‌توان آن را بر اساس status، email و بازهٔ تاریخ فیلتر کرد.

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