販売サービスと連携する

使える販売サービス

表に無い販売サービスや自社のシステムからは、汎用の受け口かManagement APIへ送って連携できます。送り方は「汎用の受け口に送る」と「自動化サービスとCRMから使う」にあります。

連携を登録する

1. 手順1使う販売サービスを選ぶ

   左のメニューの「決済・販売サービスの連携」を開き、「連携を追加する」から使うサービスを選びます。テスト用と本番用は、別の連携として登録します。

2. 手順2販売サービスに通知先のURLを登録する

   登録画面の「通知を受け取るURL」を、販売サービスの通知（Webhook）の送り先に登録し、画面に並ぶ出来事を選びます。SquareはこのURLを署名に含めるので、1文字も変えずに登録してください。

   • Shopify: 管理画面の「設定 > 通知 > Webhook」で、「注文の支払い」「注文の更新」「注文のキャンセル」のWebhookをJSON形式で作ります。Shopifyペイメントのチャージバックを反映するときは、disputes/createとdisputes/updateのWebhookも同じURLで作ってください。管理画面で選べないときは、注文の分も含めてカスタムアプリ（read_shopify_payments_disputesの権限）のWebhookで作り、アプリのクライアントシークレットを署名の鍵にします。
   • Square: Developer ConsoleのWebhooksで購読を追加し、subscription.created・subscription.updated・invoice.scheduled_charge_failed・invoice.payment_madeを選びます。請求（invoice）の通知には、請求書の読み取り（INVOICES_READ）の権限が要ります。
   • KOMOJU: 管理画面でWebhookを追加し、payment.capturedとpayment.refundedを選び、シークレットトークンを決めます。
   • Paddle: 「Developer tools > Notifications」で通知先を作り、取引・購読・返金（adjustment）・顧客の出来事を選びます。サンドボックスと本番は別の通知先です。
   • Lemon Squeezy: 「Settings > Webhooks」でWebhookを追加し、署名シークレットを決めて、注文と購読の出来事を選びます。

3. 手順3署名の鍵を入れて登録する

   販売サービスの画面の署名の鍵（ShopifyのWebhookの署名の鍵、SquareのSignature key、KOMOJUのシークレットトークン、Paddleの通知先の秘密鍵、Lemon Squeezyの署名シークレット）を入れて、「連携を登録」を押します。鍵は保存後に表示しません。汎用の受け口の鍵はUsakeyが作り、登録の直後に一度だけ表示します。

Management API（/mgmt/v1/sales-integrations）と、AIアシスタントの接続（MCP）からも登録・変更できます。読み取りにはproducts:read、変更にはproducts:writeとlicenses:writeの権限が要ります。AIアシスタントは販売サービスの署名の鍵を扱いません。AIアシスタントで登録した連携は「署名の鍵の登録待ち」になるので、連携の画面の「設定の画面で鍵を入れる」から鍵を入れてください。鍵が入るまで、通知は受け取りません。

商品とライセンスを対応づける

連携の画面の「対応を追加」から、販売サービスの商品の識別子と、発行するライセンスの利用ルールを対応づけます。対応の無い商品が買われたときは、通知の履歴に記録だけ残り、ライセンスは発行しません。ただし、購入者のアプリの確認値（usakey_claim_challenge）が付いた購入で、どの商品にも対応が無いときは保留にします。対応を追加すると、販売サービスの再送のときに発行します。

• 買い切りの利用ルールは期限なしで発行します。
• 期間制の利用ルールは、Square・Paddle・Lemon Squeezyでは販売サービスの契約期間の終わりを期限にします（有効日数を入れると、購入日からの日数にします）。ShopifyとKOMOJUは購読を反映しないので、有効日数が必要です。
• お試しの利用ルールと、管理なしの完全オフラインの買い切りは選べません。
• 数量は使いません。1つの購入（Shopifyでは注文の1明細）につき、1つのライセンスを発行します。台数や人数は利用ルールのとおりです。
• 購読（Paddle・Lemon Squeezy・Square）の商品は、期間制の利用ルールに対応づけます。購読の通知の商品を買い切りの利用ルールに対応づけると、設定の誤りとして発行に失敗します。
• 対応の商品の識別子を書き換えると、前の識別子で続いている購読の次の通知は、プランの変更として扱います。新しい識別子に合う対応が無ければ、ライセンスを停止します。

