API認証｜CheckoutOSドキュメント

CheckoutOS APIは、認証にAPIキーを使用します。このガイドでは、キーの生成、リクエストの認証、APIアクセスの安全な管理について説明します。

APIキー

APIキーは、CheckoutOS APIへのすべてのリクエストを認証するために使用します。各キーはストアに紐づき、権限を設定できます。

APIキーの生成

設定を開く

CheckoutOS → Settings → APIに進みます。

新しいキーを作成する

"Create API Key"をクリックします。

キーに名前を付ける

「本番サーバー」など、用途がわかる名前を付けます。

権限を設定する

キーがアクセスできるAPIスコープを選択します。

キーをコピーする

キーは再表示されないため、すぐにコピーしてください。

キーのセキュリティ

APIキーは作成時に1回だけ表示されます。安全に保管してください。紛失した場合は、新しいキーを生成する必要があります。

認証方法

Bearerトークン（推奨）

Authorizationヘッダーに、APIキーをBearerトークンとして含めます。

Bearerトークン認証

curl -X GET "https://api.chargezen.com/v1/checkoutos/upsells" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

X-API-Keyヘッダー

代わりにX-API-Keyヘッダーを使用することもできます。

X-API-Key認証

curl -X GET "https://api.chargezen.com/v1/checkoutos/upsells" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

APIの権限

APIキーは特定の権限に範囲を限定できます。

利用できるスコープ

{
  "scopes": {
    "read:upsells": "View upsell configurations",
    "write:upsells": "Create and modify upsells",
    "read:bundles": "View bundle configurations",
    "write:bundles": "Create and modify bundles",
    "read:analytics": "Access analytics data",
    "read:orders": "View order data",
    "write:orders": "Modify orders (edits)",
    "read:settings": "View CheckoutOS settings",
    "write:settings": "Modify settings",
    "webhooks:manage": "Create and manage webhooks"
  }
}

最小権限

連携に必要な権限だけを付与してください。分析ダッシュボード用のキーに、アップセルへの書き込み権限を付けるべきではありません。

レート制限

公平な利用を確保するため、APIリクエストにはレート制限があります。

レート制限

{
  "rate_limits": {
    "requests_per_minute": 120,
    "requests_per_hour": 3600,
    "burst_limit": 20
  },
  "headers": {
    "X-RateLimit-Limit": "120",
    "X-RateLimit-Remaining": "115",
    "X-RateLimit-Reset": "1640000000"
  }
}

レート制限に達すると、429レスポンスを受け取ります。

レート制限のレスポンス

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 45 seconds.",
    "retry_after": 45
  }
}

環境

CheckoutOSは、開発環境と本番環境を分けて提供しています。

API環境

{
  "production": {
    "base_url": "https://api.chargezen.com/v1",
    "key_prefix": "live_"
  },
  "sandbox": {
    "base_url": "https://sandbox.api.chargezen.com/v1",
    "key_prefix": "test_"
  }
}

サンドボックス環境

開発とテストにはサンドボックスを使用してください。サンドボックスのデータは本番環境と分離されており、いつでもリセットできます。

公式SDK

公式SDKは認証を自動的に処理します。

Node.js SDK

import { CheckoutOS } from '@chargezen/checkoutos-sdk';

const client = new CheckoutOS({
  apiKey: process.env.CHARGEZEN_API_KEY,
  environment: 'production'
});

const upsells = await client.upsells.list();

Python SDK

from chargezen import CheckoutOS

client = CheckoutOS(
    api_key=os.environ['CHARGEZEN_API_KEY'],
    environment='production'
)

upsells = client.upsells.list()

キーの管理

効果的な使い方

環境変数を使用 — キーをコードに直接書き込まない
定期的にキーを更新 — 少なくとも四半期ごと
環境ごとに別のキーを使用 — 開発、ステージング、本番
未使用のキーを失効 — 使わなくなったキーを削除
キーの利用を監視 — 異常なパターンを確認
スコープを最小限にする — 必要な権限だけを付与

キーの失効

API設定を開く

CheckoutOS → Settings → APIに進みます。

キーを探す

失効させるキーを一覧から探します。

失効させる

"Revoke"をクリックして確定します。

即時に反映

キーの失効は即時に反映されます。失効したキーを使用するリクエストはすべて失敗します。失効させる前に、アプリケーションの更新を済ませてください。

APIリファレンス

APIエンドポイント

利用できるAPIエンドポイント

詳しく見る

Webhook

リアルタイムのイベント通知

詳しく見る