公開API v1→v2 マイグレーションガイド

はじめに

このドキュメントは、ZAICO公開API v1を利用しているエンジニアが、v2へ移行する際に必要な情報をまとめたものです。

v2では以下の主要な変更が行われています:

• URLパス構造: company_idスコープが必須化
• レスポンス構造: エンベロープ形式 ({ data, pagination }) に統一
• ページネーション: HTTPヘッダからレスポンスボディへ移行
• エラーレスポンス: RFC 7807 Problem Details 形式に準拠
• 認証方式: Bearerスキームのみに統一、組織向けAPIトークン（新プラン）を追加

対象読者

公開APIを利用するクライアントアプリケーションの開発者

関連ドキュメント

• 公開API v1 ドキュメント: https://zaicodev.github.io/zaico_api_doc/
  • v1 のエンドポイント仕様・リクエスト/レスポンス形式の詳細は引き続きこちらを参照してください

1. 破壊的変更の一覧

1.1 URLパス構造の変更

v1ではリソースに直接アクセスしていましたが、v2ではcompany_id（拠点ID）によるスコープが必須になりました。

# v1
GET /api/v1/inventories

# v2
GET /api/v2/orgs/companies/123/inventories

v2では、すべてのリソース操作でURLにcompany_idを含める必要があります。company_idは認証ユーザーがアクセス可能な拠点のIDです。

1.2 レスポンス構造の変更（エンベロープ形式）

v1では配列やオブジェクトを直接返していましたが、v2ではエンベロープ形式に統一されました。

コレクション（一覧）レスポンス:

// v1: 配列を直接返却
[
  { "id": 1, "title": "在庫A" },
  { "id": 2, "title": "在庫B" }
]

// v2: エンベロープ形式
{
  "data": [
    { "id": 1, "title": "在庫A" },
    { "id": 2, "title": "在庫B" }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 100,
    "total_count": 2,
    "total_pages": 1
  }
}

単一リソースレスポンス:

// v1: オブジェクトを直接返却
{ "id": 1, "title": "在庫A" }

// v2: エンベロープ形式
{
  "data": { "id": 1, "title": "在庫A" }
}

1.3 ページネーションの変更

注意: v1 は全エンドポイント共通で Total-Count / Link ヘッダ + 1000件固定でしたが、v2 は エンドポイントごとに DEFAULT / MAX の per_page が異なります。一覧取得の挙動を実装する際は 3.4 節を必ず確認してください。

v1のページネーション（HTTPヘッダ）:

HTTP/1.1 200 OK
Total-Count: 2500
Link: <https://web.zaico.co.jp/api/v1/inventories?page=1>; rel="first",
      <https://web.zaico.co.jp/api/v1/inventories?page=2>; rel="next",
      <https://web.zaico.co.jp/api/v1/inventories?page=3>; rel="last"

v2のページネーション（レスポンスボディ）:

{
  "data": [...],
  "pagination": {
    "current_page": 1,
    "per_page": 100,
    "total_count": 2500,
    "total_pages": 25
  }
}

1.4 エラーレスポンス形式の変更（RFC 7807）

v2ではエラーレスポンスがRFC 7807 Problem Details形式に変更されました。

// v1
{
  "code": 403,
  "status": "error",
  "message": "Could not access API. Please Check Token or enabled API function."
}

// v2
{
  "title": "Forbidden",
  "status": 403,
  "detail": "編集権限がありません"
}

1.5 認証方式の変更

各APIトークン種別の v1/v2 ごとの呼び出し可否は 3.3 APIトークン v1/v2 互換性マトリクス を参照してください。

v2ではTokenスキームは廃止されました。すべてのリクエストでBearerスキームを使用してください。

# v1（どちらも利用可能）
Authorization: Bearer {token}
Authorization: Token {token}

# v2（Bearerのみ）
Authorization: Bearer {token}

1.6 フィールド形式の変更

一部のフィールドの型や形式が変更されています。

2. エンドポイント対応表

2.1 v1→v2対応エンドポイント

v2のベースパス: /api/v2/orgs/companies/{company_id}

2.2 v2で新規追加されたエンドポイント

3. 認証方式の移行ガイド

3.1 拠点向けAPIトークン（従来）

