سامانه ارسال رمز یک‌بار مصرف (OTP)

سامانه ارسال رمز یکبار مصرف (OTP) از طریق بله راهکاری سریع، امن و مقرون‌به‌صرفه برای کسب‌وکارهایی است که به احراز هویت کاربران خود نیاز دارند. این سرویس امکان ارسال مستقیم OTP از طریق بله را فراهم می‌کند و جایگزینی مناسب برای پیامک است. با استفاده از این روش، می‌توانید رمزهای یکبار مصرف را سریع‌تر، مطمئن‌تر برای مشتریان خود ارسال کنید.
برای ثبت‌نام و تهیه اشتراک جهت استفاده از این سامانه، ابتدا باید وارد سامانه درگاه بله (opens in a new tab) شوید. پس از تهیه اشتراک و دریافت رمز عبور و نام کاربری، قادر خواهید بود از سرویس‌های ارسال رمز یکبار مصرف استفاده کنید.

سرویس احراز هویت

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

آدرس API: /auth/token

متد: POST

این API به کلاینت‌ها این امکان را می‌دهد که با استفاده از اعتبارسنجی کلاینت (شناسه کلاینت و رمز عبور کلاینت) احراز هویت کنند و توکن دسترسی برای درخواست‌های بعدی دریافت کنند. پارامتر های بدنه این درخواست باید به شکل form-data به سمت سرور ار

URL:

POST http://safir.bale.ai/api/v2/auth/token

هدرها

• Content-Type: application/x-www-form-urlencoded

Curl

curl -X POST "https://safir.bale.ai/api/v2/auth/token" \
     -d "grant_type=client_credentials" \
     -d "client_secret={password}}" \
     -d "scope=read" \
     -d "client_id={username}"

پارامترهای بدنه درخواست:

پاسخ

موفقیت آمیز:

در صورت موفقیت در احراز هویت، پاسخ شامل اطلاعات زیر خواهد بود:

نمونه پاسخ موفقیت آمیز:

{
  "access_token": "eyadffdasasdf....asdfadf",
  "expires_in": 43200,
  "scope": "read",
  "token_type": "bearer"
}

خطاها

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

1. خطای احراز هویت نامعتبر:

در صورتی که شناسه کلاینت یا رمز عبور اشتباه باشد، پاسخ به صورت زیر خواهد بود:

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

کد وضعیت: 401 Unauthorized

2. خطای پارامترهای ناقص یا اشتباه:

اگر برخی از پارامترهای ضروری درخواست ارسال نشده باشند یا اشتباه باشند، پاسخ به صورت زیر خواهد بود:

"Failed to Parse Request"

کد وضعیت: 400 Bad Request

3. خطای سرور:

در صورت بروز مشکل داخلی در سرور، پاسخ به صورت زیر خواهد بود:

{"type": 1, "code": 2, "message": "internal server error occurred"}

کد وضعیت: 500 Internal Server Error

نکات مهم

• برای دریافت توکن دسترسی، حتماً باید شناسه کلاینت (client_id) و رمز عبور کلاینت (client_secret) معتبر و صحیح باشند.
• توکن دسترسی که دریافت می‌کنید تنها برای مدت زمان مشخصی معتبر است و پس از آن باید دوباره درخواست توکن جدید ارسال کنید.

سرویس ارسال رمز یکبار مصرف

آدرس API: /send_otp

این API به شما این امکان را می‌دهد که یک رمز یکبار مصرف (OTP) به شماره تلفن کاربر ارسال کنید. برای استفاده از این سرویس، ابتدا باید از طریق سرویس احراز هویت توکن دسترسی معتبر دریافت کرده باشید و سپس این توکن را در هدر درخواست ارسال کنید.

درخواست

URL:

POST https://safir.bale.ai/api/v2/send_otp

Curl:

curl -X POST "https://safir.bale.ai/api/v2/send_otp" \
     -H "Authorization: Bearer {access_token}" \
     -H "Content-Type: application/json" \
     -d '{
           "phone": "989123456789",
           "otp": 111111
         }'

هدرها

• Authorization: Bearer {access_token}
  (توکن دسترسی باید در هدر درخواست ارسال شود.)

پارامترهای بدنه درخواست:

نمونه درخواست:

{
  "phone": "989123456789",
  "otp": 111111
}

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

همان‌طور که مشاهده می‌کنید، شماره‌ها باید بدون صفر ابتدایی و با پیش‌شماره 98 آغاز شوند تا معتبر باشند.

پاسخ

موفقیت آمیز:

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

نمونه پاسخ موفقیت آمیز:

{
  "balance": 985
}

خطاها

در صورت بروز خطا در درخواست، یکی از کدهای زیر ممکن است به شما بازگردانده شود:

1. خطای شماره تلفن نامعتبر:

اگر شماره تلفن وارد شده نامعتبر باشد، پاسخ به صورت زیر خواهد بود:

{"type": 2, "code": 8, "message": "provided phone number is not valid"}

کد وضعیت: 400 Bad Request

2. خطای کاربر پیدا نشد:

اگر کاربر با شماره تلفن وارد شده در سیستم پیدا نشود، پاسخ به صورت زیر خواهد بود:

{"type": 3, "code": 17, "message": "this phone does not have an account in Bale"}

کد وضعیت: 404 Not Found

3. خطای عدم موجودی کافی:

اگر موجودی حساب برای ارسال OTP کافی نباشد، پاسخ به صورت زیر خواهد بود:

{"type": 2, "code": 20, "message": "payment required"}

کد وضعیت: 402 Payment Required

4. خطای داخلی سرور:

در صورت بروز خطا در سرور هنگام ارسال OTP، پاسخ به صورت زیر خواهد بود:

{"type": 1, "code": 2, "message": "internal server error occurred"}

کد وضعیت: 500 Internal Server Error

محدودیت نرخ (Rate Limit)

برای جلوگیری از ارسال بیش از حد درخواست‌ها و سوءاستفاده از سیستم، محدودیت‌های نرخ (Rate Limit) به شرح زیر اعمال می‌شوند:

۱. محدودیت برای هر شماره تلفن:

• حداکثر ۳۰ درخواست در ساعت مجاز است.

  • اگر تعداد درخواست‌های ارسالی به یک شماره تلفن در مدت یک ساعت بیش از ۳۰ بار شود، در ادامه امکان ارسال رمز یکبار مصرف برای آن شماره میسر نخواهد بود.

  • در این صورت، درخواست‌های بعدی با پاسخ زیر مواجه خواهند شد:

{"type": 2, "code": 18, "message": "rate limit exceeded"}

۱. محدودیت کلی برای هر سازمان:

همچنین برای هر عضو سامانه یک محدودیت کلی هم اعمال شده که موجب میشود هر عضو در دقیقه بتواند ۳۰۰ درخواست ارسال رمز یکبار مصرف ارسال کند.

کنترل Burst Rate:

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

نکات مهم

• برای ارسال OTP، باید توکن دسترسی معتبر (که از سرویس احراز هویت دریافت کرده‌اید) در هدر درخواست ارسال شود.
• کد OTP باید عددی ۳ تا ۸ رقمی و معتبر باشد.
• پس از ارسال OTP، هزینه ارسال از موجودی حساب کسر خواهد شد، بنابراین باید موجودی کافی داشته باشید.
• در صورت موفقیت، پاسخ شامل موجودی باقی‌مانده خواهد بود.