احراز هویت

HAPI v3 از گرنت client-credentials در OAuth2 استفاده می‌کند. یک client_id و client_secret را با یک توکن دسترسی Bearer کوتاه‌عمر عوض می‌کنید و سپس آن توکن را در همهٔ درخواست‌ها می‌فرستید.

هیچ کلید API بلندمدتی روی شبکه جابه‌جا نمی‌شود. توکن دسترسی تنها اعتبارنامه‌ای است که یک درخواست با خود دارد و پس از یک ساعت منقضی می‌شود؛ بنابراین اگر توکنی لو برود، مدت زیادی قابل سوءاستفاده نیست.

اعتبارنامه‌های شما#

مقدار	نمونه	توضیح
`client_id`	`cid_live_…` / `cid_test_…`	شناسهٔ عمومی کلاینت. پیشوند آن محیط را مشخص می‌کند.
`client_secret`	`sk_live_…` / `sk_test_…`	کلید محرمانه. هرگز آن را از مرورگر یا اپ موبایل نفرستید؛ فقط روی سرور خودتان نگهش دارید.

دریافت توکن#

POST/v3/HAPI/auth/tokens

پارامترهای بدنه#

نام	نوع	الزامی	توضیح
`grant_type`	string	الزامی	باید `client_credentials` باشد.
`client_id`	string	الزامی	شناسهٔ کلاینت شما.
`client_secret`	string	الزامی	کلید محرمانهٔ کلاینت شما.
`scope`	string	اختیاری	اسکوپ‌های جداشده با فاصله برای محدودکردن توکن. پیش‌فرض: همهٔ اسکوپ‌هایی که کلاینت دارد.

اعتبارنامه‌ها را می‌توانید در بدنهٔ JSON بفرستید یا به‌صورت HTTP Basic auth (client_id به‌عنوان نام کاربری و client_secret به‌عنوان رمز عبور):

curl -X POST https://api.simorghapi.com/v3/HAPI/auth/tokens \
  -u "cid_live_…:sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "grant_type": "client_credentials" }'

پاسخ#

{
  "access_token": "hat_live_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "expires_at": "2026-08-27T17:36:36+00:00",
  "scope": "flights:read flights:write wallet:read",
  "environment": "live"
}

فیلد	توضیح
`access_token`	توکن Bearer که باید در همهٔ درخواست‌ها بفرستید.
`token_type`	همیشه `Bearer`.
`expires_in`	تعداد ثانیه تا انقضای توکن (3600).
`expires_at`	زمان دقیق انقضا، با قالب RFC 3339 و منطقهٔ زمانی UTC.
`scope`	اسکوپ‌های اعطاشده به این توکن، جداشده با فاصله.
`environment`	`test` یا `live`، بر اساس اعتبارنامه.

استفاده از توکن#

توکن را در هدر Authorization بفرستید:

Authorization: Bearer hat_live_…

بررسی توکن (Introspect)#

ببینید یک توکن به کدام دفتر، کدام محیط و کدام اسکوپ‌ها نگاشت می‌شود.

GET/v3/HAPI/auth/introspect

{
  "active": true,
  "client_id": "cid_live_…",
  "environment": "live",
  "office": { "id": "off_2", "name": "Your Office" },
  "scopes": ["flights:read", "flights:write", "wallet:read"],
  "token_type": "Bearer",
  "expires_at": "2026-08-27T17:36:36+00:00"
}

اسکوپ‌ها#

هر توکن به مجموعه‌ای از اسکوپ‌ها محدود است. اندپوینت‌های خواندنی به اسکوپ :read محصول خودشان نیاز دارند و اندپوینت‌هایی که پول جابه‌جا می‌کنند یا رزرو می‌سازند به :write. درخواستی که اسکوپ لازم را نداشته باشد، خطای 403 insufficient_scope می‌گیرد.

اسکوپ	دسترسی
`flights:read`	جست‌وجوی پرواز، خواندن پیشنهادها، خواندن سفارش‌ها.
`flights:write`	ایجاد سفارش، صدور بلیت، لغو، استرداد.
`hotels:read` / `hotels:write`	همین تقسیم‌بندی برای هتل.
`activities:read` / `activities:write`	همین تقسیم‌بندی برای تفریحات.
`wallet:read`	خواندن موجودی دفتر شما.

محیط‌ها#

اعتبارنامهٔ test روی یک کیف پول سندباکس کار می‌کند: جست‌وجوها واقعی‌اند، اما رزروها هرگز پول واقعی جابه‌جا نمی‌کنند. اعتبارنامهٔ live روی موجودی واقعی دفتر شما کار می‌کند. چون محیط بخشی از اعتبارنامه است، هرگز لازم نیست آدرس سرور را عوض کنید؛ فقط با کلاینت متناظر احراز هویت می‌کنید.

خطاهای احراز هویت#

وضعیت	کد	معنا
400	`missing_credentials`	`client_id` / `client_secret` ارسال نشده است.
400	`unsupported_grant_type`	مقدار `grant_type` برابر `client_credentials` نبود.
401	`invalid_client`	شناسه یا کلید محرمانهٔ کلاینت اشتباه است.
401	`missing_authorization`	درخواست توکن Bearer ندارد.
401	`invalid_token`	توکن ناشناخته است.
401	`expired_token`	توکن منقضی شده است؛ توکن تازه بگیرید.
403	`insufficient_scope`	توکن اسکوپ موردنیاز اندپوینت را ندارد.

ساختار کامل پاسخ خطا را در مرجع خطاها ببینید.

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