Apr 12, 2026 · 14:38 JST

SaaSのプラン付与経路を設計する

法人向けシリアルキー配布、パートナー経由のリファラ付与、プロモーションコードなど、SaaS のプラン付与経路を課金サービス（billing）で統一的に管理する設計を整理。

課金設計 B2B SaaS ライセンス

はじめに

SaaS のプラン付与は「ユーザーが自分でプランを選んで決済する」だけではありません。実際には以下のような経路があります。

法人にライセンスを一括販売 → シリアルキーで社員に配布
パートナー経由の紹介 → リファラリンクで有料プランを自動付与
キャンペーン → プロモーションコードで割引や無料期間を付与
社内紹介 → 紹介元ユーザーにクレジット付与

これらを個別に実装するとカオスになるので、課金サービス（billing）の「プラン付与経路」として統一的に設計するのが筋です。

全体像

すべての経路が最終的に billing の「プラン付与」に収束します。

1. シリアルキー（法人ライセンス配布）

ユースケース

法人に 100 ライセンスを販売し、シリアルキーを渡す。法人の管理者がキーを社員に配布し、社員はキーを使ってサインアップする。

フロー

キーの設計

フォーマット: RELLF-XXXX-XXXX
  │      │      │
  │      │      └─ ランダム4文字（英数大文字）
  │      └──────── ランダム4文字
  └─────────────── プレフィックス（ブランド識別）

衝突確率: 36^8 ≒ 28億通り（十分）

人間が読みやすい・入力しやすい・電話で伝えやすい長さが重要です。

データモデル

運用パターン

パターン	対応
キーの使い回し防止	`status=used` で 1 回限り
キーの期限切れ	`expires_at` で検証
退職者のシート回収	ユーザー削除 → キーを `revoked` → `used_seats` 減算 → 新キー発行可能
追加購入	`total_seats` を増やす → 追加キーを発行
ダウングレード	`total_seats` を減らす → 超過分は猶予期間付きで対応

シリアルキー vs 招待リンク

	シリアルキー	招待リンク
配布方法	紙、メール、口頭	メール
入力	ユーザーが手入力	リンクをクリック
オフライン配布	可能	不可
特定ユーザーへの紐付け	なし（誰でも使える）	メアドに紐付け
横流しリスク	あり	低い

両方サポートするのが理想です。管理者が「この人に確実に渡したい」なら招待リンク、「まとめて配りたい」ならシリアルキー。

2. リファラ（パートナー経由）

ユースケース

パートナー企業のサイトからリンク経由でサインアップすると、有料プランが自動付与される。パートナーには成果報酬が発生する。

フロー

データモデル

リファラリンクの署名

リファラの偽装を防ぐために、パートナーの API キーで署名付きリンクを生成します。

https://app.example.com/signup?
  ref=partner-abc
  &plan=pro
  &ts=1712900000
  &sig=HMAC-SHA256(partner-abc:pro:1712900000, api_key)

billing がリンクの sig を検証して、正規のパートナーリンクかどうかを判定。

3. プロモーションコード

ユースケース

期間限定キャンペーンで「このコードを入力すると 3 ヶ月無料」のような施策。

フロー

データモデル

プロモコードの種類

種類	例	benefit_type
無料期間延長	「3ヶ月無料で使えます」	free_trial
割引	「初年度 50% オフ」	discount
プランアップグレード	「pro プランにアップグレード」	upgrade
クレジット付与	「5000円分のクレジット」	credit

4. 社内紹介

ユースケース

既存ユーザーが友人・同僚を紹介すると、紹介元にクレジットが付与される。

フロー

1. 既存ユーザーが紹介リンクを生成
   GET /api/me/referral-link
   → https://app.example.com/signup?invite=user-xxx

2. 友人がリンク経由でサインアップ

3. billing: 紹介元に 1000 円クレジット付与

これはパートナーリファラの簡易版で、partners テーブルの代わりにユーザー自身が紹介元になるだけです。

統一的な設計

4 つの経路は billing の中で以下のように統合されます。

共通の「プラン付与」インターフェース

type PlanActivation struct {
    OrgID       string
    Sub         string
    Plan        string
    Source      ActivationSource  // direct | license_key | referral | promo | invite
    SourceRef   string            // キーID、パートナーID、プロモコード、紹介元sub
    BenefitType string            // full_price | free_trial | discount
    BenefitDays int               // 無料期間の日数（該当する場合）
}

