外部システム連携ガイド¶

外部WEBアプリ等がサブスクライトのAPIを利用して、課金・サブスクリプション管理システムを構築する方法について説明します。

外部システム連携とは¶

サブスクライトの外部連携APIを使用することで、お持ちのWEBアプリやサービスに以下の機能を追加できます。

アプリのユーザーをサブスクライトに登録
PaymentLinkを使った安全なクレジットカード決済
ユーザーの契約状況に応じた有料機能の制御
サブスクリプションの解約・退会処理
アクティブ契約者の一括取得

カード情報はサブスクライト（Stripe）側で処理されるため、アプリ側でカード情報を扱う必要はありません。

連携フロー¶

以下のシーケンス図は、外部アプリとサブスクライト間の連携の全体像を示しています。

uml diagram

事前準備¶

外部連携を始める前に、以下の準備が必要です。

1. テナント設定の完了¶

テナント登録についてに従い、テナント設定を完了してください。

2. 商品設定の登録¶

商品を登録するに従い、販売する商品を設定してください。

成功画面URL: 商品設定で成功画面URLを設定すると、PaymentLink決済完了後にそのURLにリダイレクトされます。外部アプリの画面に戻したい場合に設定してください。
未設定の場合は、サブスクライトの標準完了画面が表示されます。

3. APIトークンの発行¶

API連携機能に従い、APIトークンを発行してください。このトークンを外部アプリに設定します。

認証方式¶

すべてのAPIリクエストには、HTTPヘッダーにBearerトークンを含める必要があります。

Authorization: Bearer {あなたのAPIトークン}

トークンはサブスクライト管理画面の「API設定」から発行できます。

APIトークンの取り扱い

APIトークンはパスワードと同様に安全に管理してください。ソースコードに直接記載せず、環境変数等で管理することを推奨します。

APIリファレンス¶

ベースURL¶

https://main.subsclite.com/api/v1/external

エンドポイント一覧¶

メソッド	エンドポイント	用途
POST	`/v1/external/users`	ユーザー登録
PUT	`/v1/external/users`	ユーザー情報更新
GET	`/v1/external/customer-status`	契約状況確認
POST	`/v1/external/subscriptions/cancel`	商品解約（1商品）
POST	`/v1/external/users/withdraw`	ユーザー退会（全商品解約）
GET	`/v1/external/active-subscribers`	アクティブ契約者一覧取得

POST /v1/external/users — ユーザー登録¶

外部アプリのユーザーをサブスクライトに登録します。Stripe Customerも自動作成されます。

リクエストパラメータ¶

パラメータ	必須	型	説明
email	必須	string	メールアドレス（テナント内で一意）
name	必須	string	氏名（最大255文字）
name_kana	任意	string	フリガナ（最大255文字）
userid	任意	string	ログインID（未指定時はメールアドレスから自動生成）
send_welcome_email	任意	boolean	ウェルカムメールの送信（デフォルト: false）

レスポンス例（成功: 201）¶

{
  "success": true,
  "message": "User created successfully",
  "user_id": 123,
  "email": "user@example.com",
  "login_id": "user_at_example_com",
  "customer_id": "123456789",
  "stripe_customer_id": "cus_xxxxxxxxxxxxx"
}

レスポンス例（再登録: 200）¶

退会済みユーザーが同じメールアドレスで再登録された場合:

{
  "success": true,
  "message": "User reactivated successfully",
  "user_id": 123,
  "email": "user@example.com",
  "login_id": "user_at_example_com",
  "customer_id": "123456789",
  "reactivated": true
}

エラーレスポンス¶

HTTPコード	原因
422	バリデーションエラー（メール形式不正等）
409	同じメールアドレスのアクティブユーザーが既に存在
500	Stripe Customer作成失敗、サーバーエラー

PUT /v1/external/users — ユーザー情報更新¶

登録済みユーザーの情報を更新します。Stripe Customer情報も自動同期されます。

リクエストパラメータ¶

ユーザー検索用（いずれか1つ以上必須）:

パラメータ	型	説明
email	string	現在のメールアドレスで検索
customer_id	integer	顧客番号で検索
userid	string	ログインIDで検索

更新内容（いずれか1つ以上必須）:

パラメータ	型	説明
new_email	string	新しいメールアドレス（テナント内で一意）
name	string	新しい氏名
name_kana	string	新しいフリガナ

レスポンス例（成功: 200）¶

{
  "success": true,
  "message": "User updated successfully",
  "user": {
    "id": 123,
    "email": "newemail@example.com",
    "name": "新しい名前",
    "name_kana": "アタラシイ ナマエ",
    "customer_id": "123456789",
    "login_id": "user_at_example_com",
    "stripe_customer_id": "cus_xxxxxxxxxxxxx"
  }
}

エラーレスポンス¶

HTTPコード	原因
422	バリデーションエラー、検索キー未指定、更新項目未指定
404	指定した条件のユーザーが見つからない
422	退会済みユーザーは更新不可
422	新しいメールアドレスが既に使用されている

GET /v1/external/customer-status — 契約状況確認¶

ユーザーの現在の契約状況を確認します。有料機能のアクセス制御に使用します。

リクエストパラメータ（クエリパラメータ、いずれか1つ以上必須）¶

パラメータ	型	説明
email	string	メールアドレスで検索
customer_id	integer	顧客番号で検索
userid	string	ログインIDで検索

リクエスト例¶

GET /api/v1/external/customer-status?email=user@example.com

レスポンス例（成功: 200）¶

{
  "success": true,
  "email": "user@example.com",
  "user_id": 123,
  "user": {
    "email": "user@example.com",
    "name": "山田太郎",
    "customer_id": 123456789,
    "created_at": "2025-01-15T10:30:00Z"
  },
  "contracts": [
    {
      "contract_id": "premium_abc123def",
      "product_name": "プレミアムプラン",
      "product_setting_id": 5,
      "status": "active",
      "contract_status": 2,
      "payment_failed": false,
      "trial_ends_at": null,
      "started_at": "2025-01-15T10:30:00Z",
      "next_billing_date": "2025-02-15",
      "stripe_subscription_id": "sub_xxxxxxxxxxxxx"
    }
  ],
  "total_active_contracts": 1,
  "has_active_subscription": true
}

契約ステータスの値¶

contract_status	status	説明
1	trialing	試用期間中
2	active	定額使用中
3	paused	休止中
7	paid	支払い済み（単発決済）
8	exempted	支払い免除

エラーレスポンス¶

HTTPコード	原因
422	検索キー未指定
404	ユーザーが見つからない

有料機能制御の実装例

has_active_subscription が true の場合に有料機能を許可し、false の場合は購入案内を表示する実装が推奨されます。特定の商品の契約を確認したい場合は contracts 配列の product_setting_id で判定してください。

POST /v1/external/subscriptions/cancel — 商品解約¶

特定の商品の契約を解約します。アカウントは維持されます。

リクエストパラメータ¶

パラメータ	必須	型	説明
email	必須	string	対象ユーザーのメールアドレス
product_setting_id	必須	integer	解約する商品の商品設定ID

レスポンス例（成功: 200）¶

{
  "success": true,
  "message": "Subscription cancelled successfully",
  "contract_id": "premium_abc123def",
  "cancelled_at": "2025-03-20T14:30:00Z"
}

エラーレスポンス¶

HTTPコード	原因
422	バリデーションエラー
404	ユーザーが見つからない、またはアクティブな契約がない

POST /v1/external/users/withdraw — ユーザー退会¶

ユーザーを退会処理します。全ての契約が解約され、アカウントが無効化されます。

リクエストパラメータ¶

パラメータ	必須	型	説明
email	必須	string	退会させるユーザーのメールアドレス

レスポンス例（成功: 200）¶

{
  "success": true,
  "message": "User withdrawn successfully",
  "user_id": 123,
  "cancelled_subscriptions": 3,
  "withdrawn_at": "2025-03-20T14:30:00Z"
}

エラーレスポンス¶

HTTPコード	原因
422	バリデーションエラー
404	ユーザーが見つからない
409	既に退会済み

解約と退会の違い

解約: 1つの商品の契約を終了します。アカウントは維持され、他の契約は影響を受けません。
退会: 全ての商品が解約され、アカウントが無効化されます。退会済みユーザーは同じメールアドレスで再登録（再有効化）が可能です。

