شعار NinjaBuyالأعمال
تواصل مع المبيعات
Catalog API2026-11إصدار تجريبي

قواعد المزامنة

ما يحدث لإعلانك حين يغيّر بائع في الصين سعرًا أو ينفد مخزونه.
  • نعيد قراءة صفحة المنتج حين يصل طلب لها ووفق جدول منتظم؛ ويوضح last_checked_at لكل منتج متى فعلنا ذلك آخر مرة. إبقاء المنتجات متزامنة مجاني.
  • كل تغيير نتصرف حياله هو حدث أيضًا: product.cost_changed وproduct.out_of_stock.
نقاط النهاية

كائن Sync rule

idstring
يبدأ بـ rule_، والقاعدة الافتراضية هي rule_default.
applies_tostring
all للقاعدة الافتراضية، أو معرّف منتج لقاعدة خاصة.
on_cost_increase.actionstring
إعادة التسعير للحفاظ على هامشك، أو إيقاف المنتج مؤقتًا، أو التنبيه فقط.
on_cost_increase.keep_margin_percentstring
مع reprice: الهامش المطلوب الحفاظ عليه، من سعر البيع.
on_cost_increase.max_increase_percentstring|null
مع reprice: أقصى ارتفاع مسموح للسعر دفعة واحدة. فوقه ينطبق above_max: إيقاف مؤقت أو تنبيه.
on_cost_decreasestring
keep_price، أو إعادة التسعير نزولًا إلى الهامش نفسه.
on_out_of_stockstring
دائمًا zero_stock: الـ SKU النافد يظهر 0 في قنواتك.
on_back_in_stockstring
restock، أو stay_paused حتى تستأنفه.
round_tostring|null
نهاية السعر للأسعار المعاد تسعيرها، مثل ‎.99 أو ‎.00.
sync_rule
{
  "id": "rule_default",
  "applies_to": "all",
  "on_cost_increase": {
    "action": "reprice",
    "keep_margin_percent": "30",
    "max_increase_percent": "15",
    "above_max": "pause"
  },
  "on_cost_decrease": "keep_price",
  "on_out_of_stock": "zero_stock",
  "on_back_in_stock": "restock",
  "round_to": ".99",
  "updated_at": "2026-11-02T08:00:00Z"
}

عرض قواعد المزامنة

GET/v1/sync_rules

القاعدة الافتراضية أولًا، ثم كل قاعدة خاصة بمنتج.

النطاقproducts:read

curl "https://www.ninjabuy.com/api/v1/sync_rules" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"
Response 200
HTTP/2 200 OK

{
  "data": [
    {
      "id": "rule_default",
      "applies_to": "all",
      "on_cost_increase": {
        "action": "reprice",
        "keep_margin_percent": "30",
        "max_increase_percent": "15",
        "above_max": "pause"
      },
      "on_cost_decrease": "keep_price",
      "on_out_of_stock": "zero_stock",
      "on_back_in_stock": "restock",
      "round_to": ".99",
      "updated_at": "2026-11-02T08:00:00Z"
    },
    {
      "id": "rule_9p3e",
      "applies_to": "prd_1x0a",
      "on_cost_increase": { "action": "pause" },
      "on_cost_decrease": "keep_price",
      "on_out_of_stock": "zero_stock",
      "on_back_in_stock": "stay_paused",
      "round_to": null,
      "updated_at": "2026-11-03T10:14:00Z"
    }
  ],
  "has_more": false,
  "cursor": null
}

جلب قاعدة مزامنة

GET/v1/sync_rules/{id}

قاعدة واحدة.

النطاقproducts:read

معاملات المسار

idstringمطلوب
معرّف القاعدة.

الأخطاء

الحالةالنوعمتى
404not-foundلا توجد قاعدة كهذه في هذا الحساب.
curl "https://www.ninjabuy.com/api/v1/sync_rules/rule_default" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"
Response 200
HTTP/2 200 OK

{
  "id": "rule_default",
  "applies_to": "all",
  "on_cost_increase": {
    "action": "reprice",
    "keep_margin_percent": "30",
    "max_increase_percent": "15",
    "above_max": "pause"
  },
  "on_cost_decrease": "keep_price",
  "on_out_of_stock": "zero_stock",
  "on_back_in_stock": "restock",
  "round_to": ".99",
  "updated_at": "2026-11-02T08:00:00Z"
}

قاعدة خاصة لمنتج

POST/v1/sync_rules

المنتج الذي له قاعدة خاصة يتبعها بدلًا من القاعدة الافتراضية. الحقول التي تتركها تأخذ قيم القاعدة الافتراضية.

