قراءة استفسارات الموردين

ثلاث نقاط نهاية للقراءة، وجميعها تتطلب النطاق supplier_inquiry:read. الاستفسارات محصورة بالتطبيق الذي أنشأها: فمعرّف استفسار يخص تطبيقًا آخر يُرجع 404 INQUIRY_NOT_FOUND وليس 403.

سرد الاستفسارات

GET /v1/supplier-inquiries

معامل الاستعلامالوصف
statusحالة استفسار واحدة (pending، processing، waiting_supplier، answered، completed، failed، cancelled)
channel1688 أو taobao
source_product_idمعرّف المنتج الدقيق في السوق
created_after / created_beforeطوابع زمنية بصيغة ISO 8601
pageالقيمة الافتراضية 1
limitالقيمة الافتراضية 20، بحد أقصى 100
GET /v1/supplier-inquiries?status=answered&channel=1688&limit=20
 
{
  "data": [
    {
      "id": "sinq_9f2c...",
      "status": "answered",
      "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": 2,
      "last_message_at": "2026-05-20T10:02:00.000Z",
      "created_at": "2026-05-20T08:31:11.000Z",
      "updated_at": "2026-05-20T11:40:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 1, "total_pages": 1 },
  "request_id": "req_..."
}

أي قيمة غير معروفة في status أو channel تُرفض بالرمز 400، حتى لا يؤدي خطأ إملائي إلى إرجاع كل شيء بصمت.

تفاصيل الاستفسار

GET /v1/supplier-inquiries/{inquiry_id} يُرجع الملخّص إضافة إلى المحادثة كاملة وخطًا زمنيًا مختصرًا.

{
  "id": "sinq_9f2c...",
  "status": "answered",
  "product": {
    "channel": "1688",
    "source_product_id": "554456348334",
    "...": "..."
  },
  "sku": {
    "id": "3245:12345",
    "label": "أسود / XL"
  },
  "message_count": 2,
  "messages": [
    {
      "id": "smsg_1a4b...",
      "type": "initial",
      "status": "answered",
      "questions": [
        {
          "id": "sqst_...",
          "type": "packed_weight",
          "note": "Weight with the retail box",
          "question": null,
          "status": "answered",
          "answer": {
            "question_id": "sqst_...",
            "type": "packed_weight",
            "status": "answered",
            "value": 1250,
            "unit": "g",
            "provider_note": null,
            "answered_at": "2026-05-20T11:40:00.000Z"
          }
        }
      ],
      "attachments": [
        {
          "id": "satt_...",
          "type": "image",
          "url": "https://files.example.com/packaging.jpg",
          "filename": "supplier-packaging.jpg",
          "mime_type": "image/jpeg",
          "source": "supplier",
          "expires_at": null,
          "created_at": "2026-05-20T11:40:00.000Z"
        }
      ],
      "provider_note": null,
      "created_at": "2026-05-20T08:31:12.000Z",
      "answered_at": "2026-05-20T11:40:00.000Z"
    }
  ],
  "timeline": [
    {
      "message_id": "smsg_1a4b...",
      "type": "initial",
      "status": "answered",
      "created_at": "2026-05-20T08:31:12.000Z",
      "answered_at": "2026-05-20T11:40:00.000Z"
    }
  ],
  "request_id": "req_..."
}

يكون الحقل question غير فارغ فقط مع الأسئلة من النوع other. والسؤال الذي لم تصل إجابته بعد يكون بالحالة status: "pending" مع answer: null.

تسرد المصفوفة attachments مراجع الملفات المرتبطة بتلك الرسالة — تلك التي أرسلتها أنت، إضافة إلى ما شاركه معك طرف المورد. ويميّز بينها الحقل source (developer، operator، supplier، system). أما الملفات التي تُبقيها خدمة الاستفسارات داخلية فلا تُعاد هنا إطلاقًا. ولا تستضيف HIOBuy هذه الملفات: فالحقل url يشير إلى مساحة تخزين المزوّد أو مساحتك أنت، وقيمة expires_at غير الفارغة هي اللحظة التي قد يتوقف بعدها ذلك الرابط عن العمل.

الرسائل فقط

GET /v1/supplier-inquiries/{inquiry_id}/messages يُرجع كائنات الرسائل نفسها دون كتلة المنتج — وهو الاستدعاء الأقل كلفة عندما تكون بيانات الاستفسار لديك بالفعل ولا تريد سوى الإجابات الجديدة.

{
  "inquiry_id": "sinq_9f2c...",
  "status": "answered",
  "data": [ /* messages, oldest first */ ],
  "request_id": "req_..."
}

الاستعلام الدوري مقابل Webhooks

فضّل Webhook الخاص بالحدث supplier_inquiry.message_answered: فحمولته تحمل أصلاً مصفوفة answers كاملة، ولذلك يكفيك الإشعار وحده في أغلب الأحيان. وإذا اخترت الاستعلام الدوري بدلاً من ذلك، فاستعلم من نقطة نهاية الرسائل بفواصل زمنية تُقاس بالدقائق — فالإجابات تصل وفق مقاييس زمنية بشرية، والاستعلام كل بضع ثوانٍ لا يؤدي إلا إلى استهلاك حد المعدل.

Get Support

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

Email support