این مستندات برای چیست؟
این صفحه دقیقا نشان میدهد Cloud SMS OTP را چگونه در رسانکس تنظیم کنید و از سیستم خودتان به Endpoint رسمی درخواست بزنید.
مسیرهای دقیق داخل پنل
مسیرها را به همین ترتیب انجام دهید:
- تنظیم سرویسدهنده پیامکی:
/app/sms-otp/providers - تنظیم صف پشتیبان:
/app/sms-otp/routing - دریافت API Key وبسرویس:
/app/webservice - مشاهده مستندات ماژول در پنل:
/app/webservice/sms_otp - بررسی گزارش ارسال:
/app/sms-otp/logs
پیشنیازهای الزامی
- ماژول
sms_otpبرای کسبوکار فعال باشد. - ماژول
webserviceبرای کسبوکار فعال باشد. - حداقل یک سرویسدهنده پیامکی تنظیم و فعال شده باشد.
- برای سرویسدهنده فعال، نام الگوی OTP ثبت شده باشد.
- API Key معتبر از بخش وبسرویس دریافت شده باشد.
Endpoint رسمی ارسال
Method:POSTPath:/v1/sms-otp/sendFull URL (مثال):https://api.rasanex.com/v1/sms-otp/send
Headerهای لازم
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
بدنه درخواست
فیلدها:
phoneاجباری: شماره مقصدcodeاختیاری: کد OTPparamsاختیاری: پارامترهای پویاoptions.idempotency_keyاختیاری: جلوگیری از ارسال تکراریtenant_idاختیاری: فقط در سناریوی توکن چندکسبوکاری
نکته مهم: در این API باید حداقل یکی از code یا params را بفرستید. اگر هیچکدام ارسال نشود، خطای 422 میگیرید.
نمونه استاندارد (پیشنهادی)
{
"phone": "09120000000",
"code": "4821",
"options": {
"idempotency_key": "sms-otp-login-20260411-01"
}
}
نمونه با params
{
"phone": "09120000000",
"params": {
"token": "4821",
"code": "4821"
},
"options": {
"idempotency_key": "sms-otp-login-20260411-02"
}
}
پاسخ موفق
{
"tracking_id": "f0e9c32b62e24b78a3e0a9c3f2d14e88",
"status": "accepted"
}
خطاهای رایج و اقدام اصلاحی
401 - توکن نامعتبر
{
"message": "Unauthorized. Invalid bearer token."
}
اقدام: Authorization را با Bearer و API Key معتبر دوباره ارسال کنید.
403 - ماژول غیرفعال یا دسترسی ناکافی
{
"error": "Webservice module must be enabled to use sms_otp webservice APIs.",
"module_id": "webservice",
"code": "module_disabled"
}
اقدام: در پنل، فعال بودن sms_otp و webservice را بررسی کنید.
422 - بدنه نامعتبر (نمونه ۱: خطای ولیدیشن)
{
"message": "The phone field is required.",
"errors": {
"phone": [
"The phone field is required."
]
}
}
422 - بدنه نامعتبر (نمونه ۲: خطای قواعد ماژول)
{
"message": "Either code or params is required."
}
اقدام: فیلد phone را همیشه بفرستید و علاوه بر آن حداقل یکی از code یا params را ارسال کنید.
نمونه کدهای آماده
cURL
curl --request POST \
--url https://api.rasanex.com/v1/sms-otp/send \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"phone": "09120000000",
"code": "4821",
"options": {
"idempotency_key": "sms-otp-login-20260411-01"
}
}'
JavaScript
const response = await fetch('https://api.rasanex.com/v1/sms-otp/send', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
phone: '09120000000',
code: '4821',
options: {
idempotency_key: 'sms-otp-login-20260411-01'
}
})
})
const data = await response.json()
console.log(data)
PHP
<?php
$payload = [
'phone' => '09120000000',
'code' => '4821',
'options' => [
'idempotency_key' => 'sms-otp-login-20260411-01',
],
];
$ch = curl_init('https://api.rasanex.com/v1/sms-otp/send');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_API_KEY',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
]);
$result = curl_exec($ch);
curl_close($ch);
echo $result;
Python
import requests
url = 'https://api.rasanex.com/v1/sms-otp/send'
headers = {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
}
payload = {
'phone': '09120000000',
'code': '4821',
'options': {
'idempotency_key': 'sms-otp-login-20260411-01'
}
}
response = requests.post(url, json=payload, headers=headers, timeout=20)
print(response.status_code)
print(response.json())
روال پیشنهادی برای جلوگیری از خطا
- ابتدا در پنل، سرویسدهنده و نام الگو را کامل تنظیم کنید.
- سپس در
/app/sms-otp/routingصف پشتیبان را ذخیره کنید. - بعد API Key را از
/app/webserviceبگیرید. - در سیستم خودتان هنگام
retryهمانidempotency_keyرا تکرار کنید. - نتیجه ارسال را با
tracking_idدر/app/sms-otp/logsبررسی کنید.
اگر این ترتیب رعایت شود، خطاهای عملیاتی بهصورت محسوسی کمتر میشود.