# مرجع API للنطاقات في DNSHE
English · 简体中文 · 繁體中文 · 日本語 · Русский · Bahasa Indonesia · Deutsch · Français · 한국어 · العربية
[العودة إلى تعريف الخدمة](../README_AR.md)
سجّل النطاقات وأدر DNS وحدّث عناوين IP الديناميكية وأتمت عمليات الحساب. تستخدم الأمثلة مضيف API الخاص بـ DNSHE وبيانات اعتماد بديلة. استبدل الأسماء والمعرّفات والمفاتيح بمواردك.
## المحتويات
- [البدء](#البدء)
- [المصادقة وقواعد الطلبات](#المصادقة-وقواعد-الطلبات)
- [إدارة النطاقات](#إدارة-النطاقات)
- [إدارة سجلات DNS](#إدارة-سجلات-dns)
- [DNS الديناميكي (DDNS)](#dns-الديناميكي-ddns)
- [إدارة مفاتيح API](#إدارة-مفاتيح-api)
- [إهداء النطاقات](#إهداء-النطاقات)
- [الحصص](#الحصص)
- [استعلام WHOIS](#استعلام-whois)
- [الأخطاء وحدود الطلبات](#الأخطاء-وحدود-الطلبات)
- [أمثلة العملاء](#أمثلة-العملاء)
- [الأمان والأسئلة الشائعة](#الأمان-والأسئلة-الشائعة)
- [الدعم](#الدعم)
## البدء
```text
https://api005.dnshe.com/index.php?m=domain_hub
```
يتضمن العنوان الأساسي m=domain_hub؛ أضف المعلمات باستخدام &. تستخدم الطلبات والاستجابات JSON باستثناء معلمات استعلام GET. الحد العام الافتراضي 60 طلبًا في الدقيقة ويمكن للمشغّل تعديله. تتوقف الميزات على الحساب وإعدادات النشر. أمثلة الأوامر مخصصة لـ Bash/sh؛ اضبط متغيرات البيئة أولًا.
```bash
export DNSHE_API_KEY='replace-with-your-api-key'
export DNSHE_API_SECRET='replace-with-your-api-secret'
export DNSHE_DDNS_TOKEN='replace-with-your-ddns-token'
```
## المصادقة وقواعد الطلبات
أنشئ المفتاح الأول من منطقة العملاء ← [إدارة النطاقات](https://my.dnshe.com/index.php?m=domain_hub) ← إدارة API. استخدم الترويستين X-API-Key وX-API-Secret؛ إرسال بيانات الاعتماد في URL أو الجسم معطّل. تُرسل معلمات GET في الاستعلام، وعمليات الكتابة بصيغة JSON مع Content-Type: application/json. يحدد endpoint المورد وaction العملية. لا يحتاج quota وwhois إلى action. يستخدم DDNS رمزًا مستقلًا.
## إدارة النطاقات
### 1.1 عرض النطاقات
GET · endpoint=subdomains · action=list
#### المعلمات
- page — integer; اختياري; القيمة الافتراضية / النطاق: 1.
- cursor_id — integer; اختياري.
- per_page — integer; اختياري; القيمة الافتراضية / النطاق: 200; 1–500.
- include_total — boolean; اختياري; القيمة الافتراضية / النطاق: false.
- search — string; اختياري.
- rootdomain — string; اختياري.
- status — string; اختياري; القيمة الافتراضية / النطاق: active | suspended | expired.
- created_from / created_to — string; اختياري; القيمة الافتراضية / النطاق: YYYY-MM-DD.
- sort_by — string; اختياري; القيمة الافتراضية / النطاق: id.
- sort_dir — string; اختياري; القيمة الافتراضية / النطاق: desc; asc | desc.
- fields — string; اختياري; القيمة الافتراضية / النطاق: all.
page رقم صفحة متوافق يبدأ من 1. للقوائم الكبيرة ابدأ بـ cursor_id=0، ثم استخدم pagination.next_cursor_id ما دام pagination.has_more=true، وتوقف عند false. يرتب وضع المؤشر حسب ID دون OFFSET. القيمة الافتراضية لـ per_page هي 200 والحد الأقصى 500، ويمكن البدء بـ 50–100. يضيف include_total=1 إحصاءً قد يكون مكلفًا. يبحث search في البادئة أو النطاق الجذر؛ وتصفّي rootdomain وstatus وcreated_from وcreated_to النتائج. صيغة التاريخ YYYY-MM-DD. خيارات sort_by: id وcreated_at وupdated_at وexpires_at وsubdomain؛ وخيارات sort_dir: asc أو desc.
fields قائمة مفصولة بفواصل أو all: id وsubdomain وrootdomain وfull_domain وstatus وcreated_at وupdated_at وexpires_at وnever_expires وcloudflare_zone_id وprovider_account_id. يُضاف id دائمًا للاختيار المخصص. يمثل count عدد العناصر المعادة، وليس بالضرورة إجمالي النتائج.
#### أمثلة الطلبات
```bash
curl --fail-with-body --silent --show-error --max-time 30 -X GET "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=subdomains&action=list" \
-H "X-API-Key: ${DNSHE_API_KEY}" \
-H "X-API-Secret: ${DNSHE_API_SECRET}"
```
```bash
curl --fail-with-body --silent --show-error --max-time 30 -X GET "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=subdomains&action=list&cursor_id=0&per_page=100&fields=id,subdomain,rootdomain,status" \
-H "X-API-Key: ${DNSHE_API_KEY}" \
-H "X-API-Secret: ${DNSHE_API_SECRET}"
```
```bash
curl --fail-with-body --silent --show-error --max-time 30 -X GET "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=subdomains&action=list&search=test&rootdomain=de5.net&status=active&sort_by=expires_at&sort_dir=asc&per_page=50" \
-H "X-API-Key: ${DNSHE_API_KEY}" \
-H "X-API-Secret: ${DNSHE_API_SECRET}"
```
#### أمثلة الاستجابات
```json
{
"success": true,
"count": 2,
"subdomains": [
{
"id": 1,
"subdomain": "test",
"rootdomain": "de5.net",
"full_domain": "test.de5.net",
"status": "active",
"created_at": "2025-10-19 10:00:00",
"updated_at": "2025-10-19 10:00:00"
},
{
"id": 2,
"subdomain": "api",
"rootdomain": "de5.net",
"full_domain": "api.de5.net",
"status": "active",
"created_at": "2025-10-19 11:00:00",
"updated_at": "2025-10-19 11:00:00"
}
]
}
```
```json
{
"success": true,
"count": 1,
"subdomains": [
{
"id": 901,
"subdomain": "test",
"rootdomain": "de5.net",
"full_domain": "test.de5.net",
"status": "active"
}
],
"pagination": {
"mode": "cursor",
"page": 1,
"per_page": 100,
"has_more": true,
"cursor_id": 0,
"next_cursor_id": 901
}
}
```
### 1.2 تسجيل نطاق
POST · endpoint=subdomains · action=create
#### المعلمات
- subdomain — string; مطلوب.
- domain — string; مطلوب.
subdomain بادئة مثل myapp، وdomain نطاق جذر متاح مثل de5.net. يستخدم التسجيل action=create والحقل domain. حقل الاستجابة ومرشح القائمة rootdomain ليسا حقلَي تسجيل. تطبق قيود التوافر وحصة الحساب.
#### أمثلة الطلبات
```bash
curl --fail-with-body --silent --show-error --max-time 30 -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=subdomains&action=create" \
-H "X-API-Key: ${DNSHE_API_KEY}" \
-H "X-API-Secret: ${DNSHE_API_SECRET}" \
-H "Content-Type: application/json" \
-d '{
"subdomain": "myapp",
"domain": "de5.net"
}'
```
#### أمثلة الاستجابات
```json
{
"success": true,
"message": "Subdomain registered successfully",
"subdomain_id": 3,
"full_domain": "myapp.de5.net"
}
```
### 1.3 تفاصيل النطاق
GET · endpoint=subdomains · action=get
#### المعلمات
- subdomain_id — integer; مطلوب.
استخدم معرّف نطاق يملكه الحساب المصادق عليه. تتضمن الاستجابة كائن النطاق وdns_records وdns_count.
#### أمثلة الطلبات
```bash
curl --fail-with-body --silent --show-error --max-time 30 -X GET "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=subdomains&action=get&subdomain_id=1" \
-H "X-API-Key: ${DNSHE_API_KEY}" \
-H "X-API-Secret: ${DNSHE_API_SECRET}"
```
#### أمثلة الاستجابات
```json
{
"success": true,
"subdomain": {
"id": 1,
"subdomain": "test",
"rootdomain": "de5.net",
"full_domain": "test.de5.net",
"status": "active",
"created_at": "2025-10-19 10:00:00",
"updated_at": "2025-10-19 10:00:00"
},
"dns_records": [
{
"id": 1,
"name": "test.de5.net",
"type": "A",
"content": "203.0.113.10",
"ttl": 600,
"priority": null,
"status": "active",
"created_at": "2025-10-19 10:05:00"
}
],
"dns_count": 1
}
```
### 1.4 حذف نطاق
POST / DELETE · endpoint=subdomains · action=delete
#### المعلمات
- subdomain_id — integer; مطلوب.
يحذف النطاق المملوك وسجلات DNS المرتبطة. يعرض dns_records_deleted عدد السجلات المحذوفة. تحقق من المعرّف قبل الإرسال.
#### أمثلة الطلبات
```bash
curl --fail-with-body --silent --show-error --max-time 30 -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=subdomains&action=delete" \
-H "X-API-Key: ${DNSHE_API_KEY}" \
-H "X-API-Secret: ${DNSHE_API_SECRET}" \
-H "Content-Type: application/json" \
-d '{
"subdomain_id": 1
}'
```
#### أمثلة الاستجابات
```json
{
"success": true,
"message": "Subdomain deleted successfully",
"subdomain_id": 1,
"full_domain": "test.de5.net",
"dns_records_deleted": 4
}
```
### 1.5 تجديد نطاق
POST / PUT · endpoint=subdomains · action=renew
#### المعلمات
- subdomain_id — integer; مطلوب.
يبقى التجديد المجاني العادي في DNSHE مجانيًا، ويستخدم المثال charged_amount=0. قد تضبط الإضافة العامة استردادًا مدفوعًا؛ تحقق من الحالة وسياسة اللوحة خلال فترة الاسترداد. اقرأ previous_expires_at وnew_expires_at وnever_expires وremaining_days وcharged_amount لتحديد النتيجة الفعلية.
أخطاء التجديد: HTTP 403 مع renewal disabled أو redemption period requires administrator أو renewal window expired؛ HTTP 422 مع renewal_not_yet_available؛ HTTP 402 مع insufficient balance for redemption renewal؛ HTTP 404 للنطاق غير الموجود أو غير المملوك. تحقق من نافذة التجديد أو تواصل مع الدعم، ولا تكرر الطلب دون انتظار.
#### أمثلة الطلبات
```bash
curl --fail-with-body --silent --show-error --max-time 30 -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=subdomains&action=renew" \
-H "X-API-Key: ${DNSHE_API_KEY}" \
-H "X-API-Secret: ${DNSHE_API_SECRET}" \
-H "Content-Type: application/json" \
-d '{
"subdomain_id": 3
}'
```
#### أمثلة الاستجابات
```json
{
"success": true,
"message": "Subdomain renewed successfully",
"subdomain_id": 3,
"subdomain": "myapp",
"previous_expires_at": "2027-05-01 00:00:00",
"new_expires_at": "2028-05-01 00:00:00",
"renewed_at": "2027-04-30 00:00:00",
"never_expires": 0,
"status": "active",
"remaining_days": 367,
"charged_amount": 0
}
```
## إدارة سجلات DNS
### 2.1 عرض سجلات DNS
GET · endpoint=dns_records · action=list
#### المعلمات
- subdomain_id — integer; مطلوب.
فضّل id الخاص بالوحدة من القائمة أو الإنشاء؛ تتكون المعرّفات العامة الجديدة من 15 رقمًا. record_id هو معرّف مزود DNS. يتطلب التعديل والحذف واحدًا على الأقل؛ وإذا أُرسلا معًا يجب أن يشيرا إلى السجل نفسه، وإلا يظهر dns_record_identifier_mismatch. تبقى المعرّفات الداخلية القديمة متوافقة. يوثق المرجع توافق record_id الرقمي حتى 2027-06-12 على الأقل؛ استخدم id لمعرّف الوحدة في العملاء الجدد.
#### أمثلة الطلبات
```bash
curl --fail-with-body --silent --show-error --max-time 30 -X GET "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=dns_records&action=list&subdomain_id=1" \
-H "X-API-Key: ${DNSHE_API_KEY}" \
-H "X-API-Secret: ${DNSHE_API_SECRET}"
```
#### أمثلة الاستجابات
```json
{
"success": true,
"count": 2,
"records": [
{
"id": 1,
"record_id": "5a0ce6c4d1d4c71bc5e60a2a2a0e4997",
"name": "test.de5.net",
"type": "A",
"content": "203.0.113.10",
"ttl": 600,
"priority": null,
"line": null,
"proxied": false,
"status": "active",
"created_at": "2025-10-19 10:05:00",
"updated_at": "2025-10-19 10:05:00"
},
{
"id": 2,
"name": "www.test.de5.net",
"type": "CNAME",
"content": "test.de5.net",
"ttl": 600,
"priority": null,
"proxied": false,
"status": "active",
"created_at": "2025-10-19 10:10:00"
}
]
}
```
### 2.2 إنشاء سجل DNS
POST · endpoint=dns_records · action=create
#### المعلمات
- subdomain_id — integer; مطلوب.
- type — string; مطلوب.
- name — string; اختياري; القيمة الافتراضية / النطاق: @.
- content — string; اختياري.
- ttl — integer; اختياري; القيمة الافتراضية / النطاق: 600.
- priority — integer; اختياري; القيمة الافتراضية / النطاق: MX: 10; SRV: 0.
- line — string; اختياري.
- record_weight / weight — integer; اختياري.
- record_port / port — integer; اختياري; القيمة الافتراضية / النطاق: 1–65535.
- record_target / target — string; اختياري.
- caa_flag — integer; اختياري; القيمة الافتراضية / النطاق: 0; 0–255.
- caa_tag — string; اختياري; القيمة الافتراضية / النطاق: issue; 1–15 [A-Za-z0-9].
- caa_value — string; اختياري.
يدعم type الأنواع A وAAAA وCNAME وMX وTXT وNS وSRV وCAA. يكون name نسبيًا للنطاق المسجل؛ حذفه أو تركه فارغًا أو @ يعني النطاق نفسه. لا يُقبل الاسم الكامل؛ وتُسمح * في الجزء الأيسر فقط. content مطلوب إلا إذا جُمّع من معلمات SRV/CAA المنظمة. القيمة الافتراضية لـ ttl هي 600 ثانية، ولـ priority هي 10 في MX و0 في SRV.
يستخدم SRV المعلمات record_weight/weight للوزن وrecord_port/port للمنفذ (1–65535) وrecord_target/target للهدف؛ ويعني الهدف . أن الخدمة غير متاحة. يستخدم CAA: caa_flag (0–255، الافتراضي 0)، وcaa_tag (1–15 حرفًا أو رقمًا، الافتراضي issue)، وcaa_value. يخص line مزود AliDNS فقط؛ ويرفض الآخرون القيمة غير الفارغة.
قد تُعطّل كتابة NS عبر disable_ns_management. بعد التفويض إلى DNS خارجي، يُرفض إنشاء أو تعديل سجلات غير NS بالخطأ external_dns_delegated. لا يمنع ذلك حذف السجلات القديمة أو المطابقة أو تنظيف الموارد المنتهية.
#### أمثلة الطلبات
```bash
curl --fail-with-body --silent --show-error --max-time 30 -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=dns_records&action=create" \
-H "X-API-Key: ${DNSHE_API_KEY}" \
-H "X-API-Secret: ${DNSHE_API_SECRET}" \
-H "Content-Type: application/json" \
-d '{
"subdomain_id": 1,
"type": "A",
"content": "203.0.113.10",
"ttl": 600
}'
```
#### أمثلة الاستجابات
```json
{
"success": true,
"message": "DNS record created successfully",
"id": 738492016583241,
"record_id": "5a0ce6c4d1d4c71bc5e60a2a2a0e4997"
}
```
### 2.3 تعديل سجل DNS
POST / PUT / PATCH · endpoint=dns_records · action=modify
#### المعلمات
- id — integer; اختياري.
- record_id — string; اختياري.
- type / name / content — string; اختياري.
- ttl / priority — integer; اختياري.
- line — string; اختياري.
- record_weight / weight — integer; اختياري.
- record_port / port — integer; اختياري.
- record_target / target — string; اختياري.
- caa_flag — integer; اختياري.
- caa_tag / caa_value — string; اختياري.
أرسل id أو record_id والحقول المراد تغييرها. قواعد الاسم وخيارات SRV/CAA مماثلة للإنشاء. يجب أن يشير المعرّفان إلى السجل نفسه. تعيد الاستجابة معرّف الوحدة والمزود.
فضّل id الخاص بالوحدة من القائمة أو الإنشاء؛ تتكون المعرّفات العامة الجديدة من 15 رقمًا. record_id هو معرّف مزود DNS. يتطلب التعديل والحذف واحدًا على الأقل؛ وإذا أُرسلا معًا يجب أن يشيرا إلى السجل نفسه، وإلا يظهر dns_record_identifier_mismatch. تبقى المعرّفات الداخلية القديمة متوافقة. يوثق المرجع توافق record_id الرقمي حتى 2027-06-12 على الأقل؛ استخدم id لمعرّف الوحدة في العملاء الجدد.
قد تُعطّل كتابة NS عبر disable_ns_management. بعد التفويض إلى DNS خارجي، يُرفض إنشاء أو تعديل سجلات غير NS بالخطأ external_dns_delegated. لا يمنع ذلك حذف السجلات القديمة أو المطابقة أو تنظيف الموارد المنتهية.
#### أمثلة الطلبات
```bash
curl --fail-with-body --silent --show-error --max-time 30 -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=dns_records&action=modify" \
-H "X-API-Key: ${DNSHE_API_KEY}" \
-H "X-API-Secret: ${DNSHE_API_SECRET}" \
-H "Content-Type: application/json" \
-d '{
"id": 738492016583241,
"type": "A",
"content": "203.0.113.20",
"ttl": 600
}'
```
#### أمثلة الاستجابات
```json
{
"success": true,
"message": "DNS record updated successfully",
"id": 738492016583241,
"record_id": "5a0ce6c4d1d4c71bc5e60a2a2a0e4997"
}
```
### 2.4 حذف سجل DNS
POST / DELETE · endpoint=dns_records · action=delete
#### المعلمات
- id — integer; اختياري.
- record_id — string; اختياري.
فضّل id الخاص بالوحدة من القائمة أو الإنشاء؛ تتكون المعرّفات العامة الجديدة من 15 رقمًا. record_id هو معرّف مزود DNS. يتطلب التعديل والحذف واحدًا على الأقل؛ وإذا أُرسلا معًا يجب أن يشيرا إلى السجل نفسه، وإلا يظهر dns_record_identifier_mismatch. تبقى المعرّفات الداخلية القديمة متوافقة. يوثق المرجع توافق record_id الرقمي حتى 2027-06-12 على الأقل؛ استخدم id لمعرّف الوحدة في العملاء الجدد.
#### أمثلة الطلبات
```bash
curl --fail-with-body --silent --show-error --max-time 30 -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=dns_records&action=delete" \
-H "X-API-Key: ${DNSHE_API_KEY}" \
-H "X-API-Secret: ${DNSHE_API_SECRET}" \
-H "Content-Type: application/json" \
-d '{
"id": 1
}'
```
```bash
curl --fail-with-body --silent --show-error --max-time 30 -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=dns_records&action=delete" \
-H "X-API-Key: ${DNSHE_API_KEY}" \
-H "X-API-Secret: ${DNSHE_API_SECRET}" \
-H "Content-Type: application/json" \
-d '{
"record_id": "5a0ce6c4d1d4c71bc5e60a2a2a0e4997"
}'
```
#### أمثلة الاستجابات
```json
{
"success": true,
"message": "DNS record deleted successfully"
}
```
## DNS الديناميكي (DDNS)
GET / POST / PUT · endpoint=ddns · action=update
أنشئ رمزًا لسجل A/AAAA محدد من إدارة النطاقات ← DDNS. أرسله عبر Authorization: Bearer <DDNS_TOKEN> أو X-DDNS-Token، وليس URL أو الجسم. لا يغيّر الرمز إلا IP السجل المرتبط. تُدعم GET وPOST وPUT، ويستخدم المثال POST. يحدد ip الاختياري IPv4/IPv6؛ وعند حذفه يُستخدم IP مصدر الاتصال المباشر. لتحديث AAAA استخدم IPv6 مناسبًا.
يعني status=good تغيير العنوان. ويُعد status=nochg مع changed=false نجاحًا أيضًا، دون استدعاء مزود DNS. يستخدم DDNS العنوان https://api005.dnshe.com مستقلًا عن منطقة العملاء.
#### أمثلة الطلبات
```bash
curl -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=ddns&action=update" \
-H "Authorization: Bearer ${DNSHE_DDNS_TOKEN}"
```
```bash
curl -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=ddns&action=update" \
-H "X-DDNS-Token: ${DNSHE_DDNS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"ip":"203.0.113.10"}'
```
#### أمثلة الاستجابات
```json
{
"success": true,
"status": "nochg",
"changed": false,
"ip": "203.0.113.10"
}
```
### Synology DSM
في Synology DSM وغيره، استخدم مهمة مجدولة ترسل الترويسات بدل قالب URL يتضمن الرمز. احفظ الرمز واختبر المهمة يدويًا. يمكن البدء بفاصل خمس دقائق، بشرط ألا يكون أقصر من الحد الأدنى المضبوط. احفظ الرمز في بيئة مهمة محمية.
```sh
#!/bin/sh
: "${DNSHE_DDNS_TOKEN:?Set DNSHE_DDNS_TOKEN}"
curl --fail-with-body --silent --show-error --max-time 30 -X POST \
-H "X-DDNS-Token: ${DNSHE_DDNS_TOKEN}" \
"https://api005.dnshe.com/index.php?m=domain_hub&endpoint=ddns&action=update"
```
## إدارة مفاتيح API
### 3.1 عرض مفاتيح API
GET · endpoint=keys · action=list
تعرض القائمة المعرّفات والأسماء والحالات وعدد الطلبات وآخر استخدام. لا يمكن استعادة Secret قديم منها. يُنشأ المفتاح الأول في اللوحة.
#### أمثلة الطلبات
```bash
curl --fail-with-body --silent --show-error --max-time 30 -X GET "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=keys&action=list" \
-H "X-API-Key: ${DNSHE_API_KEY}" \
-H "X-API-Secret: ${DNSHE_API_SECRET}"
```
#### أمثلة الاستجابات
```json
{
"success": true,
"count": 2,
"keys": [
{
"id": 1,
"key_name": "Production",
"api_key": "cfsd_xxxxxxxxxx",
"status": "active",
"request_count": 1523,
"last_used_at": "2025-10-19 15:30:00",
"created_at": "2025-10-19 10:00:00"
},
{
"id": 2,
"key_name": "Test",
"api_key": "cfsd_yyyyyyyyyy",
"status": "active",
"request_count": 45,
"last_used_at": "2025-10-19 14:00:00",
"created_at": "2025-10-19 11:00:00"
}
]
}
```
### 3.2 إنشاء مفتاح API
POST · endpoint=keys · action=create
#### المعلمات
- key_name — string; مطلوب.
- ip_whitelist — string; اختياري.
key_name هو اسم المفتاح. عند تفعيل قائمة IP، يقبل ip_whitelist عناوين IP أو CIDR مفصولة بفواصل أو أسطر أو فواصل منقوطة. استبدل عنوان المثال بعنوان خروج الخادم الحقيقي. يظهر api_secret مرة واحدة فقط؛ احفظه فورًا.
#### أمثلة الطلبات
```bash
curl --fail-with-body --silent --show-error --max-time 30 -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=keys&action=create" \
-H "X-API-Key: ${DNSHE_API_KEY}" \
-H "X-API-Secret: ${DNSHE_API_SECRET}" \
-H "Content-Type: application/json" \
-d '{
"key_name": "Deployment",
"ip_whitelist": "203.0.113.10/32"
}'
```
#### أمثلة الاستجابات
```json
{
"success": true,
"message": "API key created successfully",
"api_key": "cfsd_zzzzzzzzzz",
"api_secret": "aaaaaaaaaaaaaaaa",
"warning": "Please save the api_secret, it will not be shown again"
}
```
### 3.3 حذف مفتاح API
POST / DELETE · endpoint=keys · action=delete
#### المعلمات
- key_id — integer; مطلوب.
يلغي المفتاح key_id. استخدم مفتاحًا صالحًا آخر للإدارة حتى لا يؤدي الحذف إلى إيقاف الأتمتة الحالية بشكل غير متوقع.
#### أمثلة الطلبات
```bash
curl --fail-with-body --silent --show-error --max-time 30 -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=keys&action=delete" \
-H "X-API-Key: ${DNSHE_API_KEY}" \
-H "X-API-Secret: ${DNSHE_API_SECRET}" \
-H "Content-Type: application/json" \
-d '{
"key_id": 2
}'
```
#### أمثلة الاستجابات
```json
{
"success": true,
"message": "API key deleted successfully"
}
```
### 3.4 إعادة إنشاء API Secret
POST · endpoint=keys · action=regenerate
#### المعلمات
- key_id — integer; مطلوب.
ينشئ Secret جديدًا لـ key_id ويلغي القديم. احفظ القيمة الجديدة وحدّث الخدمات المعتمدة عليها. إذا فُقدت كل بيانات الاعتماد الصالحة، استعد الوصول من اللوحة؛ لا تتاح العملية دون مصادقة.
#### أمثلة الطلبات
```bash
curl --fail-with-body --silent --show-error --max-time 30 -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=keys&action=regenerate" \
-H "X-API-Key: ${DNSHE_API_KEY}" \
-H "X-API-Secret: ${DNSHE_API_SECRET}" \
-H "Content-Type: application/json" \
-d '{
"key_id": 1
}'
```
#### أمثلة الاستجابات
```json
{
"success": true,
"message": "API secret regenerated successfully",
"api_key": "cfsd_xxxxxxxxxx",
"api_secret": "new_secret_here",
"warning": "Please save the new api_secret, it will not be shown again"
}
```
## إهداء النطاقات
### 4.1 بدء إهداء
POST / PUT · endpoint=gifts · action=initiate
#### المعلمات
- subdomain_id — integer; مطلوب.
يجب أن يملك الحساب المصادق عليه subdomain_id. تعيد الاستجابة رمز الإهداء ووقت الانتهاء. شارك الرمز مع المستلم المقصود فقط.
#### أمثلة الطلبات
```bash
curl --fail-with-body --silent --show-error --max-time 30 -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=gifts&action=initiate" \
-H "X-API-Key: ${DNSHE_API_KEY}" \
-H "X-API-Secret: ${DNSHE_API_SECRET}" \
-H "Content-Type: application/json" \
-d '{
"subdomain_id": 123
}'
```
#### أمثلة الاستجابات
```json
{
"success": true,
"data": {
"gift_id": 88,
"subdomain_id": 123,
"full_domain": "demo.de5.net",
"code": "AB12CD34EF56GH78IJ",
"expires_at": "2026-05-12 08:00:00"
}
}
```
### 4.2 قبول إهداء
POST / PUT · endpoint=gifts · action=accept
#### المعلمات
- code — string; مطلوب.
يصادق المستلم بمفتاحه الخاص ويرسل code من المرسل. ينقل القبول النطاق؛ تحقق من النطاق والحساب الأصلي في الاستجابة.
#### أمثلة الطلبات
```bash
curl --fail-with-body --silent --show-error --max-time 30 -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=gifts&action=accept" \
-H "X-API-Key: ${DNSHE_API_KEY}" \
-H "X-API-Secret: ${DNSHE_API_SECRET}" \
-H "Content-Type: application/json" \
-d '{
"code": "AB12CD34EF56GH78IJ"
}'
```
#### أمثلة الاستجابات
```json
{
"success": true,
"data": {
"gift_id": 88,
"subdomain_id": 123,
"full_domain": "demo.de5.net",
"from_userid": 1001
}
}
```
### 4.3 إلغاء إهداء
POST / DELETE · endpoint=gifts · action=cancel
#### المعلمات
- gift_id — integer; مطلوب.
يجب أن يشير gift_id إلى إهداء pending بدأه المستخدم الحالي. يلغي الإلغاء عملية النقل المعلقة.
#### أمثلة الطلبات
```bash
curl --fail-with-body --silent --show-error --max-time 30 -X POST "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=gifts&action=cancel" \
-H "X-API-Key: ${DNSHE_API_KEY}" \
-H "X-API-Secret: ${DNSHE_API_SECRET}" \
-H "Content-Type: application/json" \
-d '{
"gift_id": 88
}'
```
#### أمثلة الاستجابات
```json
{
"success": true,
"data": {
"gift_id": 88,
"subdomain_id": 123,
"full_domain": "demo.de5.net"
}
}
```
### 4.4 عرض الإهداءات
GET · endpoint=gifts · action=list
تعرض السجلات والحالات. initiate وaccept وcancel عمليات كتابة محدودة المعدل. بعد انتهاء المهلة، تحقق من الحالة قبل التكرار؛ فقد تكون العملية نُفّذت.
#### أمثلة الطلبات
```bash
curl --fail-with-body --silent --show-error --max-time 30 -X GET "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=gifts&action=list" \
-H "X-API-Key: ${DNSHE_API_KEY}" \
-H "X-API-Secret: ${DNSHE_API_SECRET}"
```
#### أمثلة الاستجابات
```json
{
"success": true,
"count": 1,
"gifts": [
{
"id": 88,
"code": "AB12CD34EF56GH78IJ",
"full_domain": "demo.de5.net",
"status": "pending",
"from_userid": 1001,
"to_userid": 0,
"expires_at": "2026-05-12 08:00:00",
"created_at": "2026-05-11 08:00:00"
}
]
}
```
## الحصص
### 5.1 عرض الحصة
GET · endpoint=quota
يتضمن quota الحقول used وbase وinvite_bonus وtotal وavailable. استخدم القيم الفعلية لا حصة حساب المثال. لا تحتاج إلى action.
#### أمثلة الطلبات
```bash
curl --fail-with-body --silent --show-error --max-time 30 -X GET "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=quota" \
-H "X-API-Key: ${DNSHE_API_KEY}" \
-H "X-API-Secret: ${DNSHE_API_SECRET}"
```
#### أمثلة الاستجابات
```json
{
"success": true,
"quota": {
"used": 3,
"base": 5,
"invite_bonus": 2,
"total": 7,
"available": 4
}
}
```
## استعلام WHOIS
GET · endpoint=whois
#### المعلمات
- domain — string; مطلوب.
domain مطلوب ويحتوي الاسم الكامل لنطاق داخلي أو استعلام WHOIS خارجي. الوضع العام لا يحتاج مفتاحًا افتراضيًا، وحدّه طلبان في الدقيقة لكل IP، بشكل مستقل عن API العام. قد يطلب المشغّل ترويستَي المصادقة المعتادتين. لا تحتاج إلى action.
تتوقف رؤية البريد والرمز البريدي على الخصوصية؛ registrant_postal_code مستقل عن registrant_address القديم. يخص owner_userid النطاقات الداخلية ويظهر عادة للمالك المصادق عليه ما لم يغيّر المشغّل الإعداد. لا يكشف WHOIS العام المعرّفات الداخلية افتراضيًا. قد تغيب حقول الهوية الاختيارية.
تشمل الحالات Registered وRenewalGracePeriod وRedemptionPeriod وServerHold وPendingDelete وunregistered. يستخدم nameservers والاسم البديل name_servers سجلات NS الفعلية أو الإعدادات الافتراضية. يعيد النطاق الدائم expires_at="2999-12-31 23:59" دون never_expires. غير المسجل يعيد registered=false وstatus=unregistered. يوضح rate_limit العام حصة IP المتبقية.
#### أمثلة الطلبات
```bash
curl -X GET "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=whois&domain=foo.de5.net"
```
```bash
curl -X GET "https://api005.dnshe.com/index.php?m=domain_hub&endpoint=whois&domain=foo.de5.net" \
-H "X-API-Key: ${DNSHE_API_KEY}" \
-H "X-API-Secret: ${DNSHE_API_SECRET}"
```
#### أمثلة الاستجابات
```json
{
"success": true,
"domain": "foo.de5.net",
"status": "Registered",
"registered_at": "2025-01-10 08:30:00",
"expires_at": "2026-01-10 08:30:00",
"registrant_email": "whois@example.com",
"privacy_enabled": false,
"registrant_postal_code": "797653",
"owner_userid": 123,
"nameservers": [
"ns1.example.net",
"ns2.example.net"
],
"rate_limit": {
"limit": 2,
"remaining": 1,
"reset_at": "2025-01-10 08:31:00"
}
}
```
```json
{
"success": true,
"domain": "foo.de5.net",
"registered": false,
"status": "unregistered",
"message": "domain not registered"
}
```
## الأخطاء وحدود الطلبات
تحقق من HTTP وJSON success. اعتمد على error_code الثابت، لا نص الرسالة المتغير. message وصف وdetails سياق اختياري وerror القديم يكرر معنى message. تُعد الاستجابة غير JSON من المزود الأعلى فشلًا أيضًا. ترد أدناه الرموز وحالات HTTP الشائعة؛ وأخطاء التجديد موضحة في قسمها.
- bad_request — HTTP 400.
- auth_invalid_credentials — HTTP 401.
- auth_ip_not_allowed — HTTP 403.
- api_access_disabled — HTTP 403.
- not_found / subdomain_not_found / dns_record_not_found — HTTP 404.
- quota_exceeded — HTTP 429.
- rate_limit_exceeded — HTTP 429.
- provider_operation_failed — HTTP 502.
- internal_error — HTTP 500.
- renewal_not_yet_available — HTTP 422.
```json
{
"success": false,
"error_code": "auth_invalid_credentials",
"message": "Invalid API key",
"details": {
"request_id": "example-request-id"
},
"error": "Invalid API key"
}
```
الافتراضي 60 طلبًا في الدقيقة لـ API العام وطلبان في الدقيقة لكل IP لـ WHOIS العام، وقد تختلف الإعدادات. استخدم details.limit وdetails.remaining وdetails.reset_at عند وجودها. قد يعني HTTP 429 نفاد الحصة أو تجاوز المعدل؛ ميّز quota_exceeded عن rate_limit_exceeded.
```json
{
"success": false,
"error_code": "rate_limit_exceeded",
"message": "Rate limit exceeded",
"details": {
"limit": 60,
"remaining": 0,
"reset_at": "2026-10-07 12:31:00"
},
"error": "Rate limit exceeded"
}
```
للقراءات المحدودة، انتظر إعادة الضبط أو استخدم تراجعًا أُسّيًا محدودًا مع عشوائية. بعد مهلة الإنشاء أو الحذف أو التجديد أو قبول الإهداء أو تبديل Secret، تحقق من الحالة قبل الإعادة. لا يعيد العملاء عمليات الكتابة تلقائيًا.
## أمثلة العملاء
هذه أمثلة عملاء خفيفة وليست SDK رسميًا. تشمل ترميز الاستعلام وJSON والمهل وفحص HTTP/API. شغّلها من جذر المستودع. يتطلب Node.js دالتَي fetch وAbortSignal.timeout المدمجتين؛ يستخدم Python المكتبة القياسية فقط؛ ويتطلب PHP دعم cURL وJSON. احفظ بيانات الاعتماد على خادم موثوق، لا في JavaScript المتصفح.
### Node.js
[client.cjs](../examples/client.cjs)
```javascript
const { DNSHEClient } = require('./examples/client.cjs');
const client = new DNSHEClient(
'https://api005.dnshe.com/index.php?m=domain_hub',
process.env.DNSHE_API_KEY, process.env.DNSHE_API_SECRET
);
client.request('subdomains', 'list', 'GET', { cursor_id: 0, per_page: 100 })
.then(console.log)
.catch(error => { console.error(error.code || 'request_failed', error.message); process.exitCode = 1; });
```
### Python
[client.py](../examples/client.py)
```python
import os
from examples.client import DNSHEClient
client = DNSHEClient(
'https://api005.dnshe.com/index.php?m=domain_hub',
os.environ['DNSHE_API_KEY'], os.environ['DNSHE_API_SECRET']
)
print(client.request('subdomains', 'list', data={'cursor_id': 0, 'per_page': 100}))
```
### PHP
[client.php](../examples/client.php)
```php
request('subdomains', 'list', 'GET', ['cursor_id' => 0, 'per_page' => 100]));
} catch (Throwable $error) {
fwrite(STDERR, $error->getMessage() . PHP_EOL);
exit(1);
}
```
## الأمان والأسئلة الشائعة
استخدم HTTPS ومتغيرات بيئة محمية ومفاتيح منفصلة وأقل صلاحيات متاحة. فعّل قائمة IP عند توفرها، وغيّر الأسرار وألغِ المفاتيح المهملة وراقب السجلات. لا تنشر رموز API/DDNS في المستودعات أو URL أو الصور أو السجلات العامة.
فقدان Secret: أعد إنشاؤه ببيانات صالحة أخرى أو عبر اللوحة؛ يُلغى القديم. رفع الحد: تواصل مع الدعم. الحسابات الفرعية: يسمح المرجع للحساب الرئيسي فقط بإنشاء واستخدام المفاتيح. لا توجد عمليات مجمعة موثقة؛ استدعِ كل عملية منفردة. الإحصاءات متاحة في إدارة API أو قائمة المفاتيح.
## الدعم
لأسئلة الحساب والتوافر والتجديد: [support@dnshe.com](mailto:support@dnshe.com). الإعدادات في [الدليل عبر الإنترنت](https://my.dnshe.com/knowledgebase/13/DNSHE-Free-Domain-API-User-Guide-V2.0.html) و[إدارة النطاقات](https://my.dnshe.com/index.php?m=domain_hub).