تكامل واجهة برمجة تطبيقات واتساب للأعمال: دليل التجارة الإلكترونية البرازيلية 2026

تعتمد التجارة الإلكترونية البرازيلية على أربع منصات مهيمنة: VTEX (للشركات المتوسطة والكبيرة)، Tray (للشركات الصغيرة والمتوسطة إلى المتوسطة)، Nuvemshop (للشركات الصغيرة والمتوسطة)، وLoja Integrada (للشركات الصغيرة والمتوسطة). تتطلب كل منصة نمط دمج محدد لربط واجهة برمجة تطبيقات واتساب للأعمال لاستعادة السلة المتروكة، وتأكيد الطلب، وتحديثات الشحن، وتسليم الفاتورة الإلكترونية (NF-e)، والدفع عبر Pix داخل محادثة واتساب. يستعرض هذا الدليل إعداد الموصل الأصلي لجميع المنصات البرازيلية الأربع بالإضافة إلى Shopify Brasil وWooCommerce، مع أمثلة برمجية وتخطيط حدث بحدث.

إجابة سريعة: كيف تندمج واجهة برمجة تطبيقات واتساب للأعمال مع منصات التجارة الإلكترونية البرازيلية؟

بالنسبة لمنصات التجارة الإلكترونية البرازيلية الأربع المهيمنة، تتولى الموصلات الأصلية عبر Message Central التابعة لـ WhatsAppNow عملية الدمج من البداية إلى النهاية: VTEX عبر تطبيق VTEX IO، وTray عبر جسر خطاف الويب REST، وNuvemshop عبر دمج متجر التطبيقات، وLoja Integrada عبر واجهة برمجة تطبيقات مباشرة. يتلقى الموصل أحداث المنصة (سلة متروكة، طلب تم إنشاؤه، دفع مؤكد، تم الشحن) ويشغل قوالب واتساب بالإضافة إلى توليد رسوم Pix وفقًا لذلك. يستغرق الإعداد عادةً من 2 إلى 5 أيام عمل. بالنسبة للمنصات التي لا تحتوي على موصل أصلي (Shopify Brasil، WooCommerce، Magento المخصص)، فإن دمج واجهة برمجة تطبيقات REST مع جسر خطاف الويب هو المسار القياسي — ويستغرق عادةً من أسبوع إلى أسبوعين من العمل الهندسي. اطلع على منصة واجهة برمجة تطبيقات واتساب للأعمال في البرازيل.

منصات التجارة الإلكترونية البرازيلية الأربع المهمة

VTEX

منصة تجارة إلكترونية برازيلية المنشأ تتمتع بأكبر بصمة في الشركات الكبيرة والمتوسطة في البرازيل. تستخدمها Magazine Luiza، Coca-Cola، Walmart Brasil، Whirlpool، والعديد من العلامات التجارية الكبرى. مبنية على VTEX IO (منصة تطوير قائمة على TypeScript) مع قدرة التجارة اللارأسية الكاملة. موصل واتساب الأصلي عبر تطبيق VTEX IO متاح عبر Message Central. الأنسب لتجار التجزئة البرازيليين من الشركات المتوسطة إلى الكبيرة.

Tray

منصة تجارة إلكترونية برازيلية مملوكة لـ Locaweb، تركز على الشركات الصغيرة والمتوسطة إلى المتوسطة. دمج قوي متعدد القنوات مع الأسواق (Mercado Livre، Amazon Brasil). واجهة برمجة تطبيقات REST لاشتراكات أحداث المنتج والطلب والسلة. موصل واتساب الأصلي عبر Message Central عن طريق جسر خطاف الويب. الأنسب للمتاجر الإلكترونية البرازيلية من الشركات الصغيرة والمتوسطة إلى المتوسطة.

نوفيمشوب

منصة تجارة إلكترونية SaaS تركز على أمريكا اللاتينية (سابقًا Tiendanube)، تتمتع بحضور قوي في الأرجنتين والبرازيل. نظام بيئي لمتجر التطبيقات يضم مئات من عمليات التكامل الأصلية. موصل واتساب متاح عبر Message Central كتطبيق Nuvemshop. الأنسب للبائعين من الشركات الصغيرة والمتوسطة في أمريكا اللاتينية الذين يعملون في عدة بلدان.

لوجا إنتغرادا

منصة تجارة إلكترونية برازيلية للشركات الصغيرة والمتوسطة مع استراتيجية قوية للطبقة المجانية. مئات الآلاف من المتاجر البرازيلية النشطة. واجهة برمجة تطبيقات REST لأحداث سلة التسوق والطلبات. تكامل مباشر مع Message Central. الأنسب للبائعين البرازيليين من الشركات الصغيرة والمتوسطة والشركات متناهية الصغر.

