FUNBREW PDFFUNBREW PDF
2026/04/28

再販エージェンシー向け：APIキーをクライアント別にグルーピングする方法

APIキー管理再販マルチテナント請求按分ベストプラクティス

PDF生成APIを自社サービスに組み込んで複数のクライアントに提供している代理店・受託開発会社、あるいは複数テナントを抱えるSaaS運営者にとって、最も面倒なのが「どのキーが、どのクライアント向けで、いくら使ったのか」を毎月集計する作業です。

FUNBREW PDFはこの問題を解決するため、APIキーにクライアント名とタグを付与してグルーピングできる機能を提供しています。生成PDF・APIログ・利用量をクライアント単位で絞り込み、CSVエクスポートで請求按分の根拠資料まで一気通貫で出力できます。再販シナリオはユースケース集でも詳しく紹介しています。

この記事では、再販シナリオでの具体的な運用方法と、ベストプラクティスを解説します。

なぜAPIキーのグルーピングが必要か

よくある運用課題

  • 請求按分が手作業: 月末にスプレッドシートで「Acme社のキーは10,000件、Beta社は3,000件」と1つずつ集計
  • ログの絞り込みができない: トラブル発生時、「Acme社の生成だけ見たい」のに全社ログから検索
  • キー管理が属人化: 「sk-xxxxx は誰のキーだっけ？」と後任が困る

グルーピングで解決すること

課題 グルーピング後
請求按分の手作業 CSV出力で client_label 列を見るだけ
ログの絞り込み クライアント名で1クリック
キーの属人化 ダッシュボードで一目瞭然

client_label と tags の使い分け

迷ったときは下の表を見れば一発です。「請求書を分けたい単位」が client_label、それ以外の付箋が tags と覚えてください。

client_label tags
個数 1つだけ 複数可
役割 請求按分・集約のメイン軸 環境・用途などの補助分類
例 Acme Inc production, invoice-pdf
CSV出力 client_label 列に出力（請求根拠） 現状は出力対象外（管理画面のみ）
表記揺れ フィルタが効かなくなるので注意 比較的緩くてOK

実際の使い方

ステップ1: APIキーにクライアント情報を付与

ダッシュボード → APIキー → 「新規発行」または既存キーの「編集」を開きます。

  • キー名: 内部管理用の名前（例: Acme Production）
  • クライアント / プロジェクト: クライアント企業名やプロジェクト名（例: Acme Inc）
  • タグ: 環境や用途（例: production, invoice-pdf）

Tip: 同じクライアントに複数キーを発行する場合（環境別・用途別）も、client_label を同じ値で揃えておけば、後でクライアント単位で集約できます。

ステップ2: PDFファイルとAPIログをクライアント別に絞り込み

ダッシュボードのPDFファイル一覧・APIログ画面に「クライアント」フィルタが追加されます。

複数のキー（例: Acmeの本番キーとステージングキー）に同じ client_label を付与している場合、フィルタは両方のキーで生成されたPDFをまとめて表示します。キー単位ではなくクライアント単位の集約ビューになるのがポイントです。

ステップ3: CSV出力で請求按分

PDFファイル一覧の「CSVエクスポート」を実行すると、以下の列が出力されます。

filename,original_name,source_type,file_size,download_count,...,api_key,client_label
abc123.pdf,"Acme請求書_2026-04.pdf",html,254078,1,...,Acme Production,Acme Inc
def456.pdf,"Beta契約書.pdf",html,128400,2,...,Beta Production,Beta Corp

client_label 列でピボットすれば、クライアント別の生成件数・ファイルサイズ・ダウンロード数が一発で集計できます。月末の請求書発行作業がほぼ自動化されます。

再販シナリオ別ベストプラクティス

シナリオ1: 代理店モデル（クライアント企業ごとに別々の請求）

client_label: "Acme Inc"       tags: ["production"]
client_label: "Acme Inc"       tags: ["staging"]
client_label: "Beta Corp"      tags: ["production"]
client_label: "Gamma Studio"   tags: ["production", "trial"]
  • 月次CSVを client_label でグループ化 → 各クライアントへの請求書根拠に
  • トライアル中の Gamma Studio は trial タグで識別、転換時に production タグへ更新

シナリオ2: マルチテナントSaaS

client_label: "tenant_001"  tags: ["plan:pro", "production"]
client_label: "tenant_002"  tags: ["plan:enterprise", "production"]
  • client_label にテナントIDを使えば、自社DBと突き合わせやすい
  • プラン情報をタグに入れておけば、利用量超過の検知に使える

シナリオ3: 受託開発・案件単位

client_label: "Project Alpha"  tags: ["delivered", "support-2026"]
client_label: "Project Beta"   tags: ["development"]
  • 納品済み案件を delivered タグでマーク、サポート期間中は support-yyyy タグで管理
  • サポート問い合わせ時に該当プロジェクトのログだけを参照

設計上の注意点

グルーピングは管理用ラベル

