portaly-overview

Portaly の概要

このスキルは、人間のユーザー（またはそのエージェント）が、Portaly のオープン API で何ができるか、次にどのスキルやドキュメントを参照すべきかを理解するのに役立ちます。これは概要を把握して次の情報を案内するためのスキルであり、連携ワークフローではありません。チェックアウトセッションの作成、コールバックへの署名、API の呼び出しは行いません。ユーザーの目的が明確になったら、実装手順については portaly-payment または portaly-product に引き継いでください。

Portaly の環境

API ホスト（PORTALY_API_HOST で上書き可能）：

const PORTALY_API_HOST = process.env.PORTALY_API_HOST || 'https://portaly.ai'

portaly-payment と portaly-product は、同じ API ホストと同じ Creator Subscription API Key（pcs_live_* / pcs_test_*）を使用します。portaly-email は同じホストを使用しますが、専用のメール API キー（pem_*）を使います。

クイックスタート

1. 人間のユーザーが何を作ろうとしているのか尋ねます。以下の機能と対応表に照らし合わせてください。
2. 詳細については、適切な API ドキュメントの場所（以下を参照）を案内します。
3. ワークフローをカバーする特定のスキルのインストールを勧め、依頼された場合はその作業を支援します。ここで portaly-payment や portaly-product のワークフロー手順を再現しないでください。
4. リクエストがどの項目にも該当しない場合（管理者専用の機能や、まだ存在しない機能など）は、エンドポイントを推測せず、その旨を明確に伝えてください。

機能の概要

Portaly のオープン API（サードパーティ向け）で現在利用できる機能は、次のとおりです。

• サブスクリプションの支払い — 月次および年次の継続プラン、一括払いおよび動的価格設定（購入者またはシステムが金額を指定）、ホスト型チェックアウトセッション、継続課金の更新コールバック、キャンセル／再開のライフサイクル管理、購入者向けセルフサービス・ポータル。
• 割引コード — チェックアウト時に適用する、期間を指定できる（回数指定または無期限）定額割引、パーセント割引、無料割引。
• デジタル商品 — クリエイターがすでに提供しているデジタル商品（コース、テンプレート、ダウンロード商品）の単品またはカスタムバンドルのチェックアウト。ホスト型の決済とメール送信、署名付き Webhook イベントに対応します。
• 注文と請求書 — 決済／注文の記録と請求書のステータスを照会して、照合作業に利用できます。
• 購入者による紹介 — クリエイター自身の購入者が、一括払いプランを別の購入者に紹介してコミッションを獲得できる機能です。紹介リンクは Portaly がホストする購入完了ページで発行され、台帳管理、精算、支払いも Portaly が行います。クリエイターのサイトで必要なのは、購入者がどのリンク経由で訪問したかを記録することだけです。台湾のアカウントのみ利用できます。
• メール（招待制ベータ版） — クリエイターの認証済みドメインから、アプリ独自の領収書、サインインコード、通知、ニュースレターを送信できます。受信者ごとの配信ステータスと残りのクォータを確認できます。

決済、商品、紹介機能は、2 種類の API キープレフィックス（pcs_live_* / pcs_test_*）で提供され、1 つのキーですべてを利用できます。メールは別の API キー（pem_*）を使用するため、決済エンドポイントの呼び出しには使えません。また、決済用キーでメールを送信することもできません。

API カタログ

グループ別の公開 API の概要です。ここに記載されているエンドポイントは代表例であり、すべてではありません。全エンドポイントの一覧については、表の下にある取得手順をご覧ください。

