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

المنتجات

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

كائن Product

idstring
يبدأ بـ prd_.
titlestring
عنوانك. ويبقى عنوان البائع في الاستيراد.
statusstring
active، أو paused (بواسطتك، أو بقاعدة مزامنة حين ارتفعت التكلفة كثيرًا أو نفد مخزون البائع).
sourceobject
المنصة، ورابط صفحة المنتج، والبائع في الصين.
options[]array
أسماء الخيارات، ثلاثة كحد أقصى، كما يعرضها متجرك.
price_range, cost_rangeobject
أسعارك وأسعار البائع، عبر المتغيّرات.
channels[]array
أين يُعرض: المتجر، ومعرّف المنتج فيه، وحالته هناك.
syncobject
قاعدة المزامنة التي يتبعها ومتى قرأنا صفحة المنتج آخر مرة.
importstring
الاستيراد الذي حُفظ منه.
product
{
  "id": "prd_8f2k",
  "title": "Heavyweight Washed Hoodie",
  "status": "active",
  "source": {
    "marketplace": "weidian",
    "url": "https://weidian.com/item.html?itemID=7750970856",
    "seller": "Ruoyi Studio"
  },
  "options": ["Color", "Size"],
  "variants_count": 6,
  "price_range": {
    "min": { "amount": "49.99", "currency": "USD" },
    "max": { "amount": "54.99", "currency": "USD" }
  },
  "cost_range": {
    "min": { "amount": "38.00", "currency": "CNY" },
    "max": { "amount": "42.00", "currency": "CNY" }
  },
  "channels": [
    {
      "channel": "shopify",
      "shop": "acme-goods.myshopify.com",
      "external_id": "gid://shopify/Product/8812042",
      "status": "draft",
      "pushed_at": "2026-11-04T09:20:03Z"
    }
  ],
  "sync": {
    "rule": "rule_default",
    "last_checked_at": "2026-11-04T09:12:40Z"
  },
  "import": "imp_2c9d",
  "created_at": "2026-11-04T09:20:01Z",
  "updated_at": "2026-11-04T09:20:03Z"
}

عرض المنتجات

GET/v1/products

منتجاتك، الأحدث أولًا.

النطاقproducts:read

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

statusstring
اختياري. active أو paused.
channelstring
اختياري. shopify، للمنتجات المعروضة هناك.
changed_sincestring
اختياري. وقت: فقط المنتجات التي تغيّرت تكلفتها أو مخزونها منذ ذلك الحين.
limit, cursor
Pagination
curl "https://www.ninjabuy.com/api/v1/products?status=active&limit=2" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"
Response 200
HTTP/2 200 OK

{
  "data": [
    {
      "id": "prd_8f2k",
      "title": "Heavyweight Washed Hoodie",
      "status": "active",
      "variants_count": 6
    },
    {
      "id": "prd_1x0a",
      "title": "Canvas Tote",
      "status": "active",
      "variants_count": 3
    }
  ],
  "has_more": true,
  "cursor": "c_1x0a"
}

جلب منتج

GET/v1/products/{id}

منتج واحد بمصدره وقنواته وحالة مزامنته. متغيّراته على مسار خاص بها.

النطاقproducts:read

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

idstringمطلوب
معرّف المنتج.

الأخطاء

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

{
  "id": "prd_8f2k",
  "title": "Heavyweight Washed Hoodie",
  "status": "active",
  "source": {
    "marketplace": "weidian",
    "url": "https://weidian.com/item.html?itemID=7750970856",
    "seller": "Ruoyi Studio"
  },
  "options": ["Color", "Size"],
  "variants_count": 6,
  "price_range": {
    "min": { "amount": "49.99", "currency": "USD" },
    "max": { "amount": "54.99", "currency": "USD" }
  },
  "cost_range": {
    "min": { "amount": "38.00", "currency": "CNY" },
    "max": { "amount": "42.00", "currency": "CNY" }
  },
  "channels": [
    {
      "channel": "shopify",
      "shop": "acme-goods.myshopify.com",
      "external_id": "gid://shopify/Product/8812042",
      "status": "draft",
      "pushed_at": "2026-11-04T09:20:03Z"
    }
  ],
  "sync": {
    "rule": "rule_default",
    "last_checked_at": "2026-11-04T09:12:40Z"
  },
  "import": "imp_2c9d",
  "created_at": "2026-11-04T09:20:01Z",
  "updated_at": "2026-11-04T09:20:03Z"
}

تحديث منتج

PATCH/v1/products/{id}

غيّر العنوان أو الوصف، أو أوقفه مؤقتًا واستأنفه. أرسل ما يتغيّر فقط. الأسعار لكل متغيّر (المتغيّرات)، والمنتج المُرسَل ينقل التغيير إلى متجرك عند إرساله التالي.

النطاقproducts:write

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

idstringمطلوب
معرّف المنتج.

النص

