Sales Reporting API


Sales Reporting API

開発者はReporting APIを使用して売上レポートをダウンロードできます。

セキュリティプロファイルの作成

開発者コンソールのAPIを使用するには、セキュリティプロファイルを作成して、このセキュリティプロファイルに対してAPIへのアクセスをリクエストする必要があります。セキュリティプロファイルは、APIアクセス用のアクセストークンを生成するために使用されるメカニズムです。

セキュリティプロファイルを作成するには、次の手順に従います。

  1. Amazon開発者コンソールアカウントにログインします。まだアカウントを持っていない場合は、アカウントの作成を求められます。
  2. メインナビゲーションで、[アプリ&サービス] をクリックします。
  3. サブメニューで、[APIアクセス] をクリックします。
  4. APIの名前をクリックします。

    [APIアクセス] ページ

  5. [新しいセキュリティプロファイルを作成する] ボタンをクリックします。
  6. 新しいプロファイルの [Security Profile Name] と [Security Profile Description] を入力し、[保存] をクリックします。
  7. [ウェブ設定] タブを開き、表示されているクライアントIDとクライアントシークレットを保存します。Sales Reporting APIにアクセスするために、この情報が必要になります。
    クライアントIDとクライアントシークレット
  8. [APIアクセス] ページに戻ります。
  9. 先ほどクリックしたAPIの名前を再度クリックします。
  10. ドロップダウンリストから新たに作成したセキュリティプロファイルを選択します。
  11. [設定] を選択して、セキュリティプロファイルをこのAPIに関連付けます。API名と、関連付けられたセキュリティプロファイルが、[使用中のセキュリティプロファイル] パネルに追加されます。
    クライアントIDとクライアントシークレット

これで、クライアントIDとクライアントシークレットを使用して、Login With Amazon(LWA)アクセストークンをリクエストできるようになりました。

LWAアクセストークンをリクエストする

クライアントIDおよびクライアントシークレットと共にLogin With Amazon APIを使用して、Login with Amazonアクセストークンをリクエストするには、次の手順に従います。

1. トークンのリクエストを送信する

次のヘッダーとコンテンツでhttps://api.amazon.com/auth/o2/tokenにPOSTリクエストを送信します。

  • ヘッダーContent-Type: application/x-www-form-urlencoded
  • コンテンツ
    • client_id: 「セキュリティプロファイルを作成する」の手順5で保存したクライアントID。
    • client_secret: 「セキュリティプロファイルを作成する」の手順7で保存したクライアントシークレット。
    • grant_typeclient_credentialsに設定する。
    • scopeappstore::apps:readwrite(または、Reporting APIの場合はadx_reporting::appstore:marketer)に設定する。

JSONコンテンツの例:

{
    "grant_type": "client_credentials",
    "client_id": "amzn1.application-oa2-client.ae941846cdd745e9a53319f7bb98d435",
    "client_secret": "41d135b2b02ce5f2fbf7643a66477c089fcc1d88d11f69d3e4a6285b917ca35d",
    "scope": "appstore::apps:readwrite"
}

cURLリクエストの例:

curl -k -X POST -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials&client_id=amzn1.application-oa2-client.5c1462ee102c4a57a5224d0c72118741&client_secret=15d1829ddf4f12d1c5d425e57e5ca081d0f7a63bd94c9e142ff8b20d9de880a4&scope=appstore::apps:readwrite' https://api.amazon.com/auth/O2/token

2.レスポンスを保存する

レスポンスの例は以下のとおりです。

{"access_token":"Atc|MAEBIBav2tvCbJOA9Jv5sRpej6xY_qzHFuCpbWT-Z94nRqVWVcfmZVNPEhZiet-H3vdQcORqE5pO4fCKEi6kfvzzPtxHIoPIte-ZbKB1XgfjfJnciJHqnbV1UF4WJ_an1g9y7yvWKWJddQ2NLPO-C-Y71BPxJ0KDWOPonn_2qFLY5OJo3BhHKIwNHteQAwkCA9iko8d5tosS7fo3dvS-PFmiBk3OMUmr1AdYtuOnq1RVrX7-C14oWzfACudykTn5cDb48Qy2k6R70__GzHG3fC_-Rfzt7zwhfdBWpwoQk-GbV4Bes457oZwHz89Tj-AAf3DouYQ","scope":"appstore::apps:readwrite","token_type":"bearer","expires_in":3600}
  • access_token: アクセストークン。
  • expires_in: アクセストークンの有効期限が切れるまでの秒数。
  • scopeappstore::apps:readwrite(または、Reporting APIの場合はadx_reporting::appstore:marketer)。
  • token_type: 常にbearer

3. エラーレスポンスを処理する