النطاقproducts:write

النص

applies_tostringمطلوب
all للقاعدة الافتراضية، أو معرّف منتج لقاعدة خاصة.
on_cost_increase.actionstring
إعادة التسعير للحفاظ على هامشك، أو إيقاف المنتج مؤقتًا، أو التنبيه فقط.
on_cost_increase.keep_margin_percentstring
مع reprice: الهامش المطلوب الحفاظ عليه، من سعر البيع.
on_cost_increase.max_increase_percentstring|null
مع reprice: أقصى ارتفاع مسموح للسعر دفعة واحدة. فوقه ينطبق above_max: إيقاف مؤقت أو تنبيه.
on_cost_decreasestring
keep_price، أو إعادة التسعير نزولًا إلى الهامش نفسه.
on_out_of_stockstring
دائمًا zero_stock: الـ SKU النافد يظهر 0 في قنواتك.
on_back_in_stockstring
restock، أو stay_paused حتى تستأنفه.
round_tostring|null
نهاية السعر للأسعار المعاد تسعيرها، مثل ‎.99 أو ‎.00.

الأخطاء

الحالةالنوعمتى
404not-foundلا يوجد منتج كهذا في هذا الحساب.
409invalid-stateللمنتج قاعدة خاصة أصلًا: استبدلها.
curl -X POST "https://www.ninjabuy.com/api/v1/sync_rules" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "applies_to": "prd_1x0a",
    "on_cost_increase": { "action": "pause" },
    "on_back_in_stock": "stay_paused"
  }'
Response 201
HTTP/2 201 Created

{
  "id": "rule_9p3e",
  "applies_to": "prd_1x0a",
  "on_cost_increase": { "action": "pause" },
  "on_cost_decrease": "keep_price",
  "on_out_of_stock": "zero_stock",
  "on_back_in_stock": "stay_paused",
  "round_to": null,
  "updated_at": "2026-11-03T10:14:00Z"
}

استبدال قاعدة مزامنة

PUT/v1/sync_rules/{id}

أرسل القاعدة كاملة. تسري من المرة التالية التي نقرأ فيها كل صفحة منتج.

النطاقproducts:write

معاملات المسار

idstringمطلوب
معرّف القاعدة.

النص

on_cost_increase.actionstring
إعادة التسعير للحفاظ على هامشك، أو إيقاف المنتج مؤقتًا، أو التنبيه فقط.
on_cost_increase.keep_margin_percentstring
مع reprice: الهامش المطلوب الحفاظ عليه، من سعر البيع.
on_cost_increase.max_increase_percentstring|null
مع reprice: أقصى ارتفاع مسموح للسعر دفعة واحدة. فوقه ينطبق above_max: إيقاف مؤقت أو تنبيه.
on_cost_decreasestring
keep_price، أو إعادة التسعير نزولًا إلى الهامش نفسه.
on_out_of_stockstring
دائمًا zero_stock: الـ SKU النافد يظهر 0 في قنواتك.
on_back_in_stockstring
restock، أو stay_paused حتى تستأنفه.
round_tostring|null
نهاية السعر للأسعار المعاد تسعيرها، مثل ‎.99 أو ‎.00.

الأخطاء

الحالةالنوعمتى
404not-foundلا توجد قاعدة كهذه في هذا الحساب.
curl -X PUT "https://www.ninjabuy.com/api/v1/sync_rules/rule_default" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Content-Type: application/json" \
  -d '{
    "on_cost_increase": { "action": "notify" },
    "on_cost_decrease": "keep_price",
    "on_out_of_stock": "zero_stock",
    "on_back_in_stock": "restock",
    "round_to": ".99"
  }'
Response 200
HTTP/2 200 OK

{
  "id": "rule_default",
  "applies_to": "all",
  "on_cost_increase": { "action": "notify" },
  "on_cost_decrease": "keep_price",
  "on_out_of_stock": "zero_stock",
  "on_back_in_stock": "restock",
  "round_to": ".99",
  "updated_at": "2026-11-02T08:00:00Z"
}

حذف قاعدة خاصة

DELETE/v1/sync_rules/{id}

يعود المنتج إلى اتباع القاعدة الافتراضية. لا يمكن حذف rule_default نفسها.

النطاقproducts:write

معاملات المسار

idstringمطلوب
معرّف القاعدة.

الأخطاء

الحالةالنوعمتى
409invalid-stateلا يمكن حذف rule_default.
curl -X DELETE "https://www.ninjabuy.com/api/v1/sync_rules/rule_9p3e" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"
Response 200
HTTP/2 200 OK

{ "id": "rule_9p3e", "deleted": true }