احراز هویت

احراز هویت در پنل زرین‌پال، تحت پرتکل oAuth 2.0 (opens new window) و استاندارد REST انجام می‌شود. قبل از شروع روند احراز هویت، باید مشخصات کلاینت خودتان از جمله client_id و client_secret را از پشتیبانی زرین‌پال دریافت کنید.

ثبت نام (register)

برای شروع روند ثبت نام ، ابتدا باید یک درخواست POST با فرمت application/json به آدرس زیر ارسال کنید:

 https://next.zarinpal.com/api/oauth/register

لیست پارامترهای قابل‌پذیرش توسط این مقصد عبارت‌اند از:

نام	نوع قابل‌قبول	الزامی است؟	توضیحات
first_name	string	بله	نام
last_name	string	بله	نام خانوادگی
cell_number	Integer	بله	شماره تلفن همراه

مقالی برای عضویت :

$ curl 'https://next.zarinpal.com/api/oauth/register' \
  -H 'Content-Type: application/json' \
  --data-binary '{"first_name": "علی","last_name": "علیپور","cell_number":"09123456789"}'

پاسخ

در پاسخ به این درخواست،اگر کاربر قبلا ثبت نشده باشد پاسخی به این شکل ارسال می‌شود که شماره کاربری زرین پال است:

{
    "user_id": 945298
}

در صورتی که کاربر قبلا ثبت نام شده باشد خطای موجود بودن آن دریافت می شود

شروع کار (Initialization)

درخواست

برای شروع روند احراز هویت، ابتدا باید یک درخواست POST با فرمت application/json به آدرس زیر ارسال کنید:

https://next.zarinpal.com/api/oauth/initialize

لیست پارامترهای قابل‌پذیرش توسط این مقصد عبارت‌اند از:

نام	نوع قابل‌قبول	الزامی است؟	مقدار پیش‌فرض	توضیحات
username	string	بله		آدرس ایمیل یا شماره‌ی همراه کاربر
channel	string('ussd', 'sms')	خیر	'ussd'	کانال دریافت رمز یک‌بار مصرف کاربر

برای مثال، ما می‌خواهیم کاربری با شماره‌ی موبایل 09123456789 را با استفاده از کد USSD احراز هویت کنیم:

$ curl 'https://next.zarinpal.com/api/oauth/initialize' \
  -H 'Content-Type: application/json' \
  --data-binary '{"username":"09123456789","channel":"ussd"}'

curl -X POST \
  https://next.zarinpal.com/api/oauth/initialize \
  -H 'content-type: application/json' \
  -d '{"username":"09123456789","channel":"sms"}'

پاسخ

در پاسخ به این درخواست، پاسخی به این شکل ارسال می‌شود:

{
  "avatar": "https:\/\/gravatar.com\/avatar\/{EMAIL_HASH}",
  "channel": "ussd",
  "ussd_code": "*733*4*97*2#",
  "waiting_time": 120,
  "otp_time_diff": 900
}

لیست پاسخ‌های ارسال‌شده به این صورت هستند:

نام	نوع	الزامی است؟	توضیحات
avatar	string	بله	URL آواتار کاربر (معمولاً به Gravatar اشاره می‌کند)
channel	string('ussd', 'sms')	بله	کانالی که از طریق آن رمز یک‌بار مصرف در اختیار کاربر قرار می‌گیرد
ussd_code	string	خیر	شماره‌ی USSD که کاربر باید با شماره‌گیری آن، رمزش را دریافت کند؛ مقدار این کلید، در صورتی که channel برابر sms باشد، یک رشته‌ی خالی خواهد بود
waiting_time	int	بله	زمان به ثانیه قبل از این که کاربر بتواند دوباره درخواستی برای ارسال رمز یک‌بار مصرف بدهد
otp_time_diff	int	بله	@todo

تأیید رمز (Verification)

پس از این‌ که کاربر رمز یک‌بار مصرفش را وارد کرد، صحت و اعتبار رمز می‌بایستی تأیید شود. بعد از تأیید موفقیت‌آمیز رمز، یک Access Token و یک Refresh Token برای استفاده از امکانات API در پاسخ ارسال می‌شود.

درخواست

مشابه مرحله‌ی قبل، یک درخواست POST با فرمت application/json به آدرس زیر ارسال کنید:

https://next.zarinpal.com/api/oauth/token

لیست پارامترهای قابل‌پذیرش توسط این مقصد برای دریافت توکن (بدون Refresh Token) عبارت‌اند از:

نام	نوع قابل‌قبول	الزامی است؟	مقدار پیش‌فرض	توضیحات
grant_type	string	بله	'password'	نوع ورودی کاربر، در این مرحله باید برابر با 'password' باشد
client_id	int	بله		آی‌دی کلاینت شما که از زرین‌پال دریافت کرده‌اید
client_secret	string	بله		کلید کلاینت شما که از زرین‌پال دریافت کرده‌اید
username	string	بله		آدرس ایمیل یا شماره‌ی موبایل کاربر
password	string	بله		رمز یک‌بار مصرف که کاربر وارد کرده است
scope	string	بله	'*'	@todo

برای مثال، در ادامه‌ی مثال قبل، کاربری با شماره‌ی موبایل 09123456789، رمزِ 12345678 را وارد کرده است:

$ curl 'https://next.zarinpal.com/api/oauth/token' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "grant_type": "password",
    "client_id": 100,
    "client_secret": "$ecreT",
    "username": "09123456789",
    "password": "12345678",
    "scope": "*"
  }'

پاسخ

پاسخ این در درخواست (در صورت صحیح‌بودن داده‌ی ارسالی، بخش خطاها را ببینید) به صورت زیر خواهد بود:

{
  "token_type": "Bearer",
  "expires_in": 1296000,
  "access_token": "{ACCESS_TOKEN}",
  "refresh_token": "{REFRESH_TOKEN}"
}

لیست جزئیات پاسخ‌های ارسال‌شده به این صورت هستند:

نام	نوع	الزامی است؟	توضیحات
token_type	string	بله	نوع توکن ارسالی رو مشخص می‌کند؛ نوع توکن‌های زرین‌پال Bearer هستند
expires_in	int	بله	طول عمر توکن را به ثانیه مشخص می‌کند
access_token	string	بله	Access Token برای کارکردن با امکانات سرور GraphQL؛ این توکن با استاندارد JWT (opens new window) ایجاد می‌شود
refresh_token	string	بله	‍Refresh Token برای دریافت توکن جدید بعد از منقضی‌شدن توکن قبلی؛ بخش Refresh Token را ببینید

Refresh Token

بعد از این که Access Token دریافتی پس از مدتی که در فیلد expires_in مشخص شده منقضی شد، لازم است که با استفاده از refresh_token داده‌شده در مرحله‌ی قبل، یک Access Token جدید دریافت کنید.

درخواست

برای دریافت توکن جدید، مشابه مرحله‌ی قبلی، یک درخواست POST با فرمت application/json به آدرس زیر ارسال کنید:

https://next.zarinpal.com/api/oauth/token

لیست پارامترهای قابل‌پذیرش به منظور دریافت توکن جدید با Refresh Token برای این مقصد به این صورت است:

نام	نوع قابل‌قبول	الزامی است؟	مقدار پیش‌فرض	توضیحات
grant_type	string	بله	'refresh_token'	نوع ورودی کاربر، در این مرحله باید برابر با 'refresh_token' باشد
client_id	int	بله		آی‌دی کلاینت شما که از زرین‌پال دریافت کرده‌اید
client_secret	string	بله		کلید کلاینت شما که از زرین‌پال دریافت کرده‌اید
refresh_token	string	بله		مقدار Refresh Token که از مرحله‌ی قبل دریافت کردید
scope	string	بله	''	@todo

پاسخ

جزئیات و انواع فیلدهای دریافتی در پاسخ، دقیقاً مانند مرحله‌ی قبل هستند.

خطاها

در صورتی که در هر یک از مراحل بالا، خطایی رخ دهد یا داده‌ی ارسال‌شده در درخواست، نامعتبر باشند؛ فیلد errors در پاسخ دریافتی حاوی یک آرایه خواهد بود که خطاهای درخواست در آن مشخص می‌شوند و فیلد data نیز مقدار null خواهد داشت.