ライセンスキーを購入者へ渡す

発行したライセンスキーの渡し方は、次のどれかです。

• 購入者のアプリが受け取る（安全な受け取り）: アプリが購入の前に43文字の確認値（claim_verifier）を作り、そのSHA-256をusk_claim_v1_に続けた値を、購入のcustom dataのusakey_claim_challengeに入れます（Shopifyはカートの属性、KOMOJUはmetadata、PaddleはcustomData、Lemon Squeezyはcheckout[custom]）。購入のあと、連携の画面の「受け取り口のURL」へ確認値を送ると、キーを受け取れます。Stripeでの販売連携と同じ仕組みで、受け取れるのは72時間です。Squareはcustom dataを渡せないため使えません。
• 汎用の受け口の応答で受け取る: 発行を送ると、応答にライセンスキーが入ります。同じイベントIDで送り直しても、72時間は同じキーが返ります。
• 販売者が渡す: ライセンスの詳細の画面でキーを確かめて、購入者へ知らせます。

購入のあとに起きること

販売サービスの購読・支払い・返金の状態に合わせて、ライセンスを次のように変えます。連携が止めたライセンスだけを再開します。あなたが管理画面やManagement APIで止めたライセンスは、そのまま期限を過ぎたあとも、販売サービスの通知では再開しません（期限と利用ルールだけを合わせます）。

購入より先に届いた停止・再開・取消の通知も記録し、発行時に照合します。初回購入が全額返金された購入では、その後に購読が有効の通知が届いても、ライセンスを発行・再開しません。Squareは請求書ごとに未払いを管理し、別の請求への支払いでは停止を解きません。Shopifyは同じ異議申し立ての終了後に届いた古い開始通知で止め直しません。Paddleでは、購読から削除された明細のライセンスを停止し、再追加時は同じライセンスを再開します。返金対象が初回取引か分からない間は停止し、初回取引の通知で確認できたら、初回の全額返金なら取り消し、更新分の返金ならその停止を解きます。他の停止理由が残る場合は再開しません。

• 購入者は、販売サービスの顧客ID（Shopify・Square・Paddle・Lemon Squeezy）と、汎用の受け口のcustomer.referenceで、同じ顧客として扱います。メールアドレスでは照合しません。KOMOJUの通知には顧客IDが無いので、購入のたびに新しい顧客を作ります。アーカイブ済みの顧客に当たったときは、その顧客へ発行し、通知の履歴に残します。
• 別々の購入（2つのタブで買う、同じ人が購読を2つ始めるなど）には、それぞれライセンスを発行します。二重の支払いはUsakeyでは止められないので、販売サービスの側で既存の購読を確かめてから購入画面を開いてください。1つの確認値で受け取れるのは1回です。同じ確認値の2回目の購入にもライセンスを発行しますが、キーはあなたが渡します。
• 購読の解約と返金は、販売サービスで行います。Usakeyでライセンスを取り消したり、顧客をアーカイブしたりしても、販売サービスの購読と請求は止まりません。
• KOMOJUの通知には、テストと本番を見分ける項目がありません。テスト用と本番用で別のWebhookとシークレットトークンを使ってください（テストの決済の通知が本番用のWebhookに届くかは確かめていません）。

汎用の受け口に送る

自社のシステムから、連携の画面の「通知を受け取るURL」へJSONをPOSTします。署名は、UsakeyのWebhook通知と同じ形です。

• X-Usakey-Event-Id: 送り元が決める一意のID（英数字と記号（.・_・:・-）、128文字まで）。送り直すときは同じ値にします。
• X-Usakey-Timestamp: 送った時刻（Unix秒）。前後300秒まで受け付けます。
• X-Usakey-Signature: v1=に続けて、署名の鍵で「時刻.イベントID.本文」をHMAC-SHA256にした16進数。

{
  "action": "issue",
  "purchase_id": "order-1001",
  "item": "pro-yearly",
  "customer": {"email": "buyer@example.com", "name": "山田 太郎", "reference": "crm-42"},
  "expires_at": "2027-10-18T00:00:00Z"
}