トークンのリクエストでエラーが発生した場合、レスポンスのメッセージ本文には次のエラーメッセージのいずれかが含まれます。

エラーのメッセージ本文 詳細
{"error_description":"Client authentication failed","error":"invalid_client"} 無効なシークレットキー
{"error_description":"The request has an invalid parameter : scope","error":"invalid_scope"} 無効な範囲の値
{"error_description":"The authorization grant type is not supported by the authorization server","error":"unsupported_grant_type"} 無効な認証の認可タイプ
{"error_description":"The Content-Type is not supported by the authorization server","error":"invalid_request"} サポートされていないcontent-type

アクセストークンの使用方法

有効なアクセストークンを取得したら、Authorizationヘッダーを設定してReporting APIにリクエストを送信します。Authorizationヘッダーの値はBearer<YOUR_ACCESS_TOKEN>です。ここで<YOUR_ACCESS_TOKEN>は、「LWAアクセストークンをリクエストする」のレスポンス内のaccess_tokenフィールドの値です。アクセストークンは、「Atc|」で始まる長い文字列です。

cURLリクエストの例:

curl -v -k -X GET "<URLの形式は以下を参照>"   -H  "Authorization:  Bearer Atc|MAEBIKfsULrH7jSzvJTV8UmiHWr9M86O3JRmv4t1hqoCBriSMEP5Gsey_FiBxteZ8oxGd6abGuOFga8fwnMhmSD_Sg4MI4odXLPgB2IVs8M1uswjuWjnsMcvehpWvf9tzQT8HTWiBigInJLB8BrMg5J3O02hlTvcF441XxXDXthyj993COJ2u5swOTKjC_dcijiN8amuzrj32rh9Fr3CNgCpoZ0WqXnBhoHUVMYSOBV-owA5rI4-OfysXC71Zbtv1hb8igk"

アクセストークンの有効期限が切れたら、「LWAアクセストークンをリクエストする」の手順に従って新しいトークンを取得し、それを使用してリクエストを送信します。アクセストークンを最後にリクエストしてから1時間以上経過すると、403 Forbidden HTTPエラーとなり、「Request is not authorized(リクエストは認証されていません)」というメッセージが表示されるようになります。これは、アクセストークンの有効期限が切れたことを示します。

Sales Reporting APIのURL

次の文字列をSales Reporting APIのリクエストを送信するための基本URLとして使用します。

developer.amazon.com

売上レポートURLをリクエストする

1つの売上レポートファイルをダウンロードするために、Sales Reporting APIを使用できます。APIリクエストではURLが返されます。これを使用して、セキュリティで保護されたS3ストレージの場所からファイルをダウンロードできます。

構文

/api/appstore/download/report/sales/<year>/<month>

パラメーター

ダウンロードするレポートファイルの年度(4桁)
レポートファイルの月の値(2桁)

2018年1月の売上レポートをリクエストする方法を次の例に示します。

リクエスト:

curl -v -k -X GET "https://developer.amazon.com/api/appstore/download/report/sales/2018/04" -H "Authorization:  Bearer Atc|MQEBIDdrcC586BxhFBdS7FQVS454oUO-fo90H5gUYVMZB1UVsPFoOPLj_zrpkf9BuMrx-PksU_qDJHL-PJ5suEQTigL1tv7A6AKlyoJJaoyzyzKhd0dwWw3LWUGrlxXxW459nJJH66F89GSBolrmlfuNONly8Cbts2Fy_KHI9YwvzwSVcgf_nvefss_H1O8tsvoYpORVuL8IXBrzT7bHxU0Xj5VjiaxDtU6N4oOQafefT8AcdN0IOYnh3Us8uEeeur3_OH473JwO3SjA4NRaS61Aq37UyhvM9pK3ccGOO5JoMkw1V9kDQQVhKiGWfCoTUBlaVkU"

レスポンス:

https://appstore-adx-reporting.s3.amazonaws.com/85923/sales/sales_2018_01.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20180405T060912Z&X-Amz-SignedHeaders=host&X-Amz-Expires=299&X-Amz-Credential=AKIAJMFYXPVLQKTRRB7Q%2F20180405%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=adab43be54631565d330727383341d56989d129e4dea151411cf7a802b9e5e12

エラー

トークンのリクエストでエラーが発生した場合、レスポンスのメッセージ本文には次のエラーメッセージのいずれかが含まれます。

エラー 詳細
{"Message":"Request is not authorized."} 不適切なアクセスキー、または範囲外のレポートのリクエスト(たとえば、マーケティング担当者が支払いレポート/エージェンシーレポートをリクエストした場合)。
{"Message":"Unable to fetch the request scope for uri = (URL Entered) and verb = GET"} 無効なURLまたはメソッド。

