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

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

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

قبل الخوض في الآليات: ليس على عملائك رؤيتنا على الإطلاق. هناك ثلاث واجهات، وأنت تختار ما تستخدمه منها.

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

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

الطرق الأربع للوصول

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

1. الحصول على مفتاح API

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

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

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

2. إجراء أول استدعاء لك

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

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

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

المناسبة             الاستدعاء
سداد قيمة طلب        POST   /v1/orgs                                   مرة واحدة لكل عميل
                     POST   /v1/sites                                  مرة واحدة لكل خدمة
عدم سدادهم للمبلغ     POST   /v1/reseller/services/{siteId}/suspend
قيامهم بالسداد        POST   /v1/reseller/services/{siteId}/unsuspend
إلغاؤهم للاشتراك     DELETE /v1/sites/{siteId}
"تسجيل الدخول للاستضافة" POST   /v1/reseller/services/{siteId}/sso

توفير الخدمة يتم عبر استدعاءين، والمفاتيح هنا بالغة الأهمية:

# 1. حساب العميل — يتم ربطه بمعرّف العميل الخاص بك
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. موقعهم — يتم ربطه بمعرّف الخدمة الخاص بك
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 عنوان URL صالحاً للاستخدام لمرة واحدة ينقل عميلك مباشرة إلى حسابه الخاص، مسجلاً دخوله بالفعل.

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

5. تثبيت وحدة برمجية كبديل

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

6. إطلاق الخدمة والبدء الفعلي

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

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

أين تجد باقي التفاصيل

دليل مرجع API الكامل — الذي يضم كل نقطة نهاية، والمُنشأ من واقع مواصفاتنا، مع الصلاحية التي تتطلبها كل منها — متاح على <https://zinndigital.com/developers/api>.