Web Service


App Store Server API


あなたのサーバから顧客たちの App Store 取引を管理します。


App Store Server API 1.0+



概観


App Store Server API は、あなたのサーバから呼び出して顧客たちのアプリ内購入に関する情報を要求および提供するための REST API です。App Store は、JSON Web Signature (JWS) 仕様を使用して、この API が返す取引とサブスクリプション更新情報に署名します。ほとんどのエンドポイントは、あなたが提供した取引 ID で示される、あなたのアプリの単一の顧客のデータを返します。


App Store Server API は、顧客たちのデバイス上のアプリのインストール状態とは無関係です。App Store サーバは、顧客がデバイスにアプリをインストール、削除、または再インストールしたかどうかに関係なく、顧客のアプリ内購入履歴に基づいて情報を返します。


この API は以下の機能を提供します。


  • 取引と自動更新サブスクリプションのステータス。 取引情報の取得 を呼び出すことで単一の取引の情報を取得するか、取引履歴を取得する を使用して顧客の取引履歴全体を取得します。すべてのサブスクリプション状況の取得 を呼び出すと、最新のサブスクリプションステータスを取得できます。この情報を使用して、あなたのサーバ上で顧客たちの購入情報を最新の状態に保ちます。

  • 払い戻し情報。 払い戻し履歴の取得 を呼び出すと、顧客の払い戻し履歴を取得できます。App Store Server Notifications V2 から CONSUMPTION_REQUEST notificationType をあなたが受け取った後、顧客が消耗品のアプリ内購入の払い戻しを要求したときに、消費情報を送信 エンドポイントを使用して情報を App Store に送信します。あなたのデータは払い戻しの決定に役立ちます。

  • App Store サーバ通知の履歴とテスト。 通知履歴の取得 を呼び出して、過去 180 日間にあなたのサーバが見逃した可能性のある通知を要求します。テスト通知の要求 と テスト通知状況の取得 を呼び出して、あなたのサーバが App Store Server Notification V2 エンドポイントで通知を正常に受信しているかどうかをテストします。

  • サブスクリプション更新日の延長。 サブスクリプション更新日を延長する と関連エンドポイントを呼び出して、一時的なサービス停止、キャンセルされたイベント、またはライブストリーミングイベントの中断に対してあなたの顧客たちに補償するために、有料のアクティブなサブスクリプションの更新日を延長します。詳細については、自動更新サブスクリプションの更新日を延長 を参照してください。

  • 注文情報の検索。 顧客たちが電子メールで受け取る App Store の領収書に記載されている顧客の注文 ID に基づいてアプリ内購入情報を取得するには、注文 ID の検索 を呼び出します。

    • App Store Server API を使用するには、あなたのサーバが Transport Layer Security (TLS) プロトコル 1.2 以降をサポートしていなければなりません。


    この API の最新の変更内容については、App Store サーバ API の変更履歴 を確認してください。Apple Developer Web サイト で App Store Server API に関するビデオを探してください。



    あなたの API 呼び出しを承認


    API への呼び出しには、承認のための JSON Web Tokens (JWT) が必要です。tokens (トークン) を作成するためのキーは、あなたの組織の App Store Connect アカウントから取得します。あなたのキーを作成するには、API 要求を承認するため API キーの作成 を参照してください。あなたのキーを使用してトークンを生成し、API リクエストを送信するには、API 要求用の JSON Web トークンの生成 を参照してください。


    完全な署名済みトークンを取得したら、そのトークンをリクエストの承認ヘッダに持参トークンとして提供します。新しい API リクエストごとに新しいトークンを生成するか、有効期限が切れるまでトークンを再利用します。



    JWT を作成し、取引を検証し、もっと App Store サーバーライブラリを使用して


    App Store Server Library は、Apple のオープンソースライブラリで、4 つの言語で利用できます。呼び出しを承認するための JWT の作成など、App Store Server API の導入を容易にするクライアントを提供します。詳細については、App Store サーバー ライブラリを使用して実装を簡素化する および WWDC23 セッション App Store Serverライブラリについて を参照してください。



    サンドボックス環境を使用してテスト


    注文 ID の検索 を除くすべての App Store Server API エンドポイントは、サンドボックス環境でテストできます。以下の基本 URL を使用してエンドポイントに要求を送信し、サンドボックス環境にアクセスします。


    https://api.storekit-sandbox.itunes.apple.com/

    たとえば、サンドボックス環境で 取引履歴を取得する を呼び出すには、サンドボックス URL を使用して要求を送信します。


    https://api.storekit-sandbox.itunes.apple.com/inApps/v2/history/{transactionId}

    パス内の /inApps では大文字と小文字が区別されることに注意してください。


    transactionId をパラメータとして受け取るエンドポイントの場合は、取引 ID を作成するのと同じ環境を使用してエンドポイントを呼び出すようにしてください。環境情報は、JWSTransactionDecodedPayload の environment プロパティにあります。


    environment (環境) 情報がない場合は、以下の手順に従ってください。


    1. 製品 URL を使用してエンドポイントを呼び出します。呼び出しが成功した場合、取引 ID は製品の環境に属します。

    2. エラーコード 4040010 TransactionIdNotFoundError を受け取った場合は、サンドボックス環境を使用してエンドポイントを呼び出します。

    3. 呼び出しが成功した場合、取引 ID はサンドボックス環境に属します。呼び出しが 4040010 エラーコードで失敗した場合、取引 ID はどちらの環境にも存在しません。



    トピックス


    要点


    App Store サーバー ライブラリを使用して実装を簡素化する

    Apple のオープンソースライブラリを使用して JSON Web Token (JWT) を作成し、あなたの呼び出しの承認、取引の検証、領収書からの取引 ID の抽出などを行います。


    API 要求を承認するため API キーの作成

    JSON Web トークンに署名し、API 要求を承認するために使用する API キーを作成します。


    API 要求用の JSON Web トークンの生成

    あなたの秘密鍵 (private key) で署名された JSON Web トークンを作成し、App Store サーバ API および外部購入サーバー API への要求を承認します。


    レート制限の識別

    App Store Server API エンドポイントに適用されるレート制限を認識し、あなたのコード内で処理します。


    App Store サーバ API の変更履歴

    App Store Server API の新機能と更新について説明します。



    アプリ内購入履歴


    取引履歴の取得 (Get Transaction History)

    あなたのアプリの顧客のアプリ内購入取引履歴を取得します。


    object HistoryResponse

    アプリに関する顧客の取引履歴が含まれる応答。


    Get Transaction History V1

    終了した消耗品のアプリ内購入を除く、あなたのアプリの顧客のアプリ内購入取引履歴を取得します。

      廃止  



    取引情報


    取引情報の取得

    あなたのアプリの単一の取引に関する情報を取得します。


    object TransactionInfoResponse

    単一の取引の署名済み取引情報を含む応答。



    サブスクリプションの状況


    すべてのサブスクリプション状況の取得

    あなたのアプリ内で顧客の自動更新サブスクリプションすべての状況を取得します。


    object StatusResponse

    アプリ内の顧客の自動更新サブスクリプションすべての状況情報が含まれる応答。



    アプリアカウントトークン


    アプリアカウントトークンの設定


    顧客があなたのアプリ外で行う購入のアプリアカウントトークンの値を設定するか、既存の取引でその値を更新します。


    object UpdateAppAccountTokenRequest

    アプリアカウントトークンの値が含まれる要求本文。



    消費情報


    消費情報を送信

    あなたのサーバーが消費要求通知を受信した後、消耗品のアプリ内購入または自動更新サブスクリプションに関する消費情報を App Store に送信します。


    object ConsumptionRequest

    消費情報を含む要求本文。



    注文 ID の検索


    注文 ID の検索

    注文 ID を使用して、レシートから顧客のアプリ内購入を取得します。


    type orderId

    アプリ内購入の App Store 領収書の顧客の注文 ID。


    object OrderLookupResponse

    注文検索ステータスと、注文内のアプリ内購入の署名済み取引の配列を含む応答。



    払い戻しの検索


    払い戻し履歴の取得

    顧客のアプリ内購入のうち払い戻しを受けたものすべてをページ分けしたリストを取得します。

    object RefundHistoryResponse

    署名された JSON Web 署名 (JWS) 払い戻し取引の配列とページング情報を含む応答。


    払い戻し履歴の取得 V1

    顧客があなたのアプリ内で払い戻した購入のリストを最大 50 件取得します。

      廃止  


    object RefundLookupResponse

    署名された JSON Web Signature (JWS) 取引の配列を含む応答。

      廃止  



    サブスクリプションの更新日を延長


    自動更新サブスクリプションの更新日を延長

    サブスクリプションの更新日を延長することで、対象となるアクティブな加入者のサービス中断を補償します。


    サブスクリプション更新日を延長する

    元の取引 ID を使用して、顧客のアクティブなサブスクリプションの更新日を延長します。


    すべてのアクティブな加入者のサブスクリプション更新日を延長

    サブスクリプションの製品 ID を使用して、対象となるアクティブな加入者全員の更新日を延長します。


    サブスクリプション更新日延長のステータスを取得する

    更新日延長要求が完了したかどうかを確認し、成功または失敗した延長の最終件数を提供します。


    object ExtendRenewalDateRequest

    個々のサブスクリプションのサブスクリプション更新延長データが含まれる要求本文。


    object ExtendRenewalDateResponse

    個々の更新日延長が成功したかどうか、および関連する詳細を示す応答。


    object MassExtendRenewalDateRequest

    すべての対象となるアクティブな加入者に適用するサブスクリプション更新延長データを含む要求本文。


    object MassExtendRenewalDateResponse

    サーバーがサブスクリプション更新日延長要求を正常に受信したことを示す応答。


    object MassExtendRenewalDateStatusResponse

    すべての対象加入者に対してサブスクリプションの更新日を延長する要求の現在のステータスを示す応答。



    App Store サーバー通知履歴


    通知履歴の取得

    App Store サーバがあなたのサーバに送信しようとした通知のリストを取得します。


    object NotificationHistoryRequest

    通知履歴の要求本体。


    object NotificationHistoryResponse

    署名された通知ペイロードとサーバの最初の送信試行の結果を含む、App Store サーバの通知履歴レコード。


    object notificationHistoryResponseItem

    署名された通知ペイロードとサーバーの最初の送信試行の結果を含む、App Store サーバーの通知履歴記録。



    App Store サーバー通知のテスト


    テスト通知の要求

    App Store Server Notifications に、あなたのサーバーにテスト通知を送信するように依頼します。


    テスト通知状況の取得

    あなたのサーバーに送信されたテストの App Store サーバー通知のステータスを確認します。


    object SendTestNotificationResponse

    テストの通知トークンを含む応答。


    object CheckTestNotificationResponse

    App Store サーバーのテスト通知の内容とあなたのサーバーからの結果が含まれる応答。



    JWS ヘッダとペイロード


    type JWSTransaction

    App Store によって署名された取引情報 (JSON Web Signature (JWS) Compact Serialization 形式)。


    type JWSRenewalInfo

    App Store によって署名された、JSON Web Signature (JWS) 形式のサブスクリプション更新情報。


    object JWSDecodedHeader

    取引または更新情報を含む、復号された JSON Web Signature (JWS) ヘッダ。


    object JWSTransactionDecodedPayload

    取引情報を含む復号されたペイロード。


    object JWSRenewalInfoDecodedPayload

    自動更新サブスクリプションのサブスクリプション更新情報を含む復号されたペイロード。


    Data types

    復号された取引および更新情報のペイロードについては、これらのデータ型を参照してください。



    エラー情報


    エラーコード

    App Store Server API 応答が返すエラーコードを理解します。














    トップへ












    トップへ












    トップへ












    トップへ












    トップへ












    トップへ












    トップへ












    トップへ












    トップへ












    トップへ












    トップへ












    トップへ












    トップへ












    トップへ












    トップへ












    トップへ












    トップへ