S3 URLを使用してレポートをダウンロードする

Reporting APIではS3のURLが返されます。これを使用してレポートをダウンロードできます。

エラーメッセージ:

Amazon S3から次のエラーのいずれかが返されることがあります。

Report Not Found:ファイルを取得しようとしましたが、指定した名前のファイルがS3フォルダに存在しません。

Server Unavailable:レポートをダウンロードしようとする際にS3バケットが利用不可だと、HTTP 404エラーコードが返されます。

詳細については、「S3 error responses(S3エラーレスポンス)」を参照してください。

Reporting APIに関するよくある質問(FAQ)

Q: APIを使用して最も早く取得できるレポートは何ですか?

最も早く取得できるレポートは2018年1月のレポートです。現在のところ、2017年およびそれ以前のレポートは利用できません。

Q: セキュリティプロファイルを削除するにはどうすればよいですか?

セキュリティプロファイルを削除できるのは管理者レベルのユーザーのみです。[アプリ&サービス] の下の [セキュリティプロファイル] タブに移動して、求められたセキュリティプロファイルを選択して削除します。

Q: cURLコマンドの範囲はなぜマーケティング担当者と定義されているのですか?

範囲はAPIアクセスのための必須フィールドです。マーケティング担当者は、Sales Reporting APIのデフォルトの範囲として定義されています。

Q: アクセストークンと署名済みS3 URLは永続的に使用できますか?

いいえ、アクセストークンの有効期間は1時間のみです。署名済みS3 URLは5分間のみ有効です。これらのタイムアウトはセキュリティ上の理由によります。

Q: セキュリティプロファイルのクライアントIDとクライアントシークレットは永続的に使用できますか?

はい。これらは、セキュリティプロファイルが開発者コンソールから削除されるまで使用できます。ただし、セキュリティ上の理由から、セキュリティプロファイルに関連付けられたAPIを、少なくとも6か月間に1回は更新することを強くお勧めします。

Q: チームに5人の管理者がいます。管理者全員がセキュリティプロファイルを作成することは可能ですか? 可能な場合、それはどのように管理されますか?

はい、5人の管理者全員がセキュリティプロファイルを作成できます。各管理者は、すべてのセキュリティプロファイルを閲覧できます(ほかの管理者によって作成されたプロファイルであっても)。

CSVファイル形式

CSVファイルは、.csvという拡張子が付いたテキストファイルです。ローカライズされた文字列をサポートするには、CSVファイルにUTF-8エンコードを使用する必要があります。

CSVファイルの1行目は、列名を表示するヘッダーです。2行目以降は、1行に1つのレポートアイテムの情報が含まれています。請求書IDフィールドでは、レポートの各単位アイテムの一意の識別子が定義されます。

CSVファイルは、.csvという拡張子が付いたテキストファイルです。ローカライズされた文字列をサポートするには、CSVファイルにUTF-8エンコードを使用する必要があります。

CSVファイルの1行目は、列名を表示するヘッダーです。2行目以降は、1行に1つのレポートアイテムの情報が含まれています。請求書IDフィールドでは、レポートの各単位アイテムの一意の識別子が定義されます。

次の表は、CSVファイルの各行のフィールドについて説明しています。

