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

الاستيرادات

الصق رابط صفحة منتج، واحصل على متغيّراتها وتكلفة بيع كلٍّ منها: البضاعة، ورسوم الاستلام ‏12.00 CN¥‎ لطرد البائع إلينا، والضريبة الثابتة 14%، ثم خط الشحن، ورسوم المناولة ‏50.00 CN¥‎ لكل طرد والضريبة عليها، ورسوم المنصة، والسعر الذي يحافظ على هامشك.

الاستيراد مجاني، دون حد للمنتجات. تدفع فقط مقابل ما تطلبه.
كل رقم يخص قطعة واحدة، مشتراة في طلبها الخاص ومشحونة في طردها الخاص: بيعة دروبشيبينغ واحدة. عدة قطع في طلب أو طرد واحد تكلّف أقل مما يذكره هذا.
رسوم المنصة افتراضيًا هي النسبة المعلنة لكل منصة. أرسل نسبتك حين تختلف فئتك أو خطتك.

نقاط النهاية

POST/v1/importsاستورد من رابط
POST/v1/imports/{id}/analysisأعد تسعيره
GET/v1/imports/{id}جلب استيراد
GET/v1/importsعرض الاستيرادات
POST/v1/imports/{id}/saveاحفظ كمنتج

كائن Import

صفحة منتج كما قرأناها، مع تكلفة البيعة الواحدة واصلةً إلى باب مشتريك: البضاعة، ورسوم الاستلام ‏12.00 CN¥‎ لطرد البائع إلينا، والضريبة الثابتة 14%، ثم خط الشحن، ورسوم المناولة ‏50.00 CN¥‎ لكل طرد والضريبة عليها. بالدولار الأمريكي، هي ما تُحصّله بطاقة بالدولار، شاملًا تحويل العملة.

idstring: يبدأ بـ imp_.
statusstring: running (جدول اكتشافات ما زالت قراءته جارية)، أو ready، أو failed.
urlstring: الرابط الذي أرسلته.
marketplacestring: taobao أو tmall أو weidian أو 1688.
title, seller, images[]string: كما كتبها البائع، بالصينية في الغالب.
read_atstring: آخر مرة قرأنا فيها صفحة المنتج من المنصة.
analysis.ship_to, lane, weight_g: المدخلات التي سُعِّر على أساسها.
analysis.coveredboolean: false حين لا يوجد سعر منشور يشحن إلى تلك الدولة على ذلك الخط، وحينها لا يكون لأي متغيّر تكلفة واصلة.
analysis.marketplace_feeobject: percent وfixed: ما تأخذه المنصة من البيعة. تكون default قيمة true حين لم ترسل شيئًا واستخدمنا نسبتها المعلنة، وهي تقدير، وليست فاتورتك الحقيقية أبدًا.
analysis.margin_reachableboolean: false حين تأخذ الرسوم والهامش معًا السعر كله: لا يمكن لأي سعر بلوغه.
analysis.brand_hintobject|null: كلمات علامات تجارية أو تقليد في العنوان، بالإنجليزية أو الصينية. تلميح لا حكم: لا يرى الشعار في الصورة، والنتيجة النظيفة لا تثبت شيئًا.
analysis.variants[].procurementobject: goods وintake_fee وtax وtotal للطلب الذي يشتري قطعة واحدة.
analysis.variants[].seller_shippingobject|null: شحن البائع إلى مستودعنا. لا تذكره أي صفحة منتج، فهو null: غير معروف، لا مجاني.
analysis.variants[].parcelobject|null: lane وshipping وhandling_fee وtax وtotal للطرد الذي يشحنه.
analysis.variants[].landedobject: السلعة والطرد معًا: بـ CN¥ وبالدولار الأمريكي، مع رسوم التحويل ضمن المبلغ بالدولار.
analysis.variants[].minimum_priceobject|null: أقل سعر يحافظ على هامشك بعد رسوم المنصة.
analysis.variants[].suggestedobject|null: أقل سعر x.99 يساوي الحد الأدنى أو يتجاوزه، مع الرسوم والربح والهامش الذي يتركه.
productstring|null: المنتج الذي صار إليه بعد الحفظ.

