GET /v1/otp/{verification_id}

وضعیت یا long polling

خواندن وضعیت زنده ارسال، کانال فعلی، زمان باقی مانده و تاریخچه تلاش ها.

چه زمانی poll شود

GEThttps://api.navidaa.ir/v1/otp/{verification_id}

وقتی صفحه محصول نیاز دارد نشان دهد کد در کدام کانال ارسال شده یا مسیر جایگزین به مرحله بعد رفته است، این endpoint مناسب است. در وضعیت queued هر ۵ تا ۱۰ ثانیه poll کافی است. با رسیدن به وضعیت های پایانی، polling متوقف می شود.

فیلدهای پاسخ

فیلد	توضیح
`status`	وضعیت چرخه عمر همان verification.
`current_channel`	آخرین کانالی که تلاش شده، با provider، credential_id و label.
`current_channel_status`	`sent` یعنی ارائه دهنده پیام را پذیرفته؛ `failed` یعنی همان تلاش ارسال شکست خورده است.
`remaining_seconds`	زمان باقی مانده تا مسیر جایگزین بعدی. برای وضعیت پایانی، آخرین کانال یا وضعیت نامعلوم، مقدار null است.
`attempts`	تاریخچه مرتب تلاش های ارسال.

وضعیت ها

pendingفرایند ساخته شده اما هنوز تلاش ارسال ثبت نشده است. این حالت معمولا بسیار کوتاه است.

queuedحداقل یک کانال امتحان شده و فرایند هنوز فعال است.

verifiedکد درست وارد شده و تایید کامل شده است.

failed / lockedارسال به نتیجه نرسیده یا تلاش های اشتباه باعث قفل شدن شده است.

expiredزمان اعتبار تمام شده و کد دیگر قابل تایید نیست.

status	معنا	ادامه کار
`pending`	فرایند تازه ساخته شده و هنوز تلاش ارسال در تاریخچه دیده نمی شود.	کمی بعد دوباره وضعیت خوانده شود.
`queued`	فرایند فعال است؛ کد ارسال شده یا مسیر جایگزین هنوز ادامه دارد.	polling هر ۵ تا ۱۰ ثانیه یا انتظار برای وبهوک کافی است.
`verified`	کد درست وارد شده است.	فرایند موفق تمام شده است.
`failed`	همه مسیرهای ارسال شکست خورده اند.	یک فرایند جدید شروع شود یا تنظیمات ارسال بررسی شود.
`locked`	تعداد تلاش های اشتباه زیاد شده و فرایند قفل شده است.	برای کاربر فرایند جدید ساخته شود.
`expired`	زمان اعتبار verification تمام شده است. اگر فرایند فعال از زمان انقضا گذشته باشد، همین endpoint آن را به شکل موثر expired نشان می دهد.	فرایند جدید ساخته شود.

attempts

کلید attempts در JSON تاریخچه تلاش های ارسال را نشان می دهد. هر عضو این آرایه یک تلاش روی یک کانال است و ترتیب آن با فیلد sequence مشخص می شود.

فیلد	توضیح
`sequence`	شماره تلاش در مسیر ارسال؛ ۱ یعنی اولین کانال.
`channel`	جزئیات کانال و حساب استفاده شده در همان تلاش.
`status`	`sent` یعنی پیام پذیرفته شده؛ `failed` یعنی تلاش ارسال شکست خورده است.
`dispatched_at`	زمان انجام همان تلاش.
`transition_reason`	برای تلاش های قبلی معمولا `timed_out` یا `failed` است. آخرین تلاش معمولا مقدار null دارد.

نمونه پاسخ fallback

{
  "verification_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "phone": "+989123456789",
  "current_channel": {
    "type": "sms",
    "provider": "smsir",
    "credential_id": 12,
    "label": "Primary sms.ir"
  },
  "current_channel_status": "sent",
  "remaining_seconds": null,
  "expires_at": "2026-05-24T10:35:00Z",
  "verified_at": null,
  "attempts": [
    {
      "sequence": 1,
      "channel": {"type": "messenger", "provider": "eitaa", "credential_id": 21, "label": "Eitaa main"},
      "status": "sent",
      "dispatched_at": "2026-05-24T10:30:02Z",
      "transition_reason": "timed_out"
    },
    {
      "sequence": 2,
      "channel": {"type": "sms", "provider": "smsir", "credential_id": 12, "label": "Primary sms.ir"},
      "status": "sent",
      "dispatched_at": "2026-05-24T10:31:02Z",
      "transition_reason": null
    }
  ]
}