Catalog API2026-11إصدار تجريبي

المتغيّرات

خيار واحد من منتج، مقاس أو لون أو طراز هاتف، مربوط بـ SKU البائع الذي نشتريه وبالمتغيّر الذي يبيعه متجرك.

المتغيّر هو ما يذكره بند الطلب. ويحدد مستوى المخزون كم يمكنك أن تبيع منه.

نقاط النهاية

GET/v1/products/{id}/variantsعرض متغيّرات منتج
GET/v1/variants/{id}جلب متغيّر
PATCH/v1/variants/{id}تحديث متغيّر

كائن Variant

idstring: يبدأ بـ var_.
skustring: SKU البائع، كما قرأناه. ما نشتريه.
label, options: قيم الخيارات، كتسمية واحدة وحسب اسم الخيار.
costmoney: ما يتقاضاه البائع للقطعة الواحدة، بـ CN¥، كما قُرئ آخر مرة.
pricemoney: سعر البيع لديك.
in_stockboolean: هل يستطيع البائع بيعه، كما قُرئ آخر مرة.
unitsinteger: كم نشتري مقابل كل قطعة تبيعها: علبة من 3 في متجرك تشتري 3.
weight_ginteger: الوزن بعد التغليف الذي أعطيته لقطعة واحدة، ويُستخدم لتقدير الشحن.
external_variant_idstring|null: متغيّر متجرك. الطلب عليه يشتري هذا الـ SKU؛ والطلب على متغيّر غير مربوط يُرفض.

variant

{
  "id": "var_41hz",
  "product": "prd_8f2k",
  "sku": "5187209554",
  "label": "Black / M",
  "options": { "Color": "Black", "Size": "M" },
  "image": "https://media.ninjabuy.com/listings/weidian-7750970856/sku-black.webp",
  "cost": { "amount": "38.00", "currency": "CNY" },
  "price": { "amount": "49.99", "currency": "USD" },
  "in_stock": true,
  "units": 1,
  "weight_g": 180,
  "external_variant_id": "gid://shopify/ProductVariant/44100231",
  "updated_at": "2026-11-04T09:20:03Z"
}

عرض متغيّرات منتج

GET/v1/products/{id}/variants

كل متغيّر بتكلفته وسعرك ومخزونه وربطه.

النطاقproducts:read

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

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

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

limit, cursor: Pagination

الأخطاء

الحالة	النوع	متى
404	not-found	لا يوجد منتج كهذا في هذا الحساب.

curl "https://www.ninjabuy.com/api/v1/products/prd_8f2k/variants" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "data": [
    {
      "id": "var_41hz",
      "product": "prd_8f2k",
      "sku": "5187209554",
      "label": "Black / M",
      "options": { "Color": "Black", "Size": "M" },
      "image": "https://media.ninjabuy.com/listings/weidian-7750970856/sku-black.webp",
      "cost": { "amount": "38.00", "currency": "CNY" },
      "price": { "amount": "49.99", "currency": "USD" },
      "in_stock": true,
      "units": 1,
      "weight_g": 180,
      "external_variant_id": "gid://shopify/ProductVariant/44100231",
      "updated_at": "2026-11-04T09:20:03Z"
    },
    {
      "id": "var_41j0",
      "product": "prd_8f2k",
      "sku": "5187209555",
      "label": "Black / L",
      "options": { "Color": "Black", "Size": "M" },
      "image": "https://media.ninjabuy.com/listings/weidian-7750970856/sku-black.webp",
      "cost": { "amount": "38.00", "currency": "CNY" },
      "price": { "amount": "49.99", "currency": "USD" },
      "in_stock": false,
      "units": 1,
      "weight_g": 180,
      "external_variant_id": null,
      "updated_at": "2026-11-04T09:20:03Z"
    }
  ],
  "has_more": false,
  "cursor": null
}

جلب متغيّر

GET/v1/variants/{id}

متغيّر واحد.

النطاقproducts:read

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

idstringمطلوب: معرّف المتغيّر.

الأخطاء

الحالة	النوع	متى
404	not-found	لا يوجد متغيّر كهذا في هذا الحساب.

curl "https://www.ninjabuy.com/api/v1/variants/var_41hz" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "id": "var_41hz",
  "product": "prd_8f2k",
  "sku": "5187209554",
  "label": "Black / M",
  "options": { "Color": "Black", "Size": "M" },
  "image": "https://media.ninjabuy.com/listings/weidian-7750970856/sku-black.webp",
  "cost": { "amount": "38.00", "currency": "CNY" },
  "price": { "amount": "49.99", "currency": "USD" },
  "in_stock": true,
  "units": 1,
  "weight_g": 180,
  "external_variant_id": "gid://shopify/ProductVariant/44100231",
  "updated_at": "2026-11-04T09:20:03Z"
}

تحديث متغيّر

PATCH/v1/variants/{id}

اضبط سعره، أو عدد القطع المشتراة لكل بيعة، أو وزنه، أو متغيّر المتجر الذي يقابله. أرسل ما يتغيّر فقط.

النطاقproducts:write

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

idstringمطلوب: معرّف المتغيّر.

النص

pricemoney: اختياري. سعر البيع لديك.
unitsinteger: اختياري. من 1 إلى 50.
weight_ginteger: اختياري. وزن القطعة الواحدة بعد التغليف، بالغرام.
external_variant_idstring|null: اختياري. اربطه بمتغيّر في متجرك، أو null لإلغاء الربط.

الأخطاء

الحالة	النوع	متى
404	not-found	لا يوجد متغيّر كهذا في هذا الحساب.
409	invalid-state	متغيّر المتجر ذلك يقابل SKU آخر أصلًا.

curl -X PATCH "https://www.ninjabuy.com/api/v1/variants/var_41hz" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Content-Type: application/json" \
  -d '{
    "units": 2,
    "price": { "amount": "89.99", "currency": "USD" }
  }'

Response 200

HTTP/2 200 OK

{
  "id": "var_41hz",
  "product": "prd_8f2k",
  "sku": "5187209554",
  "label": "Black / M",
  "options": { "Color": "Black", "Size": "M" },
  "image": "https://media.ninjabuy.com/listings/weidian-7750970856/sku-black.webp",
  "cost": { "amount": "38.00", "currency": "CNY" },
  "price": { "amount": "89.99", "currency": "USD" },
  "in_stock": true,
  "units": 2,
  "weight_g": 180,
  "external_variant_id": "gid://shopify/ProductVariant/44100231",
  "updated_at": "2026-11-04T09:20:03Z"
}