POST /v1/otp/send

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

ایجاد یک verification و ارسال کد از مسیر پیش فرض یا مسیر اعلام شده در درخواست.

خلاصه endpoint

POSThttps://api.navidaa.ir/v1/otp/send

این endpoint یک verification می سازد، کد را تولید می کند، کانال اول را برای ارسال امتحان می کند و شناسه verification را برمی گرداند. اگر چند کانال وجود داشته باشد، ادامه مسیر جایگزین در پس زمینه انجام می شود.

برای ارسال live، Idempotency-Key ضروری است. اگر درخواست به دلیل timeout دوباره تکرار شود، استفاده دوباره از همان مقدار قبلی مانع ارسال OTP دوم می شود.

فیلد phone

شماره موبایل ایران در قالب های رایج پذیرفته و در داخل سیستم به E.164 تبدیل می شود.

قالب	نمونه
محلی	`09123456789`
E.164	`+989123456789`
بین المللی با 00	`00989123456789`
ده رقمی	`9123456789`

channels

اگر channels ارسال نشود، ترتیب ذخیره شده در داشبورد استفاده می شود. اگر ارسال شود، فقط برای همان request مسیر ارسال را تعیین می کند.

سه شکل قابل قبول

{
  "phone": "09123456789",
  "channels": "rubika"
}

{
  "phone": "09123456789",
  "channels": ["rubika", "eitaa"]
}

{
  "phone": "09123456789",
  "channels": [
    {"channel": "rubika", "wait": 45},
    {"channel": "eitaa", "sender": "shared", "wait": 45},
    {"channel": "sms", "provider": "smsir", "account_id": 12}
  ]
}

فیلد	ضروری	توضیح
`channel`	بله	یکی از `eitaa`، `bale`، `soroushplus`، `rubika` یا `sms`.
`account_id`	اختیاری	اگر چند حساب از یک کانال دارید، حساب دقیق را مشخص می کند. بدون آن، حساب پیش فرض همان کانال استفاده می شود.
`sender`	اختیاری	برای پلن شروع، مقدار `shared` مسیر اشتراکی نویدا را صراحتا انتخاب می کند. نام ساده مثل `"eitaa"` همیشه به حساب اختصاصی خودتان اشاره دارد.
`provider`	فقط پیامک	برای `channel: "sms"` معتبر است. در نسخه فعلی، حساب های پیامک قابل استفاده از داشبورد روی `smsir` تنظیم می شوند.
`wait`	اختیاری	زمان انتظار همان مرحله قبل از رفتن به کانال بعدی.

زمان انتظار

اولویت زمان انتظار به این شکل است: مقدار پیش فرض سیستم که ۶۰ ثانیه است، سپس channel_timeout در request، و در نهایت wait همان channel. محدوده معتبر برای API از ۴۵ تا ۱۲۰ ثانیه است.

template_id

این فیلد اختیاری است و فقط برای پیام رسان ها کاربرد دارد. اگر ارسال نشود، پیام رسان ها از متن پیش فرض سیستم استفاده می کنند. پیامک از قالب ثبت شده در ارائه دهنده پیامک استفاده می کند.

پاسخ

{
  "verification_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "current_attempt_channel": {
    "type": "messenger",
    "provider": "eitaa",
    "credential_id": 21,
    "label": "Eitaa main"
  },
  "expires_in": 300
}

queued یعنی کانال اول تلاش شده و verification فعال است. failed یعنی همان تلاش اول شکست خورده و کانال دیگری برای ادامه وجود نداشته است.

خطاهای مهم send

کد	معنا
`idempotency_required`	هدر Idempotency-Key ارسال نشده است.
`idempotency_key_conflict`	همان key قبلا با body متفاوت استفاده شده است.
`fallback_order_required`	channels ارسال نشده و routing پیش فرض ذخیره نشده است.
`no_credentials`	هیچ حساب ارسال فعالی وجود ندارد.
`template_not_found`	template_id متعلق به حساب شما نیست یا وجود ندارد.
`invalid_channel`	نام کانال شناخته شده نیست.
`channel_ambiguous`	چند حساب از یک کانال فعال است و پیش فرض یا account_id مشخص نشده است.
`shared_sender_not_allowed`	مسیر اشتراکی فقط برای پلن شروع فعال است.
`shared_sender_unavailable`	برای این پیام‌رسان فرستنده اشتراکی فعال نیست.
`duplicate_channel`	یک کانال یا provider بیش از یک بار در channels آمده است.

نمونه کد

Python

import requests

response = requests.post(
    "https://api.navidaa.ir/v1/otp/send",
    headers={
        "Authorization": "Bearer navidaa_xxx",
        "Content-Type": "application/json",
        "Idempotency-Key": "login-09123456789-1700000000",
    },
    json={
        "phone": "09123456789",
        "channels": [
            {"channel": "rubika", "wait": 45},
            {"channel": "sms", "provider": "smsir"},
        ],
        "channel_timeout": 60,
    },
    timeout=10,
)
response.raise_for_status()
verification_id = response.json()["verification_id"]