client_label と tags は管理画面での絞り込み・集計のためのメタデータで、APIの動作（レート制限、課金、スコープなど）には影響しません。クライアント単位でレート制限を分けたい場合は、現状はキーごとの分離で対応してください。

キーは安全に保管

クライアントに直接APIキーを渡す再販モデルではなく、自社サーバーがプロキシ的にAPIキーを保持し、クライアントのリクエストをFUNBREW PDFへ中継する運用を推奨します。クライアントごとに別キーを使い、client_label で識別すれば、万が一漏洩した際のキーローテーションも限定的な影響で済みます。

命名規則を最初に決める

複数人で運用する場合、client_label の表記揺れ（Acme Inc / acme inc / Acme Inc.）が起きるとフィルタが効かなくなります。社内で命名規則（例: 正式社名、半角スペース、敬称なし）を最初に決めておきましょう。

まとめ

PDF生成APIを再販する場合、APIキーのグルーピングは請求按分・サポート対応・運用引き継ぎの3つを劇的に楽にします。

  • client_label でクライアント単位の集約
  • tags で環境・用途の細分化
  • CSV出力で請求按分の自動化

すでにAPIキーを発行済みの場合も、ダッシュボードから既存キーを編集して client_label と tags を追加するだけで、過去のPDF・ログも遡ってフィルタできます。

詳しい使い方は公式ドキュメントを、APIキーの発行はダッシュボードからどうぞ。実装をすぐに試してみたい方はプレイグラウンドで動作確認もできます。請求書PDFの自動化全体については請求書APIガイドも参考にどうぞ。

コスト割り当てパターン

クライアント単位のグルーピングだけでなく、コストセンター・請求期間・サービスティアごとに利用コストを追跡したいケースも多いです。以下のパターンでは client_label とタグを組み合わせ、外部ツールなしに軽量なコスト割り当て基盤を構築します。

パターン1: 部門別コストセンター

1つのエンタープライズクライアントが複数の内部部門を持つ場合、部門ごとにキーを発行してタグで識別します。client_label は全部門キーで統一しておけば、CSVはアカウント単位に自動集約されます。

client_label: "Acme Corp"   tags: ["dept:finance",    "production"]
client_label: "Acme Corp"   tags: ["dept:legal",      "production"]
client_label: "Acme Corp"   tags: ["dept:marketing",  "production"]

月末にCSVをエクスポートして client_label でピボットすればAcme Corp向け請求書の根拠になり、さらに dept:* タグで絞り込めば部門別の社内チャージバックレポートが作れます。追加インフラ不要です。

パターン2: 利用上限付きのティア料金

PDFを異なる料金プランで再販するSaaS事業者は、プランをタグにエンコードして上限をプログラムで管理できます。

client_label: "tenant_A"   tags: ["plan:starter",    "production"]   # 上限: 500件/月
client_label: "tenant_B"   tags: ["plan:growth",     "production"]   # 上限: 5,000件/月
client_label: "tenant_C"   tags: ["plan:enterprise", "production"]   # 上限: 無制限

自社の請求サービスがFUNBREW PDF APIからキーごとの月次利用量を取得し、各プランの上限と比較して生成をブロックするかアップセルフローを起動します。プランがタグに入っているため、プラン変更はフィールド1つの更新だけで済み、キー構成を変える必要がありません。

パターン3: プロジェクトライフサイクルのコスト追跡

案件単位で請求する代理店では、スコーピング・プロトタイピングなどの社内費用とクライアントに請求する本番費用を分けて追跡する必要があります。

client_label: "Project Omega"   tags: ["phase:prototype", "internal"]
client_label: "Project Omega"   tags: ["phase:production", "billable"]

CSVで billable フィルタをかけた行がクライアント向け請求書の根拠になり、internal 行は自社のP&L管理に使います。プロジェクト完了後は delivered タグを追加し、キーローテーションを止めても client_label のCSV履歴はアーカイブに残ります。

使用量アラートパターン

プロアクティブな使用量監視は、請求額の急増やプラン超過によるサポート問い合わせを事前に防ぎます。FUNBREW PDF APIは使用量データをAPIで公開しているため、標準的なツールで軽量なアラートを構築できます。

cronスクリプトによるアラート

// scripts/usage-alert.js
// cronまたはスケジュールされたLambdaで毎日実行し、上限到達前に警告

import axios from 'axios';

const API_KEY       = process.env.FUNBREW_API_KEY;
const API_URL       = process.env.FUNBREW_API_URL || 'https://api.pdf.funbrew.cloud/v1';
const SLACK_WEBHOOK = process.env.SLACK_WEBHOOK_URL;

// クライアントラベルと月次PDF上限のマッピング
const LIMITS = {
  'Acme Inc':   5000,
  'Beta Corp':  1000,
  'Gamma LLC':  2500,
};

async function checkUsage() {
  const { data } = await axios.get(`${API_URL}/usage/monthly`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });

  for (const [client, usage] of Object.entries(data.byClient)) {
    const cap = LIMITS[client];
    if (!cap) continue;

    const pct = (usage.count / cap) * 100;

    if (pct >= 90) {
      await sendSlackAlert(client, usage.count, cap, pct);
    }
  }
}

