تفاصيل المقال
الإجابة المختصرة: ربط سلة عبر API يعني إن نظامك المخصص يقدر يبادل الطلبات والمنتجات والمخزون وبيانات العملاء مع متجر سلة من خلال واجهات سلة الرسمية والإشعارات (webhooks)، من غير ما الفريق ينسخ البيانات بإيده. تطبيق جاهز ممكن يكفي لو التدفق بسيط وفي اتجاه واحد؛ التكامل المخصص يستاهل الدراسة لما يكون عندك مخزون أو محاسبة أو تنفيذ طلبات برة سلة، أو محتاج إعادة محاولة، مصدر حقيقة واحد، ومسؤول واضح عن الفاتورة الضريبية.
بقلم محمد سامي، مطور Backend أول متخصص في Laravel/PHP، بخبرة سبع سنوات. تاريخ النشر: 12 نوفمبر 2026. آخر تحديث: 12 نوفمبر 2026.
المقال ده مش استشارة ضريبية ولا قانونية، ومش بديل عن المستشار أو عن وثائق سلة الرسمية.
أغلب أصحاب المتاجر اللي بيتواصلوا معايا عندهم متجر سلة شغال في السعودية أو الخليج، ومعاه شيت مخزن أو ملف محاسبة أو لوحة تنفيذ طلبات مبقتش ماشية مع لوحة التحكم. سؤال التكلفة، تفضل على منصة جاهزة ولا تبني متجر إلكتروني مخصص، ده مقال تاني، ونفس الكلام على الاختيار الأسبق بين موقع شركة ومتجر إلكتروني ومنصة مستضافة. المقال ده بيفترض إنك هتفضل سلة واجهة المتجر، ومحتاج ربط سلة عبر API بشكل يعتمد عليه مع الأنظمة اللي شغّالة عندك أصلًا. Golden Code بتبني الطبقة المخصصة دي من الصفر؛ مش بنعيد بيع تطبيق سلة جاهز ولا بننشر سعر باقة ثابت.
ربط سلة عبر API بيعمل إيه فعلًا
سلة بتنشر واجهات التاجر (Merchant APIs) كـ REST تحت العنوان الرسمي https://api.salla.dev/admin/v2. الدخول بيحصل من خلال OAuth 2.0: التاجر يصرّح للتطبيق، السيرفر بتاعك يستلم توكن وصول بمدة محدودة، وكل طلب بيحمل ترويسة Authorization. الوثائق الرسمية بتقول إن توكن الوصول مدته 14 يوم، وإن توكن التجديد (لما يتطلب بصلاحية offline_access) ينفع استخدامه خلال شهر، وهو لمرة واحدة. التاجر يقدر بعد كده يفصل التطبيق من لوحة الشركاء. ده النموذج الرسمي. مش كلمة مرور مشتركة، ومش تصدير مرة واحدة. حدود معدل طلبات الـ API بتعتمد على باقة سلة عند التاجر؛ شوف توثيق تحديد المعدل للجدول الحالي.
| الجزء | اللي غالبًا بيتعطل دلوقتي | اللي الربط لازم يعمله |
|---|---|---|
| الطلبات | الموظف بينسخ التذكرة من سلة لشيت | الطلب المؤكد بيوصل مرة واحدة لنظامك |
| المخزون | قناتين تبيعوا نفس الوحدة | مصدر حقيقة واحد، مع اتجاه كتابة واضح |
| المنتجات | الأسعار والـ SKU بتختلف بين الأنظمة | صاحب كتالوج متفق عليه |
| العملاء | المشتري موجود مرتين بمجموعات مختلفة | هوية ثابتة، من خلال الـ endpoints الرسمية الحالية |
| المحاسبة | الزيارة تتقيد مرتين، أو متتقيدش | مسؤول واحد عن الفاتورة الضريبية الرسمية |
| الأعطال | إشعار ضاع واتكتشف بعد أسابيع | طابور، فحص توقيع، وتسوية يومية |
التطبيق الخاص بتاجر واحد، والتطبيق العام المعروض لمتاجر تانية، منتجين مختلفين. دليل سلة عن إنشاء أول تطبيق بيمشي معاك في بوابة الشركاء، تختار نوع عام أو خاص، وتاخد بيانات التصريح. لو هتنشر التطبيق، اطلب اسم بالإنجليزي والعربي. قائمة المتجر مش شرط لربط متجر واحد.
أسواق سلة الرسمية، وفين مصر لسه موجودة في الدليل
سلة منصة متاجر لتجار السعودية والخليج. التوفر الرسمي هو السعودية، والإمارات، والكويت، وقطر، والبحرين، وعمان. الدليل هنا بيبدأ بمتجر سعودي أو خليجي تاني. مصر ظاهرة هنا كشركات بتبيع في السعودية، أو بتنفّذ الطلب من مصر، أو كفرق مصرية بتشتغل لتاجر خليجي، مش كسوق تاجر معادل لسلة.
الشركات المصرية لسه محتاجة ربط سلة عبر API لما تبيع في السعودية، أو تنفّذ الطلب من مصر، أو أصلًا شغّالة على مخزون مخصص أو نظام ERP مخصص لازم يتكلم مع متجر سلة. فرق التطوير المصرية اللي بتشتغل لتاجر خليجي بتواجه نفس المشكلة. فكرة المنتج ممكن تتشارك؛ قواعد الضريبة والتحصيل والبيانات تفضل منفصلة لكل دولة.
لو بتنفّذ من مصر أو بتحتفظ بسجلات العملاء هناك، اوصف التشغيل ده بوضوح. المخزون ساكن فين فعلًا؟ مين بيأكد إن الطلب يقدر يتشحن؟ سجلات العملاء موجودة فين، وأنهي منها بيانات شخصية تحت قانون حماية البيانات الشخصية في مصر؟ أكّد الالتزامات مع مستشارك. ربط الإيصال الإلكتروني مع نقاط البيع وERP في مصر مسار ضريبي مصري منفصل، مش شرح لسلة أو لـ ZATCA؛ أكّد أي التزام مع المحاسب. الربط مش المفروض يخترع قاعدة عملاء تانية في شيت من غير حماية، ومش المفروض ينسخ حقول أنت مش محتاجها.
المدفوعات اللي بتحصل أصلًا جوه سلة مش بتتحول لوحدها لربط بوابة دفع تاني في تطبيقك. لو بعد كده ضفت صفحة دفع مخصصة أو تقرير تسويات، اعتبرها نطاق منفصل ومتحقق منه. المقال ده مش هيوعد ببناء بوابة دفع مش موجودة في الجرد.
تطبيقات سلة الجاهزة مقابل طبقة مخصصة
متجر تطبيقات سلة والواجهات الرسمية ممكن يغطوا حالة بسيطة: تبعت الطلبات المدفوعة لأداة محاسبة واحدة، أو تدفع المخزون من مخزن واحد. التطبيق الجاهز نظرة أولى معقولة لما شغلك يطابق اللي المورّد بيقدّمه أصلًا، وتقدر تصدّر بياناتك، وتقبل طريقة معالجة الأعطال عنده.
بيبقى اختيار ضعيف لما تلات أنظمة تحاول تبقى مصدر الحقيقة، أو لما استرجاع أو شحنة مجزأة متوصلش للمحاسبة، أو لما متقدرش تعرف إذا كانت طلبات إمبارح وصلت كلها ولا لأ. الشغل المخصص مش أحسن تلقائيًا. هتمتلك أنت الربط، والاستضافة، وتخزين التوكن، والمراقبة. ده يستاهل لما تقدر توصف الفجوة من أسبوع طلبات حقيقي، مش من أمنية إن يبقى عندك «منصة وسيطة كاملة».
لو بتؤتمت تسليم ضيق ومستقر أصلًا، دليلنا عن n8n مستضاف ذاتيًا مقابل السحابة مقابل كود مخصص عن الاختيار ده. بوت واتساب ذكاء اصطناعي مخصص للأعمال طبقة مراسلة؛ مش بديل عن مزامنة الطلبات والمخزون عبر API سلة. مسار بصري مش بديل عن استقبال طلبات بدون تكرار، وفحص توقيع، وتقرير تسوية لما الحجم أو قائمة الاستثناءات تكبر. عرض Golden Code هو المسار المخصص فقط. بعد جرد قصير نقدر نبعث لك عرضًا تقنيًا مخصصًا لربط سلة عبر API. مش بننشر باقة ثابتة.
الإشعارات والـ API والحالات اللي بتكسر العرض التجريبي
توثيق سلة بيوصف عائلتين من الإشعارات (webhooks). أحداث التطبيق بتتبعت للتطبيق نفسه، زي التثبيت أو التصريح. أحداث المتجر هي اللي بتشترك فيها، بما في ذلك من بوابة الشركاء، عشان طلب جديد أو محدّث يوصل لسيرفرك بدل ما نظامك يسأل الـ API كل شوية. تقدر كمان تسجّل webhook من خلال الـ API. الاستعلام الدوري لسه ليه مكان في الملء الراجع وفي المراجعة اليومية. لكنه مسار أساسي ضعيف لو المخزن لازم يتحرك لما الطلب يتدفع.
الإشعار مش موثوق بس لأنه وصل. صفحة الإشعارات الرسمية بتوصف التحقق من الطلب، بما في ذلك ترويسة X-salla-signature وسر تحتفظ بيه على سيرفرك. ارفض أي حاجة مش مطابقة. رجّع رد سريع، واشتغل التقيل على طابور، عشان استدعاء محاسبة بطيء مايخليش سلة تعيد مهمة أنت بدأتها. لو نفس الحدث وصل مرتين، نظامك لازم مينشئش طلبين. خزّن هوية الحدث الرسمية، وخلي الكتابة بدون تكرار (idempotent).
واجهة قائمة الطلبات تذكير كويس إن العقود الرسمية بتتغيّر. توثيق قائمة الطلبات، اللي اتفتح في 12 نوفمبر 2026، فيه إشعار تغيير كاسر: اعتبارًا من 18 فبراير 2026، مصفوفة groups تحت كائن customer متوقفة، والبديل لمجموعات العميل هو واجهة تفاصيل العميل. إشعار تاني بيقول إن بداية من 1 سبتمبر 2026 معامل الاستعلام expanded=true مبقاش مدعوم، وإن التطبيقات المنشأة بعد 15 أغسطس 2024 أصلًا مكانتش تدعمه. اعتبارًا من النهاردة، التواريخ دي عدّت. ربط لسه متوقع الحقول القديمة هيفشل بهدوء. ابنِ على الصفحات الرسمية الحالية، واحتفظ بسجل تغييرات لما سلة تحدّث واجهة.
الإلغاء، والاسترجاع الجزئي، والشحن المجزأ، والكوبونات، والحجز غير المدفوع: دي الحالات اللي بتكسر العرض السعيد. اتفقوا عليها مكتوب قبل ما حد يكتب أول تحويل. نفس الكلام على المخزون: لو سلة والمخزن يقدروا يكتبوا الكمية الاتنين، هتبيع زيادة. اختار كاتب واحد لكل SKU، أو قاعدة دمج موثّقة، وجرّب بيع على القناتين في نفس الدقيقة.
متاجر الخليج وZATCA والبيانات اللي مش لازم تتنسخ مرتين
لمتجر سعودي، الفاتورة الضريبية غالبًا النطاق المخفي. دليلنا عن ربط الفاتورة الإلكترونية المرحلة الثانية (ZATCA) هو المكان المناسب لقراءة مسار الشغل ده. القاعدة اللي هأصر عليها هنا تشغيلية، مش تاريخ تقديم: اختار نظام واحد يصدر الفاتورة الضريبية الرسمية للطلب، ومتسيبش سلة وأداة المحاسبة يصدروا فاتورتين. أكّد الالتزام والموجة الحالية مع المحاسب والقناة الرسمية. مش هخترع موعد في المقال ده.
كيان إماراتي أو خليجي تاني بيبيع من خلال سلة لسه محتاج قواعد فاتورة وبيانات خاصة بيه. متلصقش صيغة تصدير سعودية على دولة تانية، ومتفترضش إن التزامات البيانات الشخصية المصرية بتختفي لأن واجهة المتجر في السعودية. سجلات العملاء تفضل بيانات شخصية. حدّد مكان الاستضافة، بما في ذلك النسخ الاحتياطي ووصول الدعم، واجمع بس اللي الرحلة محتاجاه.
الكتالوج ثنائي اللغة، والريال مقابل الجنيه المصري، ومخزون الفروع: دول بيتبعوا الكيانات القانونية الفعلية للتاجر، مش «قايمة أسعار عالمية» واحدة بتحوّل الأرقام في الخفاء. المعمارية البرمجية ممكن تتشارك. سياسة كل كيان لازم تفضل منفصلة.
اللي بنبنيه، واللي مش هنوعد بيه
بنحدد نطاق ربط سلة عبر API المخصص حوالين أسبوع طلبات حقيقي: إيه اللي بيتإنشأ في سلة، وإيه لازم يوصل للمخزن أو الحسابات، ومين بيتبلغ لما التسليم يفشل. الربط مع نظام تالت بيتكتب في النطاق بس لما الوصول يتحقق. واجهة سوق أو شركة شحن أو ERP متخيلة مش بند في العرض.
مش هنوعد بموصّل «يغطي كل تطبيق سلة وكل باقة محاسبة»، ولا إنه يفضل متوافق للأبد من غير صيانة. الواجهات الرسمية بتتغيّر، زي ما إشعارات قائمة الطلبات بتبيّن. العرض لازم يشمل المراقبة، والتسوية، ومسؤول لتدوير التوكن لما توكن الوصول ينتهي أو التاجر يلغي التطبيق.
Golden Code مش بتبيع منتج سلة جاهز. نظرة على خدمات التطوير هي نقطة البداية لبناء مخصص، مع تسليم الكود المصدري والاستضافة المتفق عليها في العرض.
ست خطوات لتحديد نطاق ربط سلة عبر API مخصص
الخطوة 1: حدد إيه اللي بيفضل في سلة وإيه اللي عايش في نظامك
اكتب واجهة المتجر، والمخزن، والمحاسبة، وتنفيذ الطلبات، وأي أداة تانية لمست الطلب أصلًا. سمّي مصدر الحقيقة للكتالوج والمخزون والعملاء والفواتير. الخريطة هي النطاق، مش أمنية فاضية لـ «مزامنة كاملة».
الخطوة 2: عدّد التدفقات والأحداث اللي بتبدأها
للطلبات والمنتجات والمخزون والعملاء، قول التحديث بيبدأ في سلة ولا في نظامك، وهو اتجاه واحد ولا الاتجاهين. ضمّن إلغاء، واسترجاع، وتعديل مخزون. لو تدفق مالوش صاحب، مش من حقه يدخل الإطلاق الأول.
الخطوة 3: حدد نطاق التطبيق والصلاحيات والوثائق الرسمية
اتفقوا التطبيق خاص بتاجر واحد ولا مقصود لمتاجر أكتر. عدّد صلاحيات OAuth اللي محتاجها فعلًا، من دليل التصريح وصفحات Merchant API الحالية. متطلبش وصول مش هتستخدمه، ومتثبّتش حقول الإشعارات الرسمية وقفتها خلاص.
الخطوة 4: صمّم استقبال الإشعارات والتوقيع وإعادة المحاولة
ادّي سيرفرك عنوان HTTPS ثابت، تحقق من التوقيع الرسمي، ونفّذ الشغل على طابور. خزّن هوية الحدث عشان إعادة المحاولة متنشئش طلب تاني. خلّي الاستعلام الدوري أو السحب اليومي ملء راجع، مش الطريقة الوحيدة اللي تعرف بيها إن بيع حصل.
الخطوة 5: اتفقوا على الاسترجاع والشحن ومين يصدر الفاتورة الضريبية
خد أمثلة مجهولة الهوية لطلب مدفوع، واسترجاع جزئي، وشحنة مجزأة، وكوبون. قرروا أنهي نظام يصدر الفاتورة الضريبية الرسمية، وأكّدوا أي التزام ZATCA أو محلي مع المحاسب. متسيبوش القرار لأول نزاع حي.
الخطوة 6: اختبر على متجر غير إنتاجي، وبعدين اتفقوا المراقبة والتسليم
استخدم متجر تجريبي أو بيئة اختبار قبل الكتالوج الحي. سوّي طلبات يوم كامل مقابل سلة، وافحص كل اختلاف. اتفقوا مين بيراقب المهام الفاشلة، وإزاي التوكن بيتخزن ويتدوّر، وإزاي الفريق بيتدرّب. بعد المراجعة دي نقدر نبعث لك عرضًا تقنيًا مخصصًا بناءً على خريطة طلبات ومخزون سلة.
الخطوة التالية بهدوء
لو بتدير متجر سلة في السعودية أو الخليج، أو بتبيع في السعودية من مصر، أو عندك أصلًا مخزن أو نظام محاسبة بقى متأخر عن لوحة التحكم، ابعت جرد قصير: رابط المتجر، والأنظمة اللي لازم تستقبل أو ترسل بيانات، وأسبوع استثناءات قريب. هنقول إيه اللي يدخل في ربط سلة عبر API مخصص، وإيه اللي يفضل عند المحاسب أو المستشار. تقدر كمان تبعت لجولدن كود الجرد ده لعرض تقني مخصص—من غير باقة ثابتة، عرض محدد النطاق بس.
الأسئلة الشائعة
هل لازم نسيب سلة عشان نستخدم نظام مخصص؟
لأ. الربط المخصص للحالة اللي سلة تفضل فيها واجهة المتجر، والمخزن أو الحسابات أو تنفيذ الطلبات محتاجين تبادل بيانات يعتمد عليه. ترك المنصة بالكامل قرار مختلف، وموجود في دليل تكلفة المتجر الإلكتروني.
هل تطبيق سلة الجاهز يكفي؟
ممكن يكفي، لما يكون التدفق بسيط وفي اتجاه واحد وبيطابق اللي التطبيق بيقدّمه. عادة بيبقى اختيار ضعيف لما أكتر من نظام يكتب نفس المخزون أو نفس الفاتورة، أو لما متقدرش تعرف إذا كان كل طلب مدفوع وصل.
نعتمد على الإشعارات ولا على الاستعلام الدوري من الـ API؟
استخدم الإشعارات لأحداث المتجر شبه اللحظية، مع فحص توقيع وطابور من غير تكرار، وخلّي سحب API دوري للملء الراجع والتسوية. الاستعلام لوحده مسار أساسي بطيء وناقص.
هل ربط واحد هيغطي تلقائيًا تشغيل مصري ومتجر خليجي؟
لأ. تقدر تشارك المعمارية التقنية، لكن الفواتير الضريبية والتحصيل والكتالوج وقواعد البيانات تفضل خاصة بكل كيان. أكّد المتطلبات المحلية مع المستشار والمحاسب قبل ما تنسخ إعدادات دولة على دولة تانية.
مين المفروض يصدر الفاتورة الضريبية الرسمية لطلب سلة؟
اختار نظام واحد وثبت عليه. لمتجر سعودي، اقرأ دليل المرحلة الثانية من ZATCA وأكّد الالتزام الحالي مع المحاسب. المقال ده مش هيخترع تاريخ تقديم ولا جهة إصدار تانية.
هل بتبيعوا باقة ثابتة لربط سلة عبر API؟
لأ. Golden Code مش بتنشر باقة سلة ثابتة ولا سعر تطبيق جاهز. بنسعّر شغل تقني مخصص بعد جرد المتجر والتدفقات وحالات الاستثناء.
المصادر
- وثائق منصة سلة — docs.salla.dev والبدء (أساس Merchant API هو
https://api.salla.dev/admin/v2) - سلة — التصريح (OAuth 2.0) وتحديد المعدل
- سلة — الإشعارات وتسجيل webhook
- سلة — إنشاء أول تطبيق وبوابة الشركاء
- سلة — قائمة الطلبات (إشعارات التغيير والإيقاف، اتفتحت 12 نوفمبر 2026) وتفاصيل العميل