تكامل VTEX مع واجهة برمجة تطبيقات واتساب للأعمال

تطبيقات VTEX IO هي المسار الموصى به للتكامل مع واجهة برمجة تطبيقات واتساب للأعمال. يوفر Message Central تطبيق VTEX IO منشورًا يتعامل مع تدفق الأحداث القياسي:

• حدث سلة التسوق المهجورة (من إعدادات نموذج الطلب): يشغل تسلسل استرداد واتساب بثلاث لمسات (ساعة واحدة، 24 ساعة، 72 ساعة)
• حدث إنشاء الطلب: يشغل قالب تأكيد الطلب عبر فئة أدوات واتساب
• حدث تأكيد الدفع: يشغل إيصال الدفع + قالب تسليم NF-e
• حدث شحن الطلب: يشغل قالب رمز التتبع مع تقدير التسليم
• حدث تسليم الطلب: يشغل طلب NPS أو مراجعة بعد تأخير 72 ساعة

الإعداد: انظر وثائق مطوري VTEX.

تكامل Tray مع واجهة برمجة تطبيقات واتساب للأعمال

يستخدم Tray اشتراكات الويب هوك للتكامل القائم على الأحداث. يوفر Message Central جسر ويب هوك يستمع لأحداث Tray ويشغل قالب واتساب المناسب:

• اشترك في ويب هوكس Tray من أجل: order_created, order_paid, order_shipped, order_delivered, cart_abandoned (حسب دعم خطة Tray الخاصة بك)
• قم بتكوين نقطة نهاية الويب هوك وسر التوقيع الخاص بـ Message Central في لوحة تحكم Tray
• اربط كل حدث بقالب باللغة البرتغالية البرازيلية معتمد من Meta
• اختبر باستخدام طلبات بيئة الاختبار (sandbox) قبل الإطلاق المباشر

وقت الإعداد: 1-2 أيام عمل لربط الأحداث القياسي. تضيف التدفقات المخصصة (منطق تجزئة محدد، محفزات البيع الإضافي) 2-3 أيام أخرى.

تكامل Nuvemshop مع واجهة برمجة تطبيقات واتساب للأعمال

تعتمد Nuvemshop نموذج متجر التطبيقات.

• ثبّت تطبيق Message Central WhatsApp Now من متجر تطبيقات Nuvemshop
• امنح الأذونات المطلوبة (قراءة الطلبات، قراءة العملاء، قراءة المنتجات، إرسال الإشعارات)
• قم بتكوين مفتاح واجهة برمجة تطبيقات واتساب للأعمال من لوحة تحكم Message Central
• اختر أي قوالب باللغة البرتغالية البرازيلية يتم تشغيلها عند أي أحداث Nuvemshop
• تفعيل — الإطلاق المباشر عادةً في غضون 1-2 يوم

بالنسبة لمتاجر Nuvemshop الأرجنتينية والمكسيكية والكولومبية، يدعم نفس الموصل توجيه واتساب متعدد البلدان باستخدام معرفات مرسل محلية.

تكامل Loja Integrada مع واجهة برمجة تطبيقات واتساب للأعمال

توفر Loja Integrada واجهة برمجة تطبيقات REST لأحداث الطلبات والسلة. التكامل مع واجهة برمجة تطبيقات واتساب للأعمال من Message Central:

• أنشئ مفتاح واجهة برمجة تطبيقات Loja Integrada في لوحة الإدارة
• قم بتكوين موصل Message Central باستخدام بيانات اعتماد Loja Integrada
• اربط أحداث الطلبات/السلة بقوالب واتساب
• بالنسبة للسلة المتروكة، قم بتكوين توقيت تسلسل الاسترداد (ساعة واحدة، 24 ساعة، 72 ساعة)
• لتأكيد الطلب، أرفق إنشاء فاتورة Pix للطلبات غير المدفوعة

عادةً ما تبدأ متاجر Loja Integrada للشركات الصغيرة والمتوسطة العمل في غضون يوم إلى يومين. قد تحتاج المتاجر ذات الحجم الأكبر إلى موافقة على قالب مخصص (دورة موافقة Meta تستغرق 4 ساعات عبر الفحص المسبق لـ Message Central).

تكامل شوبيفاي البرازيل و ووكومرس

للشركات البرازيلية التي تستخدم شوبيفاي أو ووكومرس، تكامل REST API هو الحل:

شوبيفاي البرازيل