import

{
  "id": "imp_2c9d",
  "status": "ready",
  "url": "https://weidian.com/item.html?itemID=7750970856",
  "marketplace": "weidian",
  "title": "Heavyweight washed hoodie",
  "seller": "Ruoyi Studio",
  "images": [
    "https://media.ninjabuy.com/listings/weidian-7750970856/1.webp"
  ],
  "read_at": "2026-11-04T09:12:40Z",
  "analysis": {
    "ship_to": "US",
    "lane": "saver",
    "weight_g": 180,
    "covered": true,
    "marketplace": "ebay",
    "marketplace_fee": {
      "percent": "13.6",
      "fixed": { "amount": "0.40", "currency": "USD" },
      "default": true
    },
    "margin_percent": "30",
    "margin_reachable": true,
    "brand_hint": null,
    "variants": [
      {
        "sku": "5187209554",
        "label": "Black / M",
        "in_stock": true,
        "procurement": {
          "goods": { "amount": "38.00", "currency": "CNY" },
          "intake_fee": { "amount": "12.00", "currency": "CNY" },
          "tax": { "amount": "7.00", "currency": "CNY" },
          "total": { "amount": "57.00", "currency": "CNY" }
        },
        "seller_shipping": null,
        "parcel": {
          "lane": "saver",
          "shipping": { "amount": "68.00", "currency": "CNY" },
          "handling_fee": { "amount": "50.00", "currency": "CNY" },
          "tax": { "amount": "16.52", "currency": "CNY" },
          "total": { "amount": "134.52", "currency": "CNY" }
        },
        "landed": {
          "cny": { "amount": "191.52", "currency": "CNY" },
          "usd": { "amount": "27.71", "currency": "USD" },
          "fx_fee": { "amount": "5.75", "currency": "CNY" }
        },
        "minimum_price": { "amount": "49.84", "currency": "USD" },
        "suggested": {
          "price": { "amount": "49.99", "currency": "USD" },
          "marketplace_fee": { "amount": "7.20", "currency": "USD" },
          "profit": { "amount": "15.08", "currency": "USD" },
          "margin_percent": "30.16"
        }
      },
      {
        "sku": "5187209555",
        "label": "Black / L",
        "in_stock": false,
        "procurement": {
          "goods": { "amount": "38.00", "currency": "CNY" },
          "intake_fee": { "amount": "12.00", "currency": "CNY" },
          "tax": { "amount": "7.00", "currency": "CNY" },
          "total": { "amount": "57.00", "currency": "CNY" }
        },
        "seller_shipping": null,
        "parcel": {
          "lane": "saver",
          "shipping": { "amount": "68.00", "currency": "CNY" },
          "handling_fee": { "amount": "50.00", "currency": "CNY" },
          "tax": { "amount": "16.52", "currency": "CNY" },
          "total": { "amount": "134.52", "currency": "CNY" }
        },
        "landed": {
          "cny": { "amount": "191.52", "currency": "CNY" },
          "usd": { "amount": "27.71", "currency": "USD" },
          "fx_fee": { "amount": "5.75", "currency": "CNY" }
        },
        "minimum_price": { "amount": "49.84", "currency": "USD" },
        "suggested": {
          "price": { "amount": "49.99", "currency": "USD" },
          "marketplace_fee": { "amount": "7.20", "currency": "USD" },
          "profit": { "amount": "15.08", "currency": "USD" },
          "margin_percent": "30.16"
        }
      }
    ]
  },
  "product": null,
  "created_at": "2026-11-04T09:12:41Z"
}

استورد من رابط

POST/v1/imports

يقرأ صفحة منتج على Taobao أو Tmall أو Weidian أو 1688 (يعمل أيضًا الرابط المختصر، أو رابط وكيل تسوّق آخر إليها) ويُرجعها محلّلة، في الاستدعاء نفسه. صفحة المنتج التي قرأناها في آخر خمس دقائق لا تُجلب مجددًا.

