Base URL, Auth Headers, Errors

مبانی و احراز هویت

قواعد مشترک درخواست ها: آدرس پایه، احراز هویت OTP با X-API-Key، احراز هویت مدیریتی با PAT و قالب خطا.

آدرس پایه

آدرس نهایی API برای تولید:

https://api.navidaa.ir

هدر Authorization برای API های مدیریتی

اگر می خواهید حساب نویدا را با API مدیریت کنید، از هدر Authorization استفاده می شود.

برای استفاده بیرونی و کارهای خودکار، روش پیشنهادی PAT است. PAT با پیشوند navidaa_pat_ ساخته می شود و در هدر به شکل زیر ارسال می شود:

Authorization: apikey navidaa_pat_xxxxxxxxxxxxxxxxxxxx

PAT می تواند دسترسی مدیریتی کامل داشته باشد، یا فقط خواندنی باشد. دسترسی فقط خواندنی برای درخواست های GET، HEAD و OPTIONS پذیرفته می شود.

JWT هم با همین هدر و به شکل Authorization: Bearer <jwt> پشتیبانی می شود، اما کاربرد اصلی آن نشست داشبورد و استفاده داخلی نویدا است.

نمونه API مدیریتی

curl "https://api.navidaa.ir/v1/manage/api-keys" \
  -H "Authorization: apikey navidaa_pat_xxxxxxxxxxxxxxxxxxxx"

هدر X-API-Key برای سرویس رمز یکبار مصرف

برای استفاده از سرویس رمز یکبار مصرف، یعنی ارسال کد، تایید کد و خواندن وضعیت، از هدر X-API-Key استفاده کنید. این کلید را از داشبورد، صفحه کلیدهای API می سازید و مقدار کامل آن فقط همان لحظه ساخت نمایش داده می شود.

کلید live با پیشوند navidaa_live_ برای مسیرهای واقعی استفاده می شود: /v1/otp/send، /v1/otp/verify و /v1/otp/{verification_id}.

کلید test با پیشوند navidaa_test_ برای مسیرهای سندباکس استفاده می شود: /v1/sandbox/otp/send، /v1/sandbox/otp/verify و /v1/sandbox/otp/{verification_id}. در سندباکس ارسال واقعی و هزینه وجود ندارد و کد تایید ثابت 123456 است.

نمونه ارسال واقعی

curl -X POST "https://api.navidaa.ir/v1/otp/send" \
  -H "X-API-Key: navidaa_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: login-09123456789-1700000000" \
  -d '{"phone":"09123456789"}'

هدرهای دیگر

هدر	وضعیت	توضیح
`Content-Type`	برای POST ضروری	در درخواست های JSON مقدار آن را `application/json` بفرستید.
`Idempotency-Key`	فقط ارسال live	برای `POST /v1/otp/send` ضروری است. برای هر تلاش منطقی ارسال، یک مقدار یکتا بسازید؛ اگر همان request را به دلیل timeout دوباره می فرستید، همان مقدار قبلی را تکرار کنید.

قالب خطا

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "details": {
      "errors": []
    }
  },
  "request_id": "..."
}

در کدهای قدیمی route ممکن است خطا داخل route به شکل ساده ساخته شود، اما exception handler آن را به همین envelope تبدیل می کند.

کدهای رایج

کد	HTTP	معنا
`unauthenticated`	401	هدر احراز هویت ارسال نشده، نامعتبر، منقضی یا revoke شده است.
`scope_insufficient`	403	نوع token برای endpoint کافی نیست؛ مثلا کلید سرویس روی APIهای مدیریتی یا PAT فقط خواندنی روی عملیات نوشتن.
`test_key_not_allowed`	403	کلید تست روی endpoint live استفاده شده است.
`live_key_not_allowed`	403	کلید live روی endpoint سندباکس استفاده شده است.
`validation_error`	422	بدنه یا path request با schema سازگار نیست.
`quota_exceeded`	429	سهمیه ماهانه پلن رایگان تمام شده است.
`insufficient_balance`	402	موجودی کیف پول برای verification کافی نیست.
`too_many_requests_phone_hour`	429	محدودیت ساعتی همان شماره فعال شده است.
`too_many_requests_phone_day`	429	محدودیت روزانه همان شماره فعال شده است.
`too_many_requests_api_key`	429	محدودیت دقیقه ای کلید API فعال شده است.