الروابط
حقول الطلب، ونتائج كل رابط، والطلبات المتكررة.
إنشاء الروابط
يتطلب POST https://www.ninjabuy.com/api/v1/links رمز bearer وContent-Type: application/json.
| الحقل | القواعد |
|---|---|
links | مصفوفة إلزامية من 1 إلى 2,000 سلسلة نصية. تُحذف المسافات من طرفي كل إدخال، ويجب أن يتكون من 1 إلى 4,096 حرفًا. |
campaign | اختياري، من 3 إلى 64 حرفًا لاتينيًا صغيرًا أو رقمًا أو شرطة، ويبدأ بحرف أو رقم: ^[a-z0-9][a-z0-9-]{2,63}$. تحمله الزيارات بوصفه utm_campaign. |
label | اسم اختياري يظهر في قائمة روابطك: من 1 إلى 40 حرفًا قابلًا للطباعة بعد حذف المسافات من الطرفين، دون أحرف تحكم. يُنتج حذف المسافات تحذيرًا. |
async | قيمة منطقية اختيارية. القيمة true تبدأ دائمًا مهمة في الخلفية. |
يمكن تحويل روابط المنتجات من Taobao وTmall وWeidian و1688، وروابط وكلاء الشحن المدعومين وروابطهم المختصرة، ومتاجر Weidian وTaobao (بما في ذلك صفحة المتجر لدى وكيل مدعوم)، وصفحات NinjaBuy العامة المدعومة. يُقبل رابط NinjaBuy أو مسار مجرد مثل /search?q=hoodie. ولصق رابط إحالة موجود من NinjaBuy يُنشئ رابطك الخاص المنسوب إليك إلى الوجهة نفسها.
فوري أو دفعة
تُعيد حتى 100 مدخلات دون async: true الحالة 200 مع results وwarnings وrequest_id. أما أكثر من 100 مدخل، أو مع async: true، فتُعيد 202 مع مهمة وLocation وRetry-After. راجع البدء السريع والمهام.
تحافظ النتائج على ترتيب المدخلات، بما في ذلك المدخلات المكررة. يحتوي كل صف على input وstatus، مع الحقول الاختيارية target وurl وcode وnote.
| الحالة | المعنى |
|---|---|
ok | تم التحويل؛ url هو رابط NinjaBuy المنسوب إليك. |
unsupported | تم التعرف عليه لكن لا يمكن إنشاء رابط له، مثل متجر إلكتروني غير مدعوم أو صفحة NinjaBuy خاصة. |
unreadable | تعذرت قراءة أي وجهة صالحة للاستخدام. |
sheet | رابط Google Sheets؛ لا تحوّل نقطة النهاية هذه محتواه. |
بالنسبة إلى الجدول، استخدم واجهة الجداول البرمجية لتحويل محتواه إلى XLSX، أو الصقه على NinjaBuy. ويمكن لصفحة NinjaBuy موجودة بصيغة /spreadsheets/d/<sheet id> أن تحصل هي نفسها على رابط منسوب إليك.
الطلبات المتكررة ونسب الإحالة
للحساب نفسه والوجهة الموحّدة نفسها والحملة والتسمية نفسيهما، يُعيد الإنشاء الرابط نفسه عبر REST وMCP والمعالجة بالدفعات. أما الحملة أو التسمية المختلفة فتحصل على رابط منفصل. ومن دون Idempotency-Key، تؤدي إعادة محاولة دفعة إلى إنشاء مهمة جديدة؛ فإعادة استخدام الروابط لا تزيل تكرار طلبات المهام.
تسجّل روابط REST الجديدة createdVia: "api". وتحافظ إعادة استخدام رابط على مصدره الأصلي (api أو mcp أو share أو redirect). يتوفر هذا الحقل في نتائج MCP list_links وlink، لا في استجابة الإنشاء عبر REST. راجع الإحالة لمعرفة كيفية النسب والتقارير.
Idempotency-Key
يمكنك اختياريًا إرسال Idempotency-Key مع POST /api/v1/links أو POST /api/v1/uploads أو POST /api/v1/sheets لإعادة محاولة طلب دون إنشاء مهمة أخرى أو استهلاك خانة أخرى من خانات إنشاء الروابط. استخدم مفتاحًا فريدًا لكل طلب مقصود: من 1 إلى 255 حرف ASCII قابلًا للطباعة.
Idempotency-Key: partner-batch-2026-10-23-001لمدة 24 ساعة، يؤدي الحساب نفسه والمفتاح نفسه والطلب نفسه الذي جرى التحقق منه إلى إعادة الحالة الأصلية والمحتوى المطابق بايتًا ببايت والترويسات، بما في ذلك request_id الأصلي، مع Idempotent-Replayed: true. لا يهم ترتيب المفاتيح في كائنات JSON. وبعد 24 ساعة يمكن إعادة استخدام المفتاح.
- محتوى مختلف أو مسار POST مختلف بالمفتاح نفسه يُعيد
422(idempotency-key-reused)؛ استخدم مفتاحًا جديدًا. - أثناء تنفيذ الطلب الأول، تُعيد المحاولات
409(idempotency-key-in-progress) معRetry-After؛ انتظر قبل إعادة المحاولة. - المفتاح غير الصالح يُعيد
400(bad-idempotency-key). ولا يحجز المحتوى غير الصالح أي مفتاح. - بمجرد بدء التنفيذ، تُخزَّن أول إجابة له، بما في ذلك الأخطاء. أما
429فلا تُخزَّن: أعد المحاولة بالمفتاح نفسه بعدRetry-After.
قد يبقى الطلب المتعطل قيد التنفيذ حتى تنتهي صلاحية المفتاح. وإعادة تشغيل الطلبات هذه منفصلة عن إعادة استخدام الروابط المطابقة الموضحة أعلاه.