REST API

REST API نسین هر کاری را که پنل انجام می‌دهد پشتیبانی می‌کند: دامنه‌ها، رکوردهای دی‌ان‌اس، قوانین لبه، گواهی‌ها، کش، آمار، آپ‌تایم و اشتراک‌گذاری.

آدرس پایه: https://api.nsin.cloud
احراز هویت: یک کلید API
مرجع کامل نقاط پایانی: REST API Reference — همه‌ی نقاط پایانی با پارامترها و اسکیمای درخواست و پاسخ، تولیدشده از همان سند OpenAPI که خود API سرویس می‌دهد.

سند ماشین‌خوان OpenAPI در /docs/openapi.yaml در دسترس است — تولیدکننده‌ی کلاینت، Postman یا IDE خود را مستقیم به همان اشاره دهید.

احراز هویت

کلید را در هر هدری که برای کلاینت شما مناسب‌تر است بفرستید؛ هر دو یکسان‌اند:

curl -H "Authorization: Bearer nsin_your_key_here" https://api.nsin.cloud/domains/
curl -H "X-Api-Key: nsin_your_key_here"            https://api.nsin.cloud/domains/

کلید به‌جای شما عمل می‌کند: دامنه‌های خودتان و دامنه‌های اشتراکی دقیقاً مثل پنل در دسترس‌اند و نقش‌های دامنه هم اعمال می‌شوند. کلید فقط‌خواندنی تنها GET، HEAD و OPTIONS می‌فرستد.

قراردادها

{domain} نام دامنه است. هر بخشی از مسیر که به‌صورت {domain} نوشته شده، نام دامنه — example.com — را می‌گیرد، نه شناسه‌ی عددی:

curl -H "X-Api-Key: $NSIN_KEY" \
  https://api.nsin.cloud/domains/example.com/records/

اسلش پایانی مهم است. مسیرها را دقیقاً همان‌طور که مرجع نوشته استفاده کنید (/domains/ و /domains/{domain}/records/ اسلش دارند، /domains/{domain} ندارد).

خطاها یکنواخت‌اند. هر خطا به شکل {"error": "پیام قابل خواندن"} است.

زمان‌ها با فرمت RFC 3339 و به UTC، و حجم‌ها بر حسب بایت‌اند.

کاری که کلید نمی‌تواند بکند

بعضی سطوح برای هر کلیدی 403 برمی‌گردانند تا کلید لو‌رفته هرگز نتواند حساب را تصاحب کند یا پول خرج کند:

سطح	چرا
`/users/**`	پروفایل، رمز، نشست‌ها و مدیریت کلیدها. کلید نمی‌تواند کلید بسازد یا باطل کند.
`/auth/**`	ورود، ثبت‌نام، رمز یک‌بارمصرف.
`/billing/**`	فهرست پلن‌ها و تنظیمات صورت‌حساب.
`/admin/**`	سطح مدیریتی.
`POST /wallet/topup`	جابه‌جایی پول.
`POST …/subscriptions/purchase`، `/switch`، `/auto-renew`	جابه‌جایی پول.

خواندن اشتراک، قابلیت‌ها، مصرف ترافیک، فاکتورها و کیف پول مجاز است — فقط نوشتن‌های مالی مسدودند.

محدودیت نرخ

به‌صورت پیش‌فرض ۳۰۰ درخواست در دقیقه برای هر کلید. با عبور از آن 429 همراه با {"error": "rate limit exceeded"} می‌گیرید. ترافیک پنل (مرورگر) جداگانه محدود می‌شود و از سهم کلید شما کم نمی‌کند.

کدهای وضعیت

کد	معنی
`400`	ورودی نامعتبر.
`401`	کلید موجود نیست، نامعتبر است یا باطل شده.
`403`	کلید فقط‌خواندنی روی عملیات نوشتن، نقش ناکافی، سطح مسدود، یا قابلیتی که در پلن نیست.
`404`	پیدا نشد — یا برای شما قابل مشاهده نیست.
`409`	تعارض؛ مثلاً دامنه قبلاً ثبت شده یا غیرفعال است.
`429`	عبور از محدودیت نرخ.

چه چیزهایی در مرجع هست

گروه	شامل
Domains	افزودن، پیکربندی، تأیید، فعال‌سازی و حذف دامنه؛ حالت توسعه‌دهنده؛ بررسی نیم‌سرورها.
DNS Records	CRUD رکوردها، به‌روزرسانی/حذف دسته‌ای، اسکن زون و ورود از BIND.
SSL	وضعیت گواهی، صدور دستی، آپلود و بررسی گواهی سفارشی.
Rules	هر دوازده نوع قانون، هرکدام با همان هفت نقطه‌ی پایانی (فهرست، ساخت، ترتیب، دریافت، به‌روزرسانی، حذف، روشن/خاموش).
Cache	آمار فضا، مرور آیتم‌های ذخیره‌شده، پاک‌سازی و تازه‌سازی.
Analytics	ترافیک، بازدیدکننده، پهنای باند، کش، کدهای وضعیت، جغرافیا، لاگ‌ها، لاگ WAF و کوئری دلخواه.
Uptime	رخدادهای قطعی، وضعیت زنده‌ی هر میزبان، تنظیمات تشخیص.
Recommendations	چک‌لیست پیشنهادها و نادیده‌گرفتن‌ها.
Sharing	اعضا، نقش‌ها، دعوت‌نامه‌ها.
Billing	خواندن اشتراک‌ها، قابلیت‌ها، مصرف ترافیک، فاکتورها و کیف پول.
Support	تیکت‌ها و پاسخ‌ها.

اولین درخواست

export NSIN_KEY=nsin_your_key_here

# فهرست دامنه‌های شما
curl -H "X-Api-Key: $NSIN_KEY" https://api.nsin.cloud/domains/

# ساخت یک رکورد A پراکسی‌شده
curl -X POST -H "X-Api-Key: $NSIN_KEY" -H "Content-Type: application/json" \
  -d '{"name":"www","type":"A","destination":"203.0.113.10","proxied":true}' \
  https://api.nsin.cloud/domains/example.com/records/

# پاک‌سازی کش دامنه
curl -X DELETE -H "X-Api-Key: $NSIN_KEY" \
  https://api.nsin.cloud/domains/example.com/cache/