نحوه درخواست سرویس
بعد از تایید کسب وکار، و بعد از ورود به سایت پادیوم، لازم است سرویسهای مورد نظر خود را از طریق بازارچه API سایت، درخواست دهید.
درخواست استفاده از وب سرویسهای مورد نظر شما، بررسی شده و در صورت تایید توسط کارشناسان فروش، میتوانید Apikey مربوط به سرویس مورد نظر خود را دریافت کنید.
شناسه محصول/شناسه سرویس : Product Id
هر سرویس/محصول دارای یک شناسه است که برای استفاده از آن سرویس، باید در درخواست شناسه‌ی آن سرویس در فیلدsc Product Id ذکرشود. این شناسه در سایت پادیوم، در هنگام درخواست سرویس و در مستندات فنی قتبل مشاهده است.
دریافت اطلاعات مربوط به کسب وکار:
نام کاربری کسب و کار، نام کاربری مالک کسب و کار حقیقی BusinessToken , ApiKey , BusinessId ,
برای ورود به پنل کسب وکار خود، وارد سایت www.podium.ir شده، و از منوی پروفایل، گزینه ورود به پنل کسب وکار را انتخاب کنید.
نام کاربری کسب وکار :
نام کاربری ایجاد شده برای کسب وکار در حین ثبت نام را میتوانید از منوی پروفایل کاربر در قسمت بالا سمت چپ پنل کسب وکار، خط دوم بدست بیاورید.
یا از بخش اطلاعات کسب وکار در لینک https://panel.pod.ir/Businesses/BusinessInfo دریافت نمایید.
نام کاربری مالک کسب وکار حقیقی:
برای کسب وکارهای حقیقی یک نام کاربری برای مالک کسب وکار (Owner) وجود دارد که در حین ثبت نام اولیه، توسط کاربر ایجاد شده است که میتوانید از
.بدست آورید https://panel.pod.ir/Businesses/BusinessInfo?tab=owner بخش اطلاعات هویتی مالک در منوی
(_token_ توکن کسب و کار (فیلد : Business Token
- در تمام درخواست‌هایی که به پلتفرم پاد ارسال میشود در هشHeader
، فیلد _token_ حاوی توکن کسب و کاری ست، که باید از پنل و منوی زیر دریافت شود:
- پنل کسب وکار: منوی ورود یکپارچه – لیست کلیدها، با کلیک بر روی دکمه اطلاعات توکن کسب وکار، قابل دریافت است.
- نیاز هست که این توکن یکبار تولید شده و ذخیره گردد تا در درخواست‌های ارسالی استفاده شود.
- با تولید دوباره این توکن، توکن‌‌های قبلی از بین نمی‌روند.
- در برخی از مستندات پلتفرم پاد و پادیوم از واژه API token برای اشاره به توکن ثابت کسب وکار استفاده میشود.
- در موارد اضطراری میتوانید تمامی توکن‌‌های خود را حذف نمایید تا دسترسی‌‌ها به حساب دیجیتال شما از طریق وب سرویس لغو
گردند.
API KEY: دریافت کلید فراخوانی سرویس (_scApiKey_ )
برای استفاده از هر سرویس یک کلید باید دریافت شود. که به دو طریق امکان دریافت آن وجود دارد:
* این کلید در تمام درخواست‌های ارسالی از آن سرو یس، ثابت است و نیاز نیست برای هربار فراخوانی سرویس، کلید جدید دریافت نمایید .
روش اول : ارسال درخواست در سایت پادیوم Podium:
* این روش برای سرویس‌‌هایی است که نیاز به ارسال شماره حساب ندارند قابل استفاده میباشد،
ابتدا وارد سایت پادیوم شده، سپس در بازارچه‌ی API، سرویسهای مورد نظر خود را انتخاب و درخواست استفاده از آن مجموعه سرویس را ارسال کنید.
درخواست شما توسط کارشناسان پادیوم، بررسی شده و بعد از تایید آن میتوانید از طریق پنل کسب وکار خود اقدام به دریافت کلید اتصال مربوط به آن سرویس نمایید. منوی: پنل کسب وکار – منوی میزکار سرویس گیرنده – درخواست‌های ارسالی – در بخش مربوط به سرویس موردنظر با کلیک بر روی "جزئیات درخواست"
در لیست باز شده با کلیک بر روی تصویر کلید سمت چپ هر سطر جدول میتوانیدApikey مربوط به ان سرویس را دریافت و ذخیره کنید.
https://panel.pod.ir/Businesses/RequestWebServices
این کلید در تمام درخواست‌های ارسالی از آن سرویس، ثابت است.
- این کلید در فیلدsc Api Key در بخشbody درخواست HTTP، استفاده میشود.
دریافت کلیدهای سرویس یک دسته/مجموعه (سرویس در قالب یک فایل):
بعد از فشردن دکمه تایید در پنجره باز شده بالا، برای تمامی سرویسهای موجود در پنل، میتوانید از گزینه "دریافت فایل خروجی"، لیست کاملی از سرویس‌ها و کلیدهای scApikey متناظر با هریک را دریافت کنید.
روش دوم: درخواست و دریافت ApiKey با استفاده از سرویس:
برای دریافت ApiKey سرویسهای بانکی یا سایر موارد خاص که امکان درخواست سرویس به روش اول (سایت)، وجود ندارد میتوانید با اعلام و هماهنگی با تیم پشتیبانی از سرویس برای درخواست و دریافت ApiKey از طریق سرویس اقدام نمایید.
2.1 دریافت ApiKey برای سرویسهای بانکی :
اگر سرویس درخواستی شما جزء سرویسهای بانکی است و برای استفاده نیاز به شماره حساب دارد، باید از طریق سرویسهای زیر اقدام به ارسال درخواست استفاده از سرویس، و دریافت ApiKey نمایید. (توجه نمایید که در آینده امکان درخواست سرویسهای بانکی ازطریق سایت نیز امکان‌پذیر خواهد بود)
2.2 ارسال درخواست تولید ApiKey برای یک سرویس بانکی :
CURL یک فراخوانی سرویس درخواست کلید در پادیوم به شکل زیر است:
برای این کار سرویس به ادرس https://api.pod.ir/srv/sc/nzh/biz/requestApiKey/ را با پارامترهای زیر فراخوانی کنید .
|
توضیح |
مقدار |
نام پارامتر |
|
Header |
||
|
توکن کسب وکار |
|
_token_ |
|
مقدار همواره ثابت 1 |
1 |
_token_issuer_ |
|
Body |
||
|
الزامی - مقدار همواره ثابت 1623 |
1623 |
businessId |
|
الزامی - شناسه سرویس مورد نظر |
|
productId |
|
الزامی - شماره حساب ثبت شده در کسب وکار (راهنمایی لازم جهت ثبت شماره حساب، از تیم پشتیبانی دریافت شود) |
W.X.Y.Z |
depositNumber |
|
خروجی سرویس به صورت یک آرایه، شامل تنها یک عنصر به شکل JSON Object Result [{}] |
||
|
شناسه درخواست |
Number |
id |
|
وضعیت( فعلی شناسه) درخواست |
String |
statusCode |
|
اطلاعات مربوط به سرویس درخواست شده |
{} |
product |
جدول مقادیر وضعیت درخواست statusCode:
|
مقدار |
توضیح |
|
CLIENT_API_KEY_STATUS_REQUESTED |
درخواست داده شده - در این وضعیت، کسب وکار باید از پشتیبانی، تایید این درخواست را بخواهد. |
|
CLIENT_API_KEY_STATUS_CONFIRMED |
تایید شده توسط پادیوم - بعد از تایید، درخواست به این وضعیت تغییر خواهد کرد که بعد از این کسب و کار میتواند، اقدام به تولید ApiKey نماید . |
- نکته: در صورتی که سرویس مورد نظر سرویس بانکی نباشد، نیاز به ارسال پارامتر depositNumber در ورودی سرویس نیست.
2.3 تولید ApiKey:
CURL یک فراخوانی سرویس دریافت کلید در پادیوم به شکل زیر است:
بعد از تایید درخواست، توسط کارشناسان پادیوم، کسب وکار میتواند از طریق فراخوانی سرویس زیر، اقدام به دریافت ApiKey سرویس خود نماید .
برای این کار سرویس با https://api.pod.ir/srv/sc/nzh/biz/generateApiKey/ را همراه با پارامترهای زیر ارسال نمایید.
|
توضیح |
مقدار |
نام پارامتر |
|
Header |
||
|
توکن کسب وکار |
|
_token_ |
|
مقدار همواره ثابت 1 |
1 |
_token_issuer_ |
|
Body |
||
|
شناسه درخواست |
Number |
id |
|
خروجی سرویس به صورت یک آرایه، و شامل تنها یک عنصر به شکل JSON Object Result {} |
||
|
شناسه درخواست |
Number |
id |
|
وضعیت( فعلی شناسه) درخواست |
String |
statusCode |
|
اگروضعیت درخواست در حالت تایید شده باشد . این فیلد حاوی کلید فراخوانی سرویس خواهد بود. |
A.B |
apiKey |
|
اطلاعات مربوط به سرویس درخواست شده |
{} |
product |
نکته: برای دریاف apikeyهای سندباکس در دو سرویس request و generate تغییرات زیر در آدرس سرویس اعمال شود:
- بیزنس ایدی از 1623 به 1841 تغییر داده شود.
- آدرس سرویس به sandbox.sandpod.ir تغییر کند.
کدهای خطای (errorCode) پلتفرم:
برخی از کدهای معمول خطا در پلتفرم در جدول زیر آمده است .
|
کد خطا |
پیام message |
توضیح |
اقدامات پیشنهادی جهت رفع خطا |
|
21 |
client not authenticated |
خطای احراز هویت - مربوط به مقدار دو فیلد ورودی _token_ _issuer_token_ |
توکن بررسی شود که توکن دریافتی از پنل باشد و شامل کاراکتر اضافی یا کمتر و بیشتر، نباشد. |
|
21 |
کلید اتصال ارسال نشده است |
فیلد scApiKey ارسال نشده شده است یا حاوی مقدار نیست |
- |
|
21 |
کلید اتصال معتبر نمی‌باشد |
مقدار فیلد scApiKey حاوی مقدار صحیح نمی‌باشد. |
- |
|
101 |
ورودی‌‌های سرویس نمی‌تواند شامل کارکترهای غیر مجاز باشد |
|
کاراکترهای خاص مانند: |
|
101 |
مقدار پارامتر اجباری X ارسال نشده است |
پارامتر الزامی در ورودی سرویس ارسال نشده است |
- |
|
141 |
ورودی عددی را صحیح وارد نمایید |
مقدار پارامتر ورودی باید حاوی اعداد و بدون کارکتر فضای خالی باشد. |
مقدار فیلد scProductId بررسی شود که صرفا شامل ارقام باشد. |
|
193 |
شناسه محصول را وارد نمایید |
فیلد scProductId ارسال نشده است. |
- |
|
227 |
سرور قادر به فراخوانی سرویس مدنظر نمی‌باشد |
معمولا زمانی که سرویس دهنده نهایی Down باشد یا اینکه به علت کندی در پاسخ دادن، سرویس دچار timeout شده باشد. توجه داشته باشید، حداکثر زمان پاسخ دادن یک سرویس دهنده 29 ثانیه میباشد، بیشتر از این زمان، سرویس خطای 227 تولید میکند و اصطلاحا timeout میشود. |
با پشتیبانی تماس حاصل گردد. |
|
378 |
خطا در اجرای اسکریپت |
معمولا به دلیل عدم ارسال صحیح پارامترهای ورودی توسط فراخوانی کننده سرویس این خطا رخ میدهد . |
با پشتیبانی تماس حاصل گردد. |
|
999 |
به علت خطای داخلی سیستم قادر به پاسخگویی به سرویس مورد نظر نیستیم |
عدم امکان پردازش پاسخ در پلفترم پاد، که معمولا به علت عدم دریافت پاسخ از سرویس دهنده میباشد. |
با پشتیبانی تماس حاصل گردد. |