API設計書

Version 1.0.0 | CRM（広告代理店向け）

広告代理店向け CRM REST API 設計文書

---

共通仕様

ベース URL

/api/v1

認証方式

全エンドポイント（認証系を除く）に Authorization: Bearer <JWT> ヘッダーが必要。

共通レスポンス構造

{
  "data": "T | T[]",
  "meta": { "total": 0, "page": 1, "perPage": 20, "totalPages": 1 },
  "message": "string"
}

共通クエリパラメータ（一覧系）

page, perPage, sort, order(asc|desc), search

ロール定義（RBAC）

ロール	略称
システム管理者	ADMIN
アカウントディレクター	AD
アカウントマネージャー	AM
メディアプランナー	MP
クリエイティブ担当	CR
経理・財務	FIN
閲覧専用	VIEWER

---

F14: 認証・ユーザー管理

認証

メソッド	パス	説明
POST	/auth/login	ログイン
POST	/auth/refresh	トークンリフレッシュ
POST	/auth/logout	ログアウト（トークン無効化）
POST	/auth/password/reset-request	パスワードリセット要求
POST	/auth/password/reset	パスワードリセット実行

POST /auth/login

• 認証: 不要
• Request: { email, password }
• Response: { accessToken, refreshToken, expiresIn, user: { id, name, email, role } }

POST /auth/refresh

• 認証: 不要（refreshToken で検証）
• Request: { refreshToken }
• Response: { accessToken, refreshToken, expiresIn }

POST /auth/logout

• 認証: Bearer JWT
• Request: なし
• Response: { message }

POST /auth/password/reset-request

• 認証: 不要
• Request: { email }
• Response: { message }

POST /auth/password/reset

• 認証: 不要（トークンで検証）
• Request: { token, newPassword }
• Response: { message }

ユーザー管理

メソッド	パス	説明
GET	/users	ユーザー一覧
POST	/users	ユーザー作成
GET	/users/:id	ユーザー詳細
PATCH	/users/:id	ユーザー更新
DELETE	/users/:id	ユーザー無効化（論理削除）
GET	/users/me	自分のプロフィール
PATCH	/users/me	自分のプロフィール更新

GET /users

• 認証: ADMIN
• Query: ?role=AM&status=active
• Response: [{ id, name, email, role, status, createdAt }]

POST /users

• 認証: ADMIN
• Request: { name, email, password, role, department }
• Response: { id, name, email, role }

GET /users/:id

• 認証: ADMIN, 本人
• Response: { id, name, email, role, department, status, lastLoginAt, createdAt }

PATCH /users/:id

• 認証: ADMIN
• Request: { name?, role?, department?, status? }
• Response: 更新後のユーザーオブジェクト

DELETE /users/:id

• 認証: ADMIN
• Response: { message }

ロール・権限

メソッド	パス	説明
GET	/roles	ロール一覧
GET	/roles/:id/permissions	ロール別権限一覧
PUT	/roles/:id/permissions	ロール別権限更新

GET /roles

• 認証: ADMIN
• Response: [{ id, name, description, userCount }]

PUT /roles/:id/permissions

• 認証: ADMIN
• Request: { permissions: ["clients:read", "clients:write", ...] }
• Response: 更新後の権限一覧

---

F01: クライアント管理

メソッド	パス	説明
GET	/clients	クライアント一覧
POST	/clients	クライアント作成
GET	/clients/:id	クライアント詳細
PATCH	/clients/:id	クライアント更新
DELETE	/clients/:id	クライアント削除（論理）
GET	/clients/:id/health-score	健全性スコア取得
GET	/clients/:id/contacts	担当者一覧
POST	/clients/:id/contacts	担当者追加
PATCH	/clients/:id/contacts/:contactId	担当者更新
DELETE	/clients/:id/contacts/:contactId	担当者削除
GET	/clients/:id/activity-log	活動履歴
POST	/clients/:id/activity-log	活動記録追加

GET /clients

• 認証: ADMIN, AD, AM, VIEWER
• Query: ?industry=&status=active&accountManagerId=&minHealthScore=70
• Response: [{ id, companyName, industry, status, accountManager, healthScore, monthlyBudget, contractEndDate }]

POST /clients

• 認証: ADMIN, AD, AM
• Request: { companyName, industry, website, address, accountManagerId, monthlyBudget, notes }
• Response: 作成されたクライアントオブジェクト

GET /clients/:id

