تشرح وثائق المطورين الرسمية في زد أداتين متكاملتين للعمل على التكاملات بمساعدة الذكاء الاصطناعي: Zid AI Agent Skill مفتوحة المصدر، وخادم MCP الخاص بتوثيق زد. تمنح المهارة الوكيل قواعد خاصة بزد وإرشادًا معماريًا قابلًا لإعادة الاستخدام، بينما يتيح MCP لأداة برمجية متوافقة استرجاع سياق التوثيق. لكن أيًا منهما لا يحوّل الكود المولد وحده إلى سلوك API موثّق.
هذا الفرق حساس في أنظمة التجارة. قد يفشل Endpoint مخترع بوضوح، لكن وضع Token متجر في Tenant خاطئ قد يكسر العزل بين العملاء. وقد تكرر Retry غير منضب عملية كتابة، أو يستهلك Agent غير مضبوط حصة API الخاصة بالمتجر. لذلك ليست المعمارية المفيدة “اطلب من الوكيل بناء التكامل”، بل مسار مضبوط يسترجع فيه الوكيل المعلومات ويقترح وينفذ الاختبارات، بينما يبقى عقد التطبيق هو المرجع الحاكم.
هذا المقال شرح عملي مبني على وثائق زد الرسمية، وليس ادعاءً عن إصدار جديد خلال آخر 48 ساعة. عُدلت صفحة AI Agent Skill في 21 يوليو 2026، وصفحة إعداد MCP في 30 يوليو 2026، وتم التحقق من الوثائق الحية المشار إليها في 2 أكتوبر 2026.
ابدأ بعقد مهمة لا Prompt واسع
قبل أن يقرأ الوكيل التوثيق أو يكتب الكود، أعطه عقد تكامل محدودًا. حدد نوع التطبيق ونطاق التاجر والفعل التجاري المطلوب والآثار الجانبية المسموحة واللغة أوFramework ودليل النجاح. عبارة “اربط طلبات زد” واسعة جدًا. أما “اقرأ الطلبات المتغيرة لمتجر مثبّت واحد، وحوّلها إلى هذا Schema، ولا تغيّر أي حالة في المصدر” فتصنع حدًا يمكن مراجعته وإنفاذه.
يجب أن يسجل العقد الأمور المجهولة بوضوح. إذا لم يكن HTTP Method أوRoute أوScope أوHeader أوالقيمة المدعومة موجودًا في التوثيق الحالي، يتوقف الوكيل ويسترجعه. لا يستنتج Endpoint من نمط التسمية أو من منصة تجارة أخرى. تضع وثيقة المهارة القاعدة نفسها: يجب فحص Method وURL والصلاحيات وAuthentication Headers والParameters وRequest Body وResponse Schema وحدود الطلبات والأخطاء مقابل صفحة Endpoint الحية قبل التنفيذ.
يمكن لملف مهمة صغير جعل هذا السلوك قابلًا للتكرار:
integration: zid
store_scope: one installed merchant
operation: read_changed_orders
side_effects: forbidden
required_evidence:
- official endpoint URL and method
- required scopes and both auth headers
- sanitized success and error fixtures
- contract tests for 401, 403, 422 and 429
unknown_behavior: stop_and_reportضع Prompt وهذا العقد في Version Control بجانب Adapter. عند تغير التنفيذ المولد، يقارن المراجع الكود بالفعل المطلوب بدل مراجعة محادثة مفتوحة بلا حدود.
استخدم Skill للقواعد وMCP للدليل الحالي
تحل الأداتان مشكلتين مختلفتين. AI Agent Skill طبقة تعليمات مستقرة تشرح OAuth في زد، وعزل بيانات الدخول لكل متجر، والتعامل مع الأخطاء وحدود الطلبات والتشخيص. أما MCP فهو طبقة استرجاع تجلب سياق التوثيق داخل الأدوات المتوافقة. تقول المهارة للوكيل كيف يفكر، ويساعده MCP على معرفة ما تقوله الوثائق الحالية.
عامل النص المسترجع كدليل لا كسلطة تنفيذ. يجب أن يذكر الوكيل صفحة التوثيق الدقيقة لكل عملية بعيدة، ويسجل تاريخ التحقق. إذا لم يجد MCP Endpoint مطابقًا، فالنتيجة الصحيحة فجوة موثقة، لا Route مخترع. وإذا اختلفت المهارة مع التوثيق الحي، تقول زد إن التوثيق الحي هو المرجع.
أنشئ Evidence Manifest أثناء التخطيط: اسم العملية، ورابط المصدر، وتاريخ التحقق، وMethod، وPath، وScopes، وHeaders، وملاحظات Pagination أوRate Limit، والأسئلة غير المحسومة. يدخل هذا الملف في Code Review وفحوص الانحراف لاحقًا. كما يمنع خطأ شائعًا: أن يسترجع الوكيل الصفحة الصحيحة ثم يكتب الكود من ذاكرته العامة.
اجعل الاسترجاع ضيقًا. حمّل مرجع OAuth لأعمال التثبيت أوRefresh، وصفحة Endpoint للمورد المطلوب، وصفحة Rate Limiting لسلوك الطابور. وضع شجرة التوثيق كلها في Context يزيد الضوضاء ويصعّب رؤية التعارض. Progressive Disclosure أكثر موثوقية من Context ضخم غير منظم.
عامل بيانات دخول زد كحد Tenant
تشرح وثائق Authorization في زد تدفق Authorization Code، وتطلب عمومًا قيمتين مختلفتين في Merchant API: `Authorization` و`X-Manager-Token`. يمنح Authorization Token الوصول إلى API، بينما يحدد Manager Token متجرًا بعينه. وتذكر الصفحة أن Backend يجب أن يحتفظ بـClient Secret، وأن حذف التاجر للتطبيق يبطل Tokens.
لا تضع القيمتين في حقل عام اسمه `api_token`. خزّن Credential Envelope مشفرة ومربوطة بالـTenant الداخلي وهوية تثبيت زد أوالمتجر الثابتة. افصل نوع Token والقيم المشفرة ووقت الانتهاء والصلاحيات وحالة التثبيت وآخر تحقق. وعلى Worker حل بيانات الدخول من Tenant Context الموجودة في Job؛ لا تسمح للCaller بتمرير Store Token عشوائي مع المهمة.
استخدم Database Constraints لمنع ربط Installation واحدة بصمت مع Tenantين. وأدخل Tenant وInstallation IDs في Cache Keys وQueue Payloads وRate-limit Buckets وسجلات Idempotency. سجل مراجع Credentials لا قيمها. وعند Uninstall، ضع التثبيت في حالة Revoked قبل جدولة التنظيف حتى لا يستمر Worker باستخدام نسخة مخبأة.
يحتاج Token Refresh إلى Single-flight Control. عندما تلاحظ Workers متعددة قرب الانتهاء، تنفذ واحدة Refresh وتنتظر الأخريات ارتفاع Credential Version. استبدل القيمتين Atomically واحتفظ بسجل قصير للانتقال دون Plaintext. وإذا كانت نتيجة Refresh مجهولة، استرجع أو أعد المحاولة فقط وفق عقد OAuth الموثق؛ ولا تسمح لWorkers متوازية بكتابة Credentials أقدم فوق الأحدث.
مرّر الوكيل عبر مراحل قابلة للمراجعة
افصل Discovery عن Planning ثم Implementation وVerification. في مرحلة الاكتشاف يعيد الوكيل Evidence Manifest فقط. وفي التخطيط يربط الحقول البعيدة بالموديل الداخلي، ويصنف عمليات القراءة والكتابة، ويحدد حدود Retry وIdempotency. بعد ذلك فقط يولد الكود.
لعمليات الكتابة، ضع Approval Boundary يملكها التطبيق. يستطيع الوكيل اقتراح Payload، لكن Service حتمية تتحقق من Tenant والعملية والصلاحية وResource ID وIdempotency Key قبل الإرسال. لا تجعل عمليات حساسة مثل Refund أوتغيير الحالة أوكتابة المخزون أوPromotion جماعية متاحة عبر أداة عامة اسمها “call Zid API”. اعرض أدوات ضيقة لها Schemas واضحة وأقل Credentials تكفيها.
يجب أن تنفذ طبقة التشغيل عقد Adapter واحدًا بغض النظر عن الوكيل:
plan -> validate evidence -> build typed request -> authorize tenant
-> acquire store rate-limit permit -> send -> record sanitized result
-> verify postcondition or mark outcome unknownلا تعطِ النموذج Client Secrets أوMerchant Tokens الخام. تحمل Tool Input مرجع Credential آمنًا للTenant، ويحلّه الخادم. ويجب أن تحذف Tool Output الـHeaders والبيانات التجارية الشخصية قبل عودتها إلى AI Context. وينطبق ذلك على Traces وScreenshots وError Bodies.
اجعل Rate Limits وRetries جزءًا من التصميم
تذكر وثائق Rate Limiting الحالية في زد حدًا قدره 60 طلبًا في الدقيقة لكل Application ولكل Store، وتشرح Leaky Bucket. عامل هذا الرقم كعقد حي يجب التحقق منه، لا كثابت أبدي مخفي في الكود. ضعه في Provider Configuration مع Verification Date وسياسة Burst محافظة.
خصص Request Budget واحدة لكل App وStore، لا Counter عالميًا ولا Counter لكل Worker. يجب أن يمنع Fair Scheduler متجرًا نشطًا من تأخير بقية المتاجر، وفي الوقت نفسه يمنع Workers المتوازية للمتجر نفسه من تجاوز Bucket. قد تحتاج قراءات User-facing إلى أولوية أعلى من Reconciliation أوAnalytics، لكن كل الأولويات تستهلك من ميزانية المتجر نفسها.
أعد فقط الأخطاء المؤقتة واحترم إرشادات الخادم. `401` يحتاج تشخيص Credential أوRefresh مضبوط، لا Retry مفتوحة. و`403` يعني غياب Permission لدى التطبيق أوالتاجر. أما Validation Failure فتحتاج إصلاح Payload. و`429` تعود إلى طابور Rate Limit الخاص بالمتجر مع Jitter ومحاولات محدودة. وبعد Write ذات نتيجة مجهولة، اقرأ المورد أو افحص سجل Idempotency قبل الإرسال من جديد.
قس Queue Age وعدد الطلبات لكل متجر ونسبة 429 والتزاحم على Refresh وعمر التوثيق ونسبة رفض الكود المولد وفشل Contract Tests. تكشف هذه المقاييس هل يوفر AI وقتًا هندسيًا من دون إخفاء مخاطر التشغيل.
اختبر الكود المولد ضد Fixtures والانحراف
يمكن للوكيل كتابة Draft مفيدة، لكن الاختبارات تحدد هل يطابق Adapter العقد. ابنِ Fixtures من أمثلة التوثيق واستجابات Sandbox مضبوطة بعد إزالة البيانات الحساسة. اختبر غياب الحقول الاختيارية، وتغيير ترتيب Arrays، وEnum غير معروفة، وCredentials منتهية أوتابعة لمتجر آخر، وPagination غير صحيحة، وThrottling. اجعل Parser متسامحًا مع الحقول الإضافية مع تثبيت Invariants المطلوبة.
أضف Contract Tests للHeaders الدقيقة دون تسجيل قيمها. اختبر أن Tenant Resolver لا يستطيع تحميل Credential متجر آخر، وأن Secrets لا تظهر في Logs، وأن Uninstall يمنع Jobs جديدة. وفي Writes اختبر Duplicate Delivery وTimeout بعد Commit بعيد وRetry بعد نتيجة مجهولة.
يحتاج Documentation Drift إلى فحص مجدول، لا إعادة كتابة إنتاج تلقائية. استرجع الصفحات المسجلة في Evidence Manifest من جديد، وقارن حقول العقد المهمة، وافتح Review عند تغيرها. لا تعِد توليد Clients أوFixtures قبل تأكيد إنساني للMethod أوSchema أوScope الجديد. وتوضح AI Agent Skill نفسها أنها لا تضمن صحة كل إجابة، ولا تستبدل Security Review أوIntegration Testing.
القرار العملي
قيمة Zid AI Agent Skill وخادم MCP أنهما يقللان المسافة بين سؤال المطور وسياق التكامل الرسمي. وتظهر فائدتهما الحقيقية داخل نظام منضبط: عقد مهمة محدود، ودليل من مصدر حي، وحل آمن لبيانات الدخول لكل Tenant، وأدوات ضيقة، وميزانية Rate Limit مشتركة، وContract Tests قابلة للتنفيذ.
لا تقِس النجاح بعدد أسطر الكود التي ولّدها الوكيل. قِسه بسرعة قدرة الفريق على إثبات أن المتجر الصحيح والEndpoint والصلاحيات والHeaders وقواعد الفشل وPostconditions ممثلة كما يجب. دع الوكيل يسرّع الاسترجاع وDraft؛ ودع الضوابط الحتمية والاختبارات تقرر ما يصل إلى Production.
المراجع الرسمية
تدعم هذه المراجع سلوك الأدوات المذكورة. الأمثلة وقرارات التصميم توضيحية، ويجب تكييفها مع متطلبات المشروع وإصداراته.
إعداد: Noor Yasser
تعمل على تحدٍ تقني مشابه؟
أساعد الفرق على تحويل القرار المعماري إلى نطاق واضح وتنفيذ يمكن تشغيله ومراجعته بثقة.