拠点向けAPIトークン（従来）は v1 / v2 のどちらでも利用できます。

• トークンプレフィックス: xzxu-
• 形式: SecureRandom.base58（32文字）

# v1/v2 共通
curl -H "Authorization: Bearer xzxu-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  https://web.zaico.co.jp/api/v2/orgs/companies/123/inventories

拠点向けAPIトークン（従来）で認証した場合、そのユーザーが所属する拠点のみアクセスできます（旧プラン）。

3.2 新プラン/旧プランの違い

旧プランの場合:

• URLに指定する company_id は、自身が所属する拠点のIDのみ許可されます
• 異なる company_id を指定すると 404 Not Found が返されます

新プランの場合:

• 組織向けAPIトークン（新プラン）で認証すると、org 配下の任意の拠点にアクセスできます
• GET /api/v2/orgs/companies で利用可能な拠点一覧を取得できます
• URLの company_id を変えることで、操作対象の拠点を切り替えられます

3.3 APIトークン v1/v2 互換性マトリクス

APIトークン種別ごとに、v1/v2 の呼び出し可否が異なります。

ポイント:

• 拠点向けAPIトークン（従来）は v1 / v2 のどちらも呼び出し可能（後方互換）
• 組織向けAPIトークン（新プラン）は v2 専用で、v1 では呼び出せません
• 新プランへ移行した利用者が組織向けAPIトークンのみを発行して v1 を叩こうとすると 401 Unauthorized が返るため、v1 を継続利用する必要がある場合は 拠点向けAPIトークン（従来） を発行して使用してください

3.4 ページネーション仕様（エンドポイント別）

v2 のページネーションは エンドポイントごとに per_page のデフォルト値（DEFAULT）と最大値（MAX）が異なります。v1 のように全エンドポイント共通で「デフォルト 1000件・固定」ではない点に注意してください。

オフセット方式（ページ番号）

オフセット方式のレスポンスは pagination.current_page / per_page / total_count / total_pages を返します。

レスポンス例（オフセット方式）:

{
  "data": [...],
  "pagination": {
    "current_page": 1,
    "per_page": 100,
    "total_count": 2500,
    "total_pages": 25
  }
}

per_page パラメータに MAX を超える値を指定した場合は MAX 値にクランプされ、未指定または 0 以下の場合は DEFAULT 値が使われます。

トークンベース方式（inventory_histories のみ）

inventory_histories は DynamoDB をデータソースとするため、トークンベースのページネーションを採用しています。current_page / total_count / total_pages は返却されず、代わりに次ページ取得用のトークンが next_page_token として返ります。

レスポンス例（トークンベース）:

{
  "data": [...],
  "pagination": {
    "per_page": 50,
    "next_page_token": "eyJpZCI6IjEyM..."
  }
}

次ページ取得の方法:

レスポンスに含まれる next_page_token を、次のリクエストの next_page_token クエリパラメータに指定します。next_page_token が null の場合は次のページが存在しないことを意味します。

# 1ページ目
curl -H "Authorization: Bearer {token}" \
  "https://web.zaico.co.jp/api/v2/orgs/companies/123/inventory_histories?per_page=50"

# 2ページ目（next_page_token を指定）
curl -H "Authorization: Bearer {token}" \
  "https://web.zaico.co.jp/api/v2/orgs/companies/123/inventory_histories?per_page=50&next_page_token=eyJpZCI6IjEyM..."

4. リクエスト/レスポンスの具体例（Before/After）

4.1 在庫一覧取得（GET）

v1:

curl -H "Authorization: Bearer {token}" \
  "https://web.zaico.co.jp/api/v1/inventories?page=1"

レスポンス:

// HTTP/1.1 200 OK
// Total-Count: 150
// Link: <...?page=1>; rel="first", <...?page=2>; rel="last"