رابط جدول اكتشافات (https://www.ninjabuy.com/spreadsheets/d/…) يستورد كل منتج فيه: 202 مع status: running، ثم استعلم عن حالة الاستيراد.

النطاقproducts:write

النص

urlstringمطلوب: رابط منتج، أو جدول اكتشافات.
ship_tostring: رمز الدولة من حرفين لتسعير الطرد لها. القيمة US إن لم تُحدَّد.
lanestring: saver أو fast. القيمة saver إن لم تُحدَّد.
weight_gintegerمطلوب: وزن القطعة الواحدة بعد التغليف، بالغرام. صفحات المنتجات لا تذكر الوزن، فيُسعَّر الطرد على وزنك.
marketplacestring: أين تبيعه: ebay أو shopify أو amazon أو tiktok. القيمة shopify إن لم تُحدَّد.
marketplace_feeobject: اختياري. percent وfixed (بالدولار الأمريكي) لاستخدامهما بدل النسبة المعلنة للمنصة، حسب فئتك أو خطتك.
margin_percentstring: الهامش المستهدف في التسعير، من سعر البيع. القيمة 30 إن لم تُحدَّد.

الأخطاء

الحالة	النوع	متى
400	bad-body	weight_g مفقود، أو حقل خارج النطاق المسموح.
422	unprocessable	ليس رابطًا يمكننا قراءته، أو أن صفحة المنتج لم تعد موجودة.
429	rate-limited	استُنفدت نافذة المنصة؛ راجع حدود المعدّل.

curl -X POST "https://www.ninjabuy.com/api/v1/imports" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://weidian.com/item.html?itemID=7750970856",
    "ship_to": "US",
    "weight_g": 180,
    "marketplace": "ebay",
    "margin_percent": "30"
  }'

Response 201

HTTP/2 201 Created

{
  "id": "imp_2c9d",
  "status": "ready",
  "url": "https://weidian.com/item.html?itemID=7750970856",
  "marketplace": "weidian",
  "title": "Heavyweight washed hoodie",
  "seller": "Ruoyi Studio",
  "images": [
    "https://media.ninjabuy.com/listings/weidian-7750970856/1.webp"
  ],
  "read_at": "2026-11-04T09:12:40Z",
  "analysis": {
    "ship_to": "US",
    "lane": "saver",
    "weight_g": 180,
    "covered": true,
    "marketplace": "ebay",
    "marketplace_fee": {
      "percent": "13.6",
      "fixed": { "amount": "0.40", "currency": "USD" },
      "default": true
    },
    "margin_percent": "30",
    "margin_reachable": true,
    "brand_hint": null,
    "variants": [
      {
        "sku": "5187209554",
        "label": "Black / M",
        "in_stock": true,
        "procurement": {
          "goods": { "amount": "38.00", "currency": "CNY" },
          "intake_fee": { "amount": "12.00", "currency": "CNY" },
          "tax": { "amount": "7.00", "currency": "CNY" },
          "total": { "amount": "57.00", "currency": "CNY" }
        },
        "seller_shipping": null,
        "parcel": {
          "lane": "saver",
          "shipping": { "amount": "68.00", "currency": "CNY" },
          "handling_fee": { "amount": "50.00", "currency": "CNY" },
          "tax": { "amount": "16.52", "currency": "CNY" },
          "total": { "amount": "134.52", "currency": "CNY" }
        },
        "landed": {
          "cny": { "amount": "191.52", "currency": "CNY" },
          "usd": { "amount": "27.71", "currency": "USD" },
          "fx_fee": { "amount": "5.75", "currency": "CNY" }
        },
        "minimum_price": { "amount": "49.84", "currency": "USD" },
        "suggested": {
          "price": { "amount": "49.99", "currency": "USD" },
          "marketplace_fee": { "amount": "7.20", "currency": "USD" },
          "profit": { "amount": "15.08", "currency": "USD" },
          "margin_percent": "30.16"
        }
      },
      {
        "sku": "5187209555",
        "label": "Black / L",
        "in_stock": false,
        "procurement": {
          "goods": { "amount": "38.00", "currency": "CNY" },
          "intake_fee": { "amount": "12.00", "currency": "CNY" },
          "tax": { "amount": "7.00", "currency": "CNY" },
          "total": { "amount": "57.00", "currency": "CNY" }
        },
        "seller_shipping": null,
        "parcel": {
          "lane": "saver",
          "shipping": { "amount": "68.00", "currency": "CNY" },
          "handling_fee": { "amount": "50.00", "currency": "CNY" },
          "tax": { "amount": "16.52", "currency": "CNY" },
          "total": { "amount": "134.52", "currency": "CNY" }
        },
        "landed": {
          "cny": { "amount": "191.52", "currency": "CNY" },
          "usd": { "amount": "27.71", "currency": "USD" },
          "fx_fee": { "amount": "5.75", "currency": "CNY" }
        },
        "minimum_price": { "amount": "49.84", "currency": "USD" },
        "suggested": {
          "price": { "amount": "49.99", "currency": "USD" },
          "marketplace_fee": { "amount": "7.20", "currency": "USD" },
          "profit": { "amount": "15.08", "currency": "USD" },
          "margin_percent": "30.16"
        }
      }
    ]
  },
  "product": null,
  "created_at": "2026-11-04T09:12:41Z"
}

