واجهة مستندات WhatsApp: ابنِ سير العمل حول ملف PDF

إرسال ملف PDF سهل. أما إدارة العملية التجارية المحيطة به فليست كذلك.

توضح وثائق Meta الحالية لرسائل المستندات كيف ترسل منصة WhatsApp Business مستنداً بوصفه كائن وسائط. وفي يوليو 2026 أعلنت Meta أيضاً أن المستخدمين يستطيعون فتح ملفات PDF مباشرة داخل WhatsApp، وإضافة تظليل أو تعليقات بسيطة عبر الويب وتطبيق سطح المكتب (تحديث WhatsApp من Meta في يوليو 2026). هذه تحسينات مفيدة، لكنها لا تخبر فريق العمليات أي نسخة هي المرجع، أو من يملك الملف المعاد، أو ما الذي يعني أن المعاملة اكتملت.

هذا هو جوهر سير عمل موثوق لـ WhatsApp document API: الرسالة تنقل الملف، بينما ينقل نموذج التشغيل الحالة إلى نتيجة مؤكدة. يبني هذا الدليل ذلك النموذج من دون افتراض أن تسليم الرسالة أو قراءتها يثبت أن المستلم راجع المستند.

1. افصل نقل المستند عن اكتمال المعاملة

تجيب طبقة المنصة عن سؤال ضيق: هل يمكن إرسال رسالة مستند إلى هذا المستلم ضمن سياق المحادثة الصحيح؟ توفر وثائق Meta طلباً لرسالة مستند وتدعم وصفاً واسم ملف (رسائل المستندات لدى Meta). أما طبقة العمل فعليها الإجابة عن بقية الأسئلة:

• هل هذا هو الملف الصحيح لهذا العميل ولهذا الغرض؟
• هل هي النسخة المعتمدة الحالية؟
• هل يجوز أن يتلقى المستلم الملف عبر هذه القناة؟
• من يملك الأسئلة أو التصحيحات أو النسخة المعادة؟
• ما الحدث الذي يغلق الحالة؟
• متى تنتهي صلاحية الملف ومسار الوصول إليه؟

اعتبار sent مساوياً لـ complete يختزل الأسئلة الستة في حدث نقل واحد. التصميم الأفضل يستخدم سجلين مترابطين: سجل رسالة لتسليم القناة، وحالة مستند لنتيجة العمل. قد تفشل الرسالة أو تُسلَّم أو تُقرأ، بينما قد تنتظر الحالة المراجعة أو تحتاج إلى تصحيح أو تستقبل نسخة منقحة أو تجتاز التحقق أو تُغلق.

يمنع هذا الفصل أيضاً خطأ شائعاً في القياس. إيصال القراءة يتعلق برسالة WhatsApp، ولا يثبت أن ملف PDF فُتح أو فُهم أو عُلّق عليه أو وُقّع أو قُبل. لا تسجل إلا النتيجة التي يستطيع نظامك ملاحظتها فعلاً.

2. امنح كل حالة مستند هوية ثابتة

أنشئ سجلاً دائماً للحالة قبل استدعاء الواجهة البرمجية. ينبغي أن يتضمن على الأقل:

• document_case_id — هوية ثابتة لعملية العمل
• contact_id — هوية المستلم في نظام العملاء الخاضع للحوكمة
• document_type — فاتورة أو عرض سعر أو تجديد أو طلب أو فئة أخرى مضبوطة
• document_version — النسخة غير القابلة للتغيير في هذه المحاولة
• purpose — سبب استحقاق هذا الشخص استلام الملف
• owner_id — الشخص أو قائمة الانتظار المسؤولة عن الإجراء التالي
• state — حالة العمل الحالية، مستقلة عن تسليم الرسالة
• source_hash — فحص سلامة الملف نفسه إذا كانت سياسة الأمن تستخدمه
• retention_class — قاعدة الاحتفاظ والحذف المعتمدة
• message_id — هوية رسالة القناة بعد الإرسال

