CNF API · v1

نظرة عامة

يوفر الإصدار 1 عمليات DNS للمناطق التي طالبت بملكيتها عبر إدارة DNS. أنشئ الرموز وألغها من الحساب ← مفاتيح API.

عنوان URL الأساسي والإصدارات

https://api.c.nf/v1

تقع جميع نقاط النهاية تحت /v1. ستستخدم التغييرات غير المتوافقة مسار إصدار رئيسي جديد. وقد تُضاف إلى v1 حقول ونقاط نهاية متوافقة مع الإصدارات السابقة، وستُسجّل في سجل التغييرات.

المصادقة والنطاقات

يجب أن يتضمن كل طلب يقرأ بيانات الحساب أو يغيّرها رمز Bearer. تبدأ الرموز بـ cnf_ متبوعة بـ 32 محرفًا سداسيًا عشريًا.

curl https://api.c.nf/v1/dns/zones \
  -H "Authorization: Bearer cnf_a1b2c3d4e5f60718293a4b5c6d7e8f90"

تُخزّن الرموز كتجزئات أحادية الاتجاه، ولا تُعرض قيمتها الكاملة إلا عند إنشائها. إذا فُقد رمز، فألغِه وأنشئ رمزًا آخر.

يحمل كل رمز نطاقات صلاحية. يحصل الرمز الذي لا يملك نطاقًا مهيأ على dns:read افتراضيًا. ويسمح نطاق الكتابة بالقراءة أيضًا.

يعيد عدم التطابق 403 forbidden_scope ويتضمن كلاً من required_scopes وtoken_scopes للمساعدة في التشخيص.

العزل لكل مستخدم

يرتبط رمز Bearer بقيمة user_id واحدة بالضبط. يتحقق كل معالج لمنطقة DNS من مطالبة ذلك المستخدم المتحقّق منها قبل أي قراءة أو كتابة. لا يوجد تجاوز للمشرف ولا مسار انتحال ولا التفاف بين المستخدمين.

حتى الرمز ذو النطاق * لا يمكنه العمل إلا على المناطق التي تحقّق مستخدمه من ملكيتها. تعيد محاولة استخدام منطقة تابعة لحساب آخر 403 forbidden_zone.

غلاف الاستجابة

استجابة ناجحة

{
  "success": true,
  "data": { "zones": [] },
  "request_id": "req_abc123def456abcd"
}

استجابة خطأ

{
  "success": false,
  "error": "forbidden_zone",
  "message": "zone not verified for this account (or does not exist)",
  "request_id": "req_abc123def456abcd",
  "zone": "example.com"
}

تظهر قيمة request_id في كل استجابة، ويمكن تسجيلها بأمان مع سجلات العميل.

رموز الأخطاء

التحقّق من منطقة DNS

عندما يطالب POST /v1/dns/zones بملكية منطقة، يختار الخادم أحد المسارات التالية:

1. تحقّق فوري (method: "auto") — يُستخدم عندما لا يكون أي حساب آخر قد طالب بالمنطقة. تُعتمد المطالبة فورًا. ولا تصبح السجلات موثوقة إلا بعد أن يوجّه المالك تفويض NS لدى مسجّل النطاق إلى خوادم الأسماء المُعادة.
2. تحقّق TXT — يُستخدم عند وجود مطالبة متنازع عليها. أضف قيمة TXT المُعادة عند _cnfdns-verify.<zone>، ثم استدعِ POST /v1/dns/zones/{zone}/verify.
3. تحقّق NS قديم — قد تستخدم المطالبات القديمة قيد الانتظار verify_method: "ns". يقارن التحقّق إجابات NS المباشرة للمنطقة بمجموعة خوادم الأسماء المتوقعة.

عملية التحقّق متكررة بأمان. يؤدي تكرارها لمطالبة متحقّق منها إلى إرجاع verified: true دون تغيير المطالبة.

أنواع السجلات وحدودها

أنواع السجلات المدعومة

A, AAAA, CNAME, MX, TXT, NS, SRV, CAA, PTR, SPF.

تكون priority مطلوبة لسجلات MX وSRV، وتُتجاهل للأنواع الأخرى. يجب أن تكون ttl بين 60 و2,592,000 ثانية.

نقاط النهاية

خدمات عامة