• 認証: ADMIN, AD, AM, VIEWER
• Response: { id, companyName, industry, website, address, accountManager, contacts[], activeContracts, totalSpend, healthScore, status, createdAt, updatedAt }

GET /clients/:id/health-score

• 認証: ADMIN, AD, AM, VIEWER
• Response: { overallScore, breakdown: { budgetUtilization, performanceScore, engagementScore, contractStatus }, trend: [{ date, score }], riskFactors: [string] }

POST /clients/:id/activity-log

• 認証: ADMIN, AD, AM
• Request: { type(meeting|call|email|note), subject, description, date, attendees[] }
• Response: 作成された活動記録

---

F02: 広告パフォーマンスダッシュボード

メソッド	パス	説明
GET	/performance/summary	KPI サマリー
GET	/performance/trends	トレンドデータ
GET	/performance/by-channel	チャネル別パフォーマンス
GET	/performance/by-campaign	キャンペーン別パフォーマンス
GET	/performance/clients/:clientId	クライアント別パフォーマンス
GET	/performance/alerts	パフォーマンスアラート一覧
PATCH	/performance/alerts/:id	アラート既読・対応済み更新
GET	/performance/alerts/rules	アラートルール一覧
POST	/performance/alerts/rules	アラートルール作成
PATCH	/performance/alerts/rules/:id	アラートルール更新
DELETE	/performance/alerts/rules/:id	アラートルール削除

GET /performance/summary

• 認証: ADMIN, AD, AM, MP, VIEWER
• Query: ?clientId=&dateFrom=&dateTo=&channel=
• Response: { impressions, clicks, ctr, conversions, cvr, spend, cpa, cpc, roas }

GET /performance/trends

• 認証: ADMIN, AD, AM, MP, VIEWER
• Query: ?clientId=&dateFrom=&dateTo=&granularity=(daily|weekly|monthly)&metrics=ctr,roas
• Response: [{ date, impressions, clicks, ctr, conversions, spend, roas }]

GET /performance/by-channel

• 認証: ADMIN, AD, AM, MP, VIEWER
• Query: ?clientId=&dateFrom=&dateTo=
• Response: [{ channel(google|meta|twitter|tiktok|display), impressions, clicks, spend, conversions, roas }]

GET /performance/alerts

• 認証: ADMIN, AD, AM, MP
• Query: ?status=(unread|acknowledged|resolved)&severity=(critical|warning|info)
• Response: [{ id, type, severity, message, clientId, campaignId, metric, threshold, currentValue, createdAt, status }]

POST /performance/alerts/rules

• 認証: ADMIN, AD, AM
• Request: { name, metric(ctr|roas|cpa|spend), condition(above|below), threshold, severity, clientIds[], channels[], notifyUserIds[] }
• Response: 作成されたルール

---

F03: メディアプランニング・予算管理

メディアプラン

メソッド	パス	説明
GET	/media-plans	メディアプラン一覧
POST	/media-plans	メディアプラン作成
GET	/media-plans/:id	メディアプラン詳細
PATCH	/media-plans/:id	メディアプラン更新
DELETE	/media-plans/:id	メディアプラン削除
POST	/media-plans/:id/duplicate	メディアプラン複製
PATCH	/media-plans/:id/status	ステータス変更（draft→approved→active→completed）

GET /media-plans

• 認証: ADMIN, AD, AM, MP, VIEWER
• Query: ?clientId=&status=(draft|approved|active|completed)&dateFrom=&dateTo=
• Response: [{ id, name, clientId, clientName, status, totalBudget, startDate, endDate, channelCount }]

POST /media-plans

• 認証: ADMIN, AD, AM, MP
• Request: { name, clientId, startDate, endDate, totalBudget, objective, notes }
• Response: 作成されたメディアプラン

GET /media-plans/:id

• 認証: ADMIN, AD, AM, MP, VIEWER
• Response: { id, name, client, status, totalBudget, startDate, endDate, objective, allocations[], notes, createdBy, createdAt }

予算配分

メソッド	パス	説明
GET	/media-plans/:planId/allocations	予算配分一覧
POST	/media-plans/:planId/allocations	予算配分追加
PATCH	/media-plans/:planId/allocations/:id	予算配分更新
DELETE	/media-plans/:planId/allocations/:id	予算配分削除

POST /media-plans/:planId/allocations

• 認証: ADMIN, AD, AM, MP
• Request: { channel, monthlyBudgets: [{ month, amount }], targetKpis: { impressions, clicks, conversions } }
• Response: 作成された配分オブジェクト

