المفاهيم

المطابقة أو الاقتراح

واميا كتالوج واحد: منتج واحد وعروض كثيرة. يأخذ apiMatchListings رموز SKU مع GTIN والعلامة ومرجع الصانع والعنوان ويجيب لكل SKU بمطابقة مع درجة ثقتها (gtin، brand_mpn، …) أو بـ unmatched. ألحق عرضًا بالمطابقة عبر apiUpsertOffers؛ ولـ SKU بلا مطابقة يقترح apiSubmitListing منتجًا جديدًا يدخل خط الاعتماد كمسودة مع الصور التي تعطيها عبر روابط ويصبح منتجًا حين يعتمده مشرف — أو درجة ثقة المتجر. تمر تعديلات محتوى منتج منشور عبر apiProposeListingEdit.

لا تنشئ تكرارات عمدًا: تصل المنتجات المطابقة إلى Buy Box فورًا بينما تنتظر المقترحة المراجعة.

خط الاعتماد والثقة

يُفحص كل اقتراح للاكتمال (الخصائص الإلزامية للعائلة وصورة واحدة على الأقل) ثم يُراجع. تُعتمد المتاجر ذات الثقة العالية تلقائيًا؛ تعود ملاحظات الإشراف في ApiListingView.moderationNotes وعبر ويب هوك listing.state_changed. صحّح وأعد الإرسال؛ يحتفظ SKU بسجله.

الوسائط

تُنسخ الصور إلى تخزين واميا: مرّر روابط https عامة إلى apiIngestMediaFromUrls (حتى 20 في النداء) وتجلبها واميا بشكل غير متزامن — يبلغ apiMyMediaImports عن التقدم — أو اطلب رفعًا موقّعًا لمدة 15 دقيقة عبر apiCreateMediaUpload وأتمّه بـ apiFinalizeMediaUpload. ألحق الأصول بمنتج عبر apiAssignProductMedia. تُرفض الشبكات الخاصة والتحويلات إليها والملفات فوق 10 ميغابايت والأنواع غير الصورية بـ MEDIA_FETCH_REFUSED.

الضوابط

تحمي قواطع الدائرة المتجر من أخطائه: تغيير سعر دفعي يحرك أكثر من الحصة المضبوطة من القوائم بأكثر من النسبة المضبوطة، أو تحديث مخزون يصفّر عددًا كبيرًا من SKU دفعة واحدة (خمس قوائم فأكثر)، يُحتجز بدل أن يُطبّق. يجيب النداء بـ BATCH_HELD مع extensions.pendingBatchId، ويتلقى المتجر ويب هوك connect.batch_held وبطاقة في اللوحة، وتستطيع الإضافة سرد الدفعات المحتجزة عبر apiPendingBatches والبت فيها عبر apiConfirmBatch أو apiDiscardBatch. لا يُطبّق شيء من الدفعة حتى ذلك الحين؛ وتنتهي الدفعة المحتجزة بعد 7 أيام.

المحاكاة (dry-run)

أرسل Wamia-Dry-Run: true مع أي تعديل للتحقق من المحتوى وتشغيل الضوابط والحصول على النتيجة لكل عنصر دون كتابة. تستخدمه الموصّلات لمعاينة معالج الاستيراد؛ استخدمه قبل أول نداء دفعي حقيقي.

المؤشرات والمطابقة الدورية

القوائم مرقّمة بمؤشر وتقبل updatedSince؛ استطلع apiMyListings(updatedSince) ليلًا وقارن بسجلاتك، أو استدعِ apiReconcileReport لملخص الفروق التي وجدتها واميا بين آخر ما أرسلته وما تحتفظ به. الويب هوك «مرة واحدة على الأقل»؛ والمطابقة الدورية هي ما يبقيك دقيقًا.

الطلبات

يُقسم طلب واميا إلى شرائح، واحدة لكل متجر ومنشأة. تعكس إضافتك الشريحة كطلب محلي (apiMyOrdersPage، apiMyOrderSlice)، وتقر باستلامها عبر apiAcknowledgeSlice، وتعلّمها مجهزة عبر apiMarkSlicePrepared وتتابع الناقل عبر apiShipments. تصل المرتجعات كطلبات RMA (apiMySliceReturnsPage) ويجيب المتجر عبر apiDecideReturn.