مرجع API نمایندگی دامنه

۱آغاز به کار

1. حسابِ شما باید به‌عنوان نمایندهٔ دامنه فعال شده باشد. تا پیش از آن، نقاطِ پایانیِ دامنه پاسخِ مجازنبودن می‌دهند.
2. در پنل کاربری، بخش امنیت، یک توکن API صادر کنید و دامنهٔ دسترسیِ آن را به کمترین چیزی که یکپارچه‌سازی‌تان لازم دارد محدود کنید.
3. نشانی IP خروجیِ سرورِ خودتان را در فهرستِ مجازِ همان توکن ثبت کنید. توکنِ بدونِ محدودیتِ IP از هر نقطه‌ای قابلِ استفاده است.
4. حساب را شارژ کنید. ثبت و تمدید در لحظهٔ فراخوانی از اعتبار تسویه می‌شوند و صورت‌حسابِ پس از مصرف وجود ندارد.
5. فراخوانیِ آزمایشی به نقطهٔ پایانیِ سلامت بزنید و سطح و اعتبارِ برگشتی را با پنل مقایسه کنید.

۲احراز هویت و دامنهٔ دسترسی

احراز هویت با توکنِ حامل در هدرِ Authorization انجام می‌شود. نشست، کوکی و CSRF در کار نیست؛ هر درخواست مستقل و بی‌حالت است. توکن نباید در نشانیِ URL، پارامترِ پرس‌وجو یا کدِ سمتِ مرورگر قرار بگیرد، چون در لاگِ سرور، لاگِ شبکهٔ توزیعِ محتوا و تاریخچهٔ مرورگر ثبت می‌شود.

curl -H "Authorization: Bearer sn_xxxxxxxx" \
     https://servernet.cloud/api/v1/ping

دامنه‌های دسترسی

دسترسیِ نوشتن به‌طور ضمنی شاملِ خواندن است؛ عکسِ آن هرگز برقرار نیست. توصیهٔ ما صدورِ توکنِ جداگانه به‌ازای هر محیط است — یکی فقط‌خواندنی برای گزارش‌گیری، یکی نوشتنی و مقیدشده به IP برای سرورِ صورت‌حساب. توکنِ لورفتهٔ فقط‌خواندنی هیچ هزینه‌ای تولید نمی‌کند.

۳قرارداد پاسخ

هر پاسخ یک پوششِ JSON با شکلِ ثابت دارد. منطقِ شرطیِ سرویس‌گیرنده باید روی شناسهٔ ماشین‌خوانِ error بنشیند، نه روی متنِ message. متن قابلِ بومی‌سازی و ویرایش است و بخشی از قراردادِ پایدار نیست؛ شناسه‌ها بخشی از قرارداد نسخهٔ ۱ هستند و تا انتشارِ نسخهٔ بعدی حذف یا تغییرِ معنا نمی‌دهند.

{"ok": true,  "data": { ... }}
{"ok": false, "error": "insufficient_credit", "message": "..."}

۴نقاط پایانی

استعلام موجودی و قیمت

POST https://servernet.cloud/api/v1/domains/check
{"domain": "example.com", "tlds": ["com", "net"]}

{"ok": true, "data": [{
  "domain": "example.com", "state": "free", "available": true,
  "currency": "IRT",
  "price": {"register": 1150000, "renew": 1250000, "retail": 1320000},
  "discount_pct": 12.88, "price_floored": false
}]}

پرچمِ price_floored با مقدارِ درست یعنی تخفیفِ سطحِ شما روی آن پسوند به‌طور کامل اعمال نشده، چون قیمتِ حاصل به کفِ حاشیهٔ ما رسیده است. این وضعیت پنهان نمی‌شود و در بخشِ قیمت‌گذاری کامل توضیح داده شده.

ثبت دامنه

POST https://servernet.cloud/api/v1/domains
Idempotency-Key: your-order-12345
{"domain": "example.com", "years": 1,
 "nameservers": ["ns1.you.com", "ns2.you.com"]}

{"ok": true, "data": {
  "domain": "example.com", "status": "pending",
  "order_state": "registered", "registrant": "reseller",
  "charged": 1265000, "currency": "IRT"
}}

۵یکتاسازی و تلاش دوباره

سرور درخواستِ بدونِ هدرِ Idempotency-Key را هم می‌پذیرد، ولی در آن حالت **هیچ محافظتی در برابرِ تکرار وجود ندارد**؛ بنابراین ارسالِ آن روی هر عملیاتِ پولی شرطِ درستیِ هر یکپارچه‌سازی است. کلید حداکثر ۸۰ نویسه است و پیش از انجامِ کار روی یک ایندکسِ یکتای پایگاه‌داده تصاحب می‌شود، پس دو درخواستِ هم‌زمان با یک کلید هرگز به دو تراکنشِ مالی منجر نمی‌شوند. پاسخِ بازپخش‌شده از نظرِ محتوا با پاسخِ اصلی یکسان است و پرچمِ replayed دارد. اگر تلاشِ اول با خطا تمام شود کلید آزاد می‌شود — یکتاسازی یعنی «یک کار دو بار انجام نشود»، نه «یک خطا تا ابد تکرار شود».

