マーチャント API：SKU、仕入れの事前登録、深圳倉庫の在庫を自社システムに連携

現在できること

• SKU を一括で作成・更新します（自社の seller_sku を基準とします）。色・サイズごとに個別の商品バーコードを設定し、Shopee／Coupang／momo の商品バリエーション番号に紐づけます。
• 11 桁の関税分類番号から輸入規制を自動照合し、商品検査や許可が必要な商品、輸入できない商品にフラグを付けます。
• 仕入れ時に追跡番号と箱ごとの内容物を事前登録します。荷物が深圳倉庫に届くと WO-SK ラベル貼付作業指示書が自動発行され、倉庫で一点ずつラベルを貼付し、スキャンして棚入れします。
• 倉庫別在庫と在庫履歴を照会し、入荷、入庫完了、数量差異、在庫変動を webhook でリアルタイムに受け取れます。

入庫フロー

1. SKU の作成：商品バーコード、バリエーション、申告品名、関税分類番号を送信します。
2. 入庫予定の登録：追跡番号と各 SKU の予定数量を送信します。
3. 深圳倉庫への入荷：追跡番号をスキャンすると WO-SK 作業指示書が自動で発行・印刷されます。
4. ラベル貼付・棚入れ：倉庫が商品バーコードを印刷し、一点ずつ貼付してスキャンで数量をカウントします。
5. 入庫完了：実際に受領した数量が深圳倉庫の在庫に計上され、破損品は別途計上されます。差異は自社システムに通知されます。

今後予定している機能

一括出荷オーダー、申告規定に基づいて自動でグループ化される出荷バッチ、桃園倉庫での事前在庫配置・仕分け・プラットフォーム配送ラベル。提供開始時に本ページでお知らせします。

利用開始の手順

1. 会員センターで「法人」の申告者を追加し、8 桁の統一編号を入力します。
2. HowBridge カスタマーサポートにマーチャント API の利用開始を申請してください。審査で承認されると API キーが発行されます。
3. API キーは一度しか表示されません。サーバー側の環境変数に保存し、ブラウザやアプリには含めないでください。
4. webhook を使う場合は、まず会員センターの API ページで URL を設定・検証してから、マーチャントイベントを購読してください。

Authorization: Bearer 12|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json

Base URL

形式と言語

リクエストとレスポンスはすべて JSON です。エラーメッセージはデフォルトで繁体字中国語です。Accept-Language: en を付けると英語で返されます。プログラムでの分岐には、常に英語で固定の error.code を使用してください。

レスポンス構造

成功時は {"success": true, "data": …, "meta": …}、失敗時は {"success": false, "error": {"code", "message", "errors", "context"}} を返します。errors はフィールドごとの詳細です。唯一の例外は API キーがない、または無効な場合で、HTTP 401、body は {"message": "Unauthenticated."} になります。

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "…",
    "errors": [
      { "code": "TRACKING_IN_USE", "field": "packages.0.tracking_no", "message": "…" }
    ]
  }
}

レート制限

API キーごとに毎分 60 回、1 日 5,000 回です（高利用量プランは毎分 300 回、1 日 50,000 回）。一括エンドポイントは 1 回の呼び出しを 1 回として数えます。リアルタイムのデータが必要な場合は、ポーリングせずに webhook を購読してください。

べき等性（Idempotency-Key）

書き込みリクエストには Idempotency-Key ヘッダーを付けられます（8–128 文字、英数字と _-:.）。ネットワークのタイムアウト後に同じキー・同じ内容で再送すると、初回のレスポンスが返り、ヘッダー Idempotent-Replayed: true が付きます。同じキーで内容を変えると 422 が返ります。記録は 24 時間保持されます。

一括処理のレスポンス

一括エンドポイントは 1 件ごとに結果を返します。すべて成功した場合は 200、一部が失敗した場合は 207、すべて失敗した場合は 422 です。各件には index、status（created／updated／failed）と失敗理由が含まれます。

識別子に使える文字

seller_sku には英数字と ._- のみ使用できます（1–64 文字）。商品バーコードではさらに / と + も使用できます（3–64 文字）。大文字と小文字は区別されません。

SKU の一括作成・更新

POST/api/v1/merchant/skus/batch

1 回あたり最大 200 件です。各件は個別に処理されるため、1 件が失敗しても他の件には影響しません。

リクエスト例（POST JSON）

curl -X POST https://0523.tw/api/v1/merchant/skus/batch \
  -H "Authorization: Bearer $LUCKY_MERCHANT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sku-sync-20260917-001" \
  -d '{
  "items": [
    {
      "seller_sku": "TEE-RED-S",
      "barcode": "4710000000011",
      "product_name": "Cotton T-shirt",
      "spec": { "color": "red", "size": "S" },
      "declared_name_en": "Cotton knitted T-shirt",
      "declared_unit_value": 18.5,
      "declared_currency": "CNY",
      "hs_code": "61091000006",
      "weight_g": 160,
      "channels": [ { "platform": "shopee", "shop_id": "123456", "item_id": "2233", "model_id": "445566" } ]
    }
  ]
}'

応答 200

{
  "success": true,
  "data": [
    {
      "index": 0,
      "seller_sku": "TEE-RED-S",
      "status": "created",
      "sku": {
        "seller_sku": "TEE-RED-S",
        "barcode": "4710000000011",
        "system_barcode": null,
        "pick_code": "131999",
        "hs_code": "61091000006",
        "regulation": { "status": "ok", "import_codes": [], "reasons": [] },
        "channels": [ { "platform": "shopee", "shop_id": "123456", "item_id": "2233", "model_id": "445566", "platform_sku": null } ]
      }
    }
  ],
  "meta": { "summary": { "created": 1, "updated": 0, "failed": 0 } }
}

輸入規制の判定（regulation.status）

SKU の一覧取得

GET/api/v1/merchant/skus

seller_sku、barcode、regulation_status、updated_since（ISO 8601）で絞り込み、page／per_page（最大 100）でページングできます。

SKU の個別取得

GET/api/v1/merchant/skus/{seller_sku}

プラットフォーム商品との紐づけの更新

PUT/api/v1/merchant/skus/{seller_sku}/channels

送信したリストで既存の紐づけをすべて置き換えます。同じプラットフォームのバリエーションを、2 つの SKU に同時に紐づけることはできません。

商品バーコードラベルのダウンロード

GET/api/v1/merchant/skus/{seller_sku}/label.pdf?qty=10

40×30mm のラベル PDF を返します。qty は枚数です（1–1000）。深圳倉庫でのラベル貼付時にも同じラベルを印刷します。出荷前に自社でラベルを貼りたい場合にご利用ください。

入庫オーダーの作成

POST/api/v1/merchant/inbound-orders

オーダー全体で検証し、エラーが 1 つでもあれば作成されません。1 つの追跡番号が同時に属せるのは、処理中の入庫オーダー 1 件のみです。同じ荷物内で重複した SKU は数量が合算されます。

リクエスト例（POST JSON）

curl -X POST https://0523.tw/api/v1/merchant/inbound-orders \
  -H "Authorization: Bearer $LUCKY_MERCHANT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: po-20260917-0001" \
  -d '{
  "reference_no": "PO-20260917-0001",
  "supplier_order_no": "1688-3312456789",
  "packages": [
    {
      "tracking_no": "YT1234567890123",
      "carrier": "yto",
      "items": [
        { "seller_sku": "TEE-RED-S", "qty": 40 },
        { "seller_sku": "TEE-RED-M", "qty": 60 }
      ]
    }
  ]
}'

入庫オーダーのステータス

荷物のステータス

入庫オーダーの一覧取得

GET/api/v1/merchant/inbound-orders

GET/api/v1/merchant/inbound-orders/{id}

status、reference_no、updated_since で絞り込めます。各荷物について、予定数量、実際の受領数量、破損数量と差異が返されます。

入庫オーダーのキャンセル

POST/api/v1/merchant/inbound-orders/{id}/cancel

キャンセルできるのは、どの荷物もまだ入荷していない場合のみです。キャンセル後は、その追跡番号を再度事前登録できます。

在庫の照会

GET/api/v1/merchant/inventory?warehouse_code=SZ

warehouse_code と seller_sku[]（最大 200 個）で絞り込めます。

応答 200

{
  "success": true,
  "data": [
    { "seller_sku": "TEE-RED-S", "barcode": "4710000000011", "warehouse_code": "SZ",
      "on_hand": 38, "reserved": 0, "available": 38, "damaged": 2, "updated_at": "2026-09-17T15:20:11+08:00" }
  ],
  "meta": { "total": 1, "page": 1, "per_page": 100, "last_page": 1 }
}

在庫履歴

GET/api/v1/merchant/inventory/movements?after_id=0&limit=200

追記のみで変更されない在庫変動の記録です。after_id カーソルで次のページを取得し（1 回あたり最大 500 件）、レスポンスの meta.next_after_id を保存しておけば、続きから取得して照合できます。

設定方法

1. 会員センターの API ページで webhook URL を設定し（https のみ）、所有権の検証を完了してください。エンドポイントは HTTP 200 を返し、body を {"challenge": "受信した値"} にする必要があります。
2. PUT /api/v1/merchant/webhook/events を呼び出してマーチャントイベントを購読します。その後、会員センターで URL を変更しても、マーチャントイベントの購読は解除されません。

curl -X PUT https://0523.tw/api/v1/merchant/webhook/events \
  -H "Authorization: Bearer $LUCKY_MERCHANT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": ["inbound.arrived", "inbound.received", "inbound.discrepancy", "inventory.changed"]}'

イベント一覧

inbound.received

{
  "event": "inbound.received",
  "delivery_id": "5b0f1c2e-8f3a-4d7e-9c21-0a6b2d4e8f10",
  "created_at": "2026-09-17T15:20:11+08:00",
  "data": {
    "inbound_order_id": 128,
    "reference_no": "PO-20260917-0001",
    "order_status": "completed_with_discrepancy",
    "tracking_no": "YT1234567890123",
    "work_order": "WO-SK-315",
    "warehouse_code": "SZ",
    "items": [
      { "seller_sku": "TEE-RED-S", "expected_qty": 40, "received_qty": 38, "damaged_qty": 2, "difference": 0 },
      { "seller_sku": "TEE-RED-M", "expected_qty": 60, "received_qty": 59, "damaged_qty": 0, "difference": -1 }
    ],
    "received_at": "2026-09-17T15:20:10+08:00"
  }
}

署名の検証

すべてのプッシュ通知には X-Lucky-Event、X-Lucky-Delivery-Id、X-Lucky-Signature: t=タイムスタンプ,v1=署名 が含まれます。webhook secret を使って「タイムスタンプ + . + 元の body」の HMAC-SHA256 を計算して v1 と比較し、5 分より古いタイムスタンプは拒否してください。同じイベントの再試行では delivery_id が変わらないため、重複排除に使用できます。

2xx 以外のレスポンスの場合、1 分後、5 分後、30 分後、2 時間後、6 時間後に再試行します。20 回連続で失敗すると自動的に無効化され、会員センターで再設定が必要になります。

// PHP
$body   = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_LUCKY_SIGNATURE'] ?? '';
parse_str(str_replace(',', '&', $header), $sig);   // ['t' => '1789…', 'v1' => 'ab12…']

$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $body, getenv('LUCKY_WEBHOOK_SECRET'));

if (! hash_equals($expected, $sig['v1'] ?? '') || abs(time() - (int) ($sig['t'] ?? 0)) > 300) {
    http_response_code(400);
    exit;
}
$event = json_decode($body, true);   // de-duplicate by $event['delivery_id']
http_response_code(200);

LINE 公式アカウント @0523tw

技術サポート用メール howyunqisoftware@gmail.com

バージョン v1 第1期（2026-09-17）：商品 SKU、入庫予定の登録、深圳倉庫でのラベル貼付・棚入れ、在庫照会、webhook。