手動仕入れ API

1つのチャネル、1人の販売者、1件の仕入れ注文

1件の仕入れ注文に複数の商品や SKU を含めることはできますが、すべて同じチャネル、同じ販売者の商品である必要があります。

顧客が異なる販売者やチャネルの商品を購入する場合、HIOBuy 注文 API を呼び出す前に、アプリケーション側でチャネルと販売者ごとに別々の仕入れ注文へ分割してください。

HIOBuy は仕入れ注文を自動分割せず、このフロー向けの一括注文 API も提供していません。

チャネルと販売者の識別方法

注文単位の channel を使用します。チャネル別の短縮パス、リクエスト本文、商品行のチャネルは一致させてください。lines[] や items[] に異なるチャネルを混在させないでください。
クライアントでのグループ分けには、取得できる場合は商品 API の実際の seller.id を使用します。1688 では sellerOpenId、Taobao の商品詳細では shop_id が元になります。自動生成された代替値 seller_1688_* / seller_taobao_*、欠落した ID、商品名、店舗名は信頼できる販売者の証明にはなりません。Taobao の店舗 ID とレンダリング応答の販売者 ID は異なる識別体系のため、直接比較しないでください。
標準の作成リクエストに新しい販売者の必須フィールドは追加されません。self モードでは、正式な注文作成前に Gateway が1688 の元の商品詳細から販売者を確認します。Taobao では render_item_list[].seller_id を使い、要求されたすべての商品と SKU が含まれていることも確認します。証明が不足する場合や帰属が曖昧な場合は拒否します。
Warehouse 仕入れモードでは、手動注文も含め、倉庫が注文作成、仕入れ開始、ウォレット引き落とし、一部成功の返却より前に販売者を検証します。Gateway は元のリクエストのチャネル競合を確認し、プラットフォームへの重複照会を行わず倉庫の検証エラーを転送します。倉庫側の受け入れ検証は別途必要です。Gateway の公開だけでは外部倉庫がこの検証を実装済みとは確認できません。
手動注文では channel=manual を指定し、全商品で同じ source_platform を使います。seller_name は表示用の申告にすぎません。倉庫は各商品の実際の販売者をプラットフォーム上で確認し、確認できなければ SELLER_ID_UNAVAILABLE を返す必要があります。呼び出し側の名称や ID の申告では代用できません。倉庫契約の受け入れ検証が完了するまで手動注文の作成機能を有効にしないでください。

エラーと対処方法

次の3つのエラーはすべて HTTP 400、カテゴリ VALIDATION_ERROR を返します。

エラーコード	対処方法
`MULTIPLE_CHANNELS_NOT_ALLOWED`	チャネルごとに分割し、短縮パス、本文、商品行のチャネルを一致させてください。
`MULTIPLE_SELLERS_NOT_ALLOWED`	各チャネル内で実際の販売者ごとに分割し、別々に注文を作成してください。
`SELLER_ID_UNAVAILABLE`	有効な商品／SKU の識別子、または信頼できる倉庫の販売者確認機能を用意してください。同じ内容の再試行や名称からの推測は避けてください。

混在注文に対して API が返す英語の原文：

A purchase order must contain products from the same channel and seller. Please split the items into separate orders by channel and seller.

販売者の検証で拒否した場合、仕入れ注文や仕入れタスクの作成、ウォレットの引き落とし、一部成功を発生させてはいけません。既存の冪等性ルールは引き続き適用されます。意図して分割した各仕入れには別の業務参照番号／キーを使い、内容が変わらない仕入れを再試行する際は元のキーを再利用してください。

仕入れ注文と倉庫での同梱発送

仕入れ注文は個々の販売者からの中国国内での購入に対応します。別々の仕入れ注文の商品を個別の荷物として入庫し、倉庫や配送の条件を満たせば、後で1件の国際発送へまとめることができます。同梱しても、元の仕入れ番号、国内送料、支払い、キャンセル、返金の状態は統合されません。