sha256("renew|example.com|2027-01-01|1")

برای تلاشِ دوباره از عقب‌نشینیِ نمایی با پراکندگیِ تصادفی استفاده کنید و همان کلید را نگه دارید؛ کلیدِ تازه در تلاشِ دوباره کلِ محافظت را خنثی می‌کند. ماژول‌های رسمیِ ما این کلید را خودشان می‌سازند و نگه می‌دارند.

۶شناسه‌های خطا

۷قیمت‌گذاری و سطح‌بندی

قیمتی که API برمی‌گرداند بهایِ خریدِ شماست: قیمتِ خرده‌فروشی پس از کسرِ تخفیفِ سطح. سطح از دو سنجه به‌طور هم‌زمان مشتق می‌شود — حجمِ خریدِ دوازده ماهِ گذشته و تعدادِ دامنهٔ فعالِ پرتفویتان — و روزانه بازبینی می‌گردد. قیمتِ برگشتی از استعلام تضمینِ اجرا نیست؛ مرجعِ تسویه همان استعلامِ تازه‌ای است که در لحظهٔ سفارش انجام می‌شود.

• ارتقا آنی است و در همان لحظه‌ای اعمال می‌شود که حجمِ خرید از آستانه عبور کند.
• تنزل تدریجی است: افتِ حجم ابتدا مهلت می‌گیرد و سپس حداکثر یک پله اعمال می‌شود. این عدمِ تقارن عمدی است.
• سطحِ جاری، فاصله تا آستانهٔ بعدی و تاریخِ آخرین بازبینی در پنلِ نمایندگی و در پاسخِ نقطهٔ پایانیِ سلامت در دسترس است.

کفِ حاشیه

حاشیهٔ سودِ ما به‌ازای هر پسوند متفاوت است و از ساختارِ هزینهٔ همان رجیستری می‌آید. روی پسوندهای کم‌حاشیه — که در عمل پرتقاضاترین‌ها هم هستند — تخفیفِ سطحِ شما تنها تا کفی اعمال می‌شود که بالای بهایِ تمام‌شدهٔ ما بماند. هر جا این کف فعال شود، پاسخِ API پرچمِ price_floored را درست می‌گذارد و درصدِ مؤثرِ اعمال‌شده را جداگانه برمی‌گرداند.

افشای این محدودیت یک تصمیمِ آگاهانه است. کفِ اعلام‌نشده اختلافی می‌سازد که سرویس‌گیرنده نمی‌تواند حسابش را ببندد و تنها راهِ کشفش مغایرت‌گیریِ دستیِ فاکتورهاست — یعنی همان چیزی که یک برنامهٔ وفاداری قرار بود از بین ببرد.

۸سهمیه‌ها و محدودیت‌ها

عبور از سقفِ نرخ پاسخِ ۴۲۹ می‌گیرد و باید با عقب‌نشینی مدیریت شود، نه با فراخوانیِ موازیِ بیشتر. افزون بر این، هر حساب یک سقفِ خرجِ روزانه دارد که در پنلِ نمایندگی قابلِ تنظیمِ رو به پایین است. این سقف یک محافظِ محدودکنندهٔ خسارت است: در سناریوی افشای توکن، بیشینهٔ زیانِ ممکن پیش از آنکه کسی متوجه شود به همان عدد محدود می‌مانَد. توصیه می‌شود آن را روی چند برابرِ گردشِ روزانهٔ واقعی‌تان تنظیم کنید، نه بیشتر.

۹عملیاتِ عمداً خارج از رابط

موارد زیر پیاده‌سازی‌نشده نیستند؛ آگاهانه از سطحِ دسترسیِ توکن کنار گذاشته شده‌اند. معیار روشن است: عملیاتی که با یک توکنِ افشاشده کنترلِ دامنهٔ مشتریِ نهایی را منتقل می‌کند، تنها با احرازِ انسانی در پنل انجام می‌شود. قفلِ انتقال از رابط فقط قابلِ روشن‌شدن است — عملیاتی که محافظت اضافه می‌کند بی‌خطر است، عملیاتی که محافظت را برمی‌دارد نیست.

۱۰ماژول‌های رسمی

دو پیاده‌سازیِ مرجع نگهداری می‌شوند که همین رابط را مصرف می‌کنند و هر دو از پنلِ نمایندگی قابلِ دریافت‌اند. اگر پشتهٔ شما یکی از این دو است، ماژول را به یکپارچه‌سازیِ دست‌نویس ترجیح دهید: محافظ‌های مالی از پیش در آنها پیاده شده‌اند.

۱۱نقشهٔ راه

موارد زیر برنامه‌ریزی شده‌اند ولی هنوز در رابطِ نسخهٔ ۱ منتشر نشده‌اند. تا لحظهٔ انتشار، فراخوانیِ نقطهٔ پایانیِ متناظر پاسخِ ۴۰۴ می‌گیرد. افزودنِ نقطهٔ پایانیِ تازه یک تغییرِ سازگار است و نسخهٔ رابط را بالا نمی‌برد؛ سرویس‌گیرندهٔ شما نباید با دیدنِ فیلدِ ناشناخته در پاسخ خطا بدهد.

داشبورد نسخهٔ PDF