سندباکس

قواعد سندباکس

سندباکس برای تست اتصال محصول به API است؛ رفتار API واقعی را شبیه سازی می کند، اما هیچ پیام واقعی ارسال نمی شود.

• ۱
  کلید تست لازم استفقط کلیدهایی با پیشوند navidaa_test_ روی مسیرهای سندباکس پذیرفته می شوند.
• ۲
  ارسال واقعی انجام نمی شودهیچ پیام رسان یا پیامکی صدا زده نمی شود و کاربر واقعی کدی دریافت نمی کند.
• ۳
  کد تایید ثابت استکد صحیح همیشه 123456 است؛ هر کد دیگر مثل جریان واقعی نتیجه ناموفق می دهد.
• ۴
  تنظیمات ارسال لازم نیستاتصال حساب، ترتیب ارسال و اطلاعات اتصال سرویس دهنده برای سندباکس لازم نیستند.
• ۵
  هزینه و سهمیه مصرف نمی شودتست های سندباکس در صورتحساب و سهمیه ارسال واقعی حساب نمی شوند.
• ۶
  ورودی ها همچنان بررسی می شوندشماره، UUID، کد و ساختار بدنه درخواست اعتبارسنجی می شوند تا خطاهای اتصال زودتر دیده شوند.
• ۷
  کلید live پذیرفته نمی شوداگر کلید live روی سندباکس استفاده شود، پاسخ live_key_not_allowed برمی گردد.

ارسال سندباکس

ارسال سندباکس یک verification واقعی در سیستم می سازد، اما مسیر ارسال فقط شبیه سازی می شود. تفاوت اصلی با ارسال live این است که Idempotency-Key، اطلاعات اتصال سرویس دهنده و ترتیب ارسال لازم نیستند.

curl -X POST https://api.navidaa.ir/v1/sandbox/otp/send \
  -H "Authorization: Bearer navidaa_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"phone":"09123456789","channels":["rubika","sms"]}'

import requests

response = requests.post(
    "https://api.navidaa.ir/v1/sandbox/otp/send",
    headers={
        "Authorization": "Bearer navidaa_test_xxx",
        "Content-Type": "application/json",
    },
    json={"phone": "09123456789", "channels": ["rubika", "sms"]},
    timeout=10,
)
print(response.json())

{
  "verification_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "current_attempt_channel": {
    "type": "messenger",
    "provider": "rubika",
    "credential_id": null,
    "label": "Sandbox (rubika)"
  },
  "expires_in": 300
}

تایید سندباکس

تایید سندباکس همان شکل تایید live را دارد، اما کد صحیح همیشه 123456 است. این باعث می شود تست های خودکار بدون دریافت پیام واقعی قابل تکرار باشند.

curl -X POST https://api.navidaa.ir/v1/sandbox/otp/verify \
  -H "Authorization: Bearer navidaa_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"verification_id":"550e8400-e29b-41d4-a716-446655440000","code":"123456"}'

import requests

response = requests.post(
    "https://api.navidaa.ir/v1/sandbox/otp/verify",
    headers={
        "Authorization": "Bearer navidaa_test_xxx",
        "Content-Type": "application/json",
    },
    json={
        "verification_id": "550e8400-e29b-41d4-a716-446655440000",
        "code": "123456",
    },
    timeout=10,
)
print(response.json())

{
  "verified": true,
  "reason": "ok"
}

{
  "verified": false,
  "reason": "invalid_code"
}

اگر verification برای حساب تست پیدا نشود، پاسخ 404 not_found برمی گردد. اگر کلید live روی این مسیر استفاده شود، پاسخ live_key_not_allowed برمی گردد.

وضعیت سندباکس

وضعیت سندباکس برای بررسی چرخه ارسال و تایید استفاده می شود. این پاسخ از نسخه live سبک تر است و فیلدهایی مثل attempts، remaining_seconds و current_channel_status ندارد.

curl https://api.navidaa.ir/v1/sandbox/otp/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer navidaa_test_xxx"

import requests

response = requests.get(
    "https://api.navidaa.ir/v1/sandbox/otp/550e8400-e29b-41d4-a716-446655440000",
    headers={"Authorization": "Bearer navidaa_test_xxx"},
    timeout=10,
)
print(response.json())

{
  "verification_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "phone": "+989123456789",
  "current_channel": {
    "type": "messenger",
    "provider": "rubika",
    "credential_id": null,
    "label": "Sandbox (rubika)"
  },
  "expires_at": "2026-05-24T10:35:00Z",
  "verified_at": null
}

{
  "verification_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "verified",
  "phone": "+989123456789",
  "current_channel": {
    "type": "messenger",
    "provider": "rubika",
    "credential_id": null,
    "label": "Sandbox (rubika)"
  },
  "expires_at": "2026-05-24T10:35:00Z",
  "verified_at": "2026-05-24T10:31:10Z"
}