# PayPalサブスク × 宴（UTAGE）公式LINE 連携の構想
> **ペンディング・未実装・確定ではない。** 2026-11-05 時点の構想メモ。今は作らない。再開するときの出発点として、今あるものと決まっていないことを残す。
## 1｜見るリポジトリと今の状態
| 置き場 | 中身 | 今の状態 |
|---|---|---|
| `subscrypt-dashboard-nexus`（main、dbfccc6） | React（Vite・TypeScript・shadcn/ui）の管理画面と、`server/` 配下の PHP API | 実装あり。仕様は `src/仕様書.md` |
| `server/paypal-webhook.php` | PayPal の Webhook を受けて DB に保存 | 実装あり。CREATED は `pending_subscriptions`、ACTIVATED・PAYMENT.FAILED・EXPIRED・SUSPENDED は `subscriptions` に保存 |
| 同上（支払い記録） | PAYMENT.SALE.COMPLETED で `payments` に記録 | ファイル冒頭に「このイベントが来ないため ACTIVATED で代替」と注記あり |
| 同上（解約） | BILLING.SUBSCRIPTION.CANCELLED | 受信対象には入っているが、保存の振り分けに専用の分岐が無い（未定義イベントとして pending 側に入る作りに見える。要確認） |
| `custom_id` の読み取り | `prid=…&uid=…` から `uid` を取り出し `subscriber_line_uid` に保存（`src/仕様書.md`「LINE連携仕様」） | **保存するだけ。宴や LINE を呼ぶ処理は無い** |
| `payment_links` テーブル | 支払いリンクを自動登録 | プラン単位の固定リンク（人ごとの `custom_id` は入らない） |
| `server/api/cancel-subscription.php` | 管理画面から PayPal の解約 API を呼ぶ | 実装あり |
| `server/batch/paypal_batch.php` | PayPal API から契約情報を同期（仕様 `paypal_batch.md`、月1回推奨） | 実装あり |
| 管理画面の分析 | LTV／CPA比／コホート／ARPU・継続率／CPA・Payback | 直近コミットは「UIイメージの実装」段階 |
| 宴（UTAGE） | 公式LINE・メール配信・購入者サイト（会員サイト）を運用中 | 決済の連携先に PayPal は無い（Stripe・テレコム・UnivaPay 等） |
| 宴の API（MCP） | 友だちIDでシナリオ登録、購入者サイトへの受講生登録・解除・停止、ラベル付与 | MCP からは可能。外部サーバーから呼べるかは未確認 |
| `youtube-marketter` | 宴の運用記録。購入フローのテスト手順は `docs/planning/hakase/2026-07-23_dow-ea-leo-sign-series/review/2026-11-05_purchase-flow-test/README.md` | 参考資料 |
## 2｜ツールとサーバーの全体像
図1 全体像。実線だけが今ある処理。点線は構想
| ツール | 置き場 | 正となるデータ（ここが本物） | 役割 |
|---|---|---|---|
| PayPal | PayPal | 契約（`subscription_id`）・支払い・契約の状態 | 決済。状態が変わると Webhook で知らせる |
| ダッシュボード | さくらのレンタルサーバー（MySQL系のDB） | `uid` と契約の対応、支払い履歴、分析の数字（契約状態は PayPal の写し） | Webhook を受けて保存。宴 API を呼ぶ（構想） |
| 宴 | 宴のサービス上 | LINE友だち・読者・シナリオ・ラベル・購入者サイトの受講生 | LINE・メールの配信と会員サイト |
| LP | 未確定（宴のページか別サーバーか未確認） | 持たない（友だちIDを PayPal へ渡すだけ） | 申込みの入口 |
## 3｜データ受け渡しのワークフロー
図2 データ受け渡しのワークフロー（赤ピンで直す対象）
| 区間 | 受け渡すもの | 状態 |
|---|---|---|
| ① LINE → ② LP | URL に宴の友だちIDを付ける | 構想。差し込めるか未確認 |
| ② LP → ③ PayPalボタン | LP が URL から ID を読み、JS SDK で契約を作るときに `custom_id` へ `uid=…` を入れる | 構想。今の支払いリンクはプラン単位の固定リンク |
| ④ PayPal → ⑤ ダッシュボード | Webhook。`custom_id` の `uid` を `subscriber_line_uid` に保存 | 実装あり |
| ⑤ ダッシュボード → ⑥ 宴 | 友だちIDでシナリオ登録・ラベル付与・購入者サイト登録 | 構想。未実装 |
## 4｜イベントごとのシナリオ移行とデータ
すべて構想。「今のDB処理」の列だけがコードで確認できた内容。
| イベント（PayPal） | 今のDB処理 | ダッシュボードで足すもの | 宴で動かすもの | ユーザーに届くもの |
|---|---|---|---|---|
| 有効化（BILLING.SUBSCRIPTION.ACTIVATED） | `subscriptions` に登録。`uid` を保存 | 宴への反映の成否を残す | 購入者シナリオに登録、ラベル「購入者」、購入者サイトに受講生登録 | 購入のお礼、購入者サイトのログイン案内 |
| 支払い完了（PAYMENT.SALE.COMPLETED） | `payments` に記録（ただし届かず ACTIVATED で代替と注記） | 最終支払日の更新 | 原則なし（継続中ラベルの要否は未確定） | 原則なし |
| 支払い失敗（BILLING.SUBSCRIPTION.PAYMENT.FAILED） | 状態を FAILED にして `subscriptions` を更新 | 失敗日を残す | 支払い確認のシナリオに登録、ラベル付与。購入者サイトをすぐ止めるか猶予を置くかは未確定 | 支払い方法の確認のお願い |
| 停止（BILLING.SUBSCRIPTION.SUSPENDED） | `subscriptions` を更新 | — | 購入者シナリオを解除、購入者サイトの受講を停止 | 停止のお知らせ |
| 期限切れ（BILLING.SUBSCRIPTION.EXPIRED） | `subscriptions` を更新 | — | シナリオ解除、ラベルの付け替え、受講生の登録解除 | 終了のお知らせ |
| 解約（BILLING.SUBSCRIPTION.CANCELLED） | 専用の分岐なし（要確認） | 解約として保存する分岐 | 期限切れと同じ扱いにするか未確定 | 解約受付のお知らせ |
## 5｜決まっていないこと・確かめること
| # | 確かめること | なぜ要るか | 状態 |
|---|---|---|---|
| ① | 宴の LINE の URL に友だちIDを差し込めるか。差し込めるのは生の LINE UID か、宴の友だちIDか | ここで ID が渡らないと、決済した人と LINE の友だちを結べない | 未確認 |
| ② | 宴の API を外部サーバー（ダッシュボード）から呼べるか。キーの発行・契約プラン | 今確認できているのは MCP 経由の操作だけ | 未確認 |
| ③ | `uid` に入れる値を宴の友だちIDにそろえる | 宴の API は友だちIDでシナリオ登録する | 構想 |
| ④ | PayPal の固定リンクでは人ごとの `custom_id` が入らない | 今の `payment_links` はプラン単位。LP で JS SDK を使い1人ずつ契約を作る必要がある | 構想（コードで固定リンクを確認） |
| ⑤ | 顧客の情報の分担: 支払い状態＝ダッシュボード、配信・会員＝宴、つなぐ鍵＝宴の友だちID、予備＝メールアドレス | 2か所に同じ人がいるので、どちらを正にするか決めておく | 構想 |
| ⑥ | 購入者サイトの受講生IDは LINE 友だちIDと別。受講生を作るのにメールアドレス等が要るか | 友だちIDだけで購入者サイト登録まで進めるかが変わる | 未確認 |
| ⑦ | 停止は「受講の停止日を入れる」か「登録を消す」か | 宴の登録解除は消すと戻せない（MCP の説明より） | 未確定 |
| ⑧ | PAYMENT.SALE.COMPLETED が届かない件と、CANCELLED の扱い | 支払い完了・解約で宴を動かすなら前提になる | 未確認 |
| ⑨ | LP をどこに置くか（宴のページか別サーバーか） | JS SDK のボタンを置けるかが置き場で変わる | 未確認 |
## 6｜連携したらできること・楽になること
すべて構想。前提の番号は5章の表（①〜⑨）を指す。
### 6-1 中心になる3つ
| # | できること・楽になること | 前提条件 | 状態 |
|---|---|---|---|
| A | 公式LINEの友だちと決済情報がひもづき、誰が購入したかを自動で管理できる | LP から PayPal の `custom_id` の `uid` に宴の友だちIDを入れられること（①③④） | 構想。`uid` を保存する処理は実装あり、IDの受け渡しは未確認 |
| B | 決済の手動確認と、LINEシナリオの手動移動がなくなる | PayPal で払った分だけ。銀行振込は今後も入金確認が手作業。宴の API を外部から呼べること（②） | 構想 |
| C | 顧客の決済状況がダッシュボードで分かり、決済に失敗した人への連絡・追いかけがしやすくなる。仕組みは 6-4 | 宴の API を外部サーバーから呼べること（②）。`uid` が宴の友だちIDであること（③）。失敗（PAYMENT.FAILED）は今も DB に保存される作り | 構想（前提が確認できれば可能）。状態の保存は実装あり |
### 6-2 宴の運用者が楽になること（候補）
| できること・楽になること | 前提条件 | 状態 |
|---|---|---|
| 解約・支払い失敗・停止に合わせて、購入者サイトの受講停止／再開が自動になる。解約後も見られてしまう漏れを防げる見込み | 受講生IDと友だちIDが別（⑥）。止め方（停止日か登録解除か）が未確定（⑦）。解約の保存分岐が今は無い（⑧） | 構想 |
| 支払いに失敗した人にだけ、LINE で支払い方法の更新のお願いを自動で送れる。仕組みは 6-4 | 宴の API を外部サーバーから呼べること（②）。`uid` が宴の友だちIDであること（③）。すぐ止めるか猶予を置くかは未確定 | 構想（前提が確認できれば可能） |
| ラベルで「継続中／失敗中／解約済み」に分けて配信できる（解約者への再案内、継続者への特典など） | 宴の API でラベルを付けられること（②）。解約の扱い（⑧） | 構想 |
| 問い合わせのとき、その人の決済状況と LINE 側の状況を1か所で確かめられる | ダッシュボードに宴への反映結果を残す作りを足すこと（4章） | 構想 |
### 6-3 管理者が楽になること（候補）
| できること・楽になること | 前提条件 | 状態 |
|---|---|---|
| スプレッドシートや管理画面どうしの照合（二重管理）が減る | 支払い状態の正をダッシュボードに決めること（⑤）。銀行振込など PayPal 以外の決済は対象外 | 構想 |
| LTV・継続率・コホート・CPA回収（Payback）を、決済データから出せる | 分析画面は「UIイメージ」段階。CPA（獲得単価）は月ごとに手で入れる作り。支払い完了イベントが届かない件（⑧） | 構想。画面は開発中（8章） |
| 解約・返金の処理漏れや、手作業のミス（別人への操作）が減る見込み | 返金イベントは今の Webhook の受信対象に無い。解約の保存分岐も無い（⑧） | 構想 |
### 6-4 LINE の自動送信はどう動くか（支払い失敗の例）
PayPal の Webhook（支払い失敗）→ ダッシュボード → 宴の API で、その友だちを「決済失敗」用のシナリオに登録（またはラベル付与）→ 宴のシナリオが LINE を送る。
- LINE 公式アカウント側の Webhook（LINE → 宴）は宴が持っているので、触らない・作らない
- 前提は「宴の API を外部サーバーから呼べる」「`uid` が宴の友だちID」の2つ。状態は構想（前提が確認できれば可能）
- 支払い方法の更新は、本人が PayPal のアカウント側で行う。LINE で送るのはそのお願い
- PayPal 自体も、失敗時に自動で再請求し、本人へメールで知らせる。LINE の案内はそれに上乗せする位置づけ
## 7｜デメリット・保守で必要なこと
「確度」は、構想上かならず要るものを「想定」、数字や中身を確かめていないものを「要確認」とした。
| 区分 | 内容 | 確度 |
|---|---|---|
| 構築工数 | ダッシュボード → 宴 API の連携、LP の PayPal ボタン（1人ずつ `custom_id`）、友だちIDの受け渡し、PayPal のサンドボックスでのテスト | 想定 |
| 保守工数 | Webhook が届いているかの確認（監視・通知）、届かなかった時の再送・手動での補正 | 想定 |
| 保守工数 | PayPal・宴の仕様変更への追従、API キー・トークンの管理（期限・漏えい対策）、サーバー（さくら）・PHP・SSL の更新 | 想定 |
| 止まった時の影響 | 連携が止まると、購入者に LINE や購入者サイトの案内が届かない。監視が必須 | 想定 |
| データの食い違い | PayPal・ダッシュボード・宴で状態がずれた時に、どれを正とするかのルールが要る（5章⑤） | 想定 |
| 上限 | 宴 API の利用回数に上限（時間あたり・月間）がある | 要確認（具体的な回数は未確認） |
## 8｜ダッシュボードの画面（UIイメージ・開発中）
**画面はUIイメージ（開発中）。** 数値と名前はすべて架空のダミーデータ（サンプル会員・example.com）。本番データ・本番サーバーにはつないでいない。手元で開発用の画面を起動し、データ取得の部分だけダミー応答に差し替えて撮った。
