ارسال درخواست به API بازار

معرفی ابزار Postman

در این مطلب مراحل ارسال ریکوئست با Postman به API بازار را آموزش خواهیم داد. Postman به شما این امکان را می‌دهد که ریکوئست‌هایی از نوع REST , SOAP و GraphQL بزنید. این نرم افزار در عین حال که رایگان است پشتیبانی گسترده‌ای از همه APIها و schemaها را دارد.

بعد از توسعه یک API شما باید صحت کارکرد آن را بررسی کنید. بنابراین شما به یک API Client نیاز دارید که به کمک آن بتوانید به API خودتان ریکوئست ارسال کرده و response آن را بررسی کنید. 

حال شما می‌توانید مستقیما از طریق کروم ریکوئست بزنید (اگر درخواست از نوع GET باشد) یا خودتان کلاینتی نوشته باشید که به API ریکوئست بزند و یا از API Client‌های آماده مثل Swagger و یا Postman استفاده کنید.

در ادامه نحوه ارسال ریکوئست با Postman به API بازار را مرحله به مرحله خواهیم گفت.

ارسال ریکوئست با Postman به API‌ بازار

گام اول:

در مرحله اول شما باید وارد پیشخان شوید و از منوی سمت راست وارد بخش تنظیمات پیشخان شده و سربرگ API توسعه‌دهندگان را باز کنید.

در این صفحه بر روی گزینه‌ «کلاینت جدید» کلید کرده و با وارد کردن وب‌سایت مورد‌نظر در فیلد Redirect URI به Client ID ، Client Secret و Client URI منحصر به فرد خود دسترسی پیدا کنید.

برای اینکه با خطا مواجه نشوید باید موقع وارد کردن آدرس سایت در ابتدای آن //:https وارد کنید.

گام دوم:

در این مرحله در مرورگر خود یک New Tab یا پنجره جدید باز کنید و آدرس زیر را تکمیل کنید:

https://pardakht.cafebazaar.ir/devapi/v2/auth/authorize/?response_type=code&access_type=offline&redirect_uri=&client_id=

در این آدرس باید redirect uri که در واقع همان client uri است و client id بدست آمده در مرحله اول را وارد کنید و با کلیک روی گزینه‌ تایید به پارامتر Code دسترسی پیدا کنید.

گام سوم: 

در مرحله سوم با استفاده از نرم افزار Postman یک تب جدید باز می‌کنیم. نوع درخواست را POST انتخاب کرده و در بخش آدرس یا URL آدرس زیر را وارد می‌کنیم:

https://pardakht.cafebazaar.ir/devapi/v2/auth/token/

در ادامه طبق راهنمایی‌های داده شده در تصویر زیر در بخش Tab Bar گزینه‌ی Body را انتخاب و و نوع ارسال اطلاعات را form-data می‌گذاریم و به ترتیب KEY و VALUEهای مورد‌نظر را همانطور که در مستندات مربوط به پیاده‌سازی API آمده وارد می‌کنیم:

grant_type=authorization_code
code=<کد دریافت شده در مرحلهٔ قبل>
client_id=<شناسه‌ٔ مشخص شده در پنل توسعه‌دهندگان>
client_secret=<عبارت رمز مشخص شده در پنل توسعه‌دهندگان>
redirect_uri=<آدرس مشخص شده در پنل توسعه‌دهندگان>

همچنین شما می‌توانید با استفاده از کد اسنیپت (cURL) نیز مقدار‌های مورد‌نظر را وارد کنید تا نیازی به وارد کردن دستی آن در Postman نداشته باشید. برای انجام این‌کار روی گزینه‌ Import کلیک کنید و چون مقدار دستور به صورت Text است در تب Raw text دستور زیر را وارد کرده و continue و سپس Import را بزنید. در تب ایجاد شده بر روی Body کلیک کرده و خواهید دید که KEYهای مورد‌نظر اضافه شده و تنها نیاز است تا code، client id، client secret و redirect uri را به عنوان VALUEهای مورد‌نظر وارد نمایید.

curl --location --request POST 'https://pardakht.cafebazaar.ir/devapi/v2/auth/token/' \
--form 'grant_type="authorization_code"' \
--form 'code="Add the amount"' \
--form 'client_id="Add the amount"' \
--form 'client_secret="Add the amount"' \
--form 'redirect_uri="Insert URL"'

