Создание запроса поставщику

В диалог с поставщиком пишут два эндпоинта: один начинает его, другой продолжает. Оба принимают один и тот же массив questions и оба поддерживают заголовок Idempotency-Key.

Создание запроса

POST /v1/supplier-inquiries — scope 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 заполняются по мере возможности. Их обогащение использует API карточки товара, которому нужна авторизация на площадке — её у вашего приложения может не быть. Если она недоступна, эти поля остаются 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 — scope supplier_inquiry:write.

POST /v1/supplier-inquiries/sinq_9f2c.../messages
{
  "questions": [
    { "type": "lead_time", "note": "Для 500 штук" },
    { "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": "Для 500 штук", "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 хранит метаданные и URL, но никогда сам файл: он не загружает, не скачивает, не копирует и не проксирует содержимое вложений и никогда не обращается к переданному вами URL. Размещайте файл сами и убедитесь, что URL остаётся доступным для сервиса запросов всё время, пока диалог открыт.

Идемпотентность

Передавайте 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