正しいリクエスト：検証済み販売者の複数 SKU

倉庫は両方の商品 URL が同じ安定したプラットフォーム販売者に属することを独立して確認する必要があります。例示 URL は販売者の証明や本番の受け入れ結果にはなりません。

{
  "channel": "manual",
  "external_order_id": "MANUAL-SELLER-A-001",
  "source_platform": "jd",
  "seller_name": "Seller A",
  "domestic_shipping_fee": 800,
  "currency": "CNY",
  "monetary_unit": "CNY_minor",
  "items": [
    {
      "product_url": "https://example.com/seller-A/shoe",
      "product_name": "Shoes",
      "specification": "Size 40",
      "unit_price": 5000,
      "quantity": 1
    },
    {
      "product_url": "https://example.com/seller-A/shoe",
      "product_name": "Shoes",
      "specification": "Size 41",
      "unit_price": 5000,
      "quantity": 1
    }
  ]
}

誤った例：実際の販売者が異なる

items[0].product_url が販売者 A、items[1].product_url が販売者 B の場合、リクエストに seller_name: "Seller A" があっても、倉庫は MULTIPLE_SELLERS_NOT_ALLOWED を返す必要があります。帰属を確認できない場合は、申告名称を信じて受け付けず SELLER_ID_UNAVAILABLE を返してください。

{
  "channel": "manual",
  "external_order_id": "INVALID-MIXED-001",
  "source_platform": "jd",
  "seller_name": "Seller A",
  "domestic_shipping_fee": 800,
  "currency": "CNY",
  "monetary_unit": "CNY_minor",
  "items": [
    {
      "product_url": "https://example.com/seller-A/shoe",
      "product_name": "Shoes",
      "specification": "Size 40",
      "unit_price": 5000,
      "quantity": 1
    },
    {
      "product_url": "https://example.com/seller-B/shirt",
      "product_name": "Shirt",
      "specification": "M",
      "unit_price": 3000,
      "quantity": 1
    }
  ]
}

倉庫の販売者検証による拒否は、既存の業務番号／冪等性契約に従って再現し、注文作成や引き落としを行ってはいけません。作成済み注文の再実行、詳細、支払い、キャンセルの動作は維持されます。

POST /v1/orders/manual

一つのリクエストで一つのプラットフォームと販売者の注文を作成します。同じ販売者の商品は複数指定できます。対応元は jd、pinduoduo、poizon のみで、seller_name は必須です。異なる販売者やプラットフォームは別の注文番号で送信してください。

Production API Key、order:create、warehouse モード、有効な倉庫連携が必要です。電商 OAuth は不要です。Sandbox は未対応です。倉庫の手動 API の実装と接続確認後に利用してください。

リクエスト

Authorization: Bearer <PRODUCTION_API_KEY>
Content-Type: application/json
Idempotency-Key: 6c14ce20-cf29-4c25-a9ee-3d36aac94c16

{
  "channel": "manual",
  "external_order_id": "EXT-10001",
  "source_platform": "jd",
  "seller_name": "Seller A",
  "domestic_shipping_fee": 800,
  "currency": "CNY",
  "monetary_unit": "CNY_minor",
  "language": "ja",
  "remark": "Please ship together",
  "items": [
    {
      "item_ref": "I001",
      "product_url": "https://example.com/item1",
      "product_name": "Wireless Mouse",
      "specification": "Black",
      "unit_price": 3500,
      "quantity": 2,
      "product_image": null,
      "remark": ""
    }
  ]
}

external_order_id はアプリの手動注文内で一意かつ必須です。同じ番号と内容は同じ注文を返し、内容の変更は HTTP 409 IDEMPOTENCY_CONFLICT です。新規購入には新しい番号を使います。作成、支払い、キャンセルには Idempotency-Key が必要です。order_sn は HIOBuy が生成し、item_ref は省略可能です。sellers 配列や商品行での販売者指定は不可です。

