Zoho ليست واجهة API واحدة، بل هي نحو خمسين منتجًا نشأ كل منها بشكل منفصل، وكل من دمج أكثر من اثنين منها يعرف تمامًا ما يعنيه ذلك: إجراءات مصادقة مختلفة لكل منتج، ومضيف (host) مختلف، وتصوّر مختلف لمكان وضع معرّف المؤسسة، ووثائق تتناقض مع نفسها أحيانًا.
كل فريق يبني على Zoho يعيد حل هذه المشكلات منتجًا تلو الآخر. فقررنا أن نحلها مرة واحدة. والنتيجة هي zone، أداة سطر أوامر مجانية ومفتوحة المصدر تضع 64 خدمة من Zoho و9,432 أمرًا محدد النوع خلف تسجيل دخول واحد، وقد نشرناها على npm ليستخدمها الجميع.
لماذا كان بناء واجهة سطر أوامر موحدة يستحق العناء
لا يكمن الاحتكاك في أي واجهة API منفردة من Zoho، فكل واحدة منها معقولة بحد ذاتها. بل تأتي التكلفة من نقاط الالتقاء بينها.
المصادقة خاصة بكل منتج. لكل خدمة مفرداتها الخاصة لنطاقات OAuth، والتسمية غير متسقة حتى داخل المنتج الواحد. كما أن Zoho لا تتحقق من أسماء النطاقات إلا بعد تسجيل الدخول، لذا فإن سلسلة نصية واحدة خاطئة ترفض شاشة الموافقة بأكملها بدلًا من رفض النطاق الخاطئ وحده. وتصحيح ذلك يدويًا يستهلك فترة ما بعد الظهر بأكملها.
المضيفات تتكاثر. يعمل CRM على نطاق، وDesk على نطاق آخر، وProjects على نطاق ثالث، وZeptoMail على نطاق رابع، ويتضاعف كل ذلك عبر عشرة مراكز بيانات، لأن حساب Zoho في الإمارات أو الهند أو كندا لا يتصل بالخوادم نفسها التي يتصل بها حساب في الولايات المتحدة. بل إن بعض المنتجات غير موجودة أصلًا في بعض المناطق.
الأعراف تتصادم. يحدد Zoho Books نطاق كل استدعاء بمعرّف المؤسسة في سلسلة الاستعلام، بينما يتوقعه Zoho Desk في ترويسة (header)، ويضع Zoho Projects معرّف البوابة في مسار URL. وتتطلب بعض نقاط نهاية DELETE جسم JSON. وبعض عمليات التحديث تكون POST بدلًا من PUT. ويمرّر Zoho Sheet أكثر من مئة عملية عبر نقطة نهاية واحدة خلف معامل method.
لا شيء من ذلك صعب، لكنه لا ينتهي، ويجب إعادة بنائه في كل عملية تكامل ونص برمجي وأداة داخلية. وواجهة سطر الأوامر الموحدة تجعل ذلك مشكلة شخص آخر، أي مشكلتنا نحن.
ما الذي تفعله zone فعليًا
ثبّتها مرة واحدة وسجّل الدخول مرة واحدة:
npm install -g wanas-zone-cli
zone login
ومن هناك يمكنك التحكم في أي منتج من Zoho بطريقتين. الأوامر محددة النوع تغطي الواجهة الموثقة وتتولى عنك أجسام الطلبات والتصفح بين الصفحات والتنزيلات والخصوصيات الخاصة بكل منتج:
zone crm record list Leads --fields Last_Name,Company
zone desk ticket list --toon
zone books invoice sent 12345
كما يصل الوكيل الشامل (universal proxy) إلى أي شيء لم يُحدَّد نوعه بعد، مع استمرار التعامل مع المصادقة وتوجيه مراكز البيانات:
zone api crm GET /Leads --query fields=Last_Name,Company
تُقاس التغطية مقارنةً بوثائق Zoho نفسها بدلًا من ادعائها. فثلاثون خدمة من أصل أربع وأربعين تغطي الآن 100% من واجهة API الموثقة رسميًا. وحيث تنشر Zoho مواصفات قابلة للقراءة آليًا، إذ تأتي عائلة التطبيقات المالية مع مستندات OpenAPI، وتوجد مستودعات مواصفات عامة لـ WorkDrive وAnalytics وLens وAssist، تُولَّد الأوامر من تلك المواصفات بدلًا من نسخها من النصوص الوصفية، مما يزيل فئة كاملة من الأخطاء البشرية.
وثمة تفصيل أهم مما يبدو: الجلسات تكون خاصة بكل مشروع افتراضيًا. فتشغيل zone login داخل مستودع عميل يكتب جلسة محلية تكتشفها الأداة بالطريقة نفسها التي يكتشف بها git المستودع، أي بالصعود من المجلد الحالي. ويمكن لكل مجلد مشروع أن يحتفظ بهوية Zoho مختلفة، لذا فإن التنقل بين عميلين لا يعني تسجيل الخروج ثم الدخول مجددًا. كما أن ملفات الجلسة مقيدة الصلاحيات وتستثني نفسها تلقائيًا من git، فلا يمكن إيداع الرموز (tokens) عن طريق الخطأ.
الجزء الذي لم نتوقعه: الوثائق نفسها
تطلّب بناء تغطية كاملة قراءة وثائق Zoho المنشورة لكل خدمة، وقد كشف ذلك عن عدد مفاجئ حقًا من العيوب، لا في واجهات API الخاصة بـ Zoho التي تعمل جيدًا في الغالب، بل في طريقة وصفها.
فقد تسربت أنماط توجيه داخلية إلى ملفات المواصفات المنشورة، بحيث لم يكن من الممكن أبدًا استدعاء عدة مسارات موثقة كما هي مطبوعة. وابتلعت منصة التوثيق قيمًا نائبة، تاركةً مسارات تحتوي على مقطع فارغ في موضع كان يُفترض أن يكون فيه معرّف. وتناقضت عدة صفحات مع أمثلة الشيفرة الخاصة بها بشأن طريقة HTTP الواجب استخدامها. ووثّق أحد المنتجات الصلاحية نفسها بتهجئتين مختلفتين في صفحتين مختلفتين.
كل واحد من هذه الأمور صغير، لكنه يكلّف المطور عشرين دقيقة وتذكرة دعم. وترميزها مرة واحدة في أداة يعني أن الشخص التالي لن يواجهها أبدًا.
مصممة لوكلاء البرمجة بالذكاء الاصطناعي
سبب أهمية ذلك الآن هو أن حصة متزايدة من أعمال التكامل مع Zoho تُنجَز بمساعدة الذكاء الاصطناعي، وZoho هدف صعب حقًا لوكيل الذكاء الاصطناعي.
وجّه وكيل برمجة إلى مهمة على Zoho دون أدوات، وستكون أنماط الفشل متوقعة: فهو يكتب تدفق OAuth يدويًا، أو يطلب منك لصق رمز تنتهي صلاحيته خلال ساعة. ويخمّن مسارات REST وإصدارات API، ثم يدور في حلقة من استجابات 404. ويخترع أسماء حقول تبدو معقولة لكنها تفشل في الكتابة بصمت. ويبني مضيفًا أمريكيًا لحساب موجود في الإمارات.
والواجهة المكونة من أوامر محددة النوع وذاتية التوثيق تزيل هذه المشكلات الأربع كلها. إذ يشغّل الوكيل zone <service> --help، ثم zone <service> <group> --help، ويكتشف الأوامر والخيارات الحقيقية بدلًا من التخمين. ويتوفر الناتج بصيغة JSON أو بصيغة TOON الأكثر إيجازًا، وتصل الأخطاء على شكل كائنات منظمة تتضمن تلميحًا قابلًا للقراءة آليًا، وتميّز رموز الخروج بين "أنت غير مصادق عليك" و"خطتك لا تتضمن هذه الميزة" و"استخدمت اسم حقل خاطئًا"، بحيث يستطيع الوكيل تصحيح نفسه بدلًا من إعادة المحاولة عشوائيًا.
وهناك أيضًا أمر يثبّت دليل الاستخدام مباشرة في أي أداة تستخدمها:
zone skill --ide claude
يكتب هذا الأمر الدليل في المكان الذي يبحث فيه وكيلك أصلًا. وهناك تسع وجهات مدعومة، منها Claude Code وCursor وWindsurf وGitHub Copilot وCline وGemini، وعُرف AGENTS.md الذي تستخدمه Codex وغيرها. لا حاجة إلى إضافة ولا إلى خادم منفصل لتشغيله.
والأهم أن الحدود تبقى في مكانها الصحيح: فتسجيل الدخول يتطلب موافقة عبر المتصفح يجب أن يكملها إنسان، لذا يستطيع الوكيل القراءة والتنفيذ، لكنه لا يستطيع منح نفسه التفويض.
أكثر من مجرد REST
تغطي zone أيضًا أجزاء تطوير Zoho التي ليست مجرد استدعاءات API بسيطة. إذ يمكنها رفع دوال Deluge وسحبها واختبارها مباشرة من محررك، كما يمكنها استخراج البيانات الوصفية الكاملة لمؤسسة CRM، من وحدات وحقول وقوائم اختيار وتخطيطات، وحفظها على القرص. وهذه الأخيرة تحل السبب الأكثر شيوعًا لفشل عمليات الكتابة بصمت: تخمين اسم API لحقل ما بدلًا من قراءته.
وإلى جانب zone، ننشر حزمتين مرافقتين: wanas-zcrm-extractor، التي تنتج لقطة منظمة لمخطط مؤسسة CRM، و**@wanasapps/zcrm-core**، المكتبة المستقلة عن بيئة التشغيل التي تقوم عليها الحزمتان.
استخدمها
الحزم الثلاث كلها مجانية ومفتوحة المصدر ومتاحة على npm:
- wanas-zone-cli — واجهة سطر الأوامر الموحدة
- wanas-zcrm-extractor — استخراج البيانات الوصفية لـ CRM
- @wanasapps/zcrm-core — المكتبة الأساسية المشتركة
npm install -g wanas-zone-cli
zone login
zone --help
تجد التفاصيل الكاملة وقائمة الأوامر ودليل إعداد وكلاء الذكاء الاصطناعي في صفحة zone CLI.
بنينا هذه الأداة لأننا احتجنا إليها. فبصفتنا شريك Zoho Premium نقدّم مشاريع Zoho CRM وأعمالًا مخصصة على Zoho Creator في الإمارات ومصر ومنطقة الشرق الأوسط وشمال أفريقيا الأوسع، كان مهندسونا يخسرون ساعات كل أسبوع في نقاط الالتقاء نفسها. وإتاحتها كمصدر مفتوح لا تكلفنا شيئًا، وتوفّر على الجميع الساعات نفسها.
إذا كنت تبني على Zoho، سواء كنت شريكًا أو مطورًا داخليًا أو مسؤول أنظمة يقضي وقته في الطرفية، فالأمر لا يتطلب سوى أمر npm install واحد.