فیشینگ و کلاهبرداری های اینترنتی، لزوم استفاده از API شاهکار را در یک کسب و کار اینترنتی یا فروشگاه آنلاین، بیشتر میکند. این وب سرویس در واقع به این سوال پاسخ می دهد: کسی که ثبت‌نام میکند، شماره موبایل متعلق به خودش را وارد کرده است؟ فرض کنید قرار است حساب فروشنده‌ای را فعال کنید؛ او کد ملی و شماره موبایل داده و کد پیامکی را هم تأیید کرده است. اما دریافت پیامک فقط دسترسی به شماره را نشان می‌دهد، نه اینکه سیم‌کارت به نام همان فرد باشد. با راه‌اندازی وب‌سرویس شاهکار می‌توانید تطابق شماره موبایل و کد ملی را داخل محصول خود بررسی کنید و پیش از ادامه فرایند، مغایرت را تشخیص دهید.
راه‌اندازی این اتصال از ساخت حساب کسب‌وکار و دریافت کلید شروع می‌شود. سپس باید ورودی‌ها را آماده کنید، درخواست بفرستید و برای پاسخ مثبت، منفی و خطای فنی، مسیرهای جداگانه داشته باشید.
در ادامه، این مراحل را با سرویس احرازینو مرور می‌کنیم.
۱. ابتدا کاربرد و محدودیت شاهکار را بشناسید
وب‌سرویس شاهکار به یک پرسش مشخص پاسخ می‌دهد: آیا شماره موبایل واردشده به نام دارنده همین کد ملی ثبت شده است؟
ورودی این خدمت، کد ملی و شماره موبایل است. خروجی نیز نتیجه تطابق است؛ نام صاحب خط یا اطلاعات کامل هویتی در پاسخ ارائه نمی‌شود.
این بررسی با تأیید پیامکی تفاوت دارد. دریافت کد پیامک نشان می‌دهد کاربر به پیام ارسال‌شده دسترسی دارد؛ شاهکار، تطابق مالکیت شماره با کد ملی را بررسی میکند. هیچ‌کدام به‌تنهایی همه ابعاد هویت کاربر را تأیید نمی‌کنند.
پیش از اتصال، محل استفاده را مشخص کنید. برای مثال، می‌توانید بررسی را هنگام فعال‌کردن حساب فروشنده انجام دهید. انتخاب این نقطه باید با نیاز محصول و قواعد کسب‌وکار هماهنگ باشد.
۲. حساب کسب‌وکار بسازید و کلید API بگیرید
برای شروع، وارد بخش API احرازینو شوید و حساب کسب‌وکار خود را بسازید. سپس مطابق راهنمای پنل، حساب را شارژ و کلید API را ایجاد کنید. تعرفه و حداقل شارژ جاری را پیش از پرداخت بررسی کنید.
کلید API، مجوز دسترسی نرم‌افزار شما به سرویس است. آن را در محل امن سمت سرور نگه دارید و در کد مرورگر یا مخزن عمومی قرار ندهید.
اگر سرور شما IP ثابت دارد، می‌توانید هنگام ساخت کلید، دسترسی را به IP مجاز محدود کنید. همچنین باید بدانید در صورت افشای کلید، چگونه آن را از پنل باطل و جایگزین کنید.
بهتر است مسئول نگهداری کلید و پیگیری مصرف از ابتدا مشخص باشد؛ به‌خصوص اگر چند نفر در تیم به محیط عملیاتی دسترسی دارند.
اگر سایتتان وردپرسی است و از ووکامرس استفاده میکنید، برای ساده‌ترشدن اتصال می‌توانید از افزونه وردپرس احراز هویت احرازینو استفاده کنید. پس از نصب، کلید API را در تنظیمات وارد و قابلیت شاهکار را فعال میکنید؛ بدون اینکه کد اتصال را خودتان بنویسید. افزونه پس از ثبت سفارش، تطابق شماره موبایل و کد ملی مشتری را بررسی میکند و نتیجه را در فهرست سفارش‌ها نشان می‌دهد. دانلود و نصب افزونه رایگان است، اما استعلام‌های فعال‌شده طبق تعرفه از موجودی حساب کسب‌وکار شما کسر می‌شوند. ولی اگر از سیستم اختصاصی خود استفاده میکنید، مراحل زیر را دنبال کنید.
۳. کد ملی و شماره موبایل را آماده کنید
دو فیلد ورودی سرویس عبارت‌اند از:
| فیلد | اطلاعات موردنیاز |
|---|---|
| nationalCode | کد ملی |
| mobile | شماره موبایل |
این مقادیر را به‌صورت متن نگه دارید تا صفرهای ابتدای آن‌ها حذف نشوند. ارقام فارسی، فاصله‌ها و شکل‌های مختلف شماره موبایل را نیز پیش از ارسال، به قالب مورد قبول سرویس تبدیل کنید.
بررسی قالب را در نرم‌افزار خود انجام دهید تا کاربر بتواند اشتباه تایپی را زودتر اصلاح کند. البته درست‌بودن طول و قالب، به معنای تأیید تطابق نیست.
اگر کاربر شماره یا کد ملی را تغییر داد، نتیجه قبلی را برای اطلاعات جدید معتبر در نظر نگیرید. هر نتیجه باید به همان ورودی‌هایی متصل باشد که بررسی شده‌اند.
۴. اولین درخواست را از سمت سرور ارسال کنید
برای بررسی جزئیات اتصال، مستندات API احرازینو را بخوانید. درخواست شاهکار با روش POST ارسال می‌شود؛ کلید در هدر و ورودی‌ها در بدنه JSON قرار می‌گیرند.
نمونه زیر قالب درخواست را نشان می‌دهد. کلید را در متغیر محیطی سرور قرار دهید و مقادیر نمونه را با داده مجاز خود جایگزین کنید:
curl --request POST \
'https://ehrazino.com/api/v1/shahkar/' \
--header "Authorization: Bearer $EHRAZINO_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"nationalCode": "",
"mobile": ""
}'
عبارت‌های داخل < > ورودی واقعی نیستند. اجرای درخواست با اطلاعات واقعی، می‌تواند طبق تعرفه مشمول هزینه شود.
برای اتصال، مهلت انتظار مشخص کنید و آن را با راهنمای سرویس هماهنگ نگه دارید. همچنین از ارسال چندباره درخواست بر اثر چند کلیک کاربر جلوگیری کنید.
۵. نتیجه تطابق را از خطای درخواست جدا کنید
پس از دریافت پاسخ، ابتدا وضعیت درخواست را بررسی کنید و سپس نتیجه تطابق را بخوانید. موفق‌بودن فراخوان، الزاماً به معنای تطابق مثبت نیست.
نمونه ساده‌شده بخش داده برای تطابق مثبت:
{
"matched": true
}
مقدار false یعنی شماره و کد ملی تطابق ندارند. این نتیجه به‌تنهایی دلیل کافی برای متقلب‌دانستن کاربر نیست؛ ممکن است سیم‌کارت به نام شرکت یا یکی از اعضای خانواده ثبت شده باشد.
برای تصمیم‌گیری، این وضعیت‌ها را جدا نگه دارید:
| وضعیت | اقدام مناسب |
|---|---|
| تطابق مثبت | ادامه مسیر طبق قواعد محصول |
| تطابق منفی | درخواست اصلاح اطلاعات یا بررسی تکمیلی |
| ورودی نامعتبر | راهنمایی کاربر برای اصلاح فرم |
| نتیجه بدون رکورد یا فیلد مورد انتظار | بررسی معنای پاسخ طبق مستندات؛ بدون تبدیل خودکار به تطابق منفی |
| خطای موقت | تعریف تلاش مجدد کنترل‌شده یا پیگیری |
به وضعیت HTTP به‌تنهایی تکیه نکنید؛ بدنه پاسخ و کد خطا را هم بخوانید. در مستندات، حالت بدون رکورد با خطای ارتباط تفاوت دارد.
برای هزینه نیز موفقیت فنی را با مثبت‌بودن تطابق یکی فرض نکنید. پاسخ معتبر منفی یا بدون رکورد ممکن است هزینه داشته باشد. مبلغ تسویه‌شده و شناسه درخواست را برای بررسی مصرف و پیگیری نگه دارید.
۶. اتصال را آزمایش و سپس در محصول اجرا کنید
پیش از انتشار عمومی، فقط پاسخ مثبت را آزمایش نکنید. ورودی نامعتبر، تطابق منفی، کلید اشتباه، موجودی ناکافی، قطع ارتباط و ارسال تکراری فرم را هم بررسی کنید.
در هر حالت، کاربر باید بداند چه اقدامی انجام دهد. پیام «اطلاعات را بررسی کنید» با «سرویس موقتاً در دسترس نیست» کاربرد متفاوتی دارد.
اگر ارتباط قطع شد، نتیجه را منفی فرض نکنید و درخواست را بی‌رویه تکرار نکنید. ابتدا سیاست پیگیری، هزینه و تلاش مجدد را روشن کنید. درخواست‌های واقعی آزمایشی نیز الزاماً رایگان نیستند.
پس از راه‌اندازی، زمان پاسخ، خطاهای فنی، مصرف و تعداد کاربران نیازمند بررسی تکمیلی را اندازه بگیرید. برای عیب‌یابی، شناسه درخواست را نگه دارید و در صورت ابهام از پشتیبانی کمک بگیرید.
قدم بعدی، انتخاب یک کاربرد محدود و اجرای همین مراحل در محیط توسعه محصول است. وقتی پاسخ‌ها و مسیرهای خطا درست مدیریت شدند، اتصال را به‌تدریج وارد فرایند اصلی کسب‌وکار کنید.
