🔧 Shopify App作成・権限設定 完全マニュアル

API連携特化・PII完全分離対応
CLI/SDK不使用、純粋REST API統合のためのApp設定

🎯 設定概要

必要な設定項目

📱 App基本設定:
  - App名・説明
  - App URL・リダイレクトURL
  - Webhook URL

🔒 API権限設定:
  - Storefront API権限
  - Admin API権限  
  - Webhook権限

🔐 セキュリティ設定:
  - API Key管理
  - Webhook Secret
  - CORS設定

📋 Step-by-Step 設定手順

Step 1: Shopify Partner Account作成

1.1 アカウント登録

URL: https://partners.shopify.com/

登録項目:

• 会社名: Contents Print Inc.
• 担当者名
• メールアドレス
• パスワード（強固なもの）

1.2 Partner Dashboard確認

確認項目:
  - Dashboard URL: https://partners.shopify.com/organizations/xxxxx
  - Organization ID記録
  - 開発者権限確認

---

Step 2: 本番Shopifyストア作成

2.1 本番ストア設定

ストア名: q1tipx-k1 
URL: q1tipx-k1.myshopify.com
目的: 猫アプリ・時の絵 本番運用ストア
プラン: Basic Shopify Plan（月額$39）

2.2 本番ストア初期設定

• 管理者アカウント設定
• ストア名: "Contents Print"
• カスタムドメイン: 設定なし（q1tipx-k1.myshopify.comのまま）
• 基本情報入力
• 配送設定（日本国内・89mm写真プリント対応）
• 税金設定（消費税10%）
• 決済設定（Shopify Payments有効化）

---

Step 3: カスタムApp作成

3.1 App作成

graph TD
    A[Partner Dashboard] --> B[Apps]
    B --> C[Create App]
    C --> D[Custom App]
    D --> E[App設定]
    E --> F[権限設定]
    F --> G[API Key取得]

3.2 App基本情報設定

項目	設定値	説明
App Name	Contents Print Integration	本番システム識別用
App URL	https://api.contents-print.jp	本番メインアプリURL
Allowed redirection URLs	https://api.contents-print.jp/auth/callback	OAuth用
API Version	2025-07 (最新)	Shopify API バージョン

3.3 App設定詳細

App Configuration:
  App Name: "Contents Print Production API"
  App URL: "https://api.contents-print.jp"
  Allowed redirection URLs:
    - "https://api.contents-print.jp/auth/callback"
    - "https://neko.contents-print.jp/auth/callback"  # 猫アプリ本番
    - "https://tokinoe.contents-print.jp/auth/callback"  # 時の絵本番

Webhook Settings:
  Webhook URL: "https://api.contents-print.jp/webhooks/shopify"
  API Version: "2024-01"

---

Step 4: API権限設定（重要）

4.1 Storefront API権限

必要権限 - Storefront Access:
  ✅ unauthenticated_read_product_listings
  ✅ unauthenticated_read_product_inventory  
  ✅ unauthenticated_read_product_tags
  ✅ unauthenticated_read_collections
  
顧客・カート権限:
  ✅ unauthenticated_read_customers
  ✅ unauthenticated_write_customers  
  ✅ unauthenticated_read_checkouts
  ✅ unauthenticated_write_checkouts

4.2 Admin API権限（詳細）

商品管理権限:
  ✅ read_products
  ✅ write_products
  ✅ read_product_listings  
  ✅ write_product_listings

注文管理権限:
  ✅ read_orders
  ✅ write_orders
  ✅ read_all_orders

顧客管理権限:
  ✅ read_customers
  ✅ write_customers

在庫管理権限:
  ✅ read_inventory
  ✅ write_inventory

ファイル管理権限:
  ✅ read_files
  ✅ write_files

メタフィールド権限:
  ✅ read_metafields
  ✅ write_metafields

Webhook権限:
  ✅ read_webhooks
  ✅ write_webhooks

4.3 権限設定の理由