ペーシング

メソッド	パス	説明
GET	/media-plans/:planId/pacing	ペーシング状況
GET	/budgets/pacing/summary	全体ペーシングサマリー

GET /media-plans/:planId/pacing

• 認証: ADMIN, AD, AM, MP, VIEWER
• Response: { planId, totalBudget, spent, remaining, percentSpent, expectedPercent, pacingStatus(on_track|under|over), byChannel: [{ channel, budget, spent, pacingStatus }], dailyBurnRate, projectedEndSpend }

GET /budgets/pacing/summary

• 認証: ADMIN, AD, AM, MP
• Query: ?clientId=&month=
• Response: [{ clientId, clientName, planId, totalBudget, spent, pacingStatus }]

---

F04: クリエイティブ管理・承認ワークフロー

クリエイティブ素材

メソッド	パス	説明
GET	/creatives	クリエイティブ一覧
POST	/creatives	クリエイティブ登録
GET	/creatives/:id	クリエイティブ詳細
PATCH	/creatives/:id	クリエイティブ更新
DELETE	/creatives/:id	クリエイティブ削除
POST	/creatives/:id/versions	新バージョンアップロード
GET	/creatives/:id/versions	バージョン履歴

GET /creatives

• 認証: ADMIN, AD, AM, CR, VIEWER
• Query: ?clientId=&type=(image|video|html5|text)&status=(draft|pending_review|approved|rejected)&channel=
• Response: [{ id, name, type, thumbnailUrl, status, clientId, clientName, currentVersion, updatedAt }]

POST /creatives

• 認証: ADMIN, AD, AM, CR
• Request: multipart/form-data { name, clientId, type, channel, file, description, specifications }
• Response: { id, name, type, fileUrl, thumbnailUrl, status(draft), version(1) }

POST /creatives/:id/versions

• 認証: ADMIN, AD, AM, CR
• Request: multipart/form-data { file, changeNote }
• Response: { versionId, versionNumber, fileUrl, changeNote, createdAt }

承認ワークフロー

メソッド	パス	説明
POST	/creatives/:id/submit-for-review	レビュー提出
POST	/creatives/:id/approve	承認
POST	/creatives/:id/reject	却下
POST	/creatives/:id/request-revision	修正依頼
GET	/creatives/:id/review-history	レビュー履歴
POST	/creatives/:id/comments	コメント追加
GET	/creatives/:id/comments	コメント一覧

POST /creatives/:id/submit-for-review

• 認証: ADMIN, CR
• Request: { reviewerIds[], dueDate, message? }
• Response: { id, status(pending_review), reviewers[], dueDate }

POST /creatives/:id/approve

• 認証: ADMIN, AD, AM
• Request: { comment? }
• Response: { id, status(approved), approvedBy, approvedAt }

POST /creatives/:id/reject

• 認証: ADMIN, AD, AM
• Request: { reason, comment }
• Response: { id, status(rejected), rejectedBy, rejectedAt, reason }

POST /creatives/:id/request-revision

• 認証: ADMIN, AD, AM
• Request: { feedback, priority(low|medium|high) }
• Response: { id, status(revision_requested), feedback }

---

F05: 代理店手数料・収益管理

メソッド	パス	説明
GET	/revenue/summary	収益サマリー
GET	/revenue/by-client	クライアント別収益
GET	/revenue/by-client/:clientId	クライアント別収益詳細
GET	/revenue/pl	P/L 一覧
GET	/revenue/pl/:id	P/L 詳細
POST	/revenue/pl	P/L レコード作成
PATCH	/revenue/pl/:id	P/L レコード更新

GET /revenue/summary

• 認証: ADMIN, AD, FIN
• Query: ?dateFrom=&dateTo=&granularity=(monthly|quarterly|yearly)
• Response: { totalRevenue, totalCost, grossProfit, grossMargin, commissionIncome, managementFees, byPeriod: [{ period, revenue, cost, profit, margin }] }

GET /revenue/by-client

• 認証: ADMIN, AD, FIN
• Query: ?dateFrom=&dateTo=
• Response: [{ clientId, clientName, mediaSpend, commissionRate, commissionAmount, managementFee, totalRevenue, cost, profit, margin }]

GET /revenue/pl

• 認証: ADMIN, AD, FIN
• Query: ?clientId=&period=&status=(draft|confirmed)
• Response: [{ id, clientId, clientName, period, mediaSpend, revenue, directCost, indirectCost, grossProfit, netProfit, margin, status }]