لا تستخدم اسم الملف بوصفه هوية للحالة. قد يشير renewal.pdf إلى عملاء ونسخ كثيرة. اسم الملف للعرض، أما document_case_id وdocument_version فهما للضبط.

نموذج حالة عملي هو: draft، ثم approved_to_send، وsent، وdelivered، وwaiting_for_customer، وrevision_received، وneeds_correction، وverified، وcompleted، وexpired. يمكنك تقليل الحالات، لكن يجب أن تصف كل واحدة قراراً يغيّر الملكية أو الإجراءات المسموح بها.

3. نفّذ فحصاً مسبقاً من سبع بوابات

يجب أن يكون الإرسال آخر خطوات التحضير لا أولها. قيّم هذه البوابات بالترتيب:

1. الغرض: يطابق الملف والرسالة المصاحبة طلب العميل الموثق أو الغرض التجاري المسموح.
2. المستلم: تتطابق جهة الاتصال ورقم الهاتف مع الشخص المقصود؛ ويؤدي أي غموض إلى مراجعة.
3. النسخة: تشير الحالة إلى الملف المعتمد غير القابل للتغيير، لا إلى مسار متغير اسمه «الأحدث».
4. التعرض: يتوافق رابط الوسائط ومدة الاحتفاظ مع سياسة الأمن، ولا يبقى الوصول عاماً أكثر من اللازم.
5. العرض: اسم الملف والوصف واضحان ولا يحتويان ملاحظات داخلية أو معرفات حساسة بالخطأ.
6. قاعدة المحادثة: يستخدم السير مسار الرسالة الحرة أو القالب المعتمد المناسب لنافذة خدمة WhatsApp الحالية.
7. الملكية: يوجد شخص أو فريق محدد جاهز لمعالجة السؤال أو الاستبدال أو المستند المعاد.

يعرض مرجع DripTell الحالي المسار POST /api/v1/send/media لإرسال صورة أو فيديو أو صوت أو مستند أو ملصق من رابط HTTPS عام، مع وصف اختياري واسم للمستند (وثائق مطوري DripTell). يصبح هذا المسار مفيداً بعد اجتياز البوابات السبع فقط. الطلب الصحيح تقنياً ليس بالضرورة قراراً تجارياً صحيحاً.

احفظ نتيجة الفحص بأسباب مثل wrong_recipient أو unapproved_version أو expired_link أو window_closed أو no_owner. بذلك يصبح عدم الإرسال قابلاً للتفسير وإعادة المحاولة، لا حدثاً خفياً.

4. اجعل الإرسال الصادر آمناً عند التكرار

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

أنشئ مفتاح idempotency من الحالة والنسخة والمستلم والإجراء المقصود، مثل case_482:v3:send_for_review. قبل الإرسال، افحص ما إذا كان لهذا الإجراء هوية رسالة ناجحة. إن وُجدت، أعد النتيجة الحالية. وإن لم توجد، أرسل مرة واحدة واحفظ هوية الرسالة بجانب نسخة المستند الدقيقة.

ثم عالج حالة التسليم بصورة مستقلة. يحمل نموذج webhook لدى Meta تحديثات حالة الرسائل وكائنات الرسائل الواردة (مكوّنات webhook في Meta Cloud API). استخدم الأحداث لتحديث حالة النقل، لكن أبقِ حالة العمل محافظة:

• sent يعني أن المنصة قبلت محاولة الإرسال؛
• delivered يعني أن الرسالة وصلت إلى جهاز المستلم وفق حدث القناة؛
• read يعني أن الرسالة عُلّمت مقروءة، لا أن المستند روجع؛
• failed يعني أن النقل يحتاج إلى إعادة مدروسة أو مسار آخر معتمد.

لا تنشئ نسخة مستند جديدة لمجرد فشل التسليم. يجب أن تعكس النسخة تغيراً في المحتوى، لا إعادة محاولة القناة.

5. تعامل مع ملف PDF المعاد بوصفه دليلاً جديداً