権限	用途	PII関連
read_products	商品情報取得	非PII
write_products	商品情報更新	非PII
read_orders	注文情報取得	PII
write_orders	注文ステータス更新	PII
read_customers	顧客情報取得	PII
write_customers	顧客情報更新	PII
read_metafields	ブランド分離用	非PII

---

Step 5: API Key取得・管理

5.1 API Key一覧

取得必要なKey:
  1. Admin API Access Token
  2. Storefront API Access Token  
  3. API Secret Key
  4. Webhook Secret Key

5.2 環境変数設定

# 本番環境変数（.env.localに設定）
SHOPIFY_STORE_DOMAIN=q1tipx-k1.myshopify.com
SHOPIFY_ADMIN_API_TOKEN=shpat_xxxxxxxxxxxxxxxxxxxxxxxx
SHOPIFY_STOREFRONT_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SHOPIFY_API_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SHOPIFY_WEBHOOK_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# ブランド設定
SHOPIFY_NEKO_BRAND_ID=neko
SHOPIFY_TOKINOE_BRAND_ID=tokinoe

5.3 セキュリティ管理

⚠️ セキュリティ要件:
  - API Keyは環境変数のみ保存
  - コードに直接記載禁止
  - 定期的なローテーション（3ヶ月毎）
  - アクセスログ監視

🔒 アクセス制限:
  - IP制限設定（Cloudflare Workers IP範囲）
  - HTTPS必須
  - CORS適切設定

---

Step 6: Webhook設定

6.1 必要なWebhook一覧

注文関連:
  - orders/create: 新規注文通知
  - orders/updated: 注文更新通知
  - orders/paid: 決済完了通知
  - orders/fulfilled: 配送完了通知

顧客関連:
  - customers/create: 新規顧客登録
  - customers/update: 顧客情報更新

商品関連:
  - products/create: 新規商品作成
  - products/update: 商品情報更新

6.2 Webhook URL設定

Base URL: https://api.contents-print.jp/webhooks/shopify

✅ 設定完了済みWebhook（必須5つ）:
  - /orders/create         # 注文作成 
  - /orders/updated        # 注文状態変更
  - /orders/paid           # 決済完了（印刷開始トリガー）
  - /orders/fulfilled      # 配送完了
  - /customers/create      # 新規顧客登録

📋 追加推奨Webhook:
  - /customers/update      # 顧客情報更新
  - /products/create       # 商品作成
  - /products/update       # 商品情報更新
  - /orders/cancelled      # 注文キャンセル

📊 Webhook設定状況:
  Status: ✅ 必須5つ完了（2025-08-24）
  Secret: 417ac888673c93ec75f614903515ddcd952cba42a79e0392f5a2def0609e503f
  API Version: 2025-07

6.3 Webhook セキュリティ

// Webhook署名検証例
async function verifyWebhook(request: Request): Promise<boolean> {
  const signature = request.headers.get('x-shopify-hmac-sha256');
  const body = await request.text();
  
  const hash = await crypto.subtle.importKey(
    'raw',
    new TextEncoder().encode(SHOPIFY_WEBHOOK_SECRET),
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign']
  );
  
  const calculatedSignature = await crypto.subtle.sign('HMAC', hash, new TextEncoder().encode(body));
  
  return signature === btoa(String.fromCharCode(...new Uint8Array(calculatedSignature)));
}

---

Step 7: メタフィールド設定（ブランド分離用）

7.1 商品メタフィールド

Brand識別:
  Namespace: custom
  Key: brand
  Type: single_line_text_field
  Values: ["neko", "tokinoe"]

Firebase UID:
  Namespace: custom  
  Key: firebase_uid
  Type: single_line_text_field
  Description: "Firebase認証UID"

Image Hash:
  Namespace: custom
  Key: image_hash
  Type: single_line_text_field
  Description: "SHA-256ハッシュ値"

7.2 顧客メタフィールド

Firebase UID連携:
  Namespace: custom
  Key: firebase_uid  
  Type: single_line_text_field
  Description: "Firebase認証との連携用"