[
  {
    "id": 1,
    "title": "テスト在庫",
    "quantity": "10.0",
    "logical_quantity": "10.0",
    "unit": "個",
    "category": "果物",
    "categories": ["果物"],
    "state": "出荷待ち",
    "place": "倉庫A",
    "etc": "備考テキスト",
    "code": "INV-001",
    "item_image": { "url": null },
    "stocktake_attributes": {
      "checked_at": "2025-01-15T00:00:00+09:00",
      "stocktake_difference": "5.0"
    },
    "optional_attributes": [
      { "name": "色", "value": "赤" },
      { "name": "サイズ", "value": "M" }
    ],
    "quantity_management_attributes": {
      "order_point_quantity": "80.0"
    },
    "created_at": "2025-01-01T00:00:00+09:00",
    "updated_at": "2025-06-15T10:30:00+09:00",
    "update_date": "2025-06-15T10:30:00+09:00",
    "create_user_name": "田中太郎",
    "update_user_name": "田中太郎",
    "user_group": "基本グループ",
    "is_quantity_auto_conversion_by_unit": "1",
    "quantity_auto_conversion_by_unit_name": "箱",
    "quantity_auto_conversion_by_unit_factor": "12.0"
  }
]

v2:

curl -H "Authorization: Bearer {token}" \
  "https://web.zaico.co.jp/api/v2/orgs/companies/123/inventories?page=1&per_page=100"

レスポンス:

{
  "data": [
    {
      "id": 1,
      "title": "テスト在庫",
      "quantity": "10.0",
      "logical_quantity": "10.0",
      "unit": "個",
      "category": "果物",
      "categories": ["果物"],
      "state": "出荷待ち",
      "place": "倉庫A",
      "etc": "備考テキスト",
      "code": "INV-001",
      "group_tag": null,
      "item_image": { "url": null },
      "stocktake_attributes": {
        "checked_at": "2025-01-15",
        "stocktake_difference": "5.0"
      },
      "optional_attributes": {
        "色": "赤",
        "サイズ": "M"
      },
      "quantity_management_attributes": {
        "order_point_quantity": "80.0"
      },
      "created_at": "2025-01-01T00:00:00.000+09:00",
      "updated_at": "2025-06-15T10:30:00.000+09:00",
      "update_date": "2025-06-15T10:30:00.000+09:00",
      "create_user_name": "田中太郎",
      "update_user_name": "田中太郎",
      "user_group": "基本グループ",
      "is_quantity_auto_conversion_by_unit": true,
      "quantity_auto_conversion_by_unit_name": "箱",
      "quantity_auto_conversion_by_unit_factor": "12.0",
      "org_item_master": null,
      "variant_setting": {
        "enabled": false
      }
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 100,
    "total_count": 150,
    "total_pages": 2
  }
}

主な違い:

• レスポンスが data 配列にラップされている
• ページネーションがHTTPヘッダではなく pagination オブジェクトに含まれる
• optional_attributes が配列からHashオブジェクトに変更
• is_quantity_auto_conversion_by_unit が文字列からbooleanに変更
• checked_at がdatetimeからdate（日付のみ）に変更
• org_item_master フィールドが追加（新プラン用、nullの場合あり）
• variant_setting フィールドが追加（バリエーション設定情報）
• per_page パラメータで1ページあたりの件数を指定可能

4.2 在庫詳細取得（GET）

v1:

curl -H "Authorization: Bearer {token}" \
  "https://web.zaico.co.jp/api/v1/inventories/1"

レスポンス:

{
  "id": 1,
  "title": "テスト在庫",
  "quantity": "10.0",
  "..."
}

v2:

curl -H "Authorization: Bearer {token}" \
  "https://web.zaico.co.jp/api/v2/orgs/companies/123/inventories/1"

レスポンス:

{
  "data": {
    "id": 1,
    "title": "テスト在庫",
    "quantity": "10.0",
    "..."
  }
}

主な違い:

• レスポンスが data オブジェクトにラップされている

4.3 在庫作成（POST）

v1:

curl -X POST \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "新しい在庫",
    "quantity": "100",
    "unit": "個",
    "category": "電子部品",
    "place": "倉庫B",
    "code": "INV-002"
  }' \
  "https://web.zaico.co.jp/api/v1/inventories"

v2:

curl -X POST \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "新しい在庫",
    "quantity": "100",
    "unit": "個",
    "category": "電子部品",
    "place": "倉庫B",
    "code": "INV-002"
  }' \
  "https://web.zaico.co.jp/api/v2/orgs/companies/123/inventories"

