بيع استضافة Zinn® من أنظمتك الخاصة

أنت تعيد بيع استضافتنا. عملاؤك هم عملاؤك: أسعارك، فواتيرك، مزود الدفع الخاص بك. هكذا تشغل منصتنا من أي نظام تشغيله حالي لديك — لوحة فوترة، أو موقع WordPress الخاص بك، أو برنامج نصي.

ما يراه عملاؤك بالفعل

قبل التطرق للتفاصيل التقنية: لا يُضطر عملاؤك أبداً لرؤيتنا. توجد ثلاث واجهات، وأنت تختار أيها تستخدم.

| الواجهة | لمن تعود | |---|---| | لوحة الاستضافات، على اسم النطاق الخاص بك | قم بتعيين اسم نطاق للوحة تحت إعادة البيع ← علامتك التجارية وسيقوم عملاؤك بتسجيل الدخول عبر panel.yourcompany.com باستخدام شعارك وألوانك. نفس اللوحة، وعنوانك. | | موقعك الإلكتروني الخاص | تضع إضافة WordPress ميزة البحث عن النطاقات ورابط تسجيل الدخول بنقرة واحدة على موقعك، وتتولى إتمام الطلب عبر صفحة الدفع الخاصة بـ WooCommerce لديك. | | لوحة الفوترة الخاصة بك | يظل WHMCS أو HostBill هو الواجهة الرئيسية؛ بينما تقوم الوحدة بالتجهيز في الخلفية ويقوم زر منطقة العملاء بتسجيل دخولهم مباشرة إلى الاستضافة الخاصة بهم. |

⛔ أياً كانت الواجهة التي تختارها، أنت تاجر السجل (merchant of record) لعملاؤك: أسعارك، فواتيرك، رقم ضريبة القيمة المضافة الخاص بك، مزود الدفع الخاص بك. نحن نُصدر الفاتورة لك، مرة واحدة في الشهر، بسعر الجملة.

بمجرد تعيين اسم نطاق للوحة، ضعْه في حقل عنوان اللوحة (Panel address) الخاص بإضافة WordPress وليس في أي مكان آخر — فرابط تسجيل الدخول الذي يولده واجهة برمجة التطبيقات (API) هذه يتبعه تلقائياً.

الطرق الأربع المتاحة

هناك أربع طرق متاحة، وكلها تفعل نفس الشيء في الخلفية:

| | مخصص لـ | |---|---| | وحدة WHMCS | متجر WHMCS | | وحدة HostBill | متجر HostBill | | إضافة WordPress | البيع من موقع WordPress أو WooCommerce الخاص بك | | واجهة برمجة التطبيقات (API) | أي شيء آخر — Blesta، نظام داخلي، برنامج نصي (cron script) |

1. احصل على مفتاح واجهة برمجة التطبيقات (API key)

في لوحة التحكم الخاصة بك، انتقل إلى مفاتيح واجهة برمجة التطبيقات (API keys) وأنشئ مفتاحاً. امنحه الصلاحيات اللازمة فقط:

| الصلاحية | السبب | |---|---| | org.read | قراءة حسابات عملائك | | sites.create | تجهيز موقع | | sites.view | قراءة خدمة | | sites.delete | إنهاء الخدمة | | reseller.view | سرد خدماتك وقراءة حجم الاستخدام | | reseller.provision | تعليق، إلغاء تعليق، وتسجيل دخول العميل |

⛔ لا تقم بمنح أي عملية تكامل صلاحية reseller.manage. تقوم هذه الصلاحية بتعديل قائمة الأسعار الخاصة بك وبيانات اعتماد بوابة الدفع الخاصة بك. وُجدت الصلاحية reseller.provision خصيصاً لئلا يحتاج المفتاح الذي تلصقه في لوحة الفوترة أو موقع الويب إلى تلك الصلاحية.

يُعرض المفتاح مرة واحدة. احفظه في نفس المكان الذي تحفظ فيه بيانات الاعتماد الأخرى الخاصة بك — ولا تضعه أبداً في ملف يخدمه خادم الويب الخاص بك.

2. قُم بالاستدعاء الأول

curl https://api.zinndigital.com/v1/reseller/services \
  -H "Authorization: Bearer zdk_live_…"

يعيد هذا كل خدمة قمت بتجهيزها، صفاً واحداً لكل موقع، مع العميل الذي تتبع له، وحالته، وما تتقاضاه مقابلها. في حساب جديد، ستكون القائمة فارغة — وهو الجواب الصحيح، وليس خطأً.

3. التكامل بالكامل، في ستة استدعاءات

متى يحدث ذلك          الاستدعاء
يتم دفع الطلب          POST   /v1/orgs                                   مرة واحدة لكل عميل (CUSTOMER)
                     POST   /v1/sites                                  مرة واحدة لكل خدمة (SERVICE)
لم يتم الدفع          POST   /v1/reseller/services/{siteId}/suspend
يتم الدفع             POST   /v1/reseller/services/{siteId}/unsuspend
يتم الإلغاء           DELETE /v1/sites/{siteId}
"تسجيل الدخول للاستضافة" POST   /v1/reseller/services/{siteId}/sso

يتم التجهيز عبر استدعاءين، والمفاتيح لها أهميتها:

# 1. حساب العميل — مُعرّف برقم تعريف العميل الخاص بك (YOUR customer id)
curl -X POST https://api.zinndigital.com/v1/orgs \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: account-4211" \
  -d '{"type":"customer","name":"Acme Ltd"}'