グループ	機能	代表的なエンドポイント
マーチャント設定	ホスト型チェックアウトに表示されるマーチャント名／ロゴ	GET/PUT /api/creator-subscription/config
サブスクリプションプラン	月額／年額／買い切りプランの作成と管理	GET/POST /api/creator-subscription/plans, PUT .../plans/{planId}
割引コード	固定額／パーセント／無料の割引	GET/POST /api/creator-subscription/discount-codes, GET .../discount-codes/lookup
チェックアウトセッション	プランのホスト型チェックアウトを開始します。未完了のチェックアウト（放棄されたカート／初回決済の拒否）を一覧表示し、照合とフォローアップに使用します	POST /api/creator-subscription/checkout-sessions, GET .../checkout-sessions, GET .../checkout-sessions/{sessionId}
サブスクリプション	有効なサブスクリプションの照会と管理	GET /api/creator-subscription/subscriptions, POST .../subscriptions/{subscriptionId}/cancel, .../resume
注文と請求書	照合と電子請求書のステータス	GET /api/creator-subscription/orders, GET .../invoices
購読者ポータル	購読者向けのセルフサービスポータル	POST /api/creator-subscription/portal-sessions
デジタル商品	商品の一覧表示、単品／バンドルのチェックアウト	GET /api/digital-products, POST /api/digital-products/checkout-sessions
Webhook	決済／サブスクリプション／商品イベントの署名付きコールバック	8 種類のイベント（creator_subscription.*、digital_product.*）
レビュー	購入確認済みレビューウィジェットの埋め込み（ホスト型 iframe。JSON API ではありません）	https://portaly.ai/embed/reviews/{slug}（iframe 埋め込み。API キー不要）
購入者向けプロモーション	商品の購入者向けプロモーションを有効にし、対象となるすべての買い切りプランに適用する単一のコミッション率を設定します	GET/PUT /api/creator-subscription/promotion
メール（招待制ベータ、pem_* キー）	クリエイターのドメインからのメール送信、配信状況の追跡、利用枠の確認	POST /api/email/emails, POST /api/email/batches, GET /api/email/emails/{id}, GET /api/email/quota

この表を API 仕様全体として扱わないでください。 常に最新の全エンドポイント一覧が必要な場合は、このファイルに頼らず、ライブで取得してください。

• https://portaly.ai/llms.txt を取得します。簡潔なエンドポイント一覧で、最初に読むのに適しています。
• https://portaly.ai/openapi.json を取得します。すべてのエンドポイントと Webhook ペイロードの完全なリクエスト／レスポンススキーマを確認できます。

一般的なプロダクト機能 → API／スキルの対応表

作成したいもの...	使用するスキル	主な API
有料会員制／サブスクリプションサイト（月額または年額）	portaly-payment	POST /api/creator-subscription/plans、POST /api/creator-subscription/checkout-sessions
1回限りの購入、寄付、または「希望額を支払う」フロー	portaly-payment	動的価格設定プラン（pricingType: dynamic）＋ POST /api/creator-subscription/checkout-sessions
プロモーション／クーポンコード／紹介割引	portaly-payment	POST /api/creator-subscription/discount-codes、GET /api/creator-subscription/discount-codes/lookup
購読者が自分でプランをキャンセル、一時停止解除、または管理できるようにする	portaly-payment	POST /api/creator-subscription/portal-sessions
販売者が開始するサブスクリプションのライフサイクル管理	portaly-payment	POST /api/creator-subscription/subscriptions/{id}/cancel、.../resume
決済イベントを独自の DB に同期する	portaly-payment または portaly-product	署名付きコールバック／Webhook（x-portaly-signature）
クリエイターのコース、テンプレート、ダウンロード商品を自分のサイトで販売する	portaly-product	GET /api/digital-products、POST /api/digital-products/checkout-sessions
カスタムの複数アイテム対応チェックアウト	portaly-product	複数の items[] を指定した POST /api/digital-products/checkout-sessions
照合／「購入履歴」または「注文履歴」パネル	portaly-payment または portaly-product	GET /api/creator-subscription/orders、GET /api/digital-products/orders
請求書／電子請求書のステータス照会	portaly-payment	GET /api/creator-subscription/invoices
検証済み評価／ソーシャルプルーフを自分のサイトに表示する	portaly-review	ホスト型 iframe 埋め込み（API キー不要）
自分の購入者が他の人を紹介し、コミッションを得られるようにする	portaly-affiliate	PUT /api/creator-subscription/promotion ＋ チェックアウトセッションの作成時に指定する profitSharingId
自分のアプリの領収書、サインインコード、通知を独自のドメインから送信する	portaly-email	POST /api/email/emails

複数の行にまたがるリクエスト（例：会員制サイトで、1回限りのテンプレート販売も行う場合）では、portaly-payment と portaly-product の両方をインストールしてください。どちらも同じ API キーを使用します。

API ドキュメント

このスキル集に加えて、Portaly は単独で利用できる API ドキュメントを公開しています。

