クイックスタートガイド

クイックスタートガイド

このガイドでは、認証情報の取得、ZenFlip APIへの認証、最初のリクエストの成功までを説明します。最後には、組織内のすべてのパブリケーションを一覧表示できるようになります。

ベースURL

すべてのAPIリクエストはバージョン付きのベースURLに対して行います：

` https://api.zenflip.io/v1 `

このガイドに記載されているすべてのエンドポイントは、このベースURLからの相対パスです。例えば、ログインエンドポイントはhttps://api.zenflip.io/v1/auth/loginに解決されます。

ステップ1 --- APIキーの取得

ZenFlipは2つの認証方法をサポートしています：JWTトークン（ユーザー向けアプリケーション用）とAPIキー（サーバー間統合用）。

APIキーを作成するには：

1. https://app.zenflip.ioでZenFlipダッシュボードにサインインします。

2. 設定 > APIキーに移動します。

3. 新しいキーを生成をクリックし、わかりやすいラベル（例：「本番バックエンド」）を付けて、すぐにキーをコピーします。キーは再表示されません。

APIキーは組織にスコープされています。APIキーで行われたリクエストは、組織オーナーの権限を継承します。

ステップ2 --- 認証

オプションA：APIキー（サーバー間通信）

AuthorizationヘッダーにBearerプレフィックス付きでAPIキーを渡します：

`bash curl https://api.zenflip.io/v1/publications \ -H "Authorization: Bearer zf_live_abc123yourAPIkeyHere" `

オプションB：JWTトークン（ユーザーセッション）

ログインエンドポイントを呼び出して、短期間有効なJWTアクセストークンを取得します：

`bash curl -X POST https://api.zenflip.io/v1/auth/login \ -H "Content-Type: application/json" \ -d '{ "email": "you@example.com", "password": "your-password" }' `

成功すると、アクセストークンとリフレッシュトークンが返されます：

`json { "accessToken": "eyJhbGciOiJIUzI1NiIs...", "refreshToken": "eyJhbGciOiJIUzI1NiIs...", "expiresIn": 3600, "user": { "id": "550e8400-e29b-41d4-a716-446655440000", "email": "you@example.com", "name": "Your Name", "role": "owner" }, "organization": { "id": "660e8400-e29b-41d4-a716-446655440000", "name": "Your Organization" } } `

以降のリクエストでaccessTokenを使用します：

`bash curl https://api.zenflip.io/v1/publications \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." `

ステップ3 --- 最初のAPI呼び出し

シンプルなGETリクエストで組織内のすべてのパブリケーションを一覧表示します：

`bash curl https://api.zenflip.io/v1/publications?page=1&limit=10 \ -H "Authorization: Bearer YOUR_TOKEN" `

レスポンスは標準的なページネーション形式です：

`json { "data": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "title": "Product Catalog 2026", "slug": "product-catalog-2026", "status": "published", "accessType": "public", "thumbnailUrl": "https://cdn.zenflip.io/thumbs/a1b2c3d4.jpg", "activeVersionNumber": 2, "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-02-01T14:22:00.000Z" } ], "meta": { "total": 1, "page": 1, "limit": 10, "totalPages": 1 } } `

レスポンス形式

すべての成功レスポンスはデータをdataキーでラップします。ページネーション付きエンドポイントには、ページネーションの詳細を含むmetaオブジェクトが含まれます。

エラーレスポンス

リクエストが失敗した場合、APIは一貫したエラー構造を返します：

`json { "statusCode": 401, "message": "Invalid or expired token", "error": "Unauthorized" } `

レート制限

APIはプランに応じた1分あたりのレート制限を適用します：

制限を超えた場合、APIは429ステータスと、待機すべき秒数を示すRetry-Afterヘッダーを返します。

次のステップ

• [認証](/docs/authentication) --- JWTトークン、リフレッシュフロー、Google OAuthの詳細。

• [パブリケーションAPI](/docs/publications-api) --- フリップブックの作成、更新、管理。

• [埋め込みウィジェット](/docs/embed-quickstart) --- インタラクティブなフリップブックを任意のウェブサイトに追加。