إشعارات طلبات أمازون

إذا كنت تبيع على أمازون، فأنت لا تريد أن تجلس تُحدّث Seller Central في انتظار شحن الطلبات لتُدخلها يدويًا في النظام. يوضّح هذا الدليل كيفية ربط حساب بائع أمازون بنما بحيث يصل إلى نما كل تغيير يُجريه أمازون على طلب من تلقاء نفسه — وفي العادة يتحوّل الطلب الذي يُعلّمه أمازون كـ "تم الشحن" إلى أمر بيع دون أن يكتبه أحد.

يعتمد الحل على إشعارات ORDER_CHANGE في واجهة SP-API من أمازون — وهي طريقة أمازون لإخبارك بأنّ "شيئًا ما حدث لهذا الطلب" في اللحظة التي يحدث فيها.

كيف يعمل (الخلاصة المختصرة)

هناك حقيقة واحدة تُشكّل الإعداد بأكمله: أمازون لن يُرسل الإشعارات مباشرةً إلى نظامك. المكان الوحيد الذي يوافق أمازون على تسليم إشعارات الطلبات إليه هو طابور رسائل Amazon SQS — صندوق وارد للرسائل موجود في حساب AWS الخاص بك. لذا يبدو التدفّق هكذا:

أمازون يُغيّر طلبًا (يشحنه مثلًا)
   → يصل إشعار ORDER_CHANGE إلى طابور SQS الخاص بك (في حساب AWS لديك)
   → يقوم نما باستطلاع الطابور وفق جدول زمني
   → لكل طلب تغيّرت حالته، يقرأه نما من جديد ويُنشئ المستند الذي تحدده سطور توليد المستندات في الموقع
     (أمر بيع في العادة)

تُعدّ الطابور مرة واحدة، وتُعطي نما ثلاث قيم ليقرأ الطابور، وتُجدوِل مهمة صغيرة تقوم بالاستطلاع. بعد ذلك يعمل كل شيء من تلقاء نفسه.

لماذا طابور بدلًا من دفع مباشر

لأنّ نما يسحب من الطابور بدلًا من انتظار أن يُدفَع إليه، يعمل هذا حتى عندما لا يكون نظامك متاحًا عبر الإنترنت — بما في ذلك التركيبات المحلية (on-premise). تنتظر الإشعارات بأمان في الطابور حتى الاستطلاع التالي، فلا يُفقَد شيء إن كان النظام متوقفًا لوهلة أو مشغولًا.

ما تحتاجه قبل البدء

• تطبيق SP-API من أمازون مفعّل عليه دور Notifications، مع تفويض مكتمل لحساب البائع.
• حساب AWS خاص بك، في نفس منطقة سوق أمازون لديك.

---

الجزء الأول — إعداد AWS (مرة واحدة، في حساب AWS الخاص بك)

الخطوة 1: إنشاء طابور SQS

في وحدة تحكم AWS اذهب إلى SQS ← Create queue، اختر النوع Standard، أعطه اسمًا مثل NamaOrderQueue، ثم أنشئه.

في صفحة الطابور، انسخ الـ ARN الظاهر في الأعلى — سيحتاجه نما لاحقًا. يبدو هكذا:

arn:aws:sqs:us-east-1:123456789012:NamaOrderQueue

يجب أن تطابق المنطقة سوقك

أنشئ الطابور في نفس منطقة AWS التي بها سوق أمازون لديك. يقرأ نما المنطقة من هذا الـ ARN مباشرةً، فإن لم تتطابقا لن تتدفّق الإشعارات.

الخطوة 2: السماح لأمازون بالإرسال إلى الطابور

يحتاج أمازون إلى صلاحية وضع الرسائل في طابورك. على الطابور افتح Access policy ← Edit واسمح لحساب SP-API الخاص بأمازون بإرسال الرسائل:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowAmazonSPAPISend",
      "Effect": "Allow",
      "Principal": { "AWS": "arn:aws:iam::437568002678:root" },
      "Action": "sqs:SendMessage",
      "Resource": "arn:aws:sqs:us-east-1:123456789012:NamaOrderQueue"
    }
  ]
}

استبدِل قيمة Resource بـ ARN طابورك من الخطوة 1. الرقم 437568002678 هو حساب SP-API الثابت الخاص بأمازون — بدون هذه العبارة سيفشل تسجيل وجهة الإشعارات في الجزء الثاني.

الخطوة 3: إنشاء مستخدم IAM ليقرأ نما الطابور

يحتاج نما إلى بيانات اعتماد خاصة به لسحب الرسائل وحذفها. في IAM ← Users ← Create user (سَمِّه مثلًا nama-sqs-reader)، ثم أرفِق سياسة مضمّنة (inline policy) محصورة بهذا الطابور وحده:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sqs:ReceiveMessage",
        "sqs:DeleteMessage",
        "sqs:GetQueueAttributes"
      ],
      "Resource": "arn:aws:sqs:us-east-1:123456789012:NamaOrderQueue"
    }
  ]
}