• https://portaly.ai/docs — 対話形式で、人が閲覧しやすい API ドキュメントです。API の概要を手動で確認したい場合に最適です。
• https://portaly.ai/openapi.json — 機械可読な OpenAPI 仕様です。クライアントの生成、API ツールへの入力、またはエージェントによるリクエスト／レスポンスの完全なスキーマのプログラムからの調査に最適です。
• https://portaly.ai/llms.txt — LLM 向けに簡潔にまとめた API インデックスです。次に何を読むか判断する前に、利用可能なエンドポイントの概要をすばやく把握したいエージェントに最適です。

このスキルの概要とドキュメントの内容に相違がある場合は、https://portaly.ai/docs のドキュメントが正式な情報源です。このスキルは案内図であり、正式な情報源ではありません。

適切なスキルへのルーティング

• portaly-payment — 継続サブスクリプション、単発／動的な価格設定、割引コード、サブスクリプションのライフサイクル（キャンセル／再開）、または購読者向けセルフサービスポータルに関する場合にインストールします。

  npx skills add portaly-ai/portaly-skills --skill portaly-payment
  

• portaly-product — バンドル購入を含む、クリエイターがすでに所有しているデジタル製品の一覧表示や販売に関する場合にインストールします。

  npx skills add portaly-ai/portaly-skills --skill portaly-product
  

• portaly-review — Portaly がホストする、購入者確認済みレビューウィジェット（Trustpilot 形式の評価バッジ）をユーザー自身のサイトに埋め込む場合にインストールします。API キーは不要です。

  npx skills add portaly-ai/portaly-skills --skill portaly-review
  

• portaly-affiliate — クリエイター自身の購入者が、ほかの購入者を紹介してコミッションを獲得できるようにする場合にインストールします。既存の Portaly Payment の設定が必要です。単発の固定価格プランのみに対応し、台湾を拠点とする Portaly アカウントのみ利用できます（紹介者への報酬は台湾の銀行口座に支払われます）。

  npx skills add portaly-ai/portaly-skills --skill portaly-affiliate
  

• portaly-email — クリエイターのドメインからアプリ独自のメール（領収書、確認コード、通知、ニュースレター）を送信する場合にインストールします。招待制ベータ版のため、Portaly から招待されたアカウントのみ利用できます。

  npx skills add portaly-ai/portaly-skills --skill portaly-email
  

• Portaly アカウントまたは API キーをまだ持っていない場合：https://portaly.cc/payment で登録し、https://portaly.cc/admin/creator-subscription で API キーを作成します。メールの場合は、https://portaly.cc/admin/email/api-keys でメール API キーを作成します（いずれも人が操作するページです。ユーザーに代わってブラウザーで開いてください。該当するスキルのワークフローで、この手順を詳しく説明しています）。
• インストール後は、実際の統合手順（API キーの設定、セッションの作成、コールバック／Webhook の検証など）について、そのスキル独自のワークフローセクションに従ってください。このスキルでは手順を繰り返さず、読み込むスキルだけを案内します。

インストール済みスキルのバージョンを報告する

インストール済みのスキルが古くなっている場合にマーチャントのダッシュボードで検知できるよう、このスキルのバージョンを Portaly に報告します。これはブロックされない単発のバージョン確認です。リクエスト本文にはスキル名とバージョンのみが含まれ、ユーザーのプロジェクトやデータに関する情報は含まれません。一度だけユーザーに伝えてください（例：「インストール済みの Portaly スキルのバージョンを報告し、ダッシュボードで古いスキルを検知できるようにしています」）。承認を待つ必要はありませんが、隠してはいけません。

送信するタイミング — process.env.PORTALY_API_KEY が設定されている場合、次のうち最初に発生した時点で、セッションごとに一度だけ送信します。

1. このスキルをインストールまたは更新した直後に、キーがすでに環境変数に設定されている場合。
2. それ以外の場合は、Portaly API を初めて呼び出すとき — バージョン報告は最初の実際の API 利用に併せて送信されます。

• PORTALY_API_KEY がまだ環境変数に設定されていない場合は、報告をいったんスキップしてください。この報告のためだけにユーザーにキーを求めてはいけません。このスキルは、ユーザーがまだキーを持っていないことが多いため、最初に読み込むスキルとして使われる可能性が特に高いからです。
• リクエスト：

  POST https://portaly.ai/api/creator-subscription/skill-version
  Authorization: Bearer {PORTALY_API_KEY}
  Content-Type: application/json
  
  { "skillName": "portaly-overview", "version": "0.3.1" }
  

