رفتن به محتوای صفحه

مستندات Cloud SMS OTP رسانکس

راهنمای رسمی راه‌اندازی و استفاده از Cloud SMS OTP در رسانکس با مسیرهای دقیق پنل، Endpoint واقعی، نمونه درخواست و مدیریت خطا.

منتشرشده در رسانکس
شروع مطالعه

تصویر مستندات Cloud SMS OTP رسانکس

این مستندات برای چیست؟

این صفحه دقیقا نشان می‌دهد Cloud SMS OTP را چگونه در رسانکس تنظیم کنید و از سیستم خودتان به Endpoint رسمی درخواست بزنید.

مسیرهای دقیق داخل پنل

مسیرها را به همین ترتیب انجام دهید:

  1. تنظیم سرویس‌دهنده پیامکی: /app/sms-otp/providers
  2. تنظیم صف پشتیبان: /app/sms-otp/routing
  3. دریافت API Key وب‌سرویس: /app/webservice
  4. مشاهده مستندات ماژول در پنل: /app/webservice/sms_otp
  5. بررسی گزارش ارسال: /app/sms-otp/logs

پیش‌نیازهای الزامی

  1. ماژول sms_otp برای کسب‌وکار فعال باشد.
  2. ماژول webservice برای کسب‌وکار فعال باشد.
  3. حداقل یک سرویس‌دهنده پیامکی تنظیم و فعال شده باشد.
  4. برای سرویس‌دهنده فعال، نام الگوی OTP ثبت شده باشد.
  5. API Key معتبر از بخش وب‌سرویس دریافت شده باشد.

Endpoint رسمی ارسال

  • Method: POST
  • Path: /v1/sms-otp/send
  • Full URL (مثال): https://api.rasanex.com/v1/sms-otp/send

Headerهای لازم

headers.http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

بدنه درخواست

فیلدها:

  • phone اجباری: شماره مقصد
  • code اختیاری: کد OTP
  • params اختیاری: پارامترهای پویا
  • options.idempotency_key اختیاری: جلوگیری از ارسال تکراری
  • tenant_id اختیاری: فقط در سناریوی توکن چندکسب‌وکاری

نکته مهم: در این API باید حداقل یکی از code یا params را بفرستید. اگر هیچ‌کدام ارسال نشود، خطای 422 می‌گیرید.

نمونه استاندارد (پیشنهادی)

request.json
{
  "phone": "09120000000",
  "code": "4821",
  "options": {
    "idempotency_key": "sms-otp-login-20260411-01"
  }
}

نمونه با params

request-with-params.json
{
  "phone": "09120000000",
  "params": {
    "token": "4821",
    "code": "4821"
  },
  "options": {
    "idempotency_key": "sms-otp-login-20260411-02"
  }
}

پاسخ موفق

202-accepted.json
{
  "tracking_id": "f0e9c32b62e24b78a3e0a9c3f2d14e88",
  "status": "accepted"
}

خطاهای رایج و اقدام اصلاحی

401 - توکن نامعتبر

401.json
{
  "message": "Unauthorized. Invalid bearer token."
}

اقدام: Authorization را با Bearer و API Key معتبر دوباره ارسال کنید.

403 - ماژول غیرفعال یا دسترسی ناکافی

403.json
{
  "error": "Webservice module must be enabled to use sms_otp webservice APIs.",
  "module_id": "webservice",
  "code": "module_disabled"
}

اقدام: در پنل، فعال بودن sms_otp و webservice را بررسی کنید.

422 - بدنه نامعتبر (نمونه ۱: خطای ولیدیشن)

422-validation.json
{
  "message": "The phone field is required.",
  "errors": {
    "phone": [
      "The phone field is required."
    ]
  }
}

422 - بدنه نامعتبر (نمونه ۲: خطای قواعد ماژول)

422-business-rule.json
{
  "message": "Either code or params is required."
}

اقدام: فیلد phone را همیشه بفرستید و علاوه بر آن حداقل یکی از code یا params را ارسال کنید.

نمونه کدهای آماده

cURL

send-sms-otp.sh
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

sendSmsOtp.js
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

send_sms_otp.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

send_sms_otp.py
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())

روال پیشنهادی برای جلوگیری از خطا

  1. ابتدا در پنل، سرویس‌دهنده و نام الگو را کامل تنظیم کنید.
  2. سپس در /app/sms-otp/routing صف پشتیبان را ذخیره کنید.
  3. بعد API Key را از /app/webservice بگیرید.
  4. در سیستم خودتان هنگام retry همان idempotency_key را تکرار کنید.
  5. نتیجه ارسال را با tracking_id در /app/sms-otp/logs بررسی کنید.

اگر این ترتیب رعایت شود، خطاهای عملیاتی به‌صورت محسوسی کمتر می‌شود.

قدم بعدی، در پنل شما.

ماژول‌ها، مسیرهای ارسال و گزارش‌ها را از پنل رسانکس مدیریت کنید.

ورود به پنل رسانکس