این سند به منظور آشنایی با نحوه استفاده از API وب‌آلفا تنظیم گردیده است.

در حال حاضر این API دارای قابلیت‌های زیر است:

• انجام عملیات مرتبط با دامنه‌های نقطه آی‌آر

اصول کلی استفاده

درخواستها و پاسخ آنها به وسیلهٔ پیغامهایی انجام میگیرد که به صورت JSON نگاشته میشوند. در این روش کاربران، درخواستهای خود را بصورت یک JSON ایجاد کرده و آن را به آدرس API مورد نظر ارسال میکند و پاسخی با فرمت JSON نیز دریافت میکنند.

جهت تصدیق شناسه شما توسط سامانه بایستی کلید API که مختص هر کاربر است در Header درخواست و با کلیدی با نام X-Api-Key قرار داده شود.

درخواست

متد ارسال اطلاعات به API بسته به نوع عملیات میتوانید یکی از انواع GET، POST، PUT، PATCH و DELETE باشد.
نکته: در درخواست‌هایی که نیاز به ارسال داده دارند، مقدار Header مربوط به Content-Type بایستی بر روی application/json قرار داده شود.

curl -X GET \
  https://api.webalfa.net/v2/example-request \
  -H 'x-api-key: demo-key'

پاسخ

در صورت موفقیت آمیز بودن عملیات مقدار پارامتر success به صورت true برگردانده خواهد شد. در غیر این صورت مقدار آن false خواهد بود. در صورتی که نیاز باشد اطلاعاتی از جانب API برگردانده شود این اطلاعات در فیلد result قرار داده خواهد شد.

{
 "success": true,
 "result": {
 "version": "1"
 }
}

در صورت موفقیت آمیز نبودن عملیات در پارامتر errors آرایه‌ای که شامل لیستی از خطاهایی است که منجر به لغو عمالیات شده است برگردانده میشود. هر خطا دارای فیلد code جهت مشخص سازی شماره خطا، فیلد message که حاوی متن خطا به زبان انگلیسی و همچنین در صورت نیاز فیلدی با نام extra است که اطلاعاتی تکمیلی در مورد خطای رخ داده شده و دلیل نادرست بودن آن را مشخص میکند.

{
  "success": false,
  "errors": [
    {
      "code": 404,
      "message": "Unrecognized request",
      "extra": {
        "incorrect_parameter": {
          "value": "Incorrect Value",
          "parameter_attribute": "Attribute value",
          "reason": "Reason of problem with the value"
        }
      }
    }
  ]
}

نکته: وجود فیلدهای parameter_attribute و reason در پاسخ خطا ضروری نمیباشد و ممکن است در پاسخ وجود نداشته باشد. در صورت وجود فیلد extra در پاسخ تنها وجود مقدار incorrect_parameter و value در پاسخ قطعی است.

عملیات مرتبط با دامنه‌های نقطه آی‌آر

برای انجام امور مربوط به دامنه‌ها درخواستهای زیر قابل استفاده است.

ثبت

این درخواست برای ثبت یک دامنه جدید انجام میگیرد.

برای ثبت دامین میبایست در قسمت رابطه های مجاز در nic.ir دسترسی به نمایندگان برای شناسه صاحب امتیاز مورد نظر فعال باشد، بعد از ثبت دامنه کاربر میتواند این دسترسی را لغو کنید.

POST https://api.webalfa.net/v2/domains/register

پارامترها

نام	توضیحات	محدودیت
name (string)	نام کامل دامنه	اجباری حداقل طول: ۳ حداکثر طول: ۶۳
period (int)	مدت ثبت	اجباری حداقل و حداکثر طول: ۱ مقادیر مجاز: ۱ و ۵
contacts (array)	شناسه‌های holder، admin، tech و bill دامنه	اجباری حداقل و حداکثر آیتم: ۴
nameservers (array)	نام سرورهای دامنه، هر نام سرور به صورت شیئی متشکل از hostname و در صورت نیاز ip	اجباری حداقل آیتم: ۱ حداکثر آیتم: ۴

نمونه درخواست (cURL)

curl -X POST \
  https://api.webalfa.net/v2/domains/example.ir/register \
  -H 'content-type: application/json' \
  -H 'x-api-key: demo-key' \
  -d '{
  "name": "example.ir",
  "period": "1",
  "contacts": {
    "holder": "ta-irnic",
    "admin": "ta-irnic",
    "tech": "ta-irnic",
    "bill": "ta-irnic"
  },
  "nameservers": [
    {
      "hostname": "ns1.example.ir",
      "ip": "8.8.8.8"
    },
    {
      "hostname": "ns2.webalfa.ir"
    }
  ]
}'

نمونه پاسخ

{
  "success": "true"
}

تمدید

