サプライヤー問い合わせ API

購入前に国際送料を見積もる

ソファ、フロアランプ、ランニングマシン、大型のペットケージ — こうした商品の国際送料は、実際にどう梱包されるか でほぼ決まります。つまり梱包後の重量、箱のサイズ、そして何個口で発送されるかです。

しかし 1688 や淘宝の商品ページには、そのデータが載っていないか、載っていても信頼できないのが日常です。その結果、顧客はきわめて現実的な問題に直面します。

商品の値段はわかる。しかし自国まで届けるのにいくらかかるのかは、まったくわからない。

サプライヤー問い合わせ API はこのギャップを埋めます。HIOBuy のサプライヤーコミュニケーションサービスが購入前に実際のサプライヤーへ連絡し、梱包重量・梱包サイズ・カートンの詳細を確認して、その回答を構造化データとしてアプリケーションに返します。送料見積もりにそのまま渡せる形です。

商品 API では足りない理由

商品 API は、マーケットプレイス自身が把握している情報 — タイトル、画像、価格、SKU、属性、ショップ情報 — を確実に返してくれます。ただし物流データについては話が別です。

• 重量がまったく掲載されていない。
• 表示されている重量が梱包後の重量ではなく、商品本体の重量である。
• 商品サイズは載っているが、梱包後のサイズは載っていない。
• 重量は出品者が手入力したもので、あくまで目安に過ぎない。
• SKU が違えば梱包後の重量も違う。
• 大型商品は複数の荷物に分割して発送される。
• カートンの入り数、カートン重量、カートンサイズはページのどこにも書かれていない。

商品 API はマーケットプレイスが知っていることを教えてくれます。サプライヤーしか確認できない情報を得るには、サプライヤー問い合わせが必要です。

例: ソファの送料を見積もる

米国の顧客が、あなたのアプリで ¥800 の 1688 のソファを見ています。商品 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 はこのタスクをサプライヤーコミュニケーションサービスに引き渡し、中国拠点のオペレーターがその出品の実際のサプライヤーへ連絡します。サプライヤーからは、ソファは 2 個口で発送されるとの回答が返ります。

荷物 1   32 kg   110 × 75 × 55 cm
荷物 2   18 kg    90 × 60 × 40 cm

これらの回答は構造化された JSON としてアプリケーションに戻り、全体の流れは次のようになります。

1688 の商品
      ↓  商品 API
価格: ¥800
      ↓  信頼できる物流データがない
サプライヤー問い合わせ
      ↓  HIOBuy が実際のサプライヤーに連絡
サプライヤーが確認: 2 個口、32 kg + 18 kg、箱のサイズ
      ↓  構造化された物流データ
国際送料の見積もり（中国 → 米国）
      ↓
顧客は購入前におおよその総額を確認できる

これがこの一連の作業の目的です。

商品代金
+ 国際送料の見積もり
= 購入前に把握できる現実的なコスト

HIOBuy の API 群における位置づけ

商品 API                    「その商品は何で、いくらなのか？」
        ↓
サプライヤー問い合わせ API   「サプライヤーは実際にどう梱包するのか？」
        ↓
送料見積もり                「国際輸送にはおおよそいくらかかるのか？」

サプライヤー問い合わせは、商品データと送料見積もりの間に欠けていたレイヤーです。

送料データだけではありません

送料見積もりのための梱包データは、この API のもっとも具体的で最初のユースケースですが、同じサプライヤーコミュニケーションチャネルは、サプライヤーしか知り得ないあらゆる情報にも回答します。

MOQ・在庫・リードタイム・無地梱包・カスタマイズ・カートン情報・商品詳細、そして other タイプによるその他の質問。

つまり現時点では 梱包データ → 送料見積もり を実現しますが、同じ呼び出しで サプライヤー情報 → 仕入れ判断 にも同様に使えます。10 種類すべてと回答スキーマについては 質問タイプ を参照してください。

仕組み

1. アプリケーションが商品 URL、任意の SKU、1 つ以上の型付けされた質問を指定して POST /v1/supplier-inquiries を呼び出します。
2. HIOBuy が問い合わせを作成し、サプライヤーコミュニケーションサービスに引き渡します。
3. 中国拠点のオペレーターがその出品のサプライヤーに連絡します。
4. サプライヤーが返信します。
5. 返信は各質問タイプのスキーマに沿って構造化データへ正規化されます。
6. 登録したエンドポイントに supplier_inquiry.message_answered の Webhook が届くか、GET /v1/supplier-inquiries/{id} をポーリングして取得します。

問い合わせは単発のリクエストではなく 会話 です。いったん作成したら、新しい問い合わせを立てるのではなく同じスレッドに追加メッセージを送り続けます。

添付ファイル

質問のなかには、画像があるだけで格段に伝わりやすくなるものがあります。梱包の参考画像、SKU のスクリーンショット、寸法図、仕様書 — そして逆方向では、サプライヤー自身が撮った梱包写真、カートンの写真、見積書の PDF などです。

あなた側とサプライヤー側のどちらのメッセージも、最大 5 件の添付ファイルを持てます。

{
  "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 Webhook に、構造化された回答とあわせて届きます。参照できるのは、問い合わせサービスがあなたに開示すると判断した添付ファイルのみです。オペレーターの作業用ファイルやサプライヤーとのチャットのスクリーンショットはサービス内部に留まり、API には届きません。

利用条件

サプライヤー問い合わせは デフォルトで無効 です。商用オンボーディング後に HIOBuy がアプリケーション単位で有効化します。利用をご希望の場合は HIOBuy サポートにご連絡ください。

機能が付与されていない、または停止されている場合、すべてのエンドポイントは 403 SUPPLIER_INQUIRY_NOT_ENABLED を返します。

対応マーケットプレイス

それ以外は UNSUPPORTED_MARKETPLACE で失敗します。商品は URL 文字列そのものではなく channel + source_product_id で識別されるため、同一商品に対する形式の異なるリンクは同じ商品として解決されます。

問い合わせステータス

pending、processing、waiting_supplier、answered は アクティブ として扱われます。1 つのアプリケーションが同一商品に対して保持できるアクティブな問い合わせは 1 件のみで、これにより商品ごとに 1 本のサプライヤースレッドが保たれます。completed または failed の問い合わせがある商品に対して作成リクエストを送ると、新規作成ではなくその会話が再開されます。

Webhook

デベロッパーポータルでエンドポイントを登録し、supplier_inquiry カテゴリを購読してください。署名と再送は標準の Webhook ルールに従います。

すべてのペイロードに inquiry_id と product.{channel,source_product_id} が含まれます。

エラーコード

SUPPLIER_INQUIRY_SERVICE_UNAVAILABLE は意図的に汎用的なコードです。残高やアカウント状態といったプロバイダー側の理由は公開されません。サポートに問い合わせる際は request_id を添えてください。

エンドポイント