主な違い:

• URLにcompany_idが含まれる
• リクエストボディの形式はv1と同一

4.4 在庫更新（PUT）

v1:

curl -X PUT \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "更新された在庫名",
    "quantity": "200"
  }' \
  "https://web.zaico.co.jp/api/v1/inventories/1"

v2:

curl -X PUT \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "更新された在庫名",
    "quantity": "200"
  }' \
  "https://web.zaico.co.jp/api/v2/orgs/companies/123/inventories/1"

4.5 在庫削除（DELETE）

v1:

curl -X DELETE \
  -H "Authorization: Bearer {token}" \
  "https://web.zaico.co.jp/api/v1/inventories/1"

v2:

curl -X DELETE \
  -H "Authorization: Bearer {token}" \
  "https://web.zaico.co.jp/api/v2/orgs/companies/123/inventories/1"

v2 のレスポンス（DELETE 全般）:

HTTP/1.1 204 No Content

v2 の DELETE 系エンドポイント（destroy アクション）は、削除成功時に 204 No Content を返し、レスポンスボディは空 です（data エンベロープも返却しません）。

v1 ではエンドポイントによって 200 OK で削除結果オブジェクトを返すケースがありましたが、v2 では削除成功時は一貫して 204 No Content で body なしです。クライアント側で JSON パースを試みているとエラーになる可能性があるため、ステータスコードのみで成否を判定してください。

4.6 エラーレスポンス例

認証エラー（401 Unauthorized）:

// v1
{
  "code": 401,
  "status": "error",
  "message": "Could not access API. Please Check Token or enabled API function."
}

// v2（Content-Type: application/problem+json）
{
  "title": "Unauthorized",
  "status": 401,
  "detail": "トークンが無効または未指定です"
}

権限エラー（403 Forbidden）:

// v1
{
  "code": 403,
  "status": "error",
  "message": "Could not access API. Please check your account permission."
}

// v2（Content-Type: application/problem+json）
{
  "title": "Forbidden",
  "status": 403,
  "detail": "編集権限がありません"
}

リソース未検出（404 Not Found）:

// v1
{
  "code": 404,
  "status": "error",
  "message": "Inventory not found."
}

// v2（Content-Type: application/problem+json）
{
  "title": "Not Found",
  "status": 404,
  "detail": "Inventory が見つかりません"
}

バリデーションエラー（v1: 422 → v2: 400）:

注意: バリデーションエラーのHTTPステータスコードがv1の422 Unprocessable Entityからv2の400 Bad Requestに変更されています。ステータスコードでエラーを分岐しているクライアントは修正が必要です。

// v1
{
  "code": 422,
  "status": "error",
  "message": "Title can't be blank"
}

// v2（Content-Type: application/problem+json）
{
  "title": "Bad Request",
  "status": 400,
  "detail": "タイトルを入力してください"
}

5. エラーハンドリングの移行ガイド

5.1 エラーレスポンスフィールド対応表

5.2 HTTPステータスコード一覧

5.3 エラーハンドリングのコード例

v1からv2へのエラーハンドリング移行の疑似コード例:

// v1のエラーハンドリング
function handleV1Error(response) {
  const error = response.data;
  console.error(`Error ${error.code}: ${error.message}`);
}

// v2のエラーハンドリング
function handleV2Error(response) {
  // Content-Typeが application/problem+json であることを確認
  const error = response.data;
  console.error(`${error.title} (${error.status}): ${error.detail || ''}`);
}

# v1のエラーハンドリング
def handle_v1_error(response):
    error = response.json()
    print(f"Error {error['code']}: {error['message']}")

# v2のエラーハンドリング
def handle_v2_error(response):
    error = response.json()
    print(f"{error['title']} ({error['status']}): {error.get('detail', '')}")

6. その他の変更点

6.1 デフォルトページサイズの変更

v1 では全エンドポイント共通でデフォルト 1000件（固定、変更不可）でしたが、v2 では per_page パラメータで指定可能になりました。ただしデフォルト値・最大値はエンドポイントごとに異なります。

詳細は 3.4 ページネーション仕様（エンドポイント別） を参照してください。