# 2. موقعهم — مُعرّف برقم تعريف الخدمة الخاص بك (YOUR service id)
curl -X POST https://api.zinndigital.com/v1/sites \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: service-9915" \
  -d '{"org_id":"<from step 1>","product_line":"mainstream","primary_domain":"acme.com"}'

قاعدتان تكلفانك مالاً عندما تخطئ فيهما

1. اجعل الحساب مُعرّفاً بالعميل (CUSTOMER) والموقع مُعرّفاً بالخدمة (SERVICE). يجب أن يتم تسجيل الطلب الثاني للعميل في الحساب الذي يملكه بالفعل. إذا قمت بتعريف كليكما على أساس الخدمة، سينتهي المطاف بالعميل بثلاثة حسابات غير مرتبطة وثلاث لوحات تحكم منفصلة.
2. أرسل ترويسة Idempotency-Key مع كل طلب POST، مُنشأة من معرّفك الخاص للشيء. يقوم كل نظام فوترة بإعادة المحاولة — قد تصل ردود بوابة الدفع مرتين، أو يعيد المسؤول تشغيل عملية تجهيز فاشلة، أو ينقر العميل نقراً مزدوجاً. بدون المفتاح، ستنشئ المحاولة الثانية موقعاً ثانياً وسيتم فوترتك مقابله.

ثلاث إجابات يجب ألا تختزلها إلى اثنتين

• يمكن أن يُرجع طلب unsuspend الرمز 409. هذا يعني أن فريق إساءة الاستخدام لدينا يحظر الموقع، وليس أنت. اعرض الرسالة؛ ولا تقم بإعادة المحاولة.
• **إنهاء الخدمة يُجدول عملية الحذف، ولا ينفذها فوراً.** يتم إرجاع التاريخ على هيئة pending_deletion_at. إخبار العميل بأن بياناته قد أُزيلت بالفعل بينما لم تحدث الإزالة أسوأ من عدم إخباره بشيء على الإطلاق.
• يمكن أن تكون قيمة disk_used_bytes عبارة عن null، وقيمة null لا تساوي الصفر. هذا يعني تعذر القياس لدينا، وليس أن المساحة المستخدمة هي صفر. تخطَّ ذلك — ولا تكتب القيمة 0 في سجلاتك الخاصة، وإلا ستعرض للعميل شريط استخدام أخضر لموقع ليس لديك قراءة حوله.

4. تسجيل دخول عميل

يُرجع الطلب POST /v1/reseller/services/{siteId}/sso رابطاً أحادي الاستخدام يضع عميلك مباشرة في حسابه الخاص، مسجلاً لدخوله بالفعل.

⛔ قم بتوليد الرابط عند النقر عليه، ولا تقم أبداً بتوليده عند تحميل الصفحة. الرابط أحادي الاستخدام وينتهي صلاحيته في غضون دقائق، لذا فإن الرابط المكتوب داخل الصفحة يتم استنفاذه عند أول عرض للصفحة ويظل مخزناً في كل ذاكرة تخزين مؤقت (cache) بينك وبين المتصفح.

5. تثبيت وحدة بديلة

• WHMCS — انسخ الوحدة إلى المجلد modules/servers/zinn/، وأضف خادماً تكون كلمة المرور (Password) فيه هي مفتاح واجهة برمجة التطبيقات الخاص بك، واضبط خط منتج الاستضافة على المنتج. اضغط على اختبار الاتصال (Test Connection): سيقوم بإجراء استدعاء حقيقي ويخبرك بما ردت به المنصة.
• HostBill — انسخ الوحدة إلى المجلد includes/modules/Hosting/zinn/ وقم بربطها بالطريقة نفسها.
• WordPress — أداة إعادة البيع من Zinn®: البحث عن النطاقات، ورابط تسجيل الدخول إلى استضافة عملائك، وتجهيز الطلب عبر WooCommerce عند دفع الطلب. متوفر كمصدر مفتوح على <https://github.com/Zinn-Digital/zinn-reseller-toolkit>، أو قم بتحميله من الإضافات (Plugins) في لوحة التحكم الخاصة بك.

6. الانتقال إلى الإنتاج (Go live)

تحقق من هذه الأمور قبل قبول طلب حقيقي:

• نجاح اختبار الاتصال على الوحدة، أو قيام أول أمر curl بإرجاع قائمة.
• تم تعيين قائمة الأسعار الخاصة بك (إعادة البيع ← أسعارك).
• بوابة الدفع الخاصة بك متصلة (إعادة البيع ← بوابات الدفع) — حيث يدفع عملاؤك لك، عبر حسابك الخاص.
• تفاصيل شركتك مُدخلة (إعادة البيع ← شركتك) لكي تحتوي فواتير عملائك على الكيان القانوني ورقم ضريبة القيمة المضافة الخاص بك، وليس الخاص بنا.
• قمت بوضع طلب حقيقي واحد من البداية إلى النهاية وراقبته حتى ظهر الموقع.

أين تجد كل شيء آخر

مرجع واجهة برمجة التطبيقات الكامل — كل نقطة نهاية (endpoint)، مُولّدة من مواصفاتنا، مع الصلاحية التي يحتاجها كل منها — متوفر على <https://zinndigital.com/developers/api>.