التكامل مع أثير (Atheer)

تشرح هذه الصفحة كيف ترسل منصة أثير طلباتها وطلبات العروض إلى نما ERP: سجل Magento Site الذي تحتاج إلى إعداده، والعنوان الذي تتصل به أثير، والعمليات الأربع التي يمكن أن ترسلها، ورمز QR الخاص بهيئة الزكاة والضريبة والجمارك (ZATCA) الذي يعيده نما، وكيف تطلب من أثير إعادة إرسال طلب.

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

إعداد سجل Magento Site

تُعَدّ أثير كسجل على شاشة Magento Site. تحمل الشاشة هذا الاسم في اللغتين مع أنها تخدم منصات كثيرة، وتحتاج إلى ترخيص magento.

1. أنشئ سجلًا واختر في Site Type القيمة Atheer Site. أعطه كودًا قصيرًا، مثل ATHEER، فأثير تستخدم هذا الكود في كل اتصال.
2. املأ بيانات الإنشاء التي تستخدمها عمليات أثير (انظر الجدول أدناه): Order Info وRequest Info وReturn Info، وفي كل منها نوع المستند الذي ينشئه نما ودفتره وتوجيهه. واملأ كذلك إعدادات العملاء وطرق الدفع وربط الأصناف. يشرح دليل تكامل التجارة الإلكترونية كل ذلك.
3. في صفحة الرئيسية، املأ Seller Name (ZATCA) وVat Number (ZATCA) باسم شركتك المسجّل ورقمها الضريبي. يستخدمهما نما لبناء رمز QR الذي يعيده إلى أثير.
4. في صفحة Atheer Site، املأ Reset Order Link Template (يأتي شرحه لاحقًا). لا يُحفظ السجل بدونه.
5. أعطِ أثير اسم مستخدم وكلمة مرور في نما لتستخدمهما في الاتصالات. تُنفَّذ الاتصالات باسم هذا المستخدم، فيجب أن يملك صلاحية إنشاء المستندات المحددة في الخطوة 2.

العنوان الذي تتصل به أثير

ترسل أثير كل اتصال كطلب HTTP من نوع POST، وفي جسمه الطلب أو العرض بصيغة JSON، إلى العنوان:

{your Nama address}/integrator?type=atheer&operation=...&siteCode=...&user=...&pass=...

حيث {your Nama address} هو عنوان نظام نما لديك.

المُدخل	قيمته
operation	إحدى العمليات الأربع الموضحة أدناه.
siteCode	كود سجل Magento Site الخاص بأثير، مثل ATHEER.
user، pass	اسم المستخدم وكلمة المرور في نما من الخطوة 5.

فمثلًا، فاتورة جديدة لسجل كوده ATHEER تُرسل إلى {your Nama address}/integrator?type=atheer&operation=add_invoice&siteCode=ATHEER&user=atheer&pass=....

يعالج نما اتصالات أثير واحدًا تلو الآخر بترتيب وصولها.

العمليات الأربع

العملية	معناها	بيانات الإنشاء المستخدمة
add_invoice	عملية بيع مكتملة. ينشئ نما المستند من الطلب الذي ترسله أثير.	Order Info
add_request	طلب ما زال ينتظر التأكيد. ينشئ نما المستند من الطلب الذي ترسله أثير.	Request Info
request_confirm	أكّد العميل طلبًا سابقًا. ينشئ نما المستند من ذلك الطلب.	Order Info
request_reject	رفض العميل طلبًا سابقًا. ينشئ نما المستند من ذلك الطلب.	Return Info

العمليتان الأخيرتان تعودان إلى الطلب الأصلي: تحتفظ أثير بالمعرّف (id) الذي أعاده نما عند إرسال add_request، ثم ترسله مرة أخرى في الحقل accounting_offer_num في رأس الطلب. مثال ذلك: ترسل أثير add_request لعرض سعر فيرد نما بالمعرّف 5f2a…، وبعد يومين يقبل العميل العرض فترسل أثير request_confirm وفيه accounting_offer_num = 5f2a…، فيُنشأ الأمر المؤكَّد من عرض السعر ذاك.

ترسل أثير تاريخ الطلب بصيغة Unix time في الحقل created من رأس الطلب. فإذا تعذّرت قراءة هذه القيمة يُرفض الاتصال بالرسالة:

Order with id {0} is failed parsing created field with value {1}

ليس لهذه الرسالة نص عربي، فتظهر بالإنجليزية في الواجهتين. ومعناها أن الخطأ في البيانات التي أرسلتها أثير، فاطلب من أثير تصحيح الطلب وإعادة إرساله.

بماذا يرد نما

كل اتصال ناجح يعيد JSON يحتوي على success، ومعه code وid وentityType لمستند نما الذي أُنشئ. وفي العمليتين add_invoice وrequest_confirm، إذا كان المستند مستند مبيعات، يحمل الرد أيضًا qr_code: رمز QR الخاص بالهيئة، مبنيًا من Seller Name (ZATCA) وVat Number (ZATCA) وتواريخ المستند وإجمالياته، جاهزًا لتطبعه أثير على إيصال العميل.

يُسجَّل كل اتصال في قائمة Atheer Integration Log List في صفحة الإحصائيات على سجل Magento Site: التاريخ، والعملية، ومستند نما، والمحتوى الذي أرسلته أثير. فإذا سأل عميل عمّا أرسلته أثير لطلب معيّن، وجدت الطلب الأصلي في هذه القائمة.

طلب إعادة إرسال طلب من أثير

لأن أثير هي التي ترسل ونما لا يقرأ، لا يمكن جلب طلب فائت أو خاطئ من جهة نما. بدلًا من ذلك يطلب نما من أثير إعادة إرساله، من خلال العنوان المحدد في Reset Order Link Template.

هذا الحقل نص Tempo يحوّله نما إلى عنوان خدمة «إعادة إرسال الطلب» لدى أثير، ثم يستدعيه بطلب HTTP من نوع GET. ضع {magentoSourceId} في موضع رقم الطلب في أثير، مثلًا:

https://<Atheer resend address>/{magentoSourceId}

وأثير هي التي تعطيك العنوان الفعلي. ويُستخدم هذا القالب في موضعين:

• الإجراء إعادة قراءة الأمر من الموقع على مستند مبيعات جاء من أثير، ويطلب من أثير إعادة إرسال طلب هذا المستند.
• مسار الكيان EAEcommerceReadOrders، بكود سجل أثير وقائمة أرقام طلبات أثير مفصولة بفواصل. يطلب من أثير إعادة إرسال كل طلب منها، وهو مفيد للطلبات التي لم تصل إلى نما أصلًا، إذ لا يوجد مستند تضغط عليه الإجراء.

بعد ذلك تتصل أثير بنما من جديد بالطلب كما سبق شرحه.