開発者は、すべてをゼロから構築することなく、課金とサブスクリプションを処理するための堅牢なソリューションをしばしば求めます。Paddle APIは、この分野で強力なツールとして登場し、支払い処理、顧客管理、収益運用をソフトウェアにシームレスに統合することを可能にします。
まず、基本を理解する必要があります。Paddle APIは、アプリケーションをPaddleの課金システムに接続するRESTfulインターフェースとして機能します。製品の作成、サブスクリプションの管理、取引の処理などの操作をサポートしています。さらに、本番稼働前に安全なテストを行うためのサンドボックス環境も提供しています。この記事を読み進めるにつれて、セットアップ、認証、および高度な使用法についての洞察が得られるでしょう。
Paddle APIとは何か、そしてなぜそれを使うべきなのか？
Paddle APIは、SaaSビジネスのグローバルな支払い、税金、コンプライアンスを処理するレコードマーチャントプラットフォームであるPaddleのバックエンドインターフェースを表します。従来の決済ゲートウェイとは異なり、Paddle APIは販売者としての責任を負い、これにより業務を簡素化し、法的負担を軽減します。
StripeやChargebeeのような競合他社とPaddle APIを分けるものは何か、と疑問に思うかもしれません。Paddleは、組み込みのサブスクリプション管理、自動請求書発行、詐欺防止など、SaaS固有の機能に焦点を当てています。例えば、200以上の国でVATや消費税の計算を自動的に管理するため、開発者はコア製品機能に集中できます。
さらに、Paddle APIはWebアプリケーション、モバイルアプリ、およびバックエンドサービスと簡単に統合できます。リクエストには標準のHTTPメソッド（GET、POST、PATCH、DELETE）を使用し、主要なデータ形式としてJSONを採用しています。この互換性により、大規模な手直しなしにNode.js、Laravel、またはNext.jsのようなフレームワークに組み込むことができます。
真の価値は、そのスケーラビリティにあります。ビジネスが成長するにつれて、Paddle APIは増加するトランザクション量を効率的に処理します。Paddleのドキュメントの統計によると、数千のベンダーに対して年間数十億ドルの収益を処理しています。したがって、Paddle APIを採用することで、あなたのアプリケーションは収益化において長期的な成功を収めることができます。
Paddle APIアクセスを開始する方法
Paddle APIにアクセスするには、まずPaddleダッシュボードでアカウントを作成することから始めます。無料アカウントにサインアップしてください。登録後、Paddleは認証用のAPIキーを提供します。
次に、サンドボックス環境と本番環境を区別します。サンドボックスモードでは、実際の課金なしでAPIコールをテストできます。ライブ取引の準備ができたら本番環境に切り替えます。Paddleは、高価なエラーを避けるためにサンドボックスから開始することを推奨しています。
さらに、より簡単に統合するためにSDKをインストールします。PaddleはPHP、Python、Node.js、Rubyなどの言語向けの公式SDKを提供しています。例えば、Node.jsでは、npm install paddle-sdkを実行してライブラリを追加します。このSDKは複雑なAPI呼び出しを抽象化し、ボイラープレートコードを削減します。
また、APIバージョンを確認します。Paddleはバージョン管理されたエンドポイントを使用しており、請求書発行の最新バージョンはv1です。更新によって破壊的な変更が導入される可能性があるため、常にdeveloper.paddle.com/api-referenceのAPIリファレンスを確認して現在のバージョンを確認してください。
最後に、ローカル開発環境をセットアップします。PADDLE_VENDOR_IDやPADDLE_VENDOR_AUTH_CODEなど、APIキーの環境変数を設定します。この方法は、機密データをコードベースから遠ざけることでセキュリティを強化します。
Paddle APIの認証を設定する方法
認証はPaddle APIとのやり取りを保護します。PaddleはAPIキーベースの認証を採用しており、リクエストにベンダーIDと認証コードを含めます。
まず、Paddleダッシュボードの「開発者ツール」>「認証」でキーを生成します。ベンダーID（数値）と認証コード（文字列）を受け取ります。これらは、AWS Secrets Managerのようなシークレットマネージャーを使用して安全に保存してください。
次に、それらをHTTPリクエストに組み込みます。基本認証の場合、Basic <base64-encoded vendor_id:auth_code>の形式を使用します。ただし、PaddleはGETリクエストの場合はクエリパラメータとして、POSTリクエストの場合はボディに渡すことを推奨しています。
例えば、製品をリスト表示するサンプルcurlリクエストは次のようになります。
curl -X GET \
'https://api.paddle.com/products' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json'
Paddleは新しいバージョンでベアラートークンに移行しましたが、レガシーシステムでは基本認証を使用する場合があります。常にドキュメントでメソッドを確認してください。
さらに、トークンのローテーションを処理します。Paddleは、キーが侵害された場合に再生成することを許可しています。PaddleのAPI制限（通常は1分あたり100リクエスト）を尊重するために、コードにレート制限を実装してください。
401 Unauthorizedのような認証エラーが発生した場合は、キーを再確認し、正しい環境（sandbox.paddle.comとapi.paddle.com）を使用していることを確認してください。
主要なPaddle APIエンドポイントとそれらの仕組み
Paddle APIは、エンドポイントを製品、顧客、サブスクリプション、トランザクションなどのカテゴリに整理しています。これらを操作して、完全な課金フローを構築します。
まず製品から始め、カタログを作成および管理します。/productsエンドポイントでは、POSTリクエストで新しいアイテムを追加できます。例えば：
{
"name": "Premium Plan",
"description": "Unlimited access",
"tax_category": "standard",
"prices": [
{
"country_codes": ["US"],
"amount": "29.99",
"currency": "USD"
}
]
}
これにより、地域に合わせた価格設定の製品が作成されます。
次に、顧客エンドポイントがユーザーデータを処理します。/customersを使用してプロファイルを作成し、サブスクリプションにリンクします。POSTリクエストには、メールアドレス、名前、カスタムメタデータが含まれる場合があります。
サブスクリプションはこれに基づいて構築されます。/subscriptionsエンドポイントは定期的な課金を管理します。次のようにサブスクリプションを作成します。
POST /subscriptions
{
"customer_id": "cus_123",
"plan_id": "plan_456",
"quantity": 1,
"trial_period_days": 14
}
これにより試用期間が開始され、定期的な料金が設定されます。
トランザクションは1回限りの支払いをカバーします。/transactionsを介して、金額、通貨、支払い方法を指定して処理します。
Webhookはリアルタイム通知を提供します。ダッシュボードで設定し、サーバーのURLを指し示します。Paddleはsubscription_createdやpayment_succeededなどのイベントを送信します。改ざんを防ぐために、提供された公開鍵を使用して署名を検証します。
エラー処理はすべてのエンドポイントで重要です。Paddleは標準のHTTPステータスコードを返します。成功には200、不正なリクエストには400、サーバーエラーには500です。常にレスポンスボディを解析して詳細を確認してください。例えば：
{
"error": {
"type": "request_error",
"detail": "Invalid customer ID"
}
}
この構造は、問題の迅速なデバッグに役立ちます。
アプリケーションにPaddle APIを統合する方法
統合には慎重な計画が必要です。まず、アプリのビジネスロジックをPaddleのエンティティにマッピングすることから始めます。
Webアプリの場合、フロントエンドの支払いにはPaddleのCheckout.jsを埋め込みます。スクリプトをロードします。
<script src="https://cdn.paddle.com/paddle/paddle.js"></script>
<script>
Paddle.Setup({ vendor: YOUR_VENDOR_ID });
</script>
次に、Paddle.Checkout.open({ product: PRODUCT_ID });でチェックアウトを開きます。
バックエンドでは、API呼び出しを介してデータを同期します。Laravelの例では、公式のPaddleパッケージを使用します: composer require paddlehq/laravel-paddle。
サブスクリプションのモデルを定義し、コントローラーでWebhookを処理します。
public function handleWebhook(Request $request)
{
$payload = $request->all();
// 署名を検証
if (!Paddle::verifyWebhookSignature($payload, $request->header('Paddle-Signature'))) {
return response('Invalid signature', 403);
}
// イベントを処理
switch ($payload['alert_name']) {
case 'subscription_created':
// ユーザーアクセスを更新
break;
}
}
これにより、リアルタイムの更新が保証されます。
さらに、プロビジョニングを実装します。支払いが成功した後、機能へのアクセスを許可します。PaddleのフルフィルメントAPIまたはカスタムロジックを使用してください。
モバイルアプリの場合、アプリからWebへの購入を活用し、RevenueCatのようなプラットフォームと統合してクロスプラットフォームの一貫性を保ちます。
サンドボックスでのテストは、実際のシナリオを模倣します。Paddleが提供するテストカード、例えば成功した課金には4111 1111 1111 1111を使用します。
ApidogでPaddle APIをテストする方法
テストはあなたの統合を検証します。ApidogはAPIクライアントツールとしてここで優れており、コードを書かずにPaddle APIへのリクエストをシミュレートできます。
さらに、Apidogのモックサーバーはスキーマに基づいて偽のレスポンスを生成し、完全なバックエンド統合前のフロントエンド開発に役立ちます。
Paddle APIにApidogを選ぶ理由は何ですか？Apidogは支払いテストを効率化し、異なる通貨や数量などの様々なシナリオに対応するためにCSVインポートを使用したデータ駆動型テストをサポートします。
Paddle APIを使用するためのベストプラクティス
ベストプラクティスを採用することで信頼性が確保されます。機密データを保護するため、リクエストには常にHTTPSを使用します。
さらに、リトライ時の重複操作を防ぐため、POSTリクエストにはべき等性キーを実装します。
Paddleの分析ダッシュボードでAPI使用状況を監視し、リクエスト量やエラー率などのメトリクスを追跡します。
さらに、支払い失敗などのエッジケースを処理します。Webhookを使用して、再試行や通知をトリガーします。
国際的なサポートのために、Paddleのローカリゼーション機能を活用し、価格に国コードを設定します。
最後に、Paddleの変更ログで最新情報を入手してください。APIの更新については、開発者ニュースレターに登録してください。
一般的なPaddle APIエラーのトラブルシューティング方法
エラーはフローを中断させる可能性があります。一般的な問題は429 Too Many Requestsです。これは、リトライ時に指数バックオフを実装することで解決します。
別の問題は、JSON内のフィールドの欠落などの無効なパラメータです。送信する前にクライアント側でペイロードを検証してください。
Webhookが失敗した場合は、サーバーのログで署名の不一致を確認してください。Paddleはテスト用にダッシュボードでシミュレーターを提供しています。
認証の問題が発生した場合は、キーを再生成し、設定を更新してください。
Paddle APIが提供する高度な機能とは？
基本機能に加えて、Paddle APIには収益に関する洞察を得るためのレポートエンドポイントが含まれています: /reports/revenue。
ブランドに合わせて、オーバーライドでチェックアウトをカスタマイズできます。
ZapierやSegmentなどのサードパーティツールとの統合により、機能が拡張されます。
エンタープライズ向けには、Paddleはカスタムエンティティと一括操作をサポートしています。
結論：最適な結果を得るためにPaddle APIをマスターする
これで、Paddle APIに自信を持ってアクセスし、使用するための知識が身につきました。セットアップから高度な統合まで、このガイドは重要な側面をカバーしています。Apidogのようなツールが効率を向上させることを忘れないでください。
実装する際は、サンドボックスで実験し、テストに基づいて反復してください。Paddle APIは、最小限のオーバーヘッドでSaaSをグローバルに拡張することを可能にします。