۷. کلید SDK و کلید محرمانه API

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

کدام کلید را استفاده کنم؟

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

ساخت کلید محرمانه در پنل

۱. وارد پنل اینپی فای شوید و پروژه را انتخاب کنید. ۲. از بخش برنامه‌ها ← کلیدهای API وارد صفحه کلیدها شوید. ۳. در قسمت کلیدهای محرمانه، گزینه ساخت کلید جدید را بزنید.

۴. نام مشخصی مانند «سرور سایت» یا «سرویس کد تخفیف» وارد کنید. ۵. از گروه‌های دسترسی، فقط عملیات موردنیاز اتصال را فعال کنید؛ دست‌کم یک مجوز لازم است.

۶. ذخیره کنید و مقدار کامل کلید را همان‌جا در محل امن سرور نگه دارید.

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

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

انتخاب مجوزهای کلید محرمانه

مجوزها مستقل هستند؛ اجازه دریافت اطلاعات مشتری به معنی اجازه حذف او نیست. نام یا عنوان کلید هم مجوز ایجاد نمی‌کند.

مثلاً برای سرویسی که فقط کد تخفیف اختصاصی می‌سازد، مجوز discount:generate را انتخاب کنید؛ حذف مشتری یا اعطای دسترسی لازم نیست. بهتر است اتصال‌های مستقل کلیدهای جدا داشته باشند تا لغو یکی، اتصال‌های دیگر را مختل نکند.

ارسال کلید به REST API

کلید محرمانه در هدر Authorization و با روش Bearer ارسال می‌شود:

Authorization: Bearer YOUR_SECRET_API_KEY
Accept: application/json
Content-Type: application/json

پروژه از کلید تعیین می‌شود؛ کلید پروژه دیگری، به اطلاعات پروژه موردنظر شما دسترسی نمی‌دهد. در endpointهای پیشنهاد، هدر X-InAppify-App-ID نیز طبق قرارداد لازم است و باید به برنامه همان پروژه اشاره کند.

کلید را در پارامتر URL، متن پیام، کد فرانت‌اند یا فایل قابل دانلود قرار ندهید. برای نمونه PHP و درخواست کامل، احراز هویت REST API را ببینید.

دریافت کلید SDK

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

۱. پروژه را انتخاب کنید و وارد برنامه‌ها ← کلیدهای API شوید. ۲. در جدول کلیدهای برنامه، نام و نوع برنامه درست را پیدا کنید.

۳. روی نمایش کلید بزنید و مقدار آن را کپی کنید. کلید برنامه برخلاف کلید محرمانه، از این جدول دوباره قابل مشاهده است.

۴. مقدار را در گزینه کلید API هنگام راه‌اندازی SDK همان برنامه قرار دهید؛ نام دقیق گزینه را از راهنمای SDK پلتفرم خود بردارید. ۵. مشتری آزمایشی را شناسایی کنید و دریافت پیشنهادها را طبق مرحله اتصال SDK آزمایش کنید.

برای نسخه بازار، مایکت، Android مستقل، iOS یا وب، کلید همان برنامه را استفاده کنید؛ یکسان‌بودن نام محصول یا پروژه به معنی یکسان‌بودن کلید برنامه‌ها نیست. کلیدهای تولیدشده می‌توانند پیشوندهایی مانند bzr_، myk_، andr_، ios_ و web_ داشته باشند؛ این‌ها راهنما هستند، نه مقدار قابل استفاده نمونه.

SDK را با کلید محرمانه‌ای که با sk_ شروع می‌شود پیکربندی نکنید. همچنین کلید RSA یا API فروشگاه را به‌جای کلید SDK اینپی فای وارد نکنید. در مسیر فعلی API برنامه نسخه ۱، کلید برنامه در فیلد apikey بررسی می‌شود؛ این قرارداد را با هدر Bearer مربوط به REST API اشتباه نگیرید. در استفاده عادی، ارسال درخواست را به SDK بسپارید.

نگه‌داری امن و تعویض کلید

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

از فهرست کلیدهای محرمانه می‌توانید نام و مجوزهای کلید را ویرایش کنید. ویرایش مجوزها، مقدار تازه‌ای برای کلید صادر نمی‌کند؛ درخواست‌های بعدی باید مجوزهای فعلی را داشته باشند. عملیات لغو کلید، استفاده بعدی از آن برای REST API را متوقف می‌کند؛ با ساخت کلید جدید، کلید قبلی خودکار لغو نمی‌شود.

برای تعویض برنامه‌ریزی‌شده: کلید جدید با حداقل مجوز بسازید، آن را در سرویس سرور جایگزین و اتصال را آزمایش کنید، سپس کلید قبلی را لغو کنید. اگر کلید افشا شده است، اولویت با توقف دسترسی آن است؛ با درنظرگرفتن اختلال اتصال، آن را لغو و کلید جایگزین را امن مستقر کنید.

لغو کلید محرمانه، کلیدهای SDK برنامه‌ها را تعویض نمی‌کند. فرم فعلی ساخت کلید محرمانه، ورودی تاریخ انقضا ندارد؛ برای محدودکردن دسترسی موقت، برنامه لغو مشخص داشته باشید. جدول فعلی SDK نیز ابزار مستقل تعویض یا لغو کلید برنامه ارائه نمی‌دهد؛ حذف برنامه را برای تعویض کلید انجام ندهید و برای این نیاز با پشتیبانی هماهنگ کنید.

رفع خطاهای اتصال

• REST API، خطای 401: کلید ارسال نشده، اشتباه است یا دیگر معتبر نیست؛ هدر Bearer، مقدار کامل و وضعیت لغو را بررسی کنید.
• خطای 403 با API_KEY_ABILITY_DENIED: کلید معتبر است، ولی مجوز همان عملیات را ندارد.
• خطای 403 با PROJECT_OWNER_IDENTITY_REQUIRED: الزام احراز هویت مالک پروژه برقرار است؛ تغییر کلید راه‌حل این خطا نیست.
• SDK نسخه ۱، خطای نبودن یا نامعتبر بودن کلید: استفاده از کلید SDK برنامه درست و ارسال آن مطابق قرارداد را بررسی کنید؛ کلید محرمانه را جایگزین نکنید.
• اتصال برقرار است، ولی پیشنهاد اشتباه یا خالی است: برنامه و پروژه مربوط به کلید، محصولات داخل بسته و تنظیمات پیشنهاد را بررسی کنید.

مقدار کلید را برای گزارش خطا ارسال نکنید؛ نام اتصال، نوع SDK، endpoint، کد وضعیت و پیام خطای بدون اطلاعات حساس برای شروع بررسی کافی است.

ادامه راه‌اندازی

پیش از آزمون خرید، اطلاعات فروشگاه یا درگاه فعال برای پرداخت مستقیم را آماده کنید. در صورت نیاز راهنمای درگاه بانکی را ببینید.

مرحله بعد؛ اتصال SDK و شناسایی مشتری.