actionはissue（発行）・change（プランの変更）・renew（期限の更新）・suspend（一時停止）・resume（再開）・revoke（取消）です。2回目からはpurchase_idだけで同じライセンスを指せます。changeはitemに新しい商品の商品コードを入れ、同じライセンスキーのまま、その対応の利用ルールへ切り替えます。同じ製品の期間制の利用ルールに対応づけた商品でないときは失敗になり、ライセンスは変わりません。suspend・resume・revokeにはreason（理由）を付けられ、操作履歴に残ります。応答の結果（反映・変更なし・失敗・保留）と、項目の詳しい意味はAPIリファレンスにあります。保留（503）の通知は、時間をおいて同じイベントIDで送り直してください。

自動化サービスとCRMから使う

署名を計算できるサービスは汎用の受け口へ、できないサービスはManagement API（APIキー）へ送ります。APIキーは、必要な操作の権限だけを持つものを作ってください。

• n8n: ワークフローの定義ファイルを取り込みます（Import from File）。Cryptoノードで署名を作り、HTTP Requestノードで汎用の受け口へ送ります。署名の鍵はCryptoの資格情報に入れます。
• Make: 変数に本文（JSONの文字列）・時刻（formatDate(now; "X")）・イベントIDを作り、sha256(時刻 + "." + イベントID + "." + 本文; "hex"; 署名の鍵)の前にv1=を付けて署名にします。HTTPの「Make a request」で、Raw・application/jsonの本文と3つのヘッダーを付けて汎用の受け口へ送ります。
• Zapier: Code by Zapier（JavaScript。Node.jsのcryptoとfetchが使えます）で署名を作り、そのままfetchで汎用の受け口へ送ります。
• Power Automate: 式にHMACの関数が無いので、HTTPアクション（プレミアム）でManagement APIへ送ります（Authorization: BearerにAPIキー）。
• Yoom: ストアに注文が入ったときなどのトリガーから、Management APIへ送ります。任意のAPIを呼ぶ方法はYoomのヘルプで確かめてください。
• kintone: Webhookは認証のヘッダーを付けられないので、Zapier・Power Automateで受けて送るか、プラグインのkintone.plugin.app.setProxyConfigにAPIキーを保存してkintone.plugin.app.proxyでManagement APIを呼びます（保存した値は利用者から見えません）。
• HubSpot: ワークフローの「Webhookを送信」（Data Hub Professional以上）で、認証に「APIキー」（リクエストヘッダーのAuthorization）を選び、Management APIへ送ります。
• Salesforce: 外部認証情報と指定ログイン情報でAuthorizationのヘッダーを付け、フローのHTTPコールアウトでManagement APIへ送ります。ApexならCrypto.generateMacで署名を作り、汎用の受け口へ送れます。

困ったときは

• 通知の履歴に何も出ないときは、署名の鍵と通知先のURLを確かめてください。署名の合わない通知は記録しません。「署名の鍵の登録待ち」の連携は、鍵を入れるまで通知を受け取りません。
• 利用ルールを編集すると、有効な対応は新しい版へ切り替わります。利用ルールを廃止すると、その対応での発行は保留になります。対応で運用中の利用ルールを選ぶと、販売サービスの再送のときに発行します。
• 「保留」は、製品の署名鍵の準備中やプランの上限など、時間をおけば成功しうるときです。販売サービスが再送すると、もう一度処理します。
• 確認値の無い購入で対応の無い商品は、あとで対応を作っても同じ通知では発行しません。ライセンスを手で発行するか、汎用の受け口でissueを送ってください。
• 販売サービスが送り直すのは決まった期間だけです（Lemon Squeezyは数分、Shopifyは4時間、Squareは24時間、Paddleは3日、KOMOJUは25日）。連携を止めている間や保留のまま期間を過ぎた通知は、販売サービスで送り直すか、ライセンスを手で直してください。ShopifyのアプリのWebhookは、失敗が続くと登録が消えることがあるので、再開したら確かめてください。
• 販売者が管理画面やManagement APIで一時停止したライセンスは、販売サービスの通知では再開しません。
• テストの通知が本番用の連携に届いたとき（Shopifyのtest、Lemon Squeezyのtest_mode）は反映しません。