フィールド	必須値または上限
`channel`	`manual`
`external_order_id`	1–200
`source_platform`	`jd` / `pinduoduo` / `poizon`
`seller_name`	1–200
`currency` / `monetary_unit`	`CNY` / `CNY_minor`
`domestic_shipping_fee` / `items[].unit_price`	integer ≥ 0
`items` / `items[].quantity`	1–100 / 1–9999

倉庫の料金

金額は整数の CNY 分です。3500 は CNY 35.00 です。商品代、国内送料、既存の 5% 手数料と合計は倉庫が計算します。例は課金基準、最低料金、丸めを定義しません。HIOBuy は料金を保存し、5% を追加しません。金額や商品対応の欠落時は支払えません。

{
  "channel": "manual",
  "success": true,
  "order_id": "WH10001",
  "order_sn": "HB202610160001",
  "external_order_id": "EXT-10001",
  "source_platform": "jd",
  "seller_name": "Seller A",
  "status": "wait_payment",
  "currency": "CNY",
  "monetary_unit": "CNY_minor",
  "total": {
    "merchandise": {
      "amount": 7000,
      "currency": "CNY"
    },
    "shipping": {
      "amount": 800,
      "currency": "CNY"
    },
    "procurement_fee": {
      "amount": 390,
      "currency": "CNY"
    },
    "payment": {
      "amount": 8190,
      "currency": "CNY"
    }
  },
  "order_list": [
    {
      "order_id": "WH10001",
      "shipping": {
        "amount": 800,
        "currency": "CNY"
      },
      "lines": [
        {
          "item_ref": "I001",
          "sub_order_id": "WI10001",
          "title": "Wireless Mouse",
          "spec_title": "Black",
          "quantity": 2,
          "unit_price": {
            "amount": 3500,
            "currency": "CNY"
          },
          "line_total": {
            "amount": 7000,
            "currency": "CNY"
          }
        }
      ]
    }
  ],
  "failed_offers": [],
  "request_id": "req_example"
}

既存の注文操作

作成時は引き落としも仕入れも開始しません。返された order_id と channel=manual で既存の支払い、キャンセル、詳細、国内追跡 API を使用します。pay_amount は送信しません。倉庫金額を保存額と照合後、既存ウォレットで支払いを行い、支払確定後に仕入れます。キャンセルは返金完了を意味しません。

{
  "channel": "manual",
  "order_id": "WH10001"
}

{
  "channel": "manual",
  "order_id": "WH10001",
  "cancel_reason": "buyer_request"
}

再試行と制限

タイムアウト時は元の番号とキーを保持して詳細を確認し、新しいキーで自動再払いしないでください。詳細に payment_status と商品対応、料金を含みます。manual は電商注文一覧と電商返金 API に未対応です。商品行は 1–100、数量 1–9999、販売者名 200 文字、商品名と仕様 500、備考 1000、HTTP/HTTPS URL 2048。金額文字列と小数は不可です。

400 VALIDATION_ERROR · 403 FULFILLMENT_MODE_NOT_SUPPORTED / WAREHOUSE_AUTH_INVALID · 409 IDEMPOTENCY_CONFLICT / ORDER_AMOUNT_CHANGED / ORDER_OPERATION_UNRESOLVED · 502 WAREHOUSE_INVALID_RESPONSE · 503 WAREHOUSE_UNAVAILABLE

Webhooks

procurement.failed / procurement.out_of_stock

{
  "type": "procurement.failed",
  "data": {
    "channel": "manual",
    "order_id": "WH10001",
    "order_sn": "HB202610160001",
    "external_order_id": "EXT-10001",
    "source_platform": "jd",
    "seller_name": "Seller A",
    "status": "partial_failure",
    "reason_code": "OUT_OF_STOCK",
    "items": [
      {
        "item_ref": "I001",
        "sub_order_id": "WI10001",
        "quantity": 1,
        "reason_code": "OUT_OF_STOCK"
      }
    ]
  }
}

Get Support

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

Email support