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

إذا كنت تبيع على أمازون، فأنت لا تريد أن تجلس تُحدّث 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

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

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

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

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

---

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

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

• الإجراء: EAEcommerceReadAmazonNotifications
• المعامل 1 — كود الموقع: كود موقع أمازون لديك
• المعامل 2 — أقصى عدد رسائل لكل تشغيل: عدد الرسائل المُفرّغة في كل تشغيل (اتركه فارغًا للقيمة الافتراضية 500)
• الفاصل الزمني: كل 1–2 دقيقة

كل تشغيل يسحب الإشعارات الجديدة المنتظرة في الطابور ويُنشئ أمر بيع لكل طلب وصل إلى حالة تم الشحن. أمّا تغييرات الحالة الأخرى فتُتجاهَل ببساطة.

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

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

---

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

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

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