func (s *BillingService) ActivatePlan(ctx context.Context, req PlanActivation) error {
    // 1. ソースの検証（キー有効？パートナー有効？プロモ有効？）
    // 2. プラン付与
    // 3. ソースの消費（キー使用済み、プロモ回数減算）
    // 4. 成果報酬の記録（該当する場合）
    // 5. イベント発行
}

すべての経路が ActivatePlan に収束します。

billing API まとめ

エンドポイント	用途
`POST /api/orgs/:id/licenses/keys`	シリアルキー一括発行
`GET /api/orgs/:id/licenses/keys`	キー一覧
`GET /api/licenses/keys/:key/validate`	キー検証
`POST /api/licenses/keys/:key/redeem`	キー消費
`POST /api/licenses/keys/:key/revoke`	キー無効化
`POST /api/orgs/:id/activate`	リファラ付きプラン付与
`GET /api/partners/:id`	パートナー情報
`GET /api/partners/:id/referrals`	パートナー成果一覧
`POST /api/promo/validate`	プロモコード検証
`POST /api/promo/redeem`	プロモコード使用
`GET /api/me/referral-link`	紹介リンク取得

イベント

イベント	発行タイミング
`LicenseKeyRedeemed`	シリアルキーが使用された
`ReferralConverted`	パートナー経由でコンバージョン
`PromoCodeRedeemed`	プロモコードが使用された
`InviteConverted`	社内紹介でコンバージョン

不正防止

リスク	対策
シリアルキーの横流し	1 キー 1 回限り、組織紐付け
リファラの偽装	HMAC 署名付きリンク
プロモコードの乱用	使用回数制限、メールドメイン制限、期限
自己紹介（自分で紹介して報酬を得る）	紹介元と紹介先のメールドメイン・IP 比較
同一ユーザーの複数利用	1 メールアドレス 1 回限り
期限切れキー/コードの使用	`expires_at` / `valid_until` で検証

認可との連携

ライセンスの種類やプロモの内容によって使える機能を変える場合、billing → authz の context で制御します。

// enterprise ライセンスなら全機能
permit(
  principal,
  action,
  resource
) when {
  context.license_type == "enterprise"
};

// トライアル中はエクスポート不可
forbid(
  principal,
  action == App::Action::"export",
  resource
) when {
  context.is_trial == true
};

// プロモで付与された pro は一部機能制限
forbid(
  principal,
  action == App::Action::"api_access",
  resource
) when {
  context.plan == "pro" &&
  context.activation_source == "promo"
};

auth 側の変更

サインアップフローにライセンスキー / プロモコードの検証を挟むだけ。auth 自体はプラン管理のロジックを持ちません。

func (c *Client) SignUp(ctx context.Context, req SignUpRequest) (*SignUpOutput, error) {
    // ライセンスキーまたはプロモコードがあれば billing に検証
    if req.LicenseKey != "" {
        if err := c.billing.ValidateKey(ctx, req.LicenseKey); err != nil {
            return nil, fmt.Errorf("invalid license key: %w", err)
        }
    }
    if req.PromoCode != "" {
        if err := c.billing.ValidatePromo(ctx, req.PromoCode); err != nil {
            return nil, fmt.Errorf("invalid promo code: %w", err)
        }
    }

    // ユーザー作成
    result, err := c.createCognitoUser(ctx, req.Email, req.Password)
    if err != nil {
        return nil, err
    }

    // キー/プロモの消費は billing に委譲（アプリ側で ActivatePlan を呼ぶ）
    return result, nil
}

まとめ

シリアルキー、リファラ、プロモコード、招待リンクは billing の**「プラン付与経路」として統一的に管理**する
すべての経路が ActivatePlan に収束する設計にすることで、新しい経路の追加が容易
auth はキー/コードの検証を billing に問い合わせるだけ。プラン管理のロジックは持たない
不正防止は経路ごとに異なるので、個別の対策を設計しておく
認可（authz）との連携で、経路やライセンス種別に応じた機能制限も表現可能

## はじめに

SaaS のプラン付与は「ユーザーが自分でプランを選んで決済する」だけではありません。実際には以下のような経路があります。

- **法人にライセンスを一括販売** → シリアルキーで社員に配布
- **パートナー経由の紹介** → リファラリンクで有料プランを自動付与
- **キャンペーン** → プロモーションコードで割引や無料期間を付与
- **社内紹介** → 紹介元ユーザーにクレジット付与

これらを個別に実装するとカオスになるので、**課金サービス（billing）の「プラン付与経路」として統一的に設計する**のが筋です。

## 全体像