استخدم خطافات الويب (Webhooks) الخاصة بشوبيفاي للأحداث التالية: checkouts/create, checkouts/update, orders/create, orders/paid, orders/fulfilled. قم بتكوين نقطة نهاية HTTPS في واجهة برمجة تطبيقات Message Central التي تستقبل حمولة شوبيفاي وتحولها إلى إرسال قالب واتساب. يدعم شوبيفاي البرازيل التسعير بالريال البرازيلي (BRL) ويتكامل مع مزودي خدمات الدفع البرازيليين (Mercado Pago, PagSeguro) لخدمة Pix.

ووكومرس

استخدم واجهة برمجة تطبيقات REST الخاصة بووكومرس + اشتراكات خطاف الويب (webhook). يلزم وجود جسر خطاف ويب مخصص إذا لم يكن هناك مكون إضافي لـ Message Central لـ ووكومرس متاحًا. العمل الهندسي النموذجي: 1-2 أسبوع.

خريطة التكامل لكل حدث

لجميع المنصات، التعيين القياسي من الحدث إلى واتساب:

سلة متروكة (بعد ساعة واحدة): قالب تسويقي، تذكير لطيف، بدون خصم. يتضمن صورة المنتج وزر للعودة إلى السلة بنقرة واحدة.

سلة متروكة (بعد 24 ساعة): قالب تسويقي بخصم 5-10% أو شحن مجاني. خيار إنشاء فاتورة Pix في نفس المحادثة.

سلة متروكة (بعد 72 ساعة): قالب تسويقي بخصم نهائي 10-15%. آخر تواصل، لا توجد رسائل أخرى بعد هذا لهذه السلة المحددة.

تم إنشاء الطلب (غير مدفوع): قالب خدمي مع ملخص الطلب ورسوم Pix للدفع.

تم تأكيد الدفع: قالب خدمي يتضمن إيصال الدفع ورقم الطلب وتاريخ التسليم المتوقع.

تم إنشاء NF-e: قالب خدمي يتضمن مرفق NF-e بصيغة PDF أو رابط تنزيل.

تم شحن الطلب: قالب خدمي يتضمن اسم شركة الشحن ورمز التتبع وتاريخ التسليم المقدر.

تم تسليم الطلب: فئة الخدمة، طلب NPS أو مراجعة بعد التسليم (بعد تأخير 24-72 ساعة).

اعتبارات LGPD والموافقة على القوالب

يتوافق كل نوع حدث مع فئة محادثة Meta ذات متطلبات LGPD مختلفة:

• رسائل سلة التسوق المهجورة: فئة التسويق — تتطلب موافقة صريحة على الاشتراك في واتساب بموجب LGPD
• تأكيد الطلب، إيصال الدفع، الشحن، NF-e: فئة خدمية — تندرج تحت الأساس القانوني لتنفيذ العقد، ولا تتطلب موافقة اشتراك منفصلة
• طلب NPS/مراجعة: فئة خدمية إذا كان ضمن نافذة 24 ساعة، وتسويقية إذا كان خارجها (يتطلب موافقة اشتراك)

اطلع على دليل الامتثال لـ LGPD في واتساب للأعمال.

أخطاء شائعة في التكامل

الخطأ الأول: إرسال رسائل سلة التسوق المهجورة دون الحصول على موافقة واتساب

‍الموافقة على تلقي رسائل البريد الإلكتروني لا تغطي واتساب بموجب قانون حماية البيانات العامة (LGPD). الحل: احصل على موافقة واتساب عند الدفع (مربع اختيار غير محدد مسبقًا).

الخطأ الثاني: الخلط بين فئات الخدمات والتسويق

‍إرسال عرض ترويجي في قالب خدمات يتم رفضه من قبل ميتا ويضر بتقييم الجودة. الحل: احتفظ بالمحتوى المتعلق بالمعاملات في فئة الخدمات، والترويجي في فئة التسويق.

الخطأ الثالث: عدم تطبيق خاصية الثبات (idempotency) على معالج الويب هوك

‍إعادة محاولات الويب هوك من VTEX، Tray، Nuvemshop يمكن أن تشغل نفس الحدث عدة مرات. الحل: تطبيق مفاتيح الثبات (idempotency keys).

الخطأ الرابع: إرسال NF-e فور تأكيد الدفع

‍تتم تسوية Pix في ثوانٍ، لكن قد لا يكون قسم التنفيذ قد سجل الطلب بعد. الحل: فترة انتظار من 30 إلى 60 ثانية.

مراجع خارجية

وثائق مطوري VTEX. وثائق API لـ Tray Brazil. وثائق مطوري Nuvemshop. وثائق واجهة برمجة تطبيقات واتساب السحابية من Meta. مواصفات Pix من BACEN.

الأسئلة الشائعة