نقاط صغيرة موثوقة لا تحتاج حسابًا: الوقت والعنوان والبلد وأسعار الصرف والبصمات.

الحساب

لمن يعود الرمز، وما الذي يسمح به.

DNS

طالِب بنطاق، وأثبت أنك تتحكم فيه، ثم أدر سجلاته.

بيانات الاعتماد

مخزن بيانات الاعتماد الخاص وراء أداة بيانات الاعتماد.

الملفات

تخزين شخصي للملفات: عرض ورفع وتحرير ومشاركة وحذف.

CDN

التخزين المؤقت على الحافة وحركة البيانات لملفاتك المشتركة.

تحويل الرسائل

الرسائل المُحوَّلة من هاتفك، والمفاتيح التي تسمح بها.

المواقع الثابتة

ارفع ملف zip واحصل على موقع.

عمليات النشر

نقاط النماذج وWebhook والروابط المختصرة التي نشرتها.

النطاقات

محفظة نطاقاتك وبيانات تسجيلها.

الحزم

انشر الإصدارات واقرأ نسخها وأعداد تنزيلاتها.

WHOIS

بيانات تسجيل النطاق، مخزّنة مؤقتًا ومشتركة مع أدوات النطاقات.

لوكلاء الذكاء الاصطناعي

وجِّه الوكيل إلى /v1/ai للحصول على ملخص مكتوب ليُلصق مباشرة في المُوجّه، أو إلى /v1/ai?format=json للحصول على النقاط نفسها كتعريفات أدوات. و/v1/openapi.json هو عقد OpenAPI 3.1 الكامل، و/llms.txt خريطة للزواحف. الأربعة تُولَّد من جدول المسارات نفسه الذي تستخدمه هذه الصفحة، فلا يمكن لأي منها أن يصف نقطة غير موجودة.

curl https://api.c.nf/v1/ai
curl https://api.c.nf/v1/ai?format=json
curl https://api.c.nf/v1/openapi.json

حقول الطلب

إنشاء مطالبة بمنطقة DNS

إنشاء سجل DNS

تحديث سجل DNS

أمثلة

curl -H "Authorization: Bearer $CNF_TOKEN" \
  https://api.c.nf/v1/dns/zones

curl -X POST https://api.c.nf/v1/dns/zones \
  -H "Authorization: Bearer $CNF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"zone":"example.com"}'

curl -X POST https://api.c.nf/v1/dns/zones/example.com/verify \
  -H "Authorization: Bearer $CNF_TOKEN"

curl -X POST https://api.c.nf/v1/dns/zones/example.com/records \
  -H "Authorization: Bearer $CNF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"A","host":"api","value":"192.0.2.10"}'

بدء سريع

1. أنشئ مفتاح API بنطاق dns:write من الحساب ← مفاتيح API، وانسخه عند عرضه.
2. خزّن الرمز في متغير بيئة محمي على جهازك.
3. استدعِ GET /v1/account/me للتأكد من الرمز ونطاقاته.
4. طالب بمنطقة DNS. توضح الاستجابة ما إذا كان التحقّق فوريًا أو باستخدام TXT أو باستخدام NS القديم.
5. أكمل إثبات DNS المُعاد عند طلبه، ثم استدعِ نقطة نهاية التحقّق.
6. لا تنشئ السجلات أو تقرأها أو تحدّثها أو تحذفها إلا بعد التحقّق من المطالبة.

سجل التغييرات

v1.1.0 — إدارة مناطق DNS

• إضافة مطالبات مناطق DNS عبر API، بما فيها مسارا التحقّق الفوري وTXT.
• إضافة نقطتي نهاية لحالة المنطقة الواحدة وللتحقّق المتكرر بأمان.
• إضافة إلغاء المطالبة دون حذف ضمني للسجلات.
• إضافة عوامل تصفية المتحقّق منها وقيد الانتظار والكل إلى قائمة المناطق.

v1.0.0 — الإصدار الأول

• إضافة مصادقة رمز Bearer وعزل مناطق DNS لكل مستخدم.
• إضافة نطاقي القراءة والكتابة.
• إضافة نقاط نهاية الحساب وقائمة المناطق وإدارة السجلات.
• إضافة غلاف استجابة موحّد يتضمن معرّف طلب.