```mermaid
flowchart LR
    subgraph routes["プラン付与の経路"]
        R1["直接購入（Stripe 等）"]
        R2["シリアルキー（法人一括）"]
        R3["リファラ（パートナー経由）"]
        R4["プロモコード（キャンペーン）"]
        R5["招待リンク（社内紹介）"]
    end
    subgraph billing["billing サービス"]
        B1["ライセンス管理"]
        B2["プラン付与"]
        B3["成果報酬管理"]
        B4["使用量管理"]
    end
    R1 --> billing
    R2 --> billing
    R3 --> billing
    R4 --> billing
    R5 --> billing
```

すべての経路が最終的に billing の「プラン付与」に収束します。

## 1. シリアルキー（法人ライセンス配布）

### ユースケース

法人に 100 ライセンスを販売し、シリアルキーを渡す。法人の管理者がキーを社員に配布し、社員はキーを使ってサインアップする。

### フロー

```mermaid
sequenceDiagram
    participant C as 法人
    participant M as 法人管理者
    participant E as 社員
    participant AU as auth
    participant BL as billing
    C->>BL: 1. 100 ライセンス購入
    Note over BL: org-abc に total_seats=100 を記録
    M->>BL: 2. POST /api/orgs/org-abc/licenses/keys?count=100
    BL-->>M: ["RELLF-A1B2-C3D4", "RELLF-E5F6-G7H8", ...]
    M->>E: 3. キーを配布（メール、社内ポータル等）
    E->>AU: 4. POST /auth/signup { email, password, license_key: "RELLF-A1B2-C3D4" }
    AU->>BL: キー検証 GET /api/licenses/keys/RELLF-A1B2-C3D4/validate
    BL-->>AU: 有効、org-abc、未使用
    AU->>AU: ユーザー作成（org-abc に所属）
    AU->>BL: キー消費 POST /api/licenses/keys/RELLF-A1B2-C3D4/redeem { sub: "user-xxx" }
```

### キーの設計

```
フォーマット: RELLF-XXXX-XXXX
  │      │      │
  │      │      └─ ランダム4文字（英数大文字）
  │      └──────── ランダム4文字
  └─────────────── プレフィックス（ブランド識別）

衝突確率: 36^8 ≒ 28億通り（十分）
```

人間が読みやすい・入力しやすい・電話で伝えやすい長さが重要です。

### データモデル

```mermaid
erDiagram
    licenses ||--o{ license_keys : "org_id で発行"
    licenses {
        varchar org_id PK "例: org-abc"
        varchar plan "例: enterprise"
        int total_seats "例: 100"
        int used_seats "例: 42"
    }
    license_keys {
        varchar key PK "例: RELLF-A1B2-C3D4"
        varchar org_id FK "例: org-abc"
        varchar status "unused / used / revoked"
        datetime created_at "例: 2026-04-12"
        varchar redeemed_by "null / user-xxx"
        datetime redeemed_at "null / 2026-04-13"
        datetime expires_at "例: 2027-04-12"
    }
```

### 運用パターン

| パターン | 対応 |
|---------|------|
| キーの使い回し防止 | `status=used` で 1 回限り |
| キーの期限切れ | `expires_at` で検証 |
| 退職者のシート回収 | ユーザー削除 → キーを `revoked` → `used_seats` 減算 → 新キー発行可能 |
| 追加購入 | `total_seats` を増やす → 追加キーを発行 |
| ダウングレード | `total_seats` を減らす → 超過分は猶予期間付きで対応 |

### シリアルキー vs 招待リンク

| | シリアルキー | 招待リンク |
|---|---|---|
| 配布方法 | 紙、メール、口頭 | メール |
| 入力 | ユーザーが手入力 | リンクをクリック |
| オフライン配布 | 可能 | 不可 |
| 特定ユーザーへの紐付け | なし（誰でも使える） | メアドに紐付け |
| 横流しリスク | あり | 低い |

両方サポートするのが理想です。管理者が「この人に確実に渡したい」なら招待リンク、「まとめて配りたい」ならシリアルキー。

## 2. リファラ（パートナー経由）

### ユースケース

パートナー企業のサイトからリンク経由でサインアップすると、有料プランが自動付与される。パートナーには成果報酬が発生する。

### フロー