كم يستغرق تكامل واجهة برمجة تطبيقات واتساب للأعمال مع منصات التجارة الإلكترونية البرازيلية؟

بالنسبة للمنصات البرازيلية الأربع الرئيسية التي تحتوي على موصلات مدمجة، يستغرق التكامل عادةً من 2 إلى 5 أيام عمل. VTEX عبر تطبيق VTEX IO: من 2 إلى 3 أيام. Tray عبر جسر الويب هوك: من يوم إلى يومين. Nuvemshop عبر متجر التطبيقات: من يوم إلى يومين. Loja Integrada عبر واجهة برمجة تطبيقات REST: من يوم إلى يومين. أما المنصات التي لا تحتوي على موصل مدمج (Shopify Brasil، WooCommerce، Magento المخصص) فتستغرق عادةً من أسبوع إلى أسبوعين من العمل الهندسي.

ما هي منصات التجارة الإلكترونية البرازيلية التي تدعم التكامل الأصلي لواجهة برمجة تطبيقات واتساب للأعمال؟

تدعم المنصات البرازيلية الأربع الرائدة جميعها التكامل الأصلي لـ واجهة برمجة تطبيقات واتساب للأعمال: VTEX، Tray، Nuvemshop، و Loja Integrada. يتم دعم Shopify Brasil و WooCommerce عبر تكامل واجهة برمجة تطبيقات REST (يتطلب جسر ويب هوك مخصص). يمكن للمنصات الأخرى (Vnda، Linx، تطويرات Magento المخصصة) التكامل عبر أنماط الويب هوك + واجهة برمجة تطبيقات REST.

هل أحتاج إلى موافقة LGPD منفصلة لرسائل السلة المتروكة مقابل تأكيد الطلب؟

نعم لرسائل السلة المتروكة، لا لتأكيد الطلب. تصنف Meta رسائل السلة المتروكة على أنها فئة تسويقية وتصنفها LGPD كتسويق مباشر، مما يتطلب موافقة صريحة على واتساب. أما تأكيد الطلب، وإيصال الدفع، وإشعار الشحن، وتسليم NF-e فهي فئة خدماتية بموجب الأساس القانوني لتنفيذ العقد، ولا تتطلب موافقة منفصلة.

هل يمكنني دمج مدفوعات Pix داخل محادثة واتساب عبر منصة التجارة الإلكترونية الخاصة بي؟

نعم. بالنسبة للمنصات البرازيلية الأربع الرئيسية، تدعم تكاملات Message Central إنشاء فاتورة Pix داخل محادثة واتساب. عندما يستجيب العميل لرسالة سلة متروكة بنية الشراء، يقوم الموصل بتوليد رمز QR لـ Pix ورمز BR داخل المحادثة. يدفع العميل عبر تطبيقهم المصرفي وتتلقى منصة التجارة الإلكترونية تأكيد الدفع عبر ويب هوك مزود خدمة الدفع (PSP). راجع دليل مدفوعات Pix.

ما هو الجهد الهندسي النموذجي المطلوب لدمج واجهة برمجة تطبيقات واتساب للأعمال (WhatsApp Business API) مع VTEX؟

بالنسبة لـ VTEX، يستغرق الدمج عبر تطبيق Message Central WhatsApp IO من يومين إلى 3 أيام عمل بشكل كامل: قم بتثبيت التطبيق من متجر تطبيقات VTEX، وقم بتهيئة مفتاح API، وربط الحدث بالقالب (سلة متروكة، طلب تم إنشاؤه، دفع مؤكد، تم الشحن، تم التسليم)، واختبر باستخدام طلبات بيئة الاختبار، ثم ابدأ بالعمل. تضيف التدفقات المخصصة (منطق تجزئة محدد، محفزات البيع الإضافي، توجيه متعدد المتاجر) من يومين إلى 5 أيام عمل هندسي إضافية.

الخطوات التالية

لدمج واجهة برمجة تطبيقات واتساب للأعمال (WhatsApp Business API) مع منصة التجارة الإلكترونية البرازيلية الخاصة بك، ابدأ بـ صفحة منصة واجهة برمجة تطبيقات واتساب للأعمال في البرازيل. لدمج Pix لإتمام المبيعات داخل المحادثة، راجع دليل مدفوعات Pix. لاستراتيجية استعادة السلة المتروكة، راجع دليل استعادة السلة. لإعلانات "النقر للواتساب" (Click-to-WhatsApp Ads) لتغذية مسار مبيعاتك، راجع دليل إعلانات النقر للواتساب. للامتثال لقانون حماية البيانات الشخصية (LGPD)، راجع دليل LGPD.