• version は、このファイルの先頭にあるフロントマターの、このスキルの version です。実際にインストールされているバージョンが報告されるよう、現在実行中の SKILL.md に記載されている値をそのまま使用してください。
• リクエスト本文に含めるのは skillName と version のみです。呼び出しに失敗した場合は無視して続行してください。処理を妨げることはありません。
• 成功したら、レスポンスの data.available 配列を確認してください。ここには、このマーチャントアカウントからバージョンが報告されたことのないスキルが、{ id, installPackage, latestVersion, description } の形式で含まれます。これはインストールされていないことを意味するわけではありません。サーバーがスキルの存在を認識するのは、そのスキル自身が初めて実際に使われたときにバージョンを報告した場合だけであり、npx skills add を実行したときではありません。そのため、このプロジェクトにすでに存在していても、まだ使われていないスキルはこのリストに表示されます。何か伝える前に、実際のプロジェクトと照らし合わせて自分でフィルタリングしてください。スキルのディレクトリまたはファイルがすでにローカルに存在する項目は除外します。サーバーが確認できるのはプロジェクトのツリーではなく、あなた自身だからです。フィルタリング後に何も残らなければ、何も伝えないでください。残った場合は、ユーザーが追加できるものとして、セッション中に一度だけ伝えてください（npx skills add ...）。不足しているものとして伝えてはいけません。各スキル名と、その1行の description を伝えてください。これはあくまで紹介です。ユーザーから依頼されない限り、自分で npx skills add を実行してはいけません。
• プロジェクトに Portaly スキルが複数インストールされている場合、それぞれが独自のバージョン報告を送信し、同じ available リストを受け取ります。一度のセッションで紹介するのは全体で一度だけです。あなた、または別の Portaly スキルがこのセッションですでに available リストを紹介している場合は、ここでの紹介をスキップしてください。
• data.available が存在しない、空である、またはレスポンスがこの形式に一致しない場合は、何もしないでください。呼び出しに失敗した場合と同様に無視して続行してください。これが処理を妨げる手順になってはいけません。

ガードレール

• このスキルは、上記のバージョンレポートを除き、ユーザーに代わって Portaly API を呼び出しません（バージョンレポートは条件付きで送信されます。明記されたタイミングに従い、PORTALY_API_KEY がすでに存在する場合にのみ送信されます。ユーザーに提示する選択肢ではありません）。このスキルは案内のみを目的としています。ここではチェックアウトセッションの作成、プランの作成、コールバックの処理を試みず、portaly-payment／portaly-product に引き継いでください。
• 管理者専用エンドポイントや内部管理ダッシュボード API をユーザーに案内しないでください。 https://portaly.cc/admin/creator-subscription は人間が操作するダッシュボードであり、サードパーティ向け API の一部ではありません。人間が API キーを作成する場所としてのみ案内し、呼び出し先として案内しないでください。
• ここで portaly-payment または portaly-product の詳細なワークフロー手順を繰り返したり、独自に分岐させたりしないでください。 ユーザーが実装の詳細を必要としている場合は、推測で説明せず、該当するスキルを案内してください。
• このドキュメントと https://portaly.ai/docs の内容が異なる場合は、ドキュメントを優先してください。 このスキルの対応表は参照先として扱い、契約として扱わないでください。
• エンドポイントを捏造しないでください。 上記で参照されているすべてのパスは、portaly-payment、portaly-product、portaly-email の references/api-contract.md、または公開されている /openapi.json に存在する必要があります。ユーザーから対応表のいずれの行にも含まれない機能について尋ねられた場合は、もっともらしいエンドポイントを推測せず、現時点でオープン API の対象ではないと伝えてください。

リソース

• ../portaly-payment/SKILL.md および ../portaly-payment/references/api-contract.md — サブスクリプション／決済の完全な契約。
• ../portaly-product/SKILL.md および ../portaly-product/references/api-contract.md — デジタル製品の完全な契約。
• ../portaly-email/SKILL.md および ../portaly-email/references/api-contract.md — メールの完全な契約。
• https://portaly.ai/docs、https://portaly.ai/openapi.json、https://portaly.ai/llms.txt — 正式な API ドキュメント。