OpenAPI ドキュメント

本文書はサードパーティシステム開発者向けに、OpenAPI を通じて倉庫、物流チャネル、在庫を照会し、注文出庫作成を実行し、注文ステータスと注文物流情報を照会する方法を説明します。

オンラインデバッグ >

1. 概要

項目	説明
プロトコル	HTTPS
データ形式	application/json; charset=UTF-8
リクエストメソッド	すべて POST
文字エンコーディング	UTF-8
認証方法	AppKey + HMAC-SHA256 署名（ログイントークン不要）

API 一覧（合計 13 個）：

番号	API 名	パス
1	倉庫リスト取得	POST /openapi/warehouse/list
2	物流チャネルリスト取得	POST /openapi/shipping/list
3	SKU 別在庫照会	POST /openapi/inventory/query
4	ページネーション在庫照会	POST /openapi/inventory/page
5	注分出庫作成	POST /openapi/order/create
6	計画ID別注文リスト照会	POST /openapi/order/listByPlan
7	注文ステータス照会	POST /openapi/order/status
8	注文物流照会	POST /openapi/order/tracking
9	商品カテゴリツリー照会	POST /openapi/goods/category/list
10	商品作成	POST /openapi/goods/create
11	商品更新	POST /openapi/goods/update
12	商品SKU照会	POST /openapi/goods/get
13	商品SKUページネーション照会	POST /openapi/goods/page

Base URL は AppKey 有効化時に運営者から提供されます。以下のテキストでは {baseUrl} として表されます。例：https://wms.example.com。

2. 認証と署名

すべての /openapi/** API は、HTTP リクエストヘッダーに以下の 4 つのフィールドを含める必要があります：

リクエストヘッダー	必須	説明
App-Key	はい	オープンプラットフォームによって割り当てられたクライアント識別子。形式：T{6 桁のテナント ID}_xxx。例：T123456_merchant_a
Timestamp	はい	Unix タイムスタンプ（秒）。サーバー時刻との偏差は 5 分以内である必要があります
Nonce	はい	ランダム文字列。5 分以内に重複してはなりません（リプレイ防止）
Sign	はい	リクエスト署名。以下のアルゴリズムを参照

2.1 署名アルゴリズム

1. リクエストボディから署名に参加する文字列を取得します（ボディがない場合は空文字列 "" を使用）

2. JSON 正規化：リクエストボディが JSON オブジェクトまたは配列の場合、まず解析してからコンパクトにシリアライズします（改行/インデントを削除、フィールド順序は解析結果に基づきます）。したがって、Postman ではフォーマットされた JSON を使用できます。内容が署名時と一致している限り問題ありません。

3. 文字列を順番に連結します：

signRaw = AppKey + Timestamp + Nonce + RequestBody

4. AppSecret を使用して signRaw に HMAC-SHA256 を実行し、大文字の 16 進数文字列（固定 64 文字）を出力します。これが Sign です。

Java 例：

Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(appSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
byte[] digest = mac.doFinal(signRaw.getBytes(StandardCharsets.UTF_8));
String sign = HexFormat.of().formatHex(digest).toUpperCase();

Python 例：

import hmac
import hashlib

sign = hmac.new(
    app_secret.encode("utf-8"),
    sign_raw.encode("utf-8"),
    hashlib.sha256
).hexdigest().upper()

2.2 署名例

前提条件：

• AppKey = T123456_test
• AppSecret = your_secret
• Timestamp = 1719500000
• Nonce = abc123def456
• RequestBody = {"warehouseCode":"JP001"}

結果：

signRaw = T123456_test1719500000abc123def456{"warehouseCode":"JP001"}
Sign    = HMAC-SHA256(signRaw, your_secret) → 大文字 HEX（64 文字）

2.3 合同デバッグ署名ツール（推奨）

開発および合同デバッグには、内部 API POST /openApi/debug/buildHeaders を呼び出すことができます（ログインホワイトリストが必要）。リクエスト例：

{
  "appKey": "T755003_xxxx",
  "appSecret": "your_secret",
  "body": {
    "warehouseCode": "JP001",
    "orderList": []
  }
}

• body：ネストされた JSON。エスケープ不要（推奨）
• headers が返され、ビジネス OpenAPI リクエストヘッダーに直接コピーできます
• requestBody が返され、署名に参加する正規化された JSON 文字列です
• ビジネス API ボディの形式は body フィールドの形式と異なっていても問題ありません（改行/インデントは影響しません）。JSON 内容が一致していれば問題ありません

2.4 レート制限

各 AppKey のデフォルト制限：60 回 / 60 秒。超えると code=429 が返されます。

3. 統一レスポンス形式

すべての OpenAPI レスポンスは JSON で、以下の構造です：

{
  "code": 0,
  "message": "success",
  "data": {}
}

フィールド	型	説明
code	int	ビジネスステータスコード。0 は成功を示します
message	string	ステータスの説明
data	object / array / null	ビジネスデータ。失敗時は通常 null です

3.1 ステータスコードの説明

認証レイヤーエラー（フィルターインターセプト。ビジネスロジックに入らない）：

code	message	説明
0	success	成功
401	AppKey Invalid	AppKey が欠落、形式エラー、またはテナントが無効
402	Sign Invalid	署名が正しくない
403	Client Not Found	クライアントが存在しない、またはマーチャントにバインドされていない
404	Client Disabled	クライアントが無効化または期限切れ
406	Request Expired	タイムスタンプが 5 分ウィンドウを超える
407	Duplicate Request	Nonce が重複（リプレイリクエスト）
429	Request Rate Limited	レート制限がトリガーされた
500	System Error	システム例外

ビジネスレイヤーエラー（Controller に入った後に返される）：

code	一般的な message	説明
500	Client not bound to merchant	AppKey に対応するクライアントがマーチャントに関連付けられていない
500	Warehouse does not exist or is disabled	渡された warehouseCode が無効、または倉庫が無効化されている
500	Order does not exist	sourceOrderNo によって対応する注分出庫記録が見つからない
500	warehouseCode cannot be empty	パラメータ検証に失敗
500	orderList cannot be empty	パラメータ検証に失敗
500	orderList maximum 200 items	注文リストが上限を超える
500	sourceOrderNo cannot be empty	パラメータ検証に失敗
500	skuList cannot be empty	パラメータ検証に失敗
500	skuList maximum 200 items	SKU リストが上限を超える
500	specifiedCarrier only allows yamato_takkyubin（ヤマト運輸・宅急便）	指定された配送方法が不正
500	deliveryDate format must be yyyy-MM-dd	配送日の形式エラー
500	deliveryTimeSlot only allows 812, 1416, 1618, 1820, 1921	配送時間帯が不正

HTTP ステータスコードは常に 200 です。レスポンスボディの code を使用して成功を判断してください。

4. API 詳細

OpenAPIオープンプラットフォームでAPI詳細を確認してください

API詳細を確認 >

5. 完全な呼び出し例（cURL）

「倉庫リスト取得」を例とします：

# 変数（実際の値に置き換えてください）
BASE_URL="https://wms.example.com"
APP_KEY="T123456_your_client"
APP_SECRET="your_app_secret"
TIMESTAMP=$(date +%s)
NONCE=$(uuidgen | tr -d '-')
BODY='{}'

# 署名を計算（HMAC-SHA256 を自分で実装するか、以下に説明するツール言語を使用する必要があります）
SIGN_RAW="${APP_KEY}${TIMESTAMP}${NONCE}${BODY}"
# SIGN = HMAC-SHA256(SIGN_RAW, APP_SECRET) 大文字 HEX

curl -X POST "${BASE_URL}/openapi/warehouse/list" \
  -H "Content-Type: application/json" \
  -H "App-Key: ${APP_KEY}" \
  -H "Timestamp: ${TIMESTAMP}" \
  -H "Nonce: ${NONCE}" \
  -H "Sign: ${SIGN}" \
  -d "${BODY}"

6. 連携提案

1. 最初に倉庫リストを呼び出す：有効な warehouseCode を取得してから、物流チャネルと在庫 API を呼び出します。

2. 在庫同期戦略：

   • SKU 数が少なく、正確な照会が必要な場合は /inventory/query を使用
   • 全量同期が必要な場合は /inventory/page ページネーション取得を使用（推奨 pageSize=500）

3. Nonce 生成：UUID またはスノーフレーク ID の使用を推奨。各リクエストの一意性を確保します。

4. 時計同期：クライアントサーバーの標準時刻からの偏差は 5 分以内に抑える必要があります。

5. エラーリトライ：407 Duplicate Request の場合は Nonce を変更してリトライ。429 の場合は頻度を下げるか、バックオフリトライ。406 の場合は時刻を校正してリトライ。

6. データ分離：注文と在庫データは AppKey にバインドされたマーチャントのデータのみを含み、他のマーチャントのデータは照会できません。

7. 注文照会提案：注文作成後、/openapi/order/status を使用して最新ステータスをポーリングできます。物流番号、運送業者などの情報が必要な場合は、/openapi/order/tracking を呼び出します。

7. 付録：在庫フィールド説明

フィールド	ビジネス意味
availableQty	現在注文/割り当てに使用可能な在庫数量
lockedQty	すでに注文またはビジネスによって占有され、まだ出荷されていない数量
onwayQty	すでに出荷され輸送中、まだ入庫が完了していない数量