ثم على المستخدم اذهب إلى Security credentials ← Create access key، اختر Application running outside AWS، وانسخ الآن Access Key ID وSecret Access Key — إذ يُظهِر AWS المفتاح السرّي مرة واحدة فقط.

---

الجزء الثاني — إعداد موقع أمازون في نما

افتح سجلّ موقع التجارة الإلكترونية الخاص بأمازون (MAGMagentoSite) واملأ:

الحقل	ما تضعه فيه
اسم المستخدم / كلمة المرور	client ID / client secret الخاص بتطبيق SP-API
معرف السوق في أمازون	السوق الخاص بك
Amazon SQS Queue ARN	الـ ARN من الجزء الأول، الخطوة 1
AWS Access Key	الـ Access Key ID من الجزء الأول، الخطوة 3
AWS Secret Key	الـ Secret Access Key من الجزء الأول، الخطوة 3
حقل حالة الطلب (Order Status Field Id)	إلزامي في مواقع أمازون — لا يُحفظ الموقع بدونه. اكتب فيه معرّف حقل نصي في مستند البيع (حقل نصي احتياطي مثلًا) يكتب فيه نما حالة الطلب في أمازون. يقارن نما كل إشعار بالحالة المحفوظة فيه، ويتخطّى الطلب إن لم يتغيّر شيء.

احفظ السجلّ، ثم:

1. اضغط Add Refresh Token وفوّض التطبيق على أمازون.
2. اضغط تفعيل التنبيهات (Register Webhooks). هذا يُخبر أمازون بأن يبدأ بتسليم إشعارات ORDER_CHANGE إلى طابور SQS الخاص بك. خلف الكواليس يُسجّل نما الطابور كـ وجهة للإشعارات ويشترك في ORDER_CHANGE؛ وعند النجاح يُملأ حقلا معرف الوجهة في أمازون ومعرف الاشتراك في أمازون.

إعادة التسجيل آمنة

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

---

الجزء الثالث — جدولة مهمة الاستطلاع

القطعة الأخيرة هي المهمة المتكرّرة التي تُفرّغ الطابور. أنشئ سجلّ مهمة مجدولة (Task Schedule):

• الإجراء: EAEcommerceReadAmazonNotifications
• المُدخل 1 — كود الموقع (Site Code): كود موقع أمازون لديك
• المُدخل 2 — أقصى عدد رسائل لكل تشغيل (Max Messages Per Run): عدد الرسائل المُفرّغة في كل تشغيل (اتركه فارغًا للقيمة الافتراضية 500)
• المُدخل 3 — معالجة إشعارات آخر (N) يوم (Process Notifications For Last (N) days): الإشعارات الأقدم من هذا العدد من الأيام تُحذف من الطابور دون معالجة. اتركه فارغًا ليُستخدم تاريخ تم التحديث حتى تاريخ في الموقع بدلًا منه (وإن كان فارغًا هو أيضًا، يُعالَج كل شيء).
• المُدخل 4 — معالجة حالات الطلب هذه فقط (Process Only Order Statuses): قائمة بحالات أمازون مفصولة بفواصل، مثل Shipped. اتركه فارغًا لمعالجة كل الحالات.
• الفاصل الزمني: كل 1–2 دقيقة

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

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

طلب واحد، قراءة واحدة

إذا تراكمت عدّة إشعارات لنفس الطلب بين الاستطلاعين، يدمجها نما ويقرأ ذلك الطلب مرة واحدة فقط — إذ يُقرأ الطلب دائمًا من جديد من واجهة Orders API لدى أمازون، فلا فائدة من قراءته مرتين. هذا يُبقيك ضمن حدود معدّل أمازون حتى مع طابور مزدحم.

---

التحقّق من أنّه يعمل

• اختبار سريع: في وحدة تحكم AWS افتح الطابور ← Send and receive messages ← أرسل رسالة ORDER_CHANGE تجريبية. في الاستطلاع التالي يُعالجها نما — راقِب سجلّ الخادم.
• اختبار حقيقي: علّم طلبًا تجريبيًا كـ تم الشحن في Amazon Seller Central. خلال فاصل استطلاع واحد ينبغي أن يظهر أمر البيع المطابق في نما.

إذا فشلت معالجة إشعار لسبب ما، يتركه نما في الطابور ليُعاد محاولته في التشغيل التالي. وبعد فشل متكرّر يَنقُله SQS إلى طابور الرسائل الميتة (dead-letter queue) — بشرط أن تكون قد أعددت واحدًا — بحيث لا تُعطّل رسالة واحدة سيئة بقية الرسائل.