المسار الوارد يحتاج إلى تصميم بقدر المسار الصادر. يعرض مرجع DripTell الحالي POST /api/send/media/fetch لاسترجاع وسائط واردة من جهة اتصال على WhatsApp. يجب أن تنتمي الوسائط إلى مساحة العمل نفسها المرتبطة بمفتاح bearer، ويمكن تحديدها بهوية رسالة أو وسيط (وثائق مطوري DripTell).

عندما يصل مستند:

1. اربط هوية الرسالة الواردة بالحالة المفتوحة فقط عندما تتطابق جهة الاتصال والحالة المتوقعة؛
2. استرجعه عبر مسار خادم خاضع للحوكمة، لا من شيفرة متصفح أو سر في عميل عام؛
3. افحص نوع الملف وحجمه وسلامته وفق الضوابط المعتمدة في مؤسستك؛
4. خزّنه ككائن دليل جديد غير قابل للتغيير، لا كاستبدال للأصل المرسل؛
5. سجل من نفذ الفحص أو النظام الذي نفذه والنتيجة؛
6. أسند الحالة إلى المراجع الصحيح مع مهلة؛
7. أكد الاستلام من دون الوعد بالقبول قبل المراجعة.

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

6. حافظ على النسخ بدلاً من استبدال التاريخ

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

استخدم سلسلة بسيطة:

source_v3 → sent_copy_v3 → customer_annotation_1 → approved_final_v3

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

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

7. مثال: حزمة تجديد عقد إيجار

تخيل مدير عقار يرسل حزمة تجديد. تُنشأ الحالة بهوية المستأجر ومرجع العقار ونسخة PDF المعتمدة والغرض والمالك وموعد الرد. يؤكد النظام المستلم الصحيح ومسار المحادثة المسموح ورابط الوسائط المضبوط واسم الملف الواضح وتوفر مالك للحالة.

بعد الإرسال تحدّث أحداث النقل سجل الرسالة. تنتقل الحالة إلى waiting_for_customer بعد التسليم، ولا تنتقل إلى completed عند قراءة الرسالة. يعيد المستأجر ملفاً معلقاً عليه وسؤالاً عن بند. يصبح الملف customer_annotation_1، ويوجَّه إلى قائمة فريق العقار، وتنتقل الحالة إلى needs_correction أو needs_answer.

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

الميزة المهمة هي قابلية التفسير. يستطيع الموظف في أي لحظة أن يجيب: أي ملف أُرسل، ولمن، ولماذا، وماذا عاد، ومن يملكه، وما الحدث الناقص؟

8. قِس المسار الذي تستطيع إثباته

ابنِ المقاييس على طبقات بدلاً من «معدل تحويل PDF» مضلل.

مقاييس النقل: قبول الإرسال والتسليم والقراءة والفشل وسبب الفشل. هذه تصف القناة.

مقاييس سير العمل: الزمن من التسليم إلى أول رد، ومن إعادة الملف إلى إسناده، ومدة الاستثناء، وعدد النسخ، ونسبة اجتياز التحقق، والزمن حتى الاكتمال المؤكد. هذه تصف العملية.

ضوابط الجودة: نسبة الإرسال المكرر، وحوادث النسخة الخاطئة، والملفات الواردة غير المطابقة، ومحاولات الروابط المنتهية، والحالات من دون مالك، ونسبة إعادة الفتح. هذه تكشف ضعف النظام.

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

9. طبّق سير العمل في DripTell

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

طبّق مفاتيح API محددة بمساحة العمل، وأقل قدر من الصلاحيات، وضوابط الاحتفاظ في مؤسستك. يصف ملخص أمان DripTell عزل مساحات العمل وضوابط الوصول، لكن نظامك يظل مسؤولاً عن تقرير المستندات التي يجوز إرسالها عبر WhatsApp، وكيف تُحمى روابط الوسائط العامة، ومدة الاحتفاظ بالأدلة.

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

إذا أردت تحويل تبادل PDF قائم إلى سير عمل ذي ملكية وقياس، احجز عرضاً توضيحياً لـ DripTell ومعك نوع مستند حقيقي وقاعدة اعتماده والحدث الذي ينبغي أن يغلق الحالة.