サプライヤー問い合わせの作成

サプライヤーとの会話に書き込むエンドポイントは 2 つあります。1 つは会話を開始し、もう 1 つは会話を継続します。どちらも同じ questions 配列を受け取り、Idempotency-Key に対応しています。

問い合わせを作成する

POST /v1/supplier-inquiries — スコープ supplier_inquiry:write。

リクエストボディ

フィールド	必須	説明
`product_url`	はい	1688 または淘宝の商品リンク（絶対 URL、最大 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、または Idempotency-Key により以前のリクエストが再生された場合は 200 OK。

{
  "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 のままとなり、問い合わせは通常どおり進行します。

商品ごとにアクティブな問い合わせは 1 件のみ

対象商品にすでにアクティブな問い合わせがある場合、リクエストは失敗します。

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": "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 文字。申告された値がそのまま保存されます

1 つのメッセージにつき添付ファイルは最大 5 件です。超過した場合は 400 TOO_MANY_ATTACHMENTS になります。

HIOBuy が保存するのはメタデータと URL のみで、ファイル自体は保存しません。添付ファイルの内容をアップロード・ダウンロード・複製・プロキシすることはなく、送信された URL を取得しに行くこともありません。ファイルは自身でホストし、会話が開いている間は問い合わせサービスから URL に到達できる状態を保ってください。

冪等性

両方の書き込みエンドポイントで Idempotency-Key（または X-Idempotency-Key、最大 200 文字）を送信してください。同一アプリケーション内で同じキーを再送すると、最初に作成されたメッセージが 201 ではなく 200 で返され、サプライヤーへの連絡が二重に行われることはありません。

タイムアウトした作成リクエストは必ず同じキーで再試行してください。キーがないと、再試行によって 2 つ目の会話が作成されたり、ACTIVE_INQUIRY_EXISTS になったりする可能性があります。

Get Support

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

Email support