フィールド 概要
Marketplace String Amazonマーケットプレイス Amazon.com
国/地域コード String トランザクション元を表す標準的な2桁のISO国/地域コード。このリストを参照してください。 US
Invoice Id String 請求書の一意のID。このフィールドは2017年以前のサマリーデータではNAに設定されています 8dd921637-b092f385a7ee4-62c6494b3ed702f113
Transaction Id 整数 このトランザクションに関連付けられている一意のID。売上情報にはある特定の日のすべてのトランザクションが含まれているため、このフィールドは2017年以前のサマリーデータではNAに設定されています 21854260140446
Transaction Time String トランザクションの日付と時刻。MM/DD/YY HH:MM:SS XSTの形式で、時間の範囲には00~23を使用します。XSTは、トランザクションのマーケットプレイスに関連付けられたタイムゾーンです。2017年以前のデータでは、このフィールドは売上が発生した日を示します。 05/21/18 14:39 PST
Transaction Type String トランザクションタイプはChargeまたはRefundのどちらかです。 Charge
Adjustment YesまたはNo トランザクションが調整である場合、このフィールドはYesに設定されます。2017年以前のデータでは、トランザクションの種類がRefundの場合、このフィールドにはnullの値が表示されます。 Yes
Vendor SKU String 150文字までの文字列。使用可能な文字は、a~z、A~Z、0~9、アンダースコア、ピリオド、ダッシュです。SKUでは大文字と小文字が区別されます。 com.gamevendor.fungame
Title(タイトル) String アプリまたはゲームのタイトル。 激突トラックゲーム
Item Name String アプリ、ゲーム、定期購入型アイテム、アプリ内課金アイテム、ゲーム内アイテムのいずれかの名前。 激突トラックゲーム
Item Type String アイテムのタイプ。値は、SubscriptionAppIn-AppGameIn-Gameなど。 Application
In-App Subscription Term String 定期購入の期間。期間は1週間ごと、2週間ごと、1か月ごと、2か月ごと、3か月ごと、6か月ごと、1年ごとのいずれかを指定できます。このフィールドは、アイテムのタイプがSubscriptionの場合にのみ適用されます。
このフィールドはTwitchには適用されません。
Weekly
In-App Subscription Status String ステータスにはTrialPaidのどちらかを指定できます。このフィールドは、アイテムのタイプがSubscriptionの場合にのみ適用されます。
このフィールドはTwitchには適用されません。
Trial
Units 整数 このトランザクションに含まれるユニット数。 1
Usage Time 文字列 Undergroundアプリの使用時間(秒単位)。このフィールドは、AmazonアプリストアのUnderground商品にのみ適用されます。ユニット数を計算するには、使用時間を60で除算します。たとえば、使用時間1200は20ユニットです。
このフィールドはTwitchには適用されません。
1200
Marketplace Currency String トランザクションの通貨はマーケットプレイスによって決定されます。マーケットプレイス別タイムゾーン表を参照してください。 USD
Sales Price Marketplace Currency 割引後にユーザーに表示される販売価格。消費税は含まれません。Undergroundアプリの場合、販売価格はアプリの使用分数の数字に基づく収益を表します。Undergroundアプリの場合、売上と利益は同じです。調整と返金のために、元のアイテムの販売価格が表示されます。実際に調整された金額または返金された金額は、販売価格と異なることがあります(一部返金など)。 4.99
Estimated Earnings Marketplace Currency このトランザクションからAmazonのロイヤリティを差し引いたあとの収益の見積もりです。調整と返金のために、調整された金額または返金された金額に基づく収益が表示されます。 3.49

説明

  • 売上データは24時間ごとに更新されます。データのプルを自動化する場合、24時間ごとにスクリプトを実行して最新情報を取得することをお勧めします。報告された情報には最大48時間の遅延があることにご注意ください。
  • APIは1秒あたり最大3つのリクエストをサポートします。API呼び出しの頻度がそれより多い場合、パフォーマンス低下につながることがあります。
  • 収益はこのファイルで見積もられます。これは、月末の収益レポートと正確に一致しないことがあります。収益レポートには、ここに含まれない追加調整が含まれる可能性があります。
  • すべての調整は、元のトランザクションが発生した月ではなく、調整が行われた月に表示されます。
  • テストASINで「Title」と「Item Name」にnull値が表示されます。これは既知の問題であり、今後のリリースで修正されます。

マーケットプレイス情報

各マーケットプレイスの国名/地域コードと通貨の種類を次の表に示します。

国/地域
コード
通貨
コード
通貨 Marketplace
AU AUD オーストラリアドル Amazon.com.au
BR BRL レアル Amazon.com.br
CA CAN カナダドル Amazon.ca
CN CHY 人民元 Amazon.cn
DE EUR ユーロ Amazon.de
ES EUR ユーロ Amazon.es
FR EUR ユーロ Amazon.fr
GB GBP ポンド Amazon.co.uk
IN INR インドルピー Amazon.in
IT EUR ユーロ Amazon.it
JP JPY 日本円 Amazon.co.jp
US USD ドル Amazon.com

APIデータセキュリティ

Sales Reporting APIを通じてアクセスできるデータはすべてAmazonの機密情報であり、開発者による使用のみを目的としています。

信頼されたサードパーティに(日々の運用サポートのために)APIアクセス権限を付与した場合、ご自身の責任でその情報を共有することに同意するものとみなされます。この情報を共有することによって生じるどのような損失や損害についても、Amazonは一切の責任を負いません。

サードパーティとAPIアクセスを共有することを選択する場合は、以下のガイドラインに従ってください。

  1. サードパーティ専用のセキュリティプロファイルを作成する。
  2. セキュリティプロファイルの名前にサードパーティの商号を含める(例:ReportingAPI_<企業名>_<サードパーティ名>)。
  3. セキュリティプロファイルの説明フィールドで、だれがセキュリティプロファイルを使用するのか明確に説明する。

ご自身のデータ保護のため、6か月ごとにセキュリティプロファイルを更新することを強くお勧めします(Sales Reporting APIに関連付けられているすべてのセキュリティプロファイル)。