# احراز هویت

همه‌ی وب‌سرویس‌های زرین‌هاب پشت یک توکن Bearer قرار دارند. برای دریافت توکن، نام کاربری API (username) و رمز API (password) را به سرویس احراز هویت ارسال می‌کنید و در پاسخ یک accessToken و یک refreshToken دریافت می‌کنید.

مهم

نام کاربری و رمز API با نام کاربری و رمز ورود به پنل زرین‌هاب یکی نیستند. هر دو در پنل کاربری ساخته می‌شوند و فقط برای فراخوانی وب‌سرویس‌ها کاربرد دارند؛ نام کاربری API شماره موبایل شما نیست. تا زمانی که رمز API را تعیین نکرده باشید، درخواست دریافت توکن با خطای Api password has not been set رد می‌شود.

# دریافت توکن

POST https://zarin-hub.com/api/v5/Authentication/GetToken
Content-Type: application/json

نام	نوع	الزامی است؟	توضیحات
username	string	بله	نام کاربری API که در پنل کاربری ساخته‌اید
password	string	بله	رمز API که در پنل کاربری تعریف کرده‌اید

curl 'https://zarin-hub.com/api/v5/Authentication/GetToken' \
  -H 'Content-Type: application/json' \
  --data-binary '{"username":"YOUR_API_USERNAME","password":"YOUR_API_PASSWORD"}'

# پاسخ

{
  "meta": {
    "trackId": "9b126e9a-184c-4cb0-a47e-62b9a3b7176f",
    "status": "auth-v5-0",
    "isSuccess": true,
    "code": 0,
    "message": "عملیات با موفقیت انجام شد",
    "errorMessage": null,
    "errorType": null,
    "errors": []
  },
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresTn": 28800,
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

نام	نوع	توضیحات
accessToken	string	توکن دسترسی؛ در هدر `Authorization` ارسال می‌شود
tokenType	string	همیشه `Bearer`
expiresTn	int	طول عمر توکن دسترسی به ثانیه (پیش‌فرض ۲۸۸۰۰ ثانیه، معادل ۸ ساعت)
refreshToken	string	توکن تمدید؛ برای گرفتن جفت‌توکن جدید بدون ارسال دوباره‌ی رمز API

نکته

نام فیلد expiresTn عمداً به همین شکل باقی مانده است. قرارداد نسخه‌ی ۵ قفل است و نام فیلدها برای حفظ سازگاری با کلاینت‌های موجود تغییر نمی‌کند.

# تمدید توکن (Refresh)

پس از پایان اعتبار accessToken، به‌جای ارسال دوباره‌ی نام کاربری و رمز، همان مقصد را با refreshToken صدا بزنید:

curl 'https://zarin-hub.com/api/v5/Authentication/GetToken' \
  -H 'Content-Type: application/json' \
  --data-binary '{"refreshToken":"YOUR_REFRESH_TOKEN"}'

پاسخ دقیقاً همان ساختار مرحله‌ی قبل است و یک جفت‌توکن تازه برمی‌گرداند. عمر پیش‌فرض refreshToken یک سال است.

مهم

با تغییر یا بازنشانی رمز API، تمام refreshTokenهای صادرشده بلافاصله بی‌اعتبار می‌شوند و باید دوباره با نام کاربری و رمز جدید توکن بگیرید.

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

توکن دریافتی را در هدر Authorization همه‌ی درخواست‌های /api/v5/* قرار دهید:

curl 'https://zarin-hub.com/api/v5/KYC/CheckShahkar' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  --data-binary '{"nationalCode":"0012345678","mobileNumber":"09123456789"}'

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

وضعیت HTTP	`meta.code`	`meta.errorType`	شرح
۴۰۰	2	BadRequest	بدنه‌ی درخواست نامعتبر است یا نام کاربری/رمز ارسال نشده
۴۰۱	6	UnAuthorized	نام کاربری یا رمز API اشتباه است، یا رمز API تعیین نشده
۴۰۱	6	UnAuthorized	`refreshToken` نامعتبر یا منقضی شده است
۴۰۳	9	Inaccessible	حساب کاربری غیرفعال شده است
۵۰۰	1	ServerError	خطای داخلی سرور

# نکات امنیتی

رمز API و توکن‌ها را هرگز در کد سمت کاربر (اپلیکیشن موبایل یا مرورگر) قرار ندهید؛ دریافت توکن باید روی سرور شما انجام شود.
توکن را تا پایان اعتبارش نگه دارید؛ گرفتن توکن جدید برای هر درخواست، فشار بی‌مورد به سرویس وارد می‌کند.
برای محدود کردن مبدأ درخواست‌ها، IP سرورهای خود را در پنل ثبت کنید. راهنمای امنیت و محدودسازی IP را ببینید.

# احراز هویت

# دریافت توکن

# پاسخ

# تمدید توکن (Refresh)

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

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

# نکات امنیتی

در این صفحه