GET /v1/external/active-subscribers — アクティブ契約者一覧取得¶

指定した商品のアクティブな契約者一覧を取得します。バッチ処理や管理画面での利用を想定しています。

リクエストパラメータ（クエリパラメータ）¶

パラメータ	必須	型	説明
product_setting_ids	必須	string	商品設定IDのカンマ区切り（例: `5,7,9`）
include_payment_failed	任意	boolean	決済失敗者を含めるか（デフォルト: false）

リクエスト例¶

GET /api/v1/external/active-subscribers?product_setting_ids=5,7&include_payment_failed=true

レスポンス例（成功: 200）¶

{
  "success": true,
  "product_setting_ids": [5, 7],
  "subscribers": [
    {
      "email": "user1@example.com",
      "name": "田中一郎",
      "customer_id": 111111111,
      "has_payment_failed": false,
      "products": [
        {
          "product_setting_id": 5,
          "product_name": "プレミアムプラン",
          "contract_status": 2,
          "payment_failed": false
        }
      ]
    },
    {
      "email": "user2@example.com",
      "name": "鈴木二郎",
      "customer_id": 222222222,
      "has_payment_failed": true,
      "products": [
        {
          "product_setting_id": 7,
          "product_name": "スタンダードプラン",
          "contract_status": 2,
          "payment_failed": true
        }
      ]
    }
  ],
  "total_count": 2
}

エラーレスポンス¶

HTTPコード	原因
422	product_setting_ids未指定、形式不正
404	指定した商品設定IDがテナントに存在しない

PaymentLinkによる購入フロー¶

外部アプリから利用者をサブスクライトの購入ページに誘導する際は、PaymentLinkを使用します。

PaymentLink URLの構成¶

https://main.subsclite.com/{URLパラメータ}/payment_link?product={商品名}&email={メールアドレス}

パラメータ	説明
URLパラメータ	テナント設定で指定したURLパラメータ
product	商品設定の商品名（URLエンコード必要）
email	利用者のメールアドレス（事前入力される）

メールアドレスの事前入力¶

emailパラメータを指定すると、購入ページのメールアドレス欄が事前入力された状態で表示されます。ユーザー登録API（POST /v1/external/users）で登録したメールアドレスを指定してください。

購入完了後のリダイレクト¶

商品設定で成功画面URLを設定している場合、購入完了後にそのURLにリダイレクトされます。これにより、利用者を外部アプリの画面に戻すことができます。

成功画面URLが設定されている場合: 指定したURLにリダイレクト
成功画面URLが未設定の場合: サブスクライトの標準完了画面を表示

実装の流れ¶

Step 1: 事前準備¶

サブスクライト管理画面でテナント設定・商品設定を完了
商品設定の成功画面URLに外部アプリのURLを設定
API設定画面でAPIトークンを発行
発行したトークンを外部アプリの環境変数等に設定

Step 2: ユーザー登録の実装¶

外部アプリでユーザーが登録された際に、POST /v1/external/users でサブスクライトにもユーザーを作成します。レスポンスの customer_id を外部アプリ側で保存しておくと、以降の操作に便利です。

Step 3: 購入フローの実装¶

有料版の購入ボタンから、PaymentLink URLにリダイレクトします。email パラメータに利用者のメールアドレスを含めてください。

Step 4: 有料機能の制御¶

有料機能を使用する際に GET /v1/external/customer-status で契約状況を確認し、has_active_subscription の値に基づいて機能の許可/不許可を制御します。

Step 5: 解約・退会の実装¶

解約・退会の操作は、それぞれのAPIエンドポイントを呼び出して処理します。

補足事項¶

決済について¶

定額決済の課金はStripeが自動的に実行します。外部アプリ側で決済処理を行う必要はありません。
利用者には領収書メールがStripeから自動送信されます。

複数商品の契約¶

1人のユーザーが複数の商品を契約することが可能です。
追加購入の際も同様にPaymentLinkにリダイレクトしてください。

退会済みユーザーの再登録¶

退会済みユーザーが同じメールアドレスで POST /v1/external/users を呼び出した場合、アカウントが再有効化されます。