A Activatist API 日本人開発者向けガイド

Invite-only closed beta / Stripe test mode

ソフトウェアのライセンス販売とアクティベーションを、まず1本のAPIから。

Activatist は、開発者が自分のソフトウェアのライセンスキーを販売し、購入後にアプリ内で検証・有効化できるようにするAPIです。このページはプログラム初学者でも実装できるように、用語、流れ、主要言語のコード例を日本語でまとめています。

最短で試す アクティベーションを理解する 
POST /v1/licenses/activate
Content-Type: application/json

{
  "product_id": "prod_123",
  "license_key": "LIC1-XXXX-XXXX-XXXX",
  "device_fingerprint": "device-abc"
}
現在の前提: 招待制 closed beta です。Stripe は test mode、live 決済と一般公開は別レビューが必要です。ギフトカード、ポイント、第三者キー転売、C2C resale には使えません。

Concepts

まず押さえる4つの言葉

Product

販売するソフトウェア本体です。例: デスクトップアプリ、プラグイン、開発ツール。1つの Product に価格、説明、サポート先、アクティベーション上限が紐づきます。

License Key

購入後に発行されるキーです。ユーザーがアプリに入力し、アプリが Activatist API に送って検証します。ログに出してはいけません。

Activation

「この端末で使い始める」操作です。同じ端末の再アクティベーションは冪等で、別端末は activation_limit を超えると拒否されます。

Device Fingerprint

端末を見分けるためのアプリ側IDです。メールアドレスや氏名などの個人情報を入れず、安定したランダムIDを使います。

Quickstart

最短の実装手順

  1. 購入後にライセンスキーを受け取るユーザーは購入完了ページでライセンスキーを確認します。メールにはキーではなく完了リンクだけが届きます。
  2. アプリにライセンス入力欄を作るユーザーが `LIC1-...` のようなキーを入力します。
  3. 端末IDを用意する初回起動時にランダムIDを生成し、アプリ設定に保存します。個人情報は使いません。
  4. `/v1/licenses/activate` を呼ぶ成功したらアプリを有料機能ONにします。失敗時はエラー内容をユーザーに表示します。
  5. 起動時は `validate` を使う毎回 activate せず、起動時チェックは validate が基本です。

Activation Deep Dive

アクティベーションを重点的に理解する

アクティベーションは「ライセンスキーが正しいか」だけでなく、「この端末を利用枠として登録できるか」も確認します。

1ユーザーがキー入力

アプリの設定画面や初回起動画面で受け取ります。

2端末IDを作る

個人情報を含まない安定IDをローカル保存します。

3activateを呼ぶ

product_id、license_key、device_fingerprint を送ります。

4結果を保存

valid=true なら有料機能を有効にします。

成功するケース

  • ライセンスが active
  • Product が一致している
  • 同じ端末で再実行した
  • 別端末でも activation_limit 内

失敗するケース

  • キーが存在しない、または別Product用
  • refund / dispute / revoked / suspended / expired
  • 別端末が上限を超えた
  • device_fingerprint が空、または不安定

Runtime Endpoints

アプリに組み込む3つのAPI

POST/v1/licenses/validate

起動時や定期チェックで使います。activation_count は増えません。

POST/v1/licenses/activate

初回認証や端末登録で使います。activation_limit を超えた別端末は `409 conflict` になります。

POST/v1/licenses/deactivate

端末の解除で使います。ポリシー上許可されている場合、利用枠を空けます。

Code Samples

主要言語のアクティベーション実装例

下のタブで言語を切り替えられます。どの例も `product_id`、`license_key`、`device_fingerprint` を送るだけの最小構成です。

JavaScript

ブラウザやElectronで使いやすい fetch の例です。

Errors

エラー時の考え方

HTTP意味アプリ側の表示例
400入力が不足、形式が不正入力内容を確認してください。
403キーが使えない状態このライセンスは利用できません。
404対象が見つからないライセンス情報が見つかりません。
409アクティベーション上限超過利用可能な端末数の上限に達しました。
429短時間にリクエストが多すぎる少し待ってから再試行してください。

API Map

API一覧

購入・利用者向け

  • GET /v1/public/products/{slug}
  • POST /v1/public/products/{slug}/checkout
  • POST /v1/purchases/complete
  • POST /v1/purchases/files/{file_id}/download-intent
  • POST /v1/licenses/validate
  • POST /v1/licenses/activate
  • POST /v1/licenses/deactivate

販売者向け

  • POST /v1/sellers
  • POST /v1/sellers/stripe/account-link
  • POST /v1/products
  • POST /v1/products/{product_id}/submit-review
  • POST /v1/products/{product_id}/files/upload-intent
  • POST /v1/products/{product_id}/files/{file_id}/finalize

管理・運用向け

  • GET /v1/admin/sellers
  • PATCH /v1/admin/products/{product_id}/review
  • GET /v1/admin/product-files
  • PATCH /v1/admin/products/{product_id}/files/{file_id}/review
  • POST /v1/stripe/webhook
  • GET /readyz

Safety Rules

実装時にやってはいけないこと

ログに出さない

ライセンスキー、completion token、buyer email、Firebase token、Bearer token、Stripe/Resend/R2/Cloudflare の秘密情報、presigned URL はログや共有メモに出さないでください。

端末IDに個人情報を使わない

device_fingerprint にメールアドレス、氏名、電話番号、住所などを入れないでください。ランダムIDを作って端末内に保存する方式が扱いやすいです。

毎回 activate しない

起動時チェックは validate、端末登録は activate、端末解除は deactivate と役割を分けると、ユーザー体験とサーバー負荷が安定します。

対象外の商品に使わない

Activatist は first-party software license 用です。ギフトカード、ポイント、第三者キー転売、C2C resale には使えません。