این درخواست برای تمدید یک دامنه انجام میگیرد. این درخواست تنها برای دامنه‌هایی که قبلا توسط درخواست دهنده (نماینده) از طریق API ثبت شده است کاربرد دارد.

در صورتی نیاز به تمدید دامنه‌ای که قبلا توسط API ثبت نشده است مستندات بخش “انتقال” را مطالعه نمایید.

POST https://api.webalfa.net/v2/domains/:domain_name/renew

بجای پارامتر :domain_name در URL بایستی نام دامنه قرار داده شود.

پارامترها

نام	توضیحات	محدودیت
period (int)	مدت تمدید	اجباری حداقل و حداکثر طول: ۱ مقادیر مجاز: ۱ و ۵

نمونه درخواست (cURL)

curl -X POST \
  https://api.webalfa.net/v2/domains/example.ir/renew \
  -H 'content-type: application/json' \
  -H 'x-api-key: demo-key' \
  -d '{
  "period": "1"
}'

نمونه پاسخ

{
  "success": "true"
}

انتقال

این درخواست برای انتقال و تمدید دامنه ای انجام میشود که قبلا توسط نماینده درخواست ثبت آن به API ارسال نشده است و کنترل آن هم اکنون بر عهده نماینده دیگری است.

جهت موفقیت آمیز بودن این عملیات نیاز است تا دو مورد زیر رعایت شود:

۱. رابط مالی دامنه برابر شناسه‌ای باشد که نماینده در زمان سفارش نمایندگی دامنه در فرم سفارش وارد کرده است.

۲. رابط نماینده دامنه برابر شناسه وب‌آلفا (ta1822-irnic) باشد.

برای انجام مورد ۲ کافی است تا بعد از تنظیم شناسه کاربر نماینده به عنوان رابط مالی دامنه (توسط صاحب امتیار دامنه)، نماینده از طریق پنل کاربری nic.ir اقدام به تنظیم شناسه وب‌آلفا به عنوان نماینده دامنه نمایید. در صورت انجام این عملیات توسط nic.ir ایمیلی جهت اطلاع صاحب امتیاز برای ایشان ارسال خواهد شد که در آن ایمیل هیچگونه نامی از وب‌آلفا ذکر نخواهد شد.

POST https://api.webalfa.net/v2/domains/transfer

پارامترها

نام	توضیحات	محدودیت
name (string)	نام کامل دامنه	اجباری حداقل طول: ۳ حداکثر طول: ۶۳
period (int)	مدت تمدید	اجباری حداقل و حداکثر طول: ۱ مقادیر مجاز: ۱ و ۵

نمونه درخواست (cURL)

curl -X POST \
  https://api.webalfa.net/v2/domains/transfer \
  -H 'content-type: application/json' \
  -H 'x-api-key: demo-key' \
  -d '{
  "name": "example.ir"
  "period": "1"
}'

نمونه پاسخ

{
  "success": "true"
}

بروزرسانی

این درخواست برای بروزرسانی نام‌سرورها و رابط‌های دامنه کاربرد دارد.

POST https://api.webalfa.net/v2/domains/:domain_name/update

بجای پارامتر :domain_name در URL بایستی نام دامنه قرار داده شود.

نمونه درخواست (cURL)

curl -X POST \
  https://api.webalfa.net/v1/domain/irnic/update/example.ir \
  -H 'content-type: application/json' \
  -H 'x-api-key: demo-key' \
  -d '{
  "contacts": {
    "admin": "ta-irnic",
    "tech": "ta-irnic",
  },
  "nameservers": [
    {
      "hostname": "ns1.example.ir",
      "ip": "8.8.8.8"
    },
    {
      "hostname": "ns2.webalfa.ir"
    }
  ]
}'

نمونه پاسخ

{
  "success": "true"
}

اطلاعات

این درخواست برای دریافت اطلاعات تکمیلی یک دامنه بکار می‌رود.

GET https://api.webalfa.net/v2/domains/:domain_name

بجای پارامتر :domain_name در URL بایستی نام دامنه قرار داده شود.

نمونه درخواست (cURL)

curl -X GET \
  https://api.webalfa.net/v2/domains/example.ir \
  -H 'x-api-key: demo-key'

نمونه پاسخ

{
  "success": "true",
  "result": {
    "status": [
      "ok",
      "irnicRegistered"
    ],
    "contacts": {
      "holder": "ta-irnic",
      "admin": "ta-irnic",
      "tech": "ta-irnic",
      "bill": "ta-irnic",
      "reseller": "ta1822-irnic"
    },
    "nameservers": [
      {
        "hostname": "ns1.example.ir",
        "ip": "8.8.8.8"
      },
      {
        "hostname": "ns2.webalfa.ir"
      }
    ],
    "expiry_date": "2022-08-06T00:02:43"
  }
}