```mermaid
sequenceDiagram
    participant U as ユーザー
    participant PS as パートナーサイト
    participant AP as アプリ
    participant AU as auth
    participant BL as billing
    participant EB as EventBridge
    PS->>U: 1. リンク https://app.example.com/signup?ref=partner-abc&plan=pro
    U->>AP: リンク経由でアクセス
    AP->>AP: 2. リファラ情報を cookie に保持
    U->>AP: 3. サインアップ
    AP->>AU: ユーザー作成
    AP->>BL: 4. POST /api/orgs/org-new/activate（リファラ付きプラン付与）
    Note over AP,BL: sub=user-xxx, referrer=partner-abc, plan=pro, source=partner_referral
    BL->>BL: 5. パートナーが有効か検証
    BL->>BL: pro プランの付与権限があるか検証
    BL->>BL: org にプラン設定
    BL->>BL: 成果報酬を記録
    BL->>EB: 6. ReferralConverted イベント発行
    Note over BL,EB: partner_id=partner-abc, org_id=org-new, plan=pro, commission_amount=9800
```

### データモデル

```mermaid
erDiagram
    partners ||--o{ referrals : "partner_id で紹介"
    partners {
        varchar partner_id PK "例: partner-abc"
        varchar name "例: パートナー企業A"
        json allowed_plans "例: [pro, standard]"
        decimal commission_rate "例: 0.2"
        varchar status "active / suspended"
        varchar api_key "例: pk_xxx"
    }
    referrals {
        varchar id PK "例: ref-001"
        varchar partner_id FK "例: partner-abc"
        varchar org_id "例: org-new"
        varchar sub "例: user-xxx"
        varchar plan_granted "例: pro"
        varchar source_url "例: https://partner-abc.com/recommend"
        datetime converted_at "例: 2026-04-12"
        int commission_amount "例: 9800"
        varchar commission_status "pending / paid"
    }
```

### リファラリンクの署名

リファラの偽装を防ぐために、パートナーの API キーで署名付きリンクを生成します。

```
https://app.example.com/signup?
  ref=partner-abc
  &plan=pro
  &ts=1712900000
  &sig=HMAC-SHA256(partner-abc:pro:1712900000, api_key)
```

billing がリンクの `sig` を検証して、正規のパートナーリンクかどうかを判定。

## 3. プロモーションコード

### ユースケース

期間限定キャンペーンで「このコードを入力すると 3 ヶ月無料」のような施策。

### フロー

```mermaid
sequenceDiagram
    participant U as ユーザー（サインアップ画面）
    participant AU as auth
    participant BL as billing
    U->>AU: 1. プロモコード入力 POST /auth/signup { email, password, promo_code: "SPRING2026" }
    AU->>BL: 2. プロモコード検証 POST /api/promo/validate { code: "SPRING2026" }
    BL-->>AU: 有効、3ヶ月無料、残り 500 回使用可能
    AU->>AU: 3. ユーザー作成
    AU->>BL: 4. プロモコード使用 POST /api/promo/redeem { code: "SPRING2026", sub: "user-xxx" }
    BL-->>AU: pro プラン + 3ヶ月無料トライアル付与
```

### データモデル

```mermaid
erDiagram
    promo_codes ||--o{ promo_redemptions : "code で使用"
    promo_codes {
        varchar code PK "例: SPRING2026"
        varchar description "例: 2026年春キャンペーン"
        varchar plan "例: pro"
        varchar benefit_type "free_trial / discount / upgrade"
        int benefit_value "例: 90（日数 or 割引率）"
        int max_redemptions "例: 1000"
        int current_redemptions "例: 500"
        datetime valid_from "例: 2026-03-01"
        datetime valid_until "例: 2026-05-31"
        json allowed_domains "空=制限なし, [example.com]=ドメイン制限"
    }
    promo_redemptions {
        varchar code FK "例: SPRING2026"
        varchar sub "例: user-xxx"
        datetime redeemed_at "例: 2026-04-12"
    }
```

### プロモコードの種類

| 種類 | 例 | benefit_type |
|------|-----|-------------|
| 無料期間延長 | 「3ヶ月無料で使えます」 | free_trial |
| 割引 | 「初年度 50% オフ」 | discount |
| プランアップグレード | 「pro プランにアップグレード」 | upgrade |
| クレジット付与 | 「5000円分のクレジット」 | credit |

## 4. 社内紹介

### ユースケース

既存ユーザーが友人・同僚を紹介すると、紹介元にクレジットが付与される。

### フロー

```
1. 既存ユーザーが紹介リンクを生成
   GET /api/me/referral-link
   → https://app.example.com/signup?invite=user-xxx

2. 友人がリンク経由でサインアップ

3. billing: 紹介元に 1000 円クレジット付与
```

これはパートナーリファラの簡易版で、`partners` テーブルの代わりにユーザー自身が紹介元になるだけです。

## 統一的な設計

4 つの経路は billing の中で以下のように統合されます。

### 共通の「プラン付与」インターフェース