# v2: per_page パラメータで1ページあたりの件数を指定（在庫一覧の場合は最大1000件）
curl -H "Authorization: Bearer {token}" \
  "https://web.zaico.co.jp/api/v2/orgs/companies/123/inventories?per_page=500"

6.2 optional_attributesの形式変更

v1（配列形式）:

"optional_attributes": [
  { "name": "色", "value": "赤" },
  { "name": "サイズ", "value": "M" }
]

v2（Hashオブジェクト形式）:

"optional_attributes": {
  "色": "赤",
  "サイズ": "M"
}

v1ではnameとvalueのペアの配列でしたが、v2ではキーバリューのHashオブジェクトに変更されました。

6.3 boolean/日付フィールドの形式変更

is_quantity_auto_conversion_by_unit:

// v1: 文字列
"is_quantity_auto_conversion_by_unit": "1"  // または "0"

// v2: boolean
"is_quantity_auto_conversion_by_unit": true  // または false

checked_at（棚卸日）:

// v1: ISO 8601 datetime
"checked_at": "2025-01-15T00:00:00+09:00"

// v2: ISO 8601 date（日付のみ）
"checked_at": "2025-01-15"

6.4 v2で追加されたパラメータ・レスポンスフィールド

v2では以下のパラメータ・フィールドが新規追加されています。

在庫（Inventories）:

• レスポンスに org_item_master フィールド追加（組織品目マスタとの紐付き情報）
• 一覧・詳細の両方に variant_setting フィールドを出力（{ enabled: boolean, items?: [...] } 形式）
• 作成/更新時に variant_setting パラメータ対応

バリアント（InventoryVariants）:

• GET {base}/inventories/:inventory_id/inventory_variants - 在庫のバリアント一覧取得（v2新規）

入庫（Purchases）:

• 一覧レスポンスに purchase_items フィールド追加
• 検索パラメータ追加: num（入庫番号）、inventory_id、memo（部分一致）、start_updated_date、end_updated_date
• 作成/更新時に variants パラメータ対応
• バリアント項目（variants[].items）の形式が { variant_setting_item_id, label, value } 配列に変更

出庫（PackingSlips）:

• 作成/更新時に user_group、variants、shipping_instruction パラメータ対応
• shipping_instruction: 出荷指示情報（宛先名、郵便番号、配送業者等、14フィールド）

配送（Deliveries）:

• バリアント項目（variants[].items）の形式が { variant_setting_item_id, label, value } 配列に変更

6.5 v2で強化されたプランチェック

v2ではプラン別の機能制限チェックが強化されています。v1ではプランチェックが不足していた一部パラメータについて、v2では適切に制御されます。

契約プランで該当機能が無効な場合、これらのパラメータは送信してもサイレントに無視されます。

移行チェックリスト

v1からv2への移行作業の完了確認に使用してください。

• URLパスを /api/v2/orgs/companies/{company_id}/ 形式に変更した
• company_id の取得方法を実装した（新プランの場合は GET /api/v2/orgs/companies で取得）
• Authorization: Token を使用している場合、Authorization: Bearer に変更した
• 利用中のAPIトークン種別が v1/v2 双方で利用可能か確認した（3.3 APIトークン v1/v2 互換性マトリクス を参照）
• レスポンスパーサーをエンベロープ形式（data, pagination）に対応させた
• ページネーション処理を HTTP ヘッダ（Total-Count, Link）からレスポンスボディ（pagination）に変更した
• エラーハンドリングを RFC 7807 形式（title, status, detail）に対応させた
• エラーレスポンスの Content-Type application/problem+json に対応した
• バリデーションエラーのステータスコードを 422 から 400 に変更した
• DELETE のレスポンスを 204 No Content（body なし）として扱うようにした
• optional_attributes のパース処理を配列 [{name,value}] から Hash {key:value} に変更した
• is_quantity_auto_conversion_by_unit を文字列 "0"/"1" から boolean false/true に変更した
• checked_at のパース処理を datetime から date（日付のみ）に変更した
• 利用エンドポイントの per_page のデフォルト値・最大値を 3.4 ページネーション仕様（エンドポイント別） で確認し、必要に応じて per_page パラメータを指定した
• inventory_histories を利用する場合、トークンベースページネーション（next_page_token）に対応した