قراردادها

چند قاعدهٔ ساده در همهٔ اندپوینت‌های HAPI v3 ثابت است. یک بار یادشان بگیرید تا API پرواز، هتل و تفریحات برایتان یکسان خوانده شوند.

آدرس پایه و انتقال#

همهٔ درخواست‌ها از طریق HTTPS به https://api.simorghapi.com/v3/HAPI فرستاده می‌شوند. بدنهٔ درخواست‌ها و پاسخ‌ها JSON با کدگذاری UTF-8 است. در درخواست‌هایی که بدنه دارند، هدر Content-Type: application/json را بفرستید.

نام‌گذاری فیلدها#

همهٔ کلیدهای JSON به‌صورت snake_case هستند. فیلدها پایدارند: به‌مرور فیلد جدید اضافه می‌کنیم، اما در یک نسخه هیچ فیلدی را تغییر نام نمی‌دهیم یا حذف نمی‌کنیم.

شناسهٔ منابع#

هر شیء یک id رشته‌ای با پیشوند کوتاهِ نوع خود دارد؛ بنابراین هر شناسه خودش نشان می‌دهد مال چیست و با شناسه‌های دیگر اشتباه گرفته نمی‌شود. شناسه‌ها مات (opaque) هستند: آن‌ها را رشته در نظر بگیرید و تجزیه‌شان نکنید.

مبالغ#

مبالغ همیشه شیء هستند، نه عدد خام. مقدار amount یک رشتهٔ اعشاری است تا خطای گردکردن اعداد ممیز شناور پیش نیاید، و currency همیشه USD است.

{
  "total": { "amount": "412.00", "currency": "USD" }
}

زمان‌ها#

همهٔ تاریخ‌ها و زمان‌ها با قالب RFC 3339 و در UTC هستند؛ برای نمونه 2026-11-14T09:40:00Z. تاریخ‌های تقویمی ساده با قالب YYYY-MM-DD می‌آیند.

شناسهٔ درخواست#

هر پاسخ یک هدر Request-Id دارد و بدنهٔ خطاها همین مقدار را با نام request_id تکرار می‌کند. آن را لاگ کنید و هنگام تماس با پشتیبانی (پنل → پشتیبانی) اعلامش کنید تا بتوان یک فراخوانی را از ابتدا تا انتها ردیابی کرد.

ایدمپوتنسی#

روی هر درخواست POST که منبعی می‌سازد (یک سفارش، یک درخواست صدور بلیت)، هدر Idempotency-Key را بفرستید. اگر فراخوانی با همان کلید تکرار شود، به‌جای ساختن نسخهٔ تکراری، همان نتیجهٔ اول برگردانده می‌شود؛ بنابراین قطع‌شدن اتصال هیچ‌وقت به رزرو دوباره منجر نمی‌شود.

Idempotency-Key: 5f2b8c1a-3e4d-4a6b-9c7e-1d2f3a4b5c6d

صفحه‌بندی#

اندپوینت‌های فهرستی با کرسر صفحه‌بندی می‌شوند. limit را بفرستید و برای ادامه، کرسر after را از صفحهٔ قبل. ساختار پاسخ می‌گوید که آیا موارد بیشتری مانده است یا نه.

{
  "data": [ /* … */ ],
  "has_more": true,
  "next_cursor": "crs_9f3c81d2"
}

کدهای وضعیت HTTP#

HAPI از کدهای وضعیت واقعی استفاده می‌کند. 2xx یعنی موفقیت؛ 4xx یعنی درخواست اشتباه بوده؛ 5xx یعنی خطا از سمت پلتفرم است.

بدنهٔ همهٔ خطاها از ساختاری پیروی می‌کند که در مرجع خطاها آمده است.