async function sendSlackAlert(client, used, cap, pct) {
  const msg = `*PDF使用量アラート* — ${client}: ${used.toLocaleString()} / ${cap.toLocaleString()} 件 (${pct.toFixed(0)}%)`;
  await axios.post(SLACK_WEBHOOK, { text: msg });
}

checkUsage().catch(console.error);

このスクリプトをcronジョブかAWS EventBridgeルールに接続すると、いずれかのクライアントが上限の90%を超えた時点でSlack通知が飛びます。

Webhookイベントによるリアルタイム追跡

イベント駆動の監視を好む場合は、FUNBREW PDFのWebhook連携を活用します。pdf.created イベントを受信してカウンターをインクリメントします。

// 擬似コード: pdf.createdイベント受信時にRedisカウンターをインクリメント
app.post('/webhooks/pdf', async (req, res) => {
  const { event, payload } = req.body;
  if (event !== 'pdf.created') return res.sendStatus(204);

  const client = payload.client_label;
  const key    = `usage:${client}:${currentMonth()}`;

  await redis.incr(key);
  await redis.expire(key, 60 * 60 * 24 * 35); // 約35日保持

  // 上限チェック
  const count = await redis.get(key);
  const cap = LIMITS[client];
  if (cap && count >= cap * 0.9) {
    await triggerAlert(client, count, cap);
  }

  res.sendStatus(204);
});

APIをポーリングせず、クライアントごとのカウンターをサブ秒で更新できます。Webhookのイベントスキーマ全体はWebhookペイロードガイドを参照してください。

クライアントオンボーディングフロー

十数個のキーが並行して動いている状況で新しいクライアントを一貫してオンボーディングするのは、思ったより難しいです。以下のチェックリストとコードスニペットで所要時間を3分以内に標準化できます。

オンボーディングチェックリスト

  1. APIキー作成 — 環境ごとに1枚（最低でも本番+ステージング）
  2. client_label 設定 — 法人名またはテナントIDを使用（命名規則は事前に決定済みであること）
  3. タグ設定 — 環境（production, staging）、プランティア（plan:growth）、その他フィルタ軸
  4. LIMITS マップへ追加 — 使用量アラートスクリプトにクライアントの上限を追記
  5. 資格情報の安全な共有 — 生のキーをメールで送らない。シークレットマネージャーや使い捨てリンクツールを使う
  6. スモークテスト — プレイグラウンドで新しいキーを使ってPDF1枚生成し、動作確認
  7. ドキュメント化 — 社内のキー台帳に追記（命名規則が統一されていれば表計算でも可）

キー作成の自動化

大量のオンボーディングが発生する場合は、ダッシュボードではなくFUNBREW PDF REST APIでキーを作成します。

# 新規クライアントの本番キーを作成
curl -X POST https://api.pdf.funbrew.cloud/v1/api-keys \
  -H "Authorization: Bearer $FUNBREW_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":         "Acme Inc — Production",
    "client_label": "Acme Inc",
    "tags":         ["production", "plan:growth"]
  }'

返却されたキー値はシークレットマネージャーにすぐ保存してください。キー値が表示されるのは一度だけです。その後、クライアントが最初のリクエストを送る前にLIMITSマップとアラート設定を更新します。

オフボーディング

クライアントとの関係が終了したら、ダッシュボードからキーをローテーションまたは失効させます。キー失効後も client_label でCSVデータを検索できるため、最終の利用量レポートを作成して締め請求書を発行できます。

# キーを失効させる（KEY_IDを実際のキーIDに置き換える）
curl -X DELETE https://api.pdf.funbrew.cloud/v1/api-keys/KEY_ID \
  -H "Authorization: Bearer $FUNBREW_MASTER_KEY"

失効後、対象の client_label でCSVをエクスポートしてプロジェクトファイルと一緒にアーカイブします。以降のサポート問い合わせにはアーカイブから回答できます。

まとめ：全体像

グルーピング・コスト割り当て・アラートの3つを組み合わせると、FUNBREW PDF APIの上に軽量なクライアント管理レイヤーができあがります。

機能 仕組み 運用コスト
クライアント別可視化 client_label オンボーディング時のみ
請求根拠 CSVエクスポート + ピボット 月次、約5分
部門別チャージバック dept:* タグ コストセンターごとに一度
プラン管理 使用量API + cronスクリプト 初期設定のみ
リアルタイム追跡 Webhook → Redisカウンター 初期設定のみ
新規オンボーディング ダッシュボードまたはREST API クライアントごとに約3分

大量のPDFを生成するクライアントを抱える場合は、バッチ処理ガイドとレート制限ガイドも参照してください。特定のクライアントが1時間に数千件のPDFを生成し始めると、どちらも重要になります。

複数クライアントにまたがるキーの保管・ローテーションについては、APIセキュリティガイドでシークレット管理・プロキシパターン・監査ログを詳しく説明しています。

記事一覧に戻る
Powered by FUNBREW PDF