Brand Preference:
  Namespace: custom
  Key: preferred_brand
  Type: single_line_text_field
  Values: ["neko", "tokinoe", "both"]

---

Step 8: テスト・検証

8.1 API接続テスト

# Storefront API テスト
curl -X POST \
  https://contents-print-dev.myshopify.com/api/2024-01/graphql.json \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Storefront-Access-Token: YOUR_STOREFRONT_TOKEN' \
  -d '{"query": "{ shop { name } }"}'

# Admin API テスト  
curl -X GET \
  https://contents-print-dev.myshopify.com/admin/api/2024-01/shop.json \
  -H 'X-Shopify-Access-Token: YOUR_ADMIN_TOKEN'

8.2 Webhook テスト

# テスト注文作成
curl -X POST \
  https://contents-print-dev.myshopify.com/admin/api/2024-01/orders.json \
  -H 'X-Shopify-Access-Token: YOUR_ADMIN_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "order": {
      "line_items": [{
        "title": "Test Product",
        "price": "10.00",
        "quantity": 1
      }]
    }
  }'

---

Step 9: 本番環境最終設定

9.1 本番ストア完全設定

ストア情報:
  Name: Contents Print
  Domain: q1tipx-k1.myshopify.com
  
商品設定:
  猫アプリ商品:
    - 89mm写真プリント（1枚）
    - 89mm写真プリント（5枚セット）
    - 89mm写真プリント（10枚セット）
  
  時の絵商品:
    - Canvas合成アート（A4）
    - Canvas合成アート（A3）
    - Canvas合成アート（B4）

SSL証明書:
  - q1tipx-k1.myshopify.com（Shopify自動）
  - api.contents-print.jp（Cloudflare側）
  - neko.contents-print.jp（Cloudflare側）
  - tokinoe.contents-print.jp（Cloudflare側）

9.2 本番運用準備

本番チェックリスト:
  ✅ Shopify Partner Account作成完了
  ✅ カスタムApp「Contents Print Integration」作成完了
  ✅ API Version 2025-07 設定完了
  ✅ 必須Webhook 5つ設定完了
  ✅ API Key・Secret取得完了
  ✅ 本番ストア q1tipx-k1.myshopify.com 接続完了
  ✅ カスタムドメイン shop.contents-print.jp 設定完了
  
本番運用準備項目（今後）:
  📋 Shopify Payments有効化
  📋 消費税10%設定確認
  📋 配送料金設定（写真プリント用）
  📋 利用規約・プライバシーポリシー設定
  📋 特定商取引法表記設定
  📋 カスタマーサポート連絡先設定
  📋 返品・交換ポリシー設定

---

🚨 重要な注意事項

セキュリティ関連

⚠️ 絶対に守ること:
  - API Keyの漏洩防止
  - Webhook署名検証必須
  - HTTPS通信必須
  - 定期的な権限レビュー

🔒 PII取り扱い:
  - Shopify外部にPII保存禁止
  - ログにPII記録禁止
  - 一時的な取得のみ許可

API制限関連

レート制限:
  - Admin API: 40 requests/minute
  - Storefront API: 制限緩い
  - Webhook: 制限なし

対策:
  - Cloudflare Queues必須
  - リトライ機能実装
  - エラーハンドリング充実

---

✅ 設定完了チェックリスト

• Shopify Partner Account作成
• 本番Shopifyストア作成・設定
• カスタムApp作成
• API権限設定完了
• API Key取得・環境変数設定
• Webhook設定完了
• メタフィールド設定完了
• API接続テスト成功
• Webhook テスト成功
• 本番環境設定完了
• 商品登録完了（猫アプリ・時の絵）
• 決済・配送設定完了

---

📍 次のステップ: API連携設定 に進んでください。

所要時間: 約3-4時間
難易度: 🔴 高（重要設定多数）

文書作成日: 2025-08-23
最終更新: 2025-08-24
バージョン: 1.1 - 本番環境対応版（猫アプリ・時の絵統合）