التوثيقAPI v1
أقسام التوثيق

خطّط للتكامل

حوّل سير عملك إلى اتصال محدّد يمكنك تنفيذه ومراجعته.

ابدأ بمهمة واحدة

دوّن طلب العميل والنتيجة التي يحتاجها والنقطة التي يتدخّل فيها شخص. اجعل المهمة الأولى محدّدة بحيث يمكن مراجعتها من الرسالة الواردة إلى السجل النهائي.

هذا دليل تخطيط. يحتاج الاتصال إلى موصّل منفّذ وإعداد للبيئة وتحقّق من العمل. يشرح مرجع الواجهة عقود المنصة، ولا يعني وجود موصّل جاهز لكل نظام أعمال.

اربط المعلومة بمصدرها

يبقى نظام أعمالك المرجع لسجلاته. استخدم السجلات الحالية للحقائق المتغيّرة والمعرفة المراجعة للسياسات التي تدعمها. افصل بين هذه الأنواع المختلفة من الأدلة.

ما يحتاجه الطلبما الذي تحدّده؟
حالة حالية أو توفّرالنظام المرجعي وعملية القراءة المسموح بها
سياسة منشورةمصدرها المعتمد وإصدارها ومن يراجعها
تغيير سجل أعمالعملية محدّدة مسموح بها ونتيجتها المسجّلة
استثناء أو قرار تقديريالشخص المسؤول والسياق الذي يحتاجه

افصل القراءات عن الإجراءات

اكتب كل عملية تحتاجها المهمة ومدخلاتها ومخرجاتها ومن يحق له استدعاؤها. قراءة سجل لا تعني السماح بتعديله. صلاحيات مفتاح مساحة العمل وإمكانات الوكيل في الأعمال حدود منفصلة؛ اضبط كليهما وفق المهمة.

احتفظ بالمفاتيح على خادمك واستخدم البيئة المخصّصة. ابدأ بمسار قراءة فقط، ثم أضف الإجراء عندما يمكن اختبار صلاحياته ونتيجته.

خطّط للنتيجة غير المؤكّدة

قد يعني انتهاء المهلة أن العملية لم تبدأ أو اكتملت أو بقيت غير محسومة. لا تحوّله إلى تأكيد نجاح ولا تنشئ طلبًا جديدًا فورًا. احتفظ بهوية الطلب وافحص الحالة المسجّلة.

استخدم عقد منع التكرار الموثّق لنقطة الوصول عند إعادة المحاولة. بعد إرسال رسالة، افحص المحادثة ودورات المعالجة لمتابعة التنفيذ. تعني HTTP 202 قبول الإدخال، ولا تثبت إجراءً خارجيًا أو وصول الردّ.

راجع سير العمل كاملًا

قبل توسيع التجربة، اختبر الطلب مع مسؤول الأعمال والأشخاص الذين يتعاملون مع الاستثناءات. تحقّق من سجل الأعمال إلى جانب المحادثة.

الحالةما الذي تتحقّق منه؟
قراءة مسموح بهاتستند الإجابة إلى السجل الحالي المقصود
إجراء مسموح بهيطابق السجل الناتج العملية المطلوبة
صلاحية مفقودةيحترم الوكيل الحدّ ويوضّح الخطوة التالية
تكرار أو انتهاء مهلةتُراجع النتيجة قبل تنفيذ عملية أخرى
مراجعة بشريةيصل السياق الكافي إلى الشخص المناسب للمتابعة