POST /revenue/pl

• 認証: ADMIN, FIN
• Request: { clientId, period, mediaSpend, commissionRate, managementFee, directCosts: [{ category, amount }], indirectCosts: [{ category, amount }] }
• Response: 作成された P/L レコード（利益・マージン自動計算済み）

---

F06: 自動レポーティング

レポートテンプレート

メソッド	パス	説明
GET	/reports/templates	テンプレート一覧
POST	/reports/templates	テンプレート作成
GET	/reports/templates/:id	テンプレート詳細
PATCH	/reports/templates/:id	テンプレート更新
DELETE	/reports/templates/:id	テンプレート削除

レポート生成・配信

メソッド	パス	説明
POST	/reports/generate	レポート即時生成
GET	/reports	生成済みレポート一覧
GET	/reports/:id	レポート詳細
GET	/reports/:id/download	レポートダウンロード
DELETE	/reports/:id	レポート削除

スケジュール配信

メソッド	パス	説明
GET	/reports/schedules	スケジュール一覧
POST	/reports/schedules	スケジュール作成
PATCH	/reports/schedules/:id	スケジュール更新
DELETE	/reports/schedules/:id	スケジュール削除

---

F07: タスク管理

メソッド	パス	説明
GET	/tasks	タスク一覧
POST	/tasks	タスク作成
GET	/tasks/:id	タスク詳細
PATCH	/tasks/:id	タスク更新
DELETE	/tasks/:id	タスク削除
PATCH	/tasks/:id/status	ステータス変更
PATCH	/tasks/:id/assign	担当者変更
GET	/tasks/kanban	カンバンボード用データ
GET	/tasks/gantt	ガントチャート用データ
POST	/tasks/:id/comments	タスクコメント追加
GET	/tasks/:id/comments	タスクコメント一覧

GET /tasks/kanban

• 認証: 全認証ユーザー
• Query: ?clientId=&assigneeId=&projectId=
• Response: { columns: [{ id(todo|in_progress|review|done), title, tasks: [{ id, title, priority, assignee, dueDate, tags[] }] }] }

GET /tasks/gantt

• 認証: 全認証ユーザー
• Query: ?clientId=&projectId=&dateFrom=&dateTo=
• Response: [{ id, title, assignee, startDate, endDate, dueDate, progress, dependencies: [{ taskId, type }], milestone }]

---

F08: 契約・IO・請求書管理

契約

メソッド	パス	説明
GET	/contracts	契約一覧
POST	/contracts	契約作成
GET	/contracts/:id	契約詳細
PATCH	/contracts/:id	契約更新
DELETE	/contracts/:id	契約削除（論理）
PATCH	/contracts/:id/status	契約ステータス変更
GET	/contracts/:id/documents	契約関連書類一覧
POST	/contracts/:id/documents	契約書類アップロード

IO明細

メソッド	パス	説明
GET	/contracts/:contractId/line-items	IO 明細一覧
POST	/contracts/:contractId/line-items	IO 明細追加
PATCH	/contracts/:contractId/line-items/:id	IO 明細更新
DELETE	/contracts/:contractId/line-items/:id	IO 明細削除

請求書

メソッド	パス	説明
GET	/invoices	請求書一覧
POST	/invoices/generate	請求書生成
GET	/invoices/:id	請求書詳細
PATCH	/invoices/:id	請求書更新
PATCH	/invoices/:id/status	請求書ステータス変更
GET	/invoices/:id/download	請求書 PDF ダウンロード

---

HTTPステータスコード規約

コード	用途
200	正常取得・更新
201	リソース作成成功
204	削除成功
400	バリデーションエラー
401	未認証
403	権限不足
404	リソース未発見
409	状態遷移の競合
422	処理不能なリクエスト
429	レートリミット超過
500	サーバーエラー

エラーレスポンス構造

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed",
  "details": [
    { "field": "email", "message": "must be a valid email address" }
  ]
}

---

エンドポイント総数

ドメイン	エンドポイント数
F14: 認証・ユーザー管理	13
F01: クライアント管理	12
F02: パフォーマンスダッシュボード	11
F03: メディアプランニング・予算管理	11
F04: クリエイティブ管理・承認	14
F05: 収益管理	7
F06: 自動レポーティング	11
F07: タスク管理	11
F08: 契約・IO・請求書管理	14
合計	104