パブリケーションAPI
フリップブックパブリケーションの作成、更新、削除、管理。PDFのアップロード、表示設定の制御、バージョン管理、QRコードの生成。
パブリケーションAPI
パブリケーションAPIを使用すると、フリップブックパブリケーションの作成、PDFのアップロードと変換、バージョン管理、アクセス設定の制御ができます。パブリックとマークされている場合を除き、すべてのエンドポイントで認証が必要です。
ベースURL: https://api.zenflip.io/v1/publications
パブリケーション一覧
組織内のパブリケーションのページネーション付き一覧を取得します。
` GET /publications `
クエリパラメータ
パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
| integer | いいえ | ページ番号（デフォルト：1） |
| integer | いいえ | 1ページあたりの項目数（デフォルト：20） |
| string | いいえ | タイトルでフィルタ（部分一致） |
| string | いいえ | ステータスでフィルタ： |
| string | いいえ | ソートフィールド（例： |
| string | いいえ | ソート順： |
リクエスト例
`bash curl "https://api.zenflip.io/v1/publications?page=1&limit=10&status=published" \ -H "Authorization: Bearer YOUR_TOKEN" `
レスポンス例
`json { "data": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "title": "Product Catalog 2026", "slug": "product-catalog-2026", "description": "Annual product catalog with pricing", "status": "published", "accessType": "public", "activeVersionNumber": 2, "thumbnailUrl": "https://cdn.zenflip.io/thumbs/a1b2c3d4.jpg", "publishedAt": "2026-01-20T09:00:00.000Z", "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-02-01T14:22:00.000Z" } ], "meta": { "total": 24, "page": 1, "limit": 10, "totalPages": 3 } } `
パブリケーションの作成
新しいパブリケーションレコードを作成します。作成後、PDFをアップロードしてフリップブックページを生成します。
` POST /publications `
必要なロール： editor以上。
リクエストボディ
フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| string | はい | パブリケーションタイトル（1〜200文字） |
| string | いいえ | パブリケーションの簡単な説明 |
リクエスト例
`bash curl -X POST https://api.zenflip.io/v1/publications \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Q1 Sales Report", "description": "Quarterly sales performance flipbook" }' `
レスポンス例
`json { "data": { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "title": "Q1 Sales Report", "slug": "q1-sales-report", "description": "Quarterly sales performance flipbook", "status": "draft", "accessType": "public", "activeVersionId": null, "activeVersionNumber": null, "settings": {}, "branding": null, "createdAt": "2026-02-20T12:00:00.000Z", "updatedAt": "2026-02-20T12:00:00.000Z" } } `
PDFのアップロード
PDFファイルをアップロードしてパブリケーションの新しいバージョンを作成します。PDFはS3に保存され、フリップブックページを生成するバックグラウンド変換ジョブがキューに入ります。
` POST /uploads/publication/:pubId/pdf `
必要なロール： editor以上。最大ファイルサイズ：200 MB。PDFファイルのみ受け付けます。
リクエスト例
`bash curl -X POST "https://api.zenflip.io/v1/uploads/publication/b2c3d4e5-f6a7-8901-bcde-f12345678901/pdf" \ -H "Authorization: Bearer YOUR_TOKEN" \ -F "file=@/path/to/report.pdf" `
レスポンス例
`json { "data": { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "publicationId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "versionNumber": 1, "pdfFilename": "report.pdf", "pdfSizeBytes": 4521984, "status": "uploaded" } } `
バージョンステータスは以下の順に進行します：uploading -> uploaded -> converting -> ready（またはfailed）。アクティブバージョンのステータスを確認するには、パブリケーション取得エンドポイントを使用してください。
パブリケーションの取得
IDでパブリケーションを1件取得します。
` GET /publications/:id `
リクエスト例
`bash curl "https://api.zenflip.io/v1/publications/b2c3d4e5-f6a7-8901-bcde-f12345678901" \ -H "Authorization: Bearer YOUR_TOKEN" `
レスポンス例
`json { "data": { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "title": "Q1 Sales Report", "slug": "q1-sales-report", "description": "Quarterly sales performance flipbook", "status": "published", "accessType": "public", "accessPassword": null, "activeVersionId": "c3d4e5f6-a7b8-9012-cdef-123456789012", "activeVersionNumber": 1, "settings": { "pageMode": "double", "toolbarVisible": true }, "branding": null, "leadCaptureEnabled": false, "thumbnailUrl": "https://cdn.zenflip.io/thumbs/b2c3d4e5.jpg", "publishedAt": "2026-02-20T14:00:00.000Z", "createdAt": "2026-02-20T12:00:00.000Z", "updatedAt": "2026-02-20T14:00:00.000Z" } } `
パブリケーションの更新
パブリケーションのメタデータを更新します。
` PATCH /publications/:id `
必要なロール： editor以上。
リクエストボディ
フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| string | いいえ | パブリケーションタイトル（1〜200文字） |
| string | いいえ | 簡単な説明 |
| string | いいえ | URLフレンドリーなスラッグ（1〜200文字） |
リクエスト例
`bash curl -X PATCH "https://api.zenflip.io/v1/publications/b2c3d4e5-f6a7-8901-bcde-f12345678901" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "title": "Q1 Sales Report - Updated", "slug": "q1-sales-report-2026" }' `
パブリケーション設定の更新
パブリケーションのビューアー設定（ページモード、自動再生、ツールバー表示など）を更新します。
` PATCH /publications/:id/settings `
必要なロール： editor以上。
リクエスト例
`bash curl -X PATCH "https://api.zenflip.io/v1/publications/b2c3d4e5.../settings" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "settings": { "autoPlay": true, "toolbarVisible": false, "pageMode": "double" } }' `
パブリケーションブランディングの更新
パブリケーションにカスタムブランディング（ロゴ、カラー、フォント）を適用します。プランのcustomBranding機能が必要です。
` PATCH /publications/:id/branding `
必要なロール： editor以上。 必要なプラン機能： customBranding。
リクエスト例
`bash curl -X PATCH "https://api.zenflip.io/v1/publications/b2c3d4e5.../branding" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "branding": { "logoUrl": "https://example.com/logo.png", "primaryColor": "#4F46E5", "fontFamily": "Inter" } }' `
公開 / アーカイブ
パブリケーションのライフサイクルステータスを変更します：
`bash
下書きを公開
curl -X POST "https://api.zenflip.io/v1/publications/:id/publish" \ -H "Authorization: Bearer YOUR_TOKEN"
パブリケーションをアーカイブ
curl -X POST "https://api.zenflip.io/v1/publications/:id/archive" \ -H "Authorization: Bearer YOUR_TOKEN" `
パブリケーションの削除
パブリケーションとすべての関連データ（バージョン、ページ、アナリティクス）を完全に削除します。
` DELETE /publications/:id `
必要なロール： admin以上。
`bash curl -X DELETE "https://api.zenflip.io/v1/publications/b2c3d4e5-f6a7-8901-bcde-f12345678901" \ -H "Authorization: Bearer YOUR_TOKEN" `
バージョン一覧
パブリケーションのすべてのバージョンを取得します。
` GET /publications/:id/versions `
レスポンス例
`json { "data": [ { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "versionNumber": 2, "pdfFilename": "report-v2.pdf", "pdfSizeBytes": 5120000, "pageCount": 24, "status": "ready", "conversionProgress": 100, "convertedAt": "2026-02-20T14:05:00.000Z", "createdAt": "2026-02-20T14:00:00.000Z" }, { "id": "d4e5f6a7-b8c9-0123-def0-234567890123", "versionNumber": 1, "pdfFilename": "report.pdf", "pdfSizeBytes": 4521984, "pageCount": 20, "status": "ready", "conversionProgress": 100, "convertedAt": "2026-02-20T12:10:00.000Z", "createdAt": "2026-02-20T12:00:00.000Z" } ] } `
バージョンの有効化
パブリケーションのアクティブ（本番）バージョンを、以前アップロードしたバージョンに切り替えます。
` POST /publications/:id/versions/:versionId/activate `
必要なロール： editor以上。
QRコードの生成
パブリケーションビューアーへのリンクを含むPNG形式のQRコードを生成します。
` GET /publications/:id/qr-code `
512x512のPNG画像を直接返します（Content-Type: image/png）。
`bash curl "https://api.zenflip.io/v1/publications/b2c3d4e5.../qr-code" \ -H "Authorization: Bearer YOUR_TOKEN" \ --output qr-code.png `
パブリックビューアーエンドポイント
パブリックフリップブックビューアー用のパブリケーションデータを取得します。認証不要です。
` GET /publications/public/:slug `
このエンドポイントはIPあたり毎分60リクエストにレート制限されており、ビューアーでのレンダリング用に解決済みのページ画像URLを含むパブリケーションを返します。