أعد تسعيره

POST/v1/imports/{id}/analysis

صفحة المنتج نفسها لدولة أو خط أو وزن أو منصة أو هامش آخر. تُسعَّر مما قرأناه مسبقًا، فلا تستهلك استدعاءً للمنصة. يُرجع التحليل الجديد ويحفظه في الاستيراد.

النطاقproducts:write

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

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

النص

ship_tostring: رمز الدولة من حرفين لتسعير الطرد لها. القيمة US إن لم تُحدَّد.
lanestring: saver أو fast. القيمة saver إن لم تُحدَّد.
weight_gintegerمطلوب: وزن القطعة الواحدة بعد التغليف، بالغرام. صفحات المنتجات لا تذكر الوزن، فيُسعَّر الطرد على وزنك.
marketplacestring: أين تبيعه: ebay أو shopify أو amazon أو tiktok. القيمة shopify إن لم تُحدَّد.
marketplace_feeobject: اختياري. percent وfixed (بالدولار الأمريكي) لاستخدامهما بدل النسبة المعلنة للمنصة، حسب فئتك أو خطتك.
margin_percentstring: الهامش المستهدف في التسعير، من سعر البيع. القيمة 30 إن لم تُحدَّد.

الأخطاء

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

curl -X POST "https://www.ninjabuy.com/api/v1/imports/imp_2c9d/analysis" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ship_to": "GB",
    "lane": "fast",
    "weight_g": 180,
    "marketplace": "tiktok",
    "margin_percent": "35"
  }'

Response 200

HTTP/2 200 OK

{
  "ship_to": "GB",
  "lane": "fast",
  "weight_g": 180,
  "covered": true,
  "marketplace": "tiktok",
  "marketplace_fee": {
    "percent": "6",
    "fixed": { "amount": "0.00", "currency": "USD" },
    "default": true
  },
  "margin_percent": "35",
  "margin_reachable": true,
  "brand_hint": null,
  "variants": [
    {
      "sku": "5187209554",
      "label": "Black / M",
      "in_stock": true,
      "procurement": {
        "goods": { "amount": "38.00", "currency": "CNY" },
        "intake_fee": { "amount": "12.00", "currency": "CNY" },
        "tax": { "amount": "7.00", "currency": "CNY" },
        "total": { "amount": "57.00", "currency": "CNY" }
      },
      "seller_shipping": null,
      "parcel": {
        "lane": "saver",
        "shipping": { "amount": "68.00", "currency": "CNY" },
        "handling_fee": { "amount": "50.00", "currency": "CNY" },
        "tax": { "amount": "16.52", "currency": "CNY" },
        "total": { "amount": "134.52", "currency": "CNY" }
      },
      "landed": {
        "cny": { "amount": "191.52", "currency": "CNY" },
        "usd": { "amount": "27.71", "currency": "USD" },
        "fx_fee": { "amount": "5.75", "currency": "CNY" }
      },
      "minimum_price": { "amount": "49.84", "currency": "USD" },
      "suggested": {
        "price": { "amount": "49.99", "currency": "USD" },
        "marketplace_fee": { "amount": "7.20", "currency": "USD" },
        "profit": { "amount": "15.08", "currency": "USD" },
        "margin_percent": "30.16"
      }
    },
    {
      "sku": "5187209555",
      "label": "Black / L",
      "in_stock": false,
      "procurement": {
        "goods": { "amount": "38.00", "currency": "CNY" },
        "intake_fee": { "amount": "12.00", "currency": "CNY" },
        "tax": { "amount": "7.00", "currency": "CNY" },
        "total": { "amount": "57.00", "currency": "CNY" }
      },
      "seller_shipping": null,
      "parcel": {
        "lane": "saver",
        "shipping": { "amount": "68.00", "currency": "CNY" },
        "handling_fee": { "amount": "50.00", "currency": "CNY" },
        "tax": { "amount": "16.52", "currency": "CNY" },
        "total": { "amount": "134.52", "currency": "CNY" }
      },
      "landed": {
        "cny": { "amount": "191.52", "currency": "CNY" },
        "usd": { "amount": "27.71", "currency": "USD" },
        "fx_fee": { "amount": "5.75", "currency": "CNY" }
      },
      "minimum_price": { "amount": "49.84", "currency": "USD" },
      "suggested": {
        "price": { "amount": "49.99", "currency": "USD" },
        "marketplace_fee": { "amount": "7.20", "currency": "USD" },
        "profit": { "amount": "15.08", "currency": "USD" },
        "margin_percent": "30.16"
      }
    }
  ]
}