titlestring
اختياري.
descriptionstring
اختياري. HTML يعرضه متجرك.
statusstring
اختياري. active أو paused. الإيقاف المؤقت يجعل المخزون 0 في قنواتك.
sync_rulestring
اختياري. معرّف قاعدة مزامنة؛ القاعدة الافتراضية حين يكون null.

الأخطاء

الحالةالنوعمتى
404not-foundلا يوجد منتج كهذا في هذا الحساب.
curl -X PATCH "https://www.ninjabuy.com/api/v1/products/prd_8f2k" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paused" }'
Response 200
HTTP/2 200 OK

{
  "id": "prd_8f2k",
  "title": "Heavyweight Washed Hoodie",
  "status": "paused",
  "source": {
    "marketplace": "weidian",
    "url": "https://weidian.com/item.html?itemID=7750970856",
    "seller": "Ruoyi Studio"
  },
  "options": ["Color", "Size"],
  "variants_count": 6,
  "price_range": {
    "min": { "amount": "49.99", "currency": "USD" },
    "max": { "amount": "54.99", "currency": "USD" }
  },
  "cost_range": {
    "min": { "amount": "38.00", "currency": "CNY" },
    "max": { "amount": "42.00", "currency": "CNY" }
  },
  "channels": [
    {
      "channel": "shopify",
      "shop": "acme-goods.myshopify.com",
      "external_id": "gid://shopify/Product/8812042",
      "status": "draft",
      "pushed_at": "2026-11-04T09:20:03Z"
    }
  ],
  "sync": {
    "rule": "rule_default",
    "last_checked_at": "2026-11-04T09:12:40Z"
  },
  "import": "imp_2c9d",
  "created_at": "2026-11-04T09:20:01Z",
  "updated_at": "2026-11-04T09:20:03Z"
}

الإرسال إلى Shopify

POST/v1/products/{id}/push

يعرض المنتج في متجرك المربوط على Shopify: منتج Shopify واحد، ومتغيّر لكل SKU أبقيته، وصوره، وكل متغيّر مخزّن في موقع Fulfilled by NinjaBuy، فتصل طلباته إلينا.

  • الإرسال الأول ينشئه كمسودة: العنوان والصور جاءت من منصة صينية، فاقرأها قبل مشتريك، ثم انشره في Shopify.
  • إعادة الإرسال تحدّث منتج Shopify نفسه: تُضبط الأسعار والمخزون مجددًا، وتُحذف المتغيّرات التي استبعدتها. الحالة والعنوان والوصف والصور تبقى كما تركتها في Shopify ما لم ترسل جديدًا.
  • المخزون هو عدد البائع، بحد أقصى 100: نشتري عند الطلب، فهو عدد الطلبات التي يقبلها Shopify قبل أن يعرض المنتج نافدًا.
  • يجب أن يبيع متجرك بالدولار الأمريكي، لأن الأسعار به. المتغيّرات النافدة تُتخطّى وتُذكر في skipped[].

النطاقproducts:write

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

idstringمطلوب
معرّف المنتج.

النص

shopstring
أي متجر مربوط، مثل acme-goods.myshopify.com. مطلوب فقط حين تربط عدة متاجر.
title, descriptionstring
اختياري. تُرسل إلى Shopify فقط حين ترسلها.

الأخطاء

الحالةالنوعمتى
409no-linked-storeلا يوجد متجر Shopify مربوط بهذا الحساب، أو توجد عدة متاجر وshop مفقود.
409store-not-readyانتهت صلاحية وصول المتجر، أو لم يُعدّ موقعنا بعد: افتح تطبيق NinjaBuy في Shopify مرة واحدة.
422store-currencyالمتجر لا يبيع بالدولار الأمريكي.
422too-many-optionsلصفحة المنتج أكثر من ثلاثة خيارات، وShopify يقبل ثلاثة.
422unprocessableكل المتغيّرات نافدة، أو رفض Shopify حقلًا، وينقل detail كلماته.
curl -X POST "https://www.ninjabuy.com/api/v1/products/prd_8f2k/push" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "shop": "acme-goods.myshopify.com" }'
Response 200
HTTP/2 200 OK

{
  "channel": "shopify",
  "shop": "acme-goods.myshopify.com",
  "external_id": "gid://shopify/Product/8812042",
  "status": "draft",
  "created": true,
  "variants": 5,
  "skipped": [{ "sku": "5187209555", "reason": "sold_out" }],
  "admin_url": "https://admin.shopify.com/store/acme-goods/products/8812042"
}

حذف منتج

DELETE/v1/products/{id}

يوقف مزامنته ويجعل مخزونه 0 في قنواتك؛ ويبقى منتج Shopify لتؤرشفه بنفسك. الطلبات المقدّمة مسبقًا تُشحن كما هي.

النطاقproducts:write

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

idstringمطلوب
معرّف المنتج.

الأخطاء

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

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