```go
type PlanActivation struct {
    OrgID       string
    Sub         string
    Plan        string
    Source      ActivationSource  // direct | license_key | referral | promo | invite
    SourceRef   string            // キーID、パートナーID、プロモコード、紹介元sub
    BenefitType string            // full_price | free_trial | discount
    BenefitDays int               // 無料期間の日数（該当する場合）
}

func (s *BillingService) ActivatePlan(ctx context.Context, req PlanActivation) error {
    // 1. ソースの検証（キー有効？パートナー有効？プロモ有効？）
    // 2. プラン付与
    // 3. ソースの消費（キー使用済み、プロモ回数減算）
    // 4. 成果報酬の記録（該当する場合）
    // 5. イベント発行
}
```

すべての経路が `ActivatePlan` に収束します。

### billing API まとめ

| エンドポイント | 用途 |
|-------------|------|
| `POST /api/orgs/:id/licenses/keys` | シリアルキー一括発行 |
| `GET /api/orgs/:id/licenses/keys` | キー一覧 |
| `GET /api/licenses/keys/:key/validate` | キー検証 |
| `POST /api/licenses/keys/:key/redeem` | キー消費 |
| `POST /api/licenses/keys/:key/revoke` | キー無効化 |
| `POST /api/orgs/:id/activate` | リファラ付きプラン付与 |
| `GET /api/partners/:id` | パートナー情報 |
| `GET /api/partners/:id/referrals` | パートナー成果一覧 |
| `POST /api/promo/validate` | プロモコード検証 |
| `POST /api/promo/redeem` | プロモコード使用 |
| `GET /api/me/referral-link` | 紹介リンク取得 |

### イベント

| イベント | 発行タイミング |
|---------|-------------|
| `LicenseKeyRedeemed` | シリアルキーが使用された |
| `ReferralConverted` | パートナー経由でコンバージョン |
| `PromoCodeRedeemed` | プロモコードが使用された |
| `InviteConverted` | 社内紹介でコンバージョン |

## 不正防止

| リスク | 対策 |
|-------|------|
| シリアルキーの横流し | 1 キー 1 回限り、組織紐付け |
| リファラの偽装 | HMAC 署名付きリンク |
| プロモコードの乱用 | 使用回数制限、メールドメイン制限、期限 |
| 自己紹介（自分で紹介して報酬を得る） | 紹介元と紹介先のメールドメイン・IP 比較 |
| 同一ユーザーの複数利用 | 1 メールアドレス 1 回限り |
| 期限切れキー/コードの使用 | `expires_at` / `valid_until` で検証 |

## 認可との連携

ライセンスの種類やプロモの内容によって使える機能を変える場合、billing → authz の context で制御します。

```cedar
// enterprise ライセンスなら全機能
permit(
  principal,
  action,
  resource
) when {
  context.license_type == "enterprise"
};

// トライアル中はエクスポート不可
forbid(
  principal,
  action == App::Action::"export",
  resource
) when {
  context.is_trial == true
};

// プロモで付与された pro は一部機能制限
forbid(
  principal,
  action == App::Action::"api_access",
  resource
) when {
  context.plan == "pro" &&
  context.activation_source == "promo"
};
```

## auth 側の変更

サインアップフローにライセンスキー / プロモコードの検証を挟むだけ。auth 自体はプラン管理のロジックを持ちません。

```go
func (c *Client) SignUp(ctx context.Context, req SignUpRequest) (*SignUpOutput, error) {
    // ライセンスキーまたはプロモコードがあれば billing に検証
    if req.LicenseKey != "" {
        if err := c.billing.ValidateKey(ctx, req.LicenseKey); err != nil {
            return nil, fmt.Errorf("invalid license key: %w", err)
        }
    }
    if req.PromoCode != "" {
        if err := c.billing.ValidatePromo(ctx, req.PromoCode); err != nil {
            return nil, fmt.Errorf("invalid promo code: %w", err)
        }
    }

// ユーザー作成
    result, err := c.createCognitoUser(ctx, req.Email, req.Password)
    if err != nil {
        return nil, err
    }

// キー/プロモの消費は billing に委譲（アプリ側で ActivatePlan を呼ぶ）
    return result, nil
}
```

## まとめ

- シリアルキー、リファラ、プロモコード、招待リンクは billing の**「プラン付与経路」として統一的に管理**する
- すべての経路が `ActivatePlan` に収束する設計にすることで、新しい経路の追加が容易
- auth はキー/コードの検証を billing に問い合わせるだけ。プラン管理のロジックは持たない
- 不正防止は経路ごとに異なるので、個別の対策を設計しておく
- 認可（authz）との連携で、経路やライセンス種別に応じた機能制限も表現可能