جلب استيراد

GET/v1/imports/{id}

أعد قراءة استيراد، أو استعلم عن جدول اكتشافات أثناء قراءته.

النطاقproducts:read

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

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

الأخطاء

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

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

Response 200

HTTP/2 200 OK

{
  "id": "imp_6t1b",
  "status": "running",
  "url": "https://www.ninjabuy.com/spreadsheets/d/1aBcD3fGh",
  "progress": { "done": 41, "total": 120 },
  "poll_after_seconds": 10
}

عرض الاستيرادات

GET/v1/imports

الأحدث أولًا. الاستيرادات التي لم تحفظها تبقى هنا لتعود إليها.

النطاقproducts:read

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

statusstring: اختياري. running أو ready أو failed.
savedboolean: اختياري. true للاستيرادات التي صارت منتجات.
limit, cursor: Pagination

curl "https://www.ninjabuy.com/api/v1/imports?saved=false&limit=2" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "data": [
    {
      "id": "imp_2c9d",
      "status": "ready",
      "title": "Heavyweight washed hoodie",
      "product": null
    },
    {
      "id": "imp_2c7a",
      "status": "ready",
      "title": "Canvas tote, 3 colours",
      "product": null
    }
  ],
  "has_more": true,
  "cursor": "c_2c7a"
}

احفظ كمنتج

POST/v1/imports/{id}/save

يحفظ المتغيّرات التي تختارها كمنتج، بالأسعار التي تضبطها أو المقترحة. أضف push_to: shopify لعرضه في متجرك في الاستدعاء نفسه (الإرسال إلى Shopify).

النطاقproducts:write

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

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

النص

variants[]array: اختياري. sku وprice لكل متغيّر تريد الاحتفاظ به. كل متغيّر متوفر بسعره المقترح إن لم يُحدَّد.
titlestring: اختياري. عنوانك الخاص؛ عنوان البائع بالصينية في الغالب.
push_tostring: اختياري. shopify.

الأخطاء

الحالة	النوع	متى
409	invalid-state	محفوظ مسبقًا، ويذكره product.
422	unprocessable	كل المتغيّرات التي أبقيتها نافدة.

curl -X POST "https://www.ninjabuy.com/api/v1/imports/imp_2c9d/save" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Heavyweight Washed Hoodie",
    "variants": [
      {
        "sku": "5187209554",
        "price": { "amount": "49.99", "currency": "USD" }
      }
    ],
    "push_to": "shopify"
  }'

Response 201

HTTP/2 201 Created

{
  "import": "imp_2c9d",
  "product": "prd_8f2k",
  "status": "draft",
  "channels": [{ "channel": "shopify", "status": "draft" }]
}