إنشاء استفسار مورد

هناك نقطتا نهاية للكتابة في محادثة المورد: واحدة تبدأ المحادثة وأخرى تكمّلها. كلتاهما تستقبلان مصفوفة questions نفسها وتقبلان ترويسة Idempotency-Key.

إنشاء استفسار

POST /v1/supplier-inquiries — النطاق supplier_inquiry:write.

جسم الطلب

الحقل	مطلوب	الوصف
`product_url`	نعم	رابط مطلق لمنتج على 1688 أو Taobao، بحد أقصى 2048 حرفًا
`questions`	نعم	من 1 إلى 10 أسئلة، راجع أنواع الأسئلة
`sku`	لا	`{ "id": "...", "label": "..." }`، 200 حرف لكل منهما — يحصر السؤال في متغيّر واحد
`attachments`	لا	حتى 5 مراجع لملفات، راجع المرفقات

POST /v1/supplier-inquiries
Authorization: Bearer hio_live_...
Idempotency-Key: inq-2026-05-20-001
 
{
  "product_url": "https://detail.1688.com/offer/554456348334.html",
  "sku": { "id": "3245:12345", "label": "أسود / XL" },
  "questions": [
    { "type": "packed_weight", "note": "الوزن مع علبة البيع بالتجزئة" },
    { "type": "carton_info" },
    { "type": "neutral_packaging" }
  ]
}

الاستجابة

201 Created، أو 200 OK عندما يعيد Idempotency-Key تنفيذ طلب سابق.

{
  "id": "sinq_9f2c...",
  "status": "waiting_supplier",
  "product": {
    "channel": "1688",
    "source_product_id": "554456348334",
    "product_url": "https://detail.1688.com/offer/554456348334.html",
    "canonical_product_url": "https://detail.1688.com/offer/554456348334.html",
    "title": "...",
    "image": "...",
    "shop_id": "...",
    "shop_name": "..."
  },
  "sku": {
    "id": "3245:12345",
    "label": "أسود / XL"
  },
  "message_count": 1,
  "last_message_at": "2026-05-20T08:31:12.000Z",
  "created_at": "2026-05-20T08:31:11.000Z",
  "updated_at": "2026-05-20T08:31:12.000Z",
  "message": {
    "id": "smsg_1a4b...",
    "type": "initial",
    "status": "waiting_supplier"
  },
  "request_id": "req_..."
}

تُملأ الحقول title وimage وshop_id وshop_name على أساس بذل أقصى جهد. فإثراؤها يستخدم واجهة تفاصيل المنتج التي تتطلب تفويضًا من السوق قد لا يملكه تطبيقك — وعند عدم توفره تبقى هذه الحقول بقيمة null ويستمر الاستفسار بشكل طبيعي.

استفسار نشط واحد لكل منتج

إذا كان للمنتج استفسار نشط بالفعل، يفشل الطلب:

409 Conflict
{
  "error": {
    "code": "ACTIVE_INQUIRY_EXISTS",
    "message": "An active supplier inquiry already exists for this product.",
    "details": { "inquiry_id": "sinq_9f2c...", "next_action": "add_message" }
  }
}

استخدم قيمة inquiry_id المُعادة لإرسال رسالة متابعة. أما إذا كانت المحادثة السابقة بحالة completed أو failed، فإن طلب الإنشاء يعيد فتحها بدلاً من الفشل، وتُسجَّل الرسالة الجديدة بالنوع follow_up.

طرح سؤال متابعة

POST /v1/supplier-inquiries/{inquiry_id}/messages — النطاق supplier_inquiry:write.

POST /v1/supplier-inquiries/sinq_9f2c.../messages
{
  "questions": [
    { "type": "lead_time", "note": "For 500 units" },
    { "type": "moq" }
  ],
  "attachments": [
    {
      "type": "image",
      "url": "https://cdn.example.com/packaging-example.jpg",
      "filename": "packaging-example.jpg",
      "mime_type": "image/jpeg"
    }
  ]
}

201 Created
{
  "inquiry_id": "sinq_9f2c...",
  "status": "waiting_supplier",
  "message": {
    "id": "smsg_77de...",
    "type": "follow_up",
    "status": "waiting_supplier",
    "questions": [
      { "id": "sqst_...", "type": "lead_time", "note": "For 500 units", "question": null, "status": "pending", "answer": null }
    ],
    "attachments": [
      {
        "id": "satt_...",
        "type": "image",
        "url": "https://cdn.example.com/packaging-example.jpg",
        "filename": "packaging-example.jpg",
        "mime_type": "image/jpeg",
        "source": "developer",
        "expires_at": null,
        "created_at": "2026-05-20T10:02:00.000Z"
      }
    ],
    "provider_note": null,
    "created_at": "2026-05-20T10:02:00.000Z",
    "answered_at": null
  },
  "request_id": "req_..."
}

الاستفسار بحالة cancelled يرفض الرسائل الجديدة بالخطأ 409 INQUIRY_NOT_ACTIVE. أما الاستفسار بحالة completed أو failed فيُعاد فتحه.

المرفقات

تقبل نقطتا الكتابة كلتاهما مصفوفة attachments اختيارية — صورة مرجعية، أو لقطة شاشة لوحدة SKU، أو رسم للأبعاد، أو ملف PDF للمواصفات. تنتمي المرفقات إلى الرسالة التي ترسلها معها، لذا تحمل كل جولة من المحادثة مرفقاتها الخاصة.

الحقل	مطلوب	الوصف
`url`	نعم	بصيغة `https://` فقط، بحد أقصى 2048 حرفًا. أما `http:` و`file:` و`data:` و`javascript:` و`ftp:` فتُرفض بالخطأ `INVALID_ATTACHMENT_URL`
`type`	لا	`image` أو `document` أو `other`؛ والقيمة الافتراضية `other`
`filename`	لا	بحد أقصى 255 حرفًا
`mime_type`	لا	بحد أقصى 128 حرفًا — القيمة التي تصرّح بها، وتُخزَّن كما هي

خمسة مرفقات كحد أقصى لكل رسالة، وإلا فالخطأ 400 TOO_MANY_ATTACHMENTS.

تخزّن HIOBuy البيانات الوصفية والرابط، لا الملف نفسه: فهي لا ترفع محتوى المرفقات ولا تنزّله ولا تنسخه ولا تمرّره عبر وسيط، ولا تجلب أبدًا الرابط الذي ترسله. استضِف الملف بنفسك واحرص على أن يظل الرابط قابلاً للوصول من خدمة الاستفسارات طوال بقاء المحادثة مفتوحة.

عدم التكرار (Idempotency)

أرسل ترويسة Idempotency-Key (أو X-Idempotency-Key، بحد أقصى 200 حرف) على نقطتي الكتابة كلتيهما. يؤدي تكرار المفتاح نفسه داخل التطبيق ذاته إلى إعادة الرسالة التي أُنشئت في المرة الأولى، بالحالة 200 بدلاً من 201، ودون التواصل مع المورد مرتين.

أعد دائمًا محاولة طلب الإنشاء الذي انتهت مهلته باستخدام المفتاح نفسه — فبدونه قد تفتح إعادة المحاولة محادثة ثانية أو تصطدم بالخطأ ACTIVE_INQUIRY_EXISTS.

Get Support

Need integration help? Contact Developer Support at support@hiobuy.com · Response within 1–2 business days

Email support