API запросов поставщику

Рассчитайте международную доставку до того, как покупатель оформит заказ

Для дивана, торшера, беговой дорожки или большой клетки для животных стоимость международной доставки почти полностью определяется тем, как товар реально упакован: весом в упаковке, габаритами коробки и количеством мест, в которых он отправляется.

Этих данных на карточках товаров 1688 и Taobao, как правило, нет или им нельзя доверять. А у вашего покупателя из-за этого возникает очень практическая проблема:

Он знает, сколько стоит товар. И совершенно не представляет, во сколько обойдётся доставить его в свою страну.

API запросов поставщику закрывает этот пробел. Сервис общения с поставщиками HIOBuy связывается с реальным поставщиком до покупки, уточняет вес в упаковке, габариты упаковки и данные о коробе и возвращает ответы в ваше приложение в виде структурированных данных — готовых для расчёта доставки.

Почему Product API недостаточно

API товаров надёжно возвращает то, что известно самой площадке: название, изображения, цену, SKU, характеристики, информацию о магазине. С логистическими данными всё иначе:

• вес вообще не указан;
• указан чистый вес товара, а не вес в упаковке;
• габариты товара есть, но не габариты после упаковки;
• вес вписан продавцом вручную и носит лишь ориентировочный характер;
• разные SKU упаковываются с разным весом;
• крупногабаритный товар отправляется несколькими местами;
• количества в коробе, веса короба и его размеров на странице нет вовсе.

Product API сообщает то, что знает площадка. Запрос поставщику даёт то, что может подтвердить только поставщик.

Пример: расчёт доставки дивана

Покупатель в США смотрит в вашем приложении диван с 1688 по цене ¥800. Product API уже вернул товар, цену, изображения, SKU и характеристики — но без достоверного веса в упаковке и габаритов упаковки.

А значит, ваше приложение не может ответить на единственный по-настоящему важный следующий вопрос:

Цена товара             ¥800
Международная доставка  ???

На крупногабаритном товаре эта неизвестная легко может превысить стоимость самого товара.

Ваше приложение создаёт запрос:

POST /v1/supplier-inquiries
{
  "product_url": "https://detail.1688.com/offer/554456348334.html",
  "questions": [
    { "type": "packed_weight" },
    { "type": "package_dimensions" },
    { "type": "carton_info" }
  ]
}

HIOBuy передаёт задачу сервису общения с поставщиками, и оператор в Китае связывается с реальным поставщиком этого предложения. Поставщик отвечает, что диван отправляется двумя местами:

Место 1   32 kg   110 × 75 × 55 cm
Место 2   18 kg    90 × 60 × 40 cm

Эти ответы возвращаются в ваше приложение структурированным JSON, а весь путь выглядит так:

Товар на 1688
      ↓  Product API
Цена: ¥800
      ↓  достоверных логистических данных нет
Запрос поставщику
      ↓  HIOBuy связывается с реальным поставщиком
Поставщик подтверждает: 2 места, 32 kg + 18 kg, габариты коробок
      ↓  структурированные логистические данные
Расчёт международной доставки (Китай → США)
      ↓
Покупатель видит примерную итоговую стоимость до покупки

В чём и состоит весь смысл:

Стоимость товара
+ расчётная международная доставка
= реалистичная стоимость до покупки

Место в линейке API HIOBuy

Product API           «Что это за товар и сколько он стоит?»
        ↓
API запросов поставщику  «Как поставщик реально его упакует?»
        ↓
Расчёт доставки       «Сколько примерно будет стоить международная доставка?»

Запрос поставщику — это недостающий слой между данными о товаре и расчётом доставки.

Не только данные для доставки

Данные об упаковке для расчёта доставки — это первый и самый наглядный сценарий использования этого API, но тот же канал общения с поставщиком отвечает на любые вопросы, ответ на которые знает только поставщик:

MOQ · наличие · срок производства · нейтральная упаковка · кастомизация · информация о коробе · детали товара · что угодно ещё через тип other.

Так что сегодня он даёт вам данные об упаковке → расчёт доставки, и тот же вызов равно хорошо работает как информация от поставщика → решение о закупке. Все десять типов и схемы их ответов см. в разделе типы вопросов.

Как это работает

1. Ваше приложение вызывает POST /v1/supplier-inquiries, передавая URL товара, необязательный SKU и один или несколько типизированных вопросов.
2. HIOBuy создаёт запрос и передаёт его сервису общения с поставщиками.
3. Оператор в Китае связывается с поставщиком этого предложения.
4. Поставщик отвечает.
5. Ответ приводится к структурированным данным по схеме соответствующего типа вопроса.
6. На ваш эндпоинт приходит вебхук supplier_inquiry.message_answered, либо вы опрашиваете GET /v1/supplier-inquiries/{id}.

Запрос — это диалог, а не единичный вызов. После его создания вы добавляете уточняющие сообщения в ту же ветку, а не открываете вторую.

Вложения

Некоторые вопросы гораздо проще задать с картинкой. Образец упаковки, скриншот SKU, чертёж с габаритами, спецификация — и в обратную сторону: собственное фото упаковки от поставщика, фото короба или PDF с коммерческим предложением.

Любое сообщение — и ваше, и от поставщика — может содержать до пяти вложений:

{
  "message": "Please ask the supplier whether they can use packaging similar to this.",
  "attachments": [
    {
      "type": "image",
      "url": "https://example.com/reference-packaging.jpg",
      "filename": "reference-packaging.jpg",
      "mime_type": "image/jpeg"
    }
  ]
}

type принимает значения image, document или other. URL должен начинаться с https://; всё остальное отклоняется с ошибкой INVALID_ATTACHMENT_URL.

Ответы поставщика тоже могут содержать вложения. Они приходят в массиве attachments соответствующего сообщения и в вебхуке supplier_inquiry.message_answered — вместе со структурированными ответами. Вы видите только те вложения, которые сервис запросов пометил как доступные вам: рабочие файлы оператора и скриншоты переписки с поставщиком остаются внутри сервиса и в API не попадают.

Доступ

Запросы поставщику по умолчанию отключены. HIOBuy включает эту возможность для каждого приложения отдельно после коммерческого подключения — чтобы запросить доступ, обратитесь в поддержку HIOBuy.

Если возможность не подключена или приостановлена, все эндпоинты возвращают 403 SUPPLIER_INQUIRY_NOT_ENABLED.

Поддерживаемые площадки

Всё остальное завершается ошибкой UNSUPPORTED_MARKETPLACE. Товар идентифицируется парой channel + source_product_id, а не самой строкой URL, поэтому разные варианты ссылок на одно предложение сводятся к одному товару.

Статусы запроса

Статусы pending, processing, waiting_supplier и answered считаются активными. Приложение может держать только один активный запрос по товару — именно это обеспечивает единую ветку общения с поставщиком по каждому предложению. Запрос на создание для товара с запросом в статусе completed или failed возобновляет тот диалог, а не создаёт новый.

Вебхуки

Зарегистрируйте эндпоинт в портале разработчика и подпишитесь на категорию supplier_inquiry. Подпись и повторные попытки подчиняются стандартным правилам вебхуков.

Каждый payload содержит inquiry_id и product.{channel,source_product_id}.

Коды ошибок

Код SUPPLIER_INQUIRY_SERVICE_UNAVAILABLE намеренно обобщённый: причины на стороне провайдера, такие как баланс или состояние аккаунта, не раскрываются. При обращении в поддержку укажите request_id.

Эндпоинты