{ "openapi": "3.1.0", "info": { "title": "مستندات وب‌سرویس پنل Domain123", "summary": "مرجع کامل API نسخهٔ ۱ پنل: احراز هویت، دامنه‌ها، نیم‌سرورها، قفل ثبت‌کننده، کیف پول و شناسه‌ها — با نمونه‌کد cURL و PHP و پاسخ‌های JSON.", "description": "مرجع کامل API نسخهٔ ۱ پنل: احراز هویت، دامنه‌ها، نیم‌سرورها، قفل ثبت‌کننده، کیف پول و شناسه‌ها — با نمونه‌کد cURL و PHP و پاسخ‌های JSON.", "version": "1.0.0" }, "servers": [ { "url": "https://panel.domain123.ir/api/v1", "description": "Panel API" } ], "tags": [ { "name": "اندپوینت‌های عمومی" }, { "name": "حساب و کیف پول" }, { "name": "دامنه‌ها" }, { "name": "شناسه‌ها (Contacts)" } ], "paths": { "/public/prices": { "get": { "operationId": "publicPrices", "summary": "دریافت تعرفه‌های منتشرشده", "description": "تعرفهٔ جاری یک سطح قیمتی را از آخرین نسخهٔ منتشرشدهٔ پنل برمی‌گرداند. اگر تعرفه کهنه باشد، به‌جای عدد نادرست، خطای ۵۰۳ برگردانده می‌شود.", "tags": [ "اندپوینت‌های عمومی" ], "security": [], "parameters": [ { "name": "level", "in": "query", "required": false, "description": "کلید سطح قیمتی. اگر ارسال نشود، نخستین سطح منتشرشده انتخاب می‌شود.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "۲۰۰ — پاسخ موفق", "content": { "application/json": { "example": { "ok": true, "data": { "level": "reseller", "currency": "IRR", "publication": { "id": 41, "version": 7, "current": true, "published_at": 1762041600 }, "tier": { "slab_id": 3, "name": "نمایندگی" }, "rows": [ { "tld_id": 1, "extension": "ir", "currency": "IRR", "register": 450000, "renew": 450000, "transfer": 0, "restore": 0, "move": 0, "five_year": 2250000 }, { "tld_id": 2, "extension": "com", "currency": "IRR", "register": 1250000, "renew": 1250000, "transfer": 1250000, "restore": 0, "move": 0, "five_year": 6250000 } ] } } } } }, "503": { "description": "۵۰۳ — تعرفهٔ منتشرشده در دسترس نیست", "content": { "application/json": { "example": { "ok": false, "error": { "code": "prices-unavailable", "message": "قیمت منتشرشده و به‌روزی برای این سطح وجود ندارد." } } } } } } } }, "/public/whois": { "get": { "operationId": "publicWhois", "summary": "استعلام WHOIS", "description": "نتیجهٔ WHOIS یک دامنه را به‌صورت پاک‌سازی‌شده برمی‌گرداند: آزاد بودن، وضعیت‌ها، تاریخ انقضا و نیم‌سرورها. دادهٔ شخصی مالک در این پاسخ نمایش داده نمی‌شود.", "tags": [ "اندپوینت‌های عمومی" ], "security": [], "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "نام کامل دامنه، مثلاً example.ir", "schema": { "type": "string" } } ], "responses": { "200": { "description": "۲۰۰ — پاسخ موفق", "content": { "application/json": { "example": { "ok": true, "data": { "domain": "example.ir", "available": false, "statuses": [ "ok" ], "expiry": "2027-04-12", "nameservers": [ "ns1.example.ir", "ns2.example.ir" ], "source": "irnic", "checked_at": 1762300000 } } } } }, "422": { "description": "۴۲۲ — نام دامنه نامعتبر است", "content": { "application/json": { "example": { "ok": false, "error": { "code": "domain-invalid", "message": "پاسخ معتبر WHOIS برای این دامنه در دسترس نیست." } } } } } } } }, "/account": { "get": { "operationId": "accountShow", "summary": "اطلاعات حساب", "description": "شناسه، نام، ایمیل، موجودی کیف پول و مشخصات کلید جاری را برمی‌گرداند. برای تشخیص اینکه کلید به کدام حساب تعلق دارد و چه سطحی دارد، از همین اندپوینت استفاده کنید.", "tags": [ "حساب و کیف پول" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "۲۰۰ — پاسخ موفق", "content": { "application/json": { "example": { "ok": true, "data": { "account_id": 9701, "name": "نمونه کاربر", "email": "user@example.com", "wallet": { "balance": 12500000, "currency": "IRR" }, "key": { "id": 12, "name": "whmcs-prod", "permissions": "full" } } } } } }, "401": { "description": "۴۰۱ — کلید نامعتبر یا IP غیرمجاز", "content": { "application/json": { "example": { "ok": false, "error": { "code": "unauthenticated", "message": "کلید API معتبر نیست، لغو شده، منقضی شده یا IP درخواست مجاز نیست." } } } } } } } }, "/wallet": { "get": { "operationId": "accountWallet", "summary": "موجودی و گردش کیف پول", "description": "موجودی جاری و ۵۰ تراکنش آخر کیف پول را برمی‌گرداند. هر ردیف، مبلغ، موجودی پس از تراکنش، نوع و عملیات مرتبط را نشان می‌دهد.", "tags": [ "حساب و کیف پول" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "۲۰۰ — پاسخ موفق", "content": { "application/json": { "example": { "ok": true, "data": { "balance": 12500000, "currency": "IRR", "history": [ { "id": 8831, "amount": -450000, "balance_after": 12500000, "type": "debit", "operation": "register", "status": "success", "note": "ثبت دامنه example.ir", "at": "2026-11-02 14:31:08" } ] } } } } }, "404": { "description": "۴۰۴ — حساب یافت نشد", "content": { "application/json": { "example": { "ok": false, "error": { "code": "account-not-found", "message": "حساب کلید یافت نشد." } } } } } } } }, "/domains": { "get": { "operationId": "domainsIndex", "summary": "فهرست دامنه‌ها", "description": "دامنه‌های همین حساب را با جست‌وجو، فیلتر و صفحه‌بندی برمی‌گرداند. پاسخ همیشه یا کامل است یا صریحاً یک صفحه از یک مجموعهٔ شمارش‌شده؛ فهرست ناقصِ شبیه به کامل وجود ندارد.", "tags": [ "دامنه‌ها" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "جست‌وجو در نام دامنه (حداکثر ۱۰۰ نویسه)", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "فیلتر وضعیت: active، pending، expired، redemption، pending_registration، pending_transfer، fraud", "schema": { "type": "string" } }, { "name": "registrar", "in": "query", "required": false, "description": "فیلتر تخصیص ثبت‌کننده: assigned یا unknown", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "شمارهٔ صفحه؛ پیش‌فرض ۱", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "اندازهٔ صفحه؛ پیش‌فرض ۱۰۰ و حداکثر ۵۰۰", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "۲۰۰ — پاسخ موفق", "content": { "application/json": { "example": { "ok": true, "data": { "status": "ok", "reason": null, "counts": { "total": 1, "active": 1, "pending": 0, "expired": 0, "renewal": 0, "other": 0, "unknown_registrar": 0 }, "total": 1, "matched": 1, "page": { "current": 1, "pages": 1, "per_page": 100, "from": 1, "to": 1, "numbers": [ 1 ] }, "filters": { "q": null, "status": "active", "registrar": null }, "truncated": false, "domains": [ { "id": 39841, "fqdn": "example.ir", "status": "active", "expiry_date": "2027-04-12", "locked": true, "autorenew": true, "nameservers": [ "ns1.example.ir", "ns2.example.ir" ], "nameservers_source": "MIRROR", "nameservers_established": true, "nameservers_reason": null, "nameservers_read_at": 1762200000, "registrar": "domain123ir", "registrar_state": "assigned" } ] } } } } }, "422": { "description": "۴۲۲ — اندازهٔ صفحهٔ نامعتبر", "content": { "application/json": { "example": { "ok": false, "error": { "code": "invalid-per-page", "message": "بیشترین اندازهٔ صفحه 500 است." } } } } } } } }, "/domains/lookup": { "get": { "operationId": "domainsLookup", "summary": "جست‌وجوی دامنه با نام", "description": "دامنهٔ این حساب را با نام کامل پیدا می‌کند و همان پاسخ جزئیات را برمی‌گرداند. این اندپوینت برای مصرف‌کنندگانی ساخته شده که دامنه را با نام می‌شناسند، نه با شناسهٔ داخلی پنل.", "tags": [ "دامنه‌ها" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "fqdn", "in": "query", "required": true, "description": "نام کامل دامنه، مثلاً example.ir", "schema": { "type": "string" } } ], "responses": { "200": { "description": "۲۰۰ — پاسخ موفق", "content": { "application/json": { "example": { "ok": true, "data": { "id": 39841, "fqdn": "example.ir", "status": "active", "expiry_date": "2027-04-12", "locked": true, "autorenew": true, "nameservers": [ "ns1.example.ir", "ns2.example.ir" ], "nameservers_source": "REGISTRAR", "nameservers_established": true, "registrar": "domain123ir", "registrar_state": "assigned", "live": true, "read_at": 1762300123, "read_reason": null, "statuses": [ "ok" ], "contacts": [], "state": "registered", "state_label": "ثبت‌شده و فعال", "registrar_lock": { "state": "ESTABLISHED", "locked": true, "inactive": null, "statuses": [ "ok" ] } } } } } }, "404": { "description": "۴۰۴ — دامنه در این حساب نیست", "content": { "application/json": { "example": { "ok": false, "error": { "code": "domain-not-found", "message": "دامنه در این حساب یافت نشد." } } } } } } } }, "/domains/{id}": { "get": { "operationId": "domainsShow", "summary": "جزئیات دامنه", "description": "یک خواندن زندهٔ ثبت‌کننده انجام می‌دهد و اطلاعات نهایی را برمی‌گرداند: وضعیت‌ها، تاریخ انقضا، نیم‌سرورها، قفل و روابط شناسه. اگر خواندن شکست بخورد، آخرین وضعیت معتبر ذخیره‌شده با live=false و علت آن برگردانده می‌شود؛ هیچ چیزی پاک یا حدس زده نمی‌شود.", "tags": [ "دامنه‌ها" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "شناسهٔ عددی دامنه در پنل", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "۲۰۰ — خواندن ثبت‌کننده ناموفق (آخرین وضعیت معتبر)", "content": { "application/json": { "example": { "ok": true, "data": { "id": 39841, "fqdn": "example.ir", "status": "active", "expiry_date": "2027-04-12", "locked": true, "autorenew": true, "nameservers": [ "ns1.example.ir", "ns2.example.ir" ], "nameservers_source": "MIRROR", "nameservers_established": true, "nameservers_reason": "registrar-unreachable", "registrar": "domain123ir", "registrar_state": "assigned", "live": false, "read_at": 1762200000, "read_reason": "registrar-unreachable", "statuses": [], "contacts": [], "state": "unknown", "state_label": "نامعلوم", "registrar_lock": { "state": "UNAVAILABLE", "locked": null, "inactive": null, "statuses": [] } } } } } } } } }, "/domains/availability": { "post": { "operationId": "domainsAvailability", "summary": "استعلام موجودی نام", "description": "آزاد بودن یک نام را از ثبت‌کننده می‌پرسد. این درخواست فقط‌خواندنی است: چیزی رزرو نمی‌کند، صورتحساب نمی‌سازد و پول مصرف نمی‌کند.", "tags": [ "دامنه‌ها" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fqdn": { "type": "string" } }, "required": [ "fqdn" ] }, "example": { "fqdn": "example.ir" } } } }, "responses": { "200": { "description": "۲۰۰ — نام آزاد نیست", "content": { "application/json": { "example": { "ok": true, "data": { "status": "unavailable", "reason": "provider-reported-unavailable", "fqdn": "example.ir", "registrar": "domain123ir", "operation_id": "op_5d1f0a9c3b7e4a21" } } } } } } } }, "/domains/register": { "post": { "operationId": "domainsRegister", "summary": "ثبت دامنه", "description": "یک نام جدید را ثبت می‌کند. پیش از هر اثر مالی، آزاد بودن نام از ثبت‌کننده پرسیده می‌شود، تعرفهٔ جاری از انتشار فعال خوانده می‌شود و مبلغ در کیف پول رزرو می‌گردد.\n\nشناسهٔ NIC الزامی است. مقدار handle لازم نیست در دفتر شناسه‌های این حساب وجود داشته باشد؛ ثبت‌کننده خودش آن را تأیید می‌کند. اگر نه handle و نه contact_id ارسال نشود، ثبت رد می‌شود.\n\nپذیرش قوانین ثبت (فیلد Conditions در وب‌سرویس قدیم) در این نسخه به‌صورت خودکار و در جریان ثبت اعمال می‌شود و پارامتر جداگانه ندارد.\n\nدر دامنه‌های ملی، فقط حروف لاتین، ارقام و خط تیره مجاز است؛ خط تیره نباید در ابتدا یا انتهای نام باشد. نام‌های IDN باید به فرم Punycode ارسال شوند.", "tags": [ "دامنه‌ها" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fqdn": { "type": "string" }, "period": { "type": "integer" }, "handle": { "type": "string" }, "contact_id": { "type": "integer" }, "nameservers": { "type": "array", "items": { "type": "string" } } }, "required": [ "fqdn", "period" ] }, "example": { "fqdn": "example.ir", "period": 1, "handle": "ex123-irnic", "nameservers": [ "ns1.example.ir", "ns2.example.ir" ] } } } }, "responses": { "200": { "description": "۲۰۰ — ثبت موفق", "content": { "application/json": { "example": { "ok": true, "data": { "result": "successful", "reason": "registration-completed", "message": null, "operation_id": "op_9f3c1a7b2d4e5f60", "domain_id": 39841, "amount": 450000, "currency": "IRR", "reserve_state": "CONSUMED", "case_state": null, "returned_amount": 0 } } } } }, "422": { "description": "۴۲۲ — موجودی کیف پول کافی نیست", "content": { "application/json": { "example": { "ok": false, "error": { "code": "insufficient-balance", "message": "موجودی قابل استفادهٔ کیف پول برای این عملیات کافی نیست.", "case_state": null, "returned_amount": 0 } } } } } } } }, "/domains/renew": { "post": { "operationId": "domainsRenew", "summary": "تمدید دامنه", "description": "مدت اعتبار یک دامنهٔ متعلق به همین حساب را افزایش می‌دهد. تعرفه از انتشار فعال خوانده می‌شود و مبلغ پیش از تماس با ثبت‌کننده رزرو می‌گردد.", "tags": [ "دامنه‌ها" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain_id": { "type": "integer" }, "period": { "type": "integer" } }, "required": [ "domain_id", "period" ] }, "example": { "domain_id": 39841, "period": 1 } } } }, "responses": { "200": { "description": "۲۰۰ — تمدید موفق", "content": { "application/json": { "example": { "ok": true, "data": { "result": "successful", "reason": "renewal-completed", "message": null, "operation_id": "op_2b7e5c9a1f0d3e84", "domain_id": 39841, "amount": 450000, "currency": "IRR", "reserve_state": "CONSUMED", "case_state": null, "returned_amount": 0 } } } } }, "422": { "description": "۴۲۲ — تمدید پذیرفته نشد", "content": { "application/json": { "example": { "ok": false, "error": { "code": "domain-not-renewable", "message": "دامنه در وضعیتی نیست که قابل تمدید باشد.", "case_state": null, "returned_amount": 0 } } } } } } } }, "/domains/transfer": { "post": { "operationId": "domainsTransfer", "summary": "انتقال دامنه", "description": "انتقال یک دامنه از ثبت‌کنندهٔ دیگر به Domain123 را آغاز می‌کند. مبلغ تأییدشدهٔ کاربر باید با تعرفهٔ لحظهٔ اجرا یکسان باشد.\n\nاگر confirmed_amount با تعرفهٔ جاری یکسان نباشد، درخواست پیش از هر اثر مالی رد می‌شود؛ ابتدا تعرفهٔ جدید را نمایش دهید و سپس دوباره تأیید بگیرید.", "tags": [ "دامنه‌ها" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fqdn": { "type": "string" }, "period": { "type": "integer" }, "confirmed_amount": { "type": "integer" } }, "required": [ "fqdn", "period", "confirmed_amount" ] }, "example": { "fqdn": "example.ir", "period": 1, "confirmed_amount": 450000 } } } }, "responses": { "200": { "description": "۲۰۰ — انتقال پذیرفته شد", "content": { "application/json": { "example": { "ok": true, "data": { "result": "successful", "reason": "transfer-accepted", "message": null, "operation_id": "op_7c4a2d8e6b1f0935", "domain_id": 40112, "amount": 450000, "currency": "IRR", "reserve_state": "CONSUMED", "case_state": null, "returned_amount": 0 } } } } }, "422": { "description": "۴۲۲ — مبلغ تأییدشده کهنه است", "content": { "application/json": { "example": { "ok": false, "error": { "code": "confirmed-amount-mismatch", "message": "مبلغ تأییدشده با تعرفهٔ جاری یکسان نیست.", "case_state": null, "returned_amount": 0 } } } } } } } }, "/domains/restore": { "post": { "operationId": "domainsRestore", "summary": "بازگردانی دامنه", "description": "دامنهٔ منقضی را از دورهٔ بازگردانی (Redemption) خارج و دوباره فعال می‌کند. این عملیات معمولاً هزینهٔ بازگردانی دارد.\n\nبرای دامنه‌های قفل‌شده، ابتدا مجوز بازگردانی را با POST /domains/restore-flag ثبت کنید و سپس بازگردانی را اجرا کنید.", "tags": [ "دامنه‌ها" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain_id": { "type": "integer" }, "confirmed_amount": { "type": "integer" } }, "required": [ "domain_id", "confirmed_amount" ] }, "example": { "domain_id": 39841, "confirmed_amount": 1200000 } } } }, "responses": { "200": { "description": "۲۰۰ — بازگردانی موفق", "content": { "application/json": { "example": { "ok": true, "data": { "result": "successful", "reason": "restore-completed", "message": null, "operation_id": "op_4e8b1f6a9c2d7053", "domain_id": 39841, "amount": 1200000, "currency": "IRR", "reserve_state": "CONSUMED", "case_state": null, "returned_amount": 0 } } } } }, "422": { "description": "۴۲۲ — دامنه قابل بازگردانی نیست", "content": { "application/json": { "example": { "ok": false, "error": { "code": "restore-not-eligible", "message": "این دامنه در وضعیت قابل بازگردانی نیست.", "case_state": null, "returned_amount": 0 } } } } } } } }, "/domains/restore-flag": { "post": { "operationId": "domainsRestoreFlag", "summary": "ثبت مجوز بازگردانی", "description": "مجوز تاریخ‌دار بازیابی یک نام قفل‌شده را ثبت می‌کند. این یک «اجازه» است، نه عملیات: چیزی رزرو نمی‌کند، با ثبت‌کننده تماس نمی‌گیرد و هزینه‌ای ندارد.", "tags": [ "دامنه‌ها" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain_id": { "type": "integer" } }, "required": [ "domain_id" ] }, "example": { "domain_id": 39841 } } } }, "responses": { "200": { "description": "۲۰۰ — مجوز ثبت شد", "content": { "application/json": { "example": { "ok": true, "data": { "result": "flagged", "domain_id": 39841, "flag_id": 771, "flag_date": "2026-11-05", "flag_state": "ACTIVE", "created": true, "amount_charged": 0, "reason": null } } } } }, "422": { "description": "۴۲۲ — مجوز ثبت نشد", "content": { "application/json": { "example": { "ok": false, "error": { "code": "restore-flag-refused", "message": "ثبت مجوز بازگردانی برای این دامنه ممکن نیست." } } } } } } } }, "/domains/move": { "post": { "operationId": "domainsMove", "summary": "تغییر مالکیت (Move)", "description": "شناسهٔ مالک دامنه را به یک NIC handle جدید تغییر می‌دهد. مبلغ در صورت وجود، پیش از تماس با ثبت‌کننده رزرو می‌شود.\n\nتغییر مالکیت برای دامنهٔ قفل‌شده یا منقضی رد می‌شود. پیش از فراخوانی، قفل ثبت‌کننده را با POST /domains/lock باز کنید و وضعیت انقضا را بررسی نمایید.\n\nروابط شناسهٔ مالک جدید باید از قبل در ایرنیک تأیید شده باشد؛ در غیر این صورت ثبت‌کننده درخواست را رد می‌کند و نتیجه به‌صورت failed و با کد دلیل بازگردانده می‌شود.", "tags": [ "دامنه‌ها" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fqdn": { "type": "string" }, "handle": { "type": "string" }, "confirmed_amount": { "type": "integer" } }, "required": [ "fqdn", "handle" ] }, "example": { "fqdn": "example.ir", "handle": "new456-irnic", "confirmed_amount": 0 } } } }, "responses": { "200": { "description": "۲۰۰ — تغییر مالکیت موفق", "content": { "application/json": { "example": { "ok": true, "data": { "result": "successful", "reason": "move-completed", "message": null, "operation_id": "op_1a6d9e3c8b5f2047", "domain_id": 39841, "amount": 0, "currency": "IRR", "reserve_state": "NONE", "case_state": null, "returned_amount": 0 } } } } }, "422": { "description": "۴۲۲ — دامنه قفل است", "content": { "application/json": { "example": { "ok": false, "error": { "code": "domain-locked", "message": "دامنه در وضعیت قفل است و تغییر مالکیت ممکن نیست.", "case_state": null, "returned_amount": 0 } } } } } } } }, "/domains/nameservers": { "post": { "operationId": "domainsNameservers", "summary": "تغییر نیم‌سرورها", "description": "مجموعهٔ نیم‌سرورهای دامنه را جایگزین می‌کند. این عملیات رایگان است و هیچ مبلغی رزرو نمی‌کند، اما تغییردهنده است و کلید Idempotency می‌خواهد.\n\nبرای جلوگیری از تغییر ناخواسته، پیش از ذخیره، مجموعهٔ فعلی را با GET /domains/{id} بخوانید. اگر خواندن وضعیت ثبت‌کننده ممکن نباشد، ذخیره انجام نمی‌شود.", "tags": [ "دامنه‌ها" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain_id": { "type": "integer" }, "nameservers": { "type": "array", "items": { "type": "string" } } }, "required": [ "domain_id", "nameservers" ] }, "example": { "domain_id": 39841, "nameservers": [ "ns1.example.ir", "ns2.example.ir" ] } } } }, "responses": { "200": { "description": "۲۰۰ — ذخیره شد", "content": { "application/json": { "example": { "ok": true, "data": { "result": "successful", "reason": "nameservers-saved", "message": null, "operation_id": "op_6f2c8d1a4e9b3075", "domain_id": 39841, "amount": 0, "currency": "IRR", "reserve_state": "NONE", "case_state": null, "returned_amount": 0 } } } } }, "422": { "description": "۴۲۲ — فهرست نیم‌سرور نامعتبر", "content": { "application/json": { "example": { "ok": false, "error": { "code": "nameserver-invalid", "message": "نام نیم‌سرور معتبر نیست.", "case_state": null, "returned_amount": 0 } } } } } } } }, "/domains/lock": { "post": { "operationId": "domainsLock", "summary": "قفل ثبت‌کننده (Registrar Lock)", "description": "قفل ثبت‌کننده را روی دامنه فعال یا غیرفعال می‌کند. این عملیات رایگان است، اما یک تغییر واقعی در ثبت‌کننده است و کلید Idempotency می‌خواهد.\n\nوضعیت قفل را با GET /domains/{id} و فیلد registrar_lock بخوانید. اگر state برابر UNAVAILABLE باشد، معنایش «قفل نیست» نیست؛ یعنی وضعیت خوانده نشده است.", "tags": [ "دامنه‌ها" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain_id": { "type": "integer" }, "target": { "type": "string" } }, "required": [ "domain_id", "target" ] }, "example": { "domain_id": 39841, "target": "LOCKED" } } } }, "responses": { "200": { "description": "۲۰۰ — قفل اعمال شد", "content": { "application/json": { "example": { "ok": true, "data": { "result": "successful", "reason": "lock-applied", "message": null, "operation_id": "op_3e7b0c5d9a2f8146", "domain_id": 39841, "amount": 0, "currency": "IRR", "reserve_state": "NONE", "case_state": null, "returned_amount": 0 } } } } }, "422": { "description": "۴۲۲ — هدف قفل نامعتبر", "content": { "application/json": { "example": { "ok": false, "error": { "code": "lock-target-invalid", "message": "هدف قفل باید LOCKED یا UNLOCKED باشد." } } } } } } } }, "/contacts": { "get": { "operationId": "contactsIndex", "summary": "فهرست شناسه‌ها", "description": "شناسه‌های همین حساب را با نوع، handle، نام، ایمیل و وضعیت برمی‌گرداند.", "tags": [ "شناسه‌ها (Contacts)" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "۲۰۰ — پاسخ موفق", "content": { "application/json": { "example": { "ok": true, "data": { "contacts": [ { "id": 221, "type": "personal", "handle": "ex123-irnic", "name": "نمونه کاربر", "email": "user@example.com", "status": "active" } ] } } } } }, "403": { "description": "۴۰۳ — سطح دسترسی کافی نیست", "content": { "application/json": { "example": { "ok": false, "error": { "code": "forbidden", "message": "این کلید مجوز لازم برای این عملیات را ندارد." } } } } } } }, "post": { "operationId": "contactsStore", "summary": "ایجاد شناسه", "description": "یک شناسهٔ جدید از نوع مشخص می‌سازد. مجموعهٔ فیلدهای الزامی به نوع شناسه و تعریف‌های همین نصب بستگی دارد؛ فیلدهای ارسال‌شده پیش از تماس با ثبت‌کننده اعتبارسنجی می‌شوند.\n\nبرای نوع personal یکی از national_code یا passport_num الزامی است. برای انواع حقوقی، فیلدهای شرکت جایگزین کد ملی شخص می‌شوند.\n\nشناسه‌های محدود (مانند ایمیل‌های رزرو‌شدهٔ سامانه) پذیرفته نمی‌شوند و پاسخ handle-restricted برمی‌گردد.", "tags": [ "شناسه‌ها (Contacts)" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string" }, "phone_number": { "type": "string" }, "national_code": { "type": "string" }, "company_name": { "type": "string" }, "country / state / city / address / post_code": { "type": "string" } }, "required": [ "type", "first_name", "last_name", "email", "phone_number" ] }, "example": { "type": "personal", "first_name": "نمونه", "last_name": "کاربر", "email": "user@example.com", "phone_number": "09120000000", "national_code": "0012345678" } } } }, "responses": { "201": { "description": "۲۰۱ — شناسه ساخته شد", "content": { "application/json": { "example": { "ok": true, "data": { "result": "accepted", "reason": null, "operation_id": "op_8a1f4c7e2b9d6035", "handle": "ex789-irnic", "status": "active" } } } } }, "422": { "description": "۴۲۲ — دادهٔ شناسه ناقص است", "content": { "application/json": { "example": { "ok": false, "error": { "code": "contact-data-incomplete", "message": "فیلدهای الزامی این نوع شناسه کامل نیست." } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "کلید API ساخته‌شده در پنل؛ IP درخواست باید در فهرست مجاز کلید باشد." } } } }