در صورت نیاز به دستور تکمیل شده نیز مجدد می‌توانید برای آن یک کپی از کرل (cURL) آن داشته باشید. برای اینکار روی علامت کد "</>" در Postman که در واقع همان Code Snippet است کلیک کرده و با انتخاب cURL دستور مد‌نظر را کپی کنید.

دقت داشته باشید که هرگونه فاصله در تکمیل فیلد VALUE و یا عدم دقت در گذاشتن "/" در انتهای URIها باعث دریافت خطا خواهد شد.

پس از ارسال درخواست SEND نتیجه به صورت یک قالب JSON دریافت می‌شود که حاوی access token ، زمان انقضا ، نوع توکن مورد‌نظر، scope و refresh token است.

"access_token": "GWObRK06KHLr8pCQzDXJ9hcDdSC3eV",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "yBC4br1l6OCNWnahJvreOchIZ9B6ze",
"scope": "androidpublisher"

expires_in به صورت تقریبی ۴۱ روز بوده و بر حسب ثانیه عدد آن ۳۶۰۰۰۰۰ است.

گام چهارم:

با توجه به مقادیر بدست آمده در مرحله سوم اکنون می‌توانید وضعیت خرید یا اشتراک خود را بررسی کرده و یا نسبت به دریافت access token جدید با کمک refresh token اقدام کنید.

بررسی وضعیت محصولات به کمک Postman:

در Postman یک تب جدید باز کنید و متد درخواست را GET بگذارید و در بخش آدرس یا URL آدرس زیر را وارد کند:

https://pardakht.cafebazaar.ir/devapi/v2/api/تابع ورودی?access_token=

تابع ورودی برای محصولات خریدنی: validate/package_name/inapp/product_id/purchases/purchases_token آدرس پس از وارد کردن تابع ورودی: https://pardakht.cafebazaar.ir/devapi/v2/api/ validate/package_name/inapp/product_id/purchases/purchases_token?access_token=

تابع ورودی برای محصولات اشتراکی:  applications/package_name/subscriptions/1/purchases/subscription_token آدرس پس از وارد کردن تابع ورودی: https://pardakht.cafebazaar.ir/devapi/v2/api/  applications/package_name/subscriptions/1/purchases/ subscription_token?access_token=

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

بررسی محصول خریدنی در Postman:

در بخش Tab Bar گزینه‌ی Params را انتخاب کرده و پس از وارد کردن مقادیر آدرس گفته شده در بالا بر اساس نوع تابع که در اینجا محصول خریدنی است، روی گزینه‌ SENT کلیک می‌کنیم. نتیجه موفق در قالب JSON به صورت زیر خواهد بود:

"consumptionState": 1,
"purchaseState": 0,
"kind": "androidpublisher#inappPurchase",
"developerPayload": "something",
"purchaseTime": 1414181378566

در پاسخ ارسالی اگر consumptionState برابر با صفر باشد یعنی محصول مصرف شده و اگر پاسخ یک باشد یعنی مصرف نشده است.

در پاسخ ارسالی اگر purchaseState برابر با صفر باشد یعنی خرید محصول روند عادی خود را طی نموده و اگر پاسخ یک باشد یعنی ریفاند صورت گرفته است.

برای تبدیل purchaseTime به روز یا هر واحد دیگر که بر حسب میلی ‌ثانیه است می‌توانید از این سایت استفاده کنید.

بررسی محصول اشتراکی در Postman:

همانند بررسی محصولات خریدنی در بخش Tab Bar گزینه‌ی Params را انتخاب کرده و پس از وارد کردن مقادیر آدرس گفته شده در بالا بر اساس نوع تابع که در اینجا محصول اشتراکی است، روی گزینه‌ SENT کلیک می‌کنیم. نتیجه موفق در قالب JSON به صورت زیر خواهد بود:

"kind": "androidpublisher#subscriptionPurchase",
"initiationTimestampMsec": 1414181378566,
"validUntilTimestampMsec": 1435912745710,
"autoRenewing": true,
"linkedSubscriptionToken": "YYNaa3I0uquyEA8X"

initiationTimestampMsec که بر حسب میلی‌ثانیه است زمان شروع اشتراک را نشان می‌دهد.

validUntilTimestampMsec که بر حسب میلی‌ثانیه است زمان شارژ بعدی اشتراک را نشان می‌دهد. این مقدار اگر خرید اشتراک خودکار نباشد نشان‌دهنده پایان اشتراک است

autoRenewing که پاسخ آن true/ false است نشان‌دهنده شارژ خودکار اشتراک است. این فیلد نمی‌تواند تضمینی برای تمدید اشتراک داشته باشد. این فیلد تنها نشان‌دهنده فعال بودن تمدید اشتراک است. به عنوان مثال ممکن است تمدید اشتراک فعال باشد ولی کاربر شارژ نداشته باشد یا مشکلی پیش آید که کاربر موفق به تمدید نشود.

برای بررسی محصولات خریدنی و اشتراکی می‌توانید همانند توضیحات داده شده در مرحله سوم از دستور cURL استفاده کنید. به این صورت که پس از بررسی یک محصول cURL‌ آن را کپی کرده و تنها با تغییر توکن و محصول، درخواست را ارسال و نتیجه را بررسی کنید.

بررسی اشتراک فعال

برای بررسی وضعیت اشتراک فعال کاربر در سرویس اشتراک بازار در بخش آدرس از این متد استفاده کنید:

https://pardakht.cafebazaar.ir/devapi/v2/api/applications/<package_name>/active-

subscriptions/<token>/

توکن‌های مورد استفاده در این متد می‌تواند توکن‌های تمدید اشتراک را نیز شامل شود و برخلاف بررسی وضعیت محصولات اشتراکی، محدودیتی برای استفاده از توکن‌های اشتراک اولیه خریداری شده ندارد.

نتیجه موفق این درخواست، در قالب JSON و به شکل زیر خواهد بود:

{"subscriptions": 
[{
"kind": "androidpublisher#subscriptionPurchase", 
"initiationTimestampMsec": 1649788805381, 
"validUntilTimestampMsec": 1649875205381, 
"autoRenewing": true, 
"linkedSubscriptionToken": "subscription_token", 
"sku": "product_sku"
}]}

لغو اشتراک

این متد اشتراک مورد نظر را لغو خواهد کرد:

https://pardakht.cafebazaar.ir/devapi/v2/api/applications/<package_name>/subscriptions/1/purchases/<subscription_token>/cancel/

در صورت لغو شدن اشتراک، نتیجه این درخواست یک شئ خالی JSON خواهد بود:

{}

هر توسعه‌دهنده می‌تواند در روز ۵۰ هزار درخواست از API داشته باشد.

دریافت access token جدید با استفاده از refresh token در Postman

در صورت منقضی شدن access token می‌توانید با استفاده از refresh token یک access token جدید تولید کنید. برای انجام این‌کار در نرم افزار Postman یک تب جدید باز کنید و در قسمت Tab Bar گزینه‌ Body را انتخاب و متد درخواست را POST بگذارید و آدرس زیر را وارد کنید:

https://pardakht.cafebazaar.ir/devapi/v2/auth/token/

اکنون نوع ارسال اطلاعات را form-data گذاشته و KEY و VALUE‌ها را همانطور که در مستندات مربوط به پیاده‌سازی API آمده وارد می‌کنیم:

grant_type=refresh_token
client_id=<شناسه‌ٔ مشخص شده در پنل توسعه‌دهندگان>
client_secret=<عبارت رمز مشخص شده در پنل توسعه‌دهندگان>
refresh_token=<توکن دریافتی در مرحلهٔ ۶>

در انتها نتیجه به صورت یک قالب JSON ارسال می‌گردد که در آن به access token جدید دسترسی خواهید داشت:

"access_token": "uX5qC82EGWjkjjeyvTzTufHOM9HZfM",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "androidpublisher"

همانند مراحل قبل نیز می‌توانید با Import کردن کد اسنیپت زیر به عنوان دستور cURL مقادیر را به راحتی در تب جدید داشته باشید.

curl --lcurl --location --request POST 'https://pardakht.cafebazaar.ir/devapi/v2/auth/token/' \
--form 'grant_type="refresh_token"' \
--form 'client_id="Add the amount"' \
--form 'client_secret="Add the amount"' \
--form 'refresh_token="Add the amount"'

در نهایت اگر برای شما ابهامی وجود دارد می‌توانید چه از طریق ثبت تیکت و چه تماس با شماره ۰۲۱۹۱۰۰۹۷۹۸ از همکاران ما در پشتیبانی بازار راهنمایی بگیرید.