حالت آزمایشی، حالت واقعی و کلیدهای API
دو حالت چطور داده‌ها را از هم جدا نگه می‌دارند، کدام کلید را کجا به کار ببرید و چطور کلید را عوض یا محدود کنید.
دو حالت، دو مجموعه داده
هر حساب کسب‌وکار یک حالت آزمایشی و یک حالت واقعی دارد. پرداخت‌ها، رسیدها، واریزها، کارت‌ها و حساب‌ها، گوشی‌ها، لینک‌های پرداخت، مشتری‌ها، نقطه‌های دریافت وب‌هوک، رویدادها و کلیدها هر کدام مال یک حالت‌اند و از حالت دیگر دیده نمی‌شوند. تیم و طرح شما برای هر دو حالت یکی است.
| موضوع | حالت آزمایشی | حالت واقعی |
|---|---|---|
| پول | جابه‌جا نمی‌شود؛ رسید هر عکسی می‌تواند باشد و واریزها شبیه‌سازی‌اند | انتقال واقعی به کارت یا حساب واقعی شما |
| اثبات پرداخت | رسیدی که روی صفحهٔ پرداخت آزمایشی بارگذاری و تأیید می‌کنید، POST / یا واریز شبیه‌سازی‌شده در داشبورد | رسیدهای مشتری که تیم شما تأیید می‌کند، پیامک بانکی که اپ اختیاری می‌فرستد، یا واریزی که دستی ثبت می‌کنید |
| اعلان پیامکی و ایمیلی | هرگز فرستاده نمی‌شود | طبق تنظیمات اعلان شما فرستاده می‌شود |
| سقف طرح برای کارت و حساب، گوشی و لینک | حساب نمی‌شود | حساب می‌شود |
| صفحهٔ پرداخت | نوار «پرداخت آزمایشی» دارد | بدون نوار |
حالت از روی کلید معلوم می‌شود و API هیچ پارامتری برای حالت ندارد.
انواع کلید
کلیدها را از توسعه‌دهندگان ← کلیدهای API و در همان حالتی که لازم دارید بسازید.
| پیشوند | نوع | کاربرد |
|---|---|---|
sk_test_ / sk_live_ | مخفی | سرور شما. دسترسی کامل به API همان حالت. |
rk_test_ / rk_live_ | محدود | بخشی از سرور که دسترسی کمتری لازم دارد: برای هر منبع none، read یا write را انتخاب می‌کنید. |
pk_test_ / pk_live_ | عمومی | رزرو شده. فعلاً همهٔ مسیرهای API آن را با secret_key_required رد می‌کنند. |
کلید مخفی فقط یک بار، هنگام ساخت، نمایش داده می‌شود. بزن به کارت فقط هش آن را نگه می‌دارد؛ پس کلید گم‌شده دوباره نمایش داده نمی‌شود و باید کلید تازه بسازید.
احراز هویت
کلید را به‌صورت توکن Bearer بفرستید:
curl https://a.bezanbecard.com/v1/account \
-H "Authorization: Bearer sk_test_…"احراز هویت HTTP Basic هم کار می‌کند؛ کلید را نام کاربری بگذارید و رمز را خالی (curl -u sk_test_…:). درخواست بدون کلید api_key_missing، کلید ناشناخته api_key_invalid و کلید باطل‌شده api_key_revoked می‌گیرد.
کلیدهای محدود
کلید محدود برای هر منبع دسترسی‌اش را مشخص می‌کند: account، payments، receipts، deposits، payment_links، customers، events، webhook_endpoints، cards و devices. دسترسی write شامل read هم هست. درخواستی بیرون از این دسترسی با permission_denied رد می‌شود. فرستادن رسید هم payments و هم receipts را با write می‌خواهد و expand[]=receipts دسترسی read روی receipts را.
افزونه‌های فروشگاهی همین‌طور کار می‌کنند: وصل کردن افزونه یک کلید محدود می‌سازد که payments، payment_links و customers را write و events را read دارد و نه چیز دیگری.
تعویض کلید
اگر کلید ممکن است لو رفته باشد یا کسی که آن را می‌دانست از تیم رفته، از ردیف همان کلید در توسعه‌دهندگان ← کلیدهای API آن را تعویض کنید. تعویض یک کلید تازه می‌سازد و کلید قبلی را تا چند ساعتی که خودتان انتخاب می‌کنید فعال نگه می‌دارد: از ۰ (همین حالا قطع شود) تا ۱۶۸ ساعت (یک هفته)، به‌طور پیش‌فرض ۲۴ ساعت. این‌طور می‌توانید کلید تازه را بدون قطعی جایگزین کنید. بعد از آن، کلید قبلی api_key_expired می‌گیرد. باطل کردن، کلید را همان لحظه از کار می‌اندازد.
نسخه‌ها
API با تاریخ نسخه‌بندی می‌شود. با هدر Bezanbecard-Version: 2026-10-01 نسخهٔ یک درخواست را ثابت کنید؛ بدون آن، نسخهٔ خود کلید به کار می‌رود. نسخهٔ ناشناخته api_version_invalid می‌گیرد. کتابخانه‌های رسمی نسخه‌ای را که برایش نوشته شده‌اند می‌فرستند.
سقف درخواست
هر کلید در حالت واقعی ۱۰۰ و در حالت آزمایشی ۲۵ درخواست در ثانیه می‌تواند بفرستد. بیش از آن، API پاسخ 429 با هدر Retry-After می‌دهد (کد rate_limit). کتابخانه‌های رسمی صبر می‌کنند و خودشان دوباره تلاش می‌کنند.
پرداخت واقعی و وضعیت حساب
پرداخت واقعی به حساب فعال نیاز دارد. حسابی که اپراتور محدودش کرده، یا به خاطر صورت‌حساب پرداخت‌نشده محدود شده، نمی‌تواند پرداخت واقعی بسازد (account_restricted) ولی بقیهٔ کارها انجام می‌شود؛ کلیدهای حساب تعلیق‌شده هم رد می‌شوند (account_suspended). GET /v1/account وضعیت حساب و امکانات طرح را نشان می‌دهد.