OPENLOGI API v1.6 へ移行する際の手順と、バージョン間の仕様差分・対処方法をこのページでご案内します。
APIの全体仕様や個別エンドポイントの詳細は、APIリファレンスをご参照ください。
v1.6 を利用するには、すべてのAPIリクエストに X-Api-Version ヘッダを明示的に指定する必要があります。
リクエストヘッダに以下を追加してください。
X-Api-Version: 1.6
curlの場合の例：
export TOKEN="YOUR_API_TOKEN"
curl -sG 'https://api.openlogi.com/api/shipments' \
--variable '%TOKEN' \
--expand-header 'Authorization: Bearer {{TOKEN}}' \
-H 'X-Api-Version: 1.6'
X-Api-Version ヘッダを指定しないリクエストは、旧バージョンで動作するのでご注意ください。
旧バージョンは将来 Deprecated・End of Life となります。意図しない旧バージョン利用を避けるためにも、v1.6 への移行に合わせてすべてのリクエストでバージョンを明示することを強く推奨します。
v1.6 で仕様変更があるのは、以下の一覧系GETエンドポイントのみです。
| カテゴリ | エンドポイント | 概要 |
|---|---|---|
| 商品 | GET /api/items | 商品一覧 |
| 商品 | GET /api/items/{account_id} | code指定の商品一覧 |
| 入荷依頼 | GET /api/warehousings | 入荷依頼一覧 |
| 入荷実績 | GET /api/warehousings/stocked | 直近の入荷実績 |
| 入荷実績 | GET /api/warehousings/stocked/{year}/{month}/{day} | 指定年月日の入荷実績 |
| 出荷依頼 | GET /api/shipments | 出荷依頼一覧 |
| 出荷依頼 | GET /api/shipments/{account_id} | identifier指定の出荷依頼一覧 |
| 出荷実績 | GET /api/shipments/shipped | 直近の出荷実績 |
| 出荷実績 | GET /api/shipments/shipped/{year}/{month}/{day} | 指定年月日の出荷実績 |
ご利用中のアプリケーションが上記いずれかを呼び出している場合、以下「変更点ごとの仕様と対処方法」をご確認のうえ対応してください。
v1.6 では、一覧系GETのレスポンスに metadata.page プロパティが必ず含まれるようになります。
{
"shipments": [
{ "id": "AB001-S000001", "...": "..." },
{ "id": "AB001-S000002", "...": "..." }
]
}
{
"shipments": [
{ "id": "AB001-S000001", "...": "..." },
{ "id": "AB001-S000002", "...": "..." }
],
"metadata": {
"page": {
"next_cursor": "eyJrZXkiOjEwMDAwMCwic2FtcGxlTWV0YWRhdGEiOnRydWV9",
"has_more": true
}
}
}
| プロパティ | 型 | 説明 |
|---|---|---|
| next_cursor | string または null | 次ページ取得用カーソル。最終ページでは null |
| has_more | boolean | 次ページが存在する場合 true、最終ページでは false |
v1.6 から、影響を受ける一覧系GETエンドポイントに以下のクエリパラメータが追加されました。
| パラメータ | 型 | 必須 | デフォルト | 上限 | 説明 |
|---|---|---|---|---|---|
| cursor | string | 任意 | なし | — | 次ページ取得用カーソル。前回レスポンスの metadata.page.next_cursor の値をそのまま指定 |
| limit | integer | 任意 | 10 | 1,000 | 1ページあたりの取得件数 |
1ページ目のリクエスト（limit=100 を明示）：
export TOKEN="YOUR_API_TOKEN"
curl -sG 'https://api.openlogi.com/api/shipments' \
--variable '%TOKEN' \
--expand-header 'Authorization: Bearer {{TOKEN}}' \
-H 'X-Api-Version: 1.6' \
--data-urlencode 'limit=100'
レスポンス例：
{
"shipments": [
{ "id": "AB001-S000001", "...": "..." },
{ "id": "AB001-S000002", "...": "..." },
...
],
"metadata": {
"page": {
"next_cursor": "eyJrZXkiOjEwMDAwMCwic2FtcGxlTWV0YWRhdGEiOnRydWV9",
"has_more": true
}
}
}
shipments 配列には、指定した limit の件数（この例では100件）が入ります。
2ページ目のリクエスト（前回レスポンスの next_cursor を cursor パラメータに指定）：
export TOKEN="YOUR_API_TOKEN"
curl -sG 'https://api.openlogi.com/api/shipments' \
--variable '%TOKEN' \
--expand-header 'Authorization: Bearer {{TOKEN}}' \
-H 'X-Api-Version: 1.6' \
--data-urlencode 'limit=100' \
--data-urlencode 'cursor=eyJrZXkiOjEwMDAwMCwic2FtcGxlTWV0YWRhdGEiOnRydWV9'
v1.5 以下で呼び出していた一覧系GETは、v1.6 ではデフォルトで先頭10件しか返却されません。全件取得を前提とした実装は、移行後にエラーにならずに件数が欠落するため、必ず対応が必要です。
全件取得が必要な処理は、has_more が false になるまで next_cursor で追従する実装に書き換えてください。limit は実用的には100〜1,000の範囲を推奨します。
curl と jq を使った bash 例：
#!/bin/bash
set -e
export TOKEN="YOUR_API_TOKEN"
ENDPOINT="https://api.openlogi.com/api/shipments"
OUTPUT="shipments.jsonl"
: > "$OUTPUT"
cursor=""
while :; do
if [ -z "$cursor" ]; then
response=$(curl -sG "$ENDPOINT" \
--variable '%TOKEN' \
--expand-header 'Authorization: Bearer {{TOKEN}}' \
-H "X-Api-Version: 1.6" \
--data-urlencode "limit=100")
else
response=$(curl -sG "$ENDPOINT" \
--variable '%TOKEN' \
--expand-header 'Authorization: Bearer {{TOKEN}}' \
-H "X-Api-Version: 1.6" \
--data-urlencode "limit=100" \
--data-urlencode "cursor=${cursor}")
fi
echo "$response" | jq -c '.shipments[]' >> "$OUTPUT"
# 次ページ有無の確認
has_more=$(echo "$response" | jq -r '.metadata.page.has_more')
if [ "$has_more" != "true" ]; then
break
fi
# 次ページカーソルの取得
cursor=$(echo "$response" | jq -r '.metadata.page.next_cursor')
done
id や code、identifier などのクエリパラメータで複数件を指定して取得するケース（例: GET /api/items?id=A,B,C）も、v1.6 ではデフォルト limit=10 の影響を受けます。
export TOKEN="YOUR_API_TOKEN"
curl -sG 'https://api.openlogi.com/api/items' \
--variable '%TOKEN' \
--expand-header 'Authorization: Bearer {{TOKEN}}' \
-H 'X-Api-Version: 1.6' \
--data-urlencode 'id=AB001-I000001,AB001-I000002,...' \
--data-urlencode 'limit=100'
v1.6 で各エンドポイントの並び順がリファレンス上で明文化されました。v1.5 と比較して並び順そのものに変更はありませんが、cursor による追従の前提となるため改めてご確認ください。
| エンドポイント | 並び順 |
|---|---|
| GET /api/items | 商品ID 昇順 |
| GET /api/items/{account_id} | 商品ID 昇順 |
| GET /api/warehousings | 入荷ID 降順 |
| GET /api/warehousings/stocked | 初回入荷日時と入荷ID 昇順 |
| GET /api/warehousings/stocked/{year}/{month}/{day} | 初回入荷日時と入荷ID 昇順 |
| GET /api/shipments | 出荷ID 昇順 |
| GET /api/shipments/{account_id} | 出荷ID 昇順 |
| GET /api/shipments/shipped | 出荷完了日時と出荷ID 昇順 |
| GET /api/shipments/shipped/{year}/{month}/{day} | 出荷完了日時と出荷ID 昇順 |