MENU
    1. ホーム
    2. 未分類
    3. SP-API Finances APIについての勉強会開催

    SP-API Finances APIについての勉強会開催

    未分類
    EIKING
    目次

    イントロダクション: SP-APIファイナンスAPIとlistTransactions

    まずはSelling Partner API (SP-API) 全体の中でファイナンスAPIが果たす役割に触れます。Amazon出品者の売上・手数料・返金など金銭に関するイベントを取得するのがファイナンスAPIです。その最新版(Finances API v2024-06-19)に用意されたのが**listTransactions**というエンドポイントで、指定した期間内の取引イベント（transaction）一覧を取得できますdeveloper-docs.amazon.com。これにより、出品者の財務情報をステートメント期間（2週間ごとの支払サイクル）を待たずに随時取得することが可能ですdeveloper-docs.amazon.comdeveloper-docs.amazon.com。

    listTransactionsは日時範囲やマーケットプレイスを指定して呼び出し、一度に最大500件までの取引データを取得できますdeveloper-docs.amazon.com。もしデータ件数が多い場合は、レスポンスに含まれるnextTokenを使用してページ分割取得を継続しますdeveloper-docs.amazon.com。注意点として、最新の注文に関する取引データは即時反映されず最大48時間程度遅れる場合がありますdeveloper-docs.amazon.com。つまり直近48時間以内の注文は financial events に含まれない可能性があるため、最新取引を追跡する際はこの遅延を考慮する必要がありますdeveloper-docs.amazon.com。

    なお、SP-APIの他の操作と同様、listTransactionsを利用するには適切な認可と権限が必要です。具体的にはデベロッパーアカウントで「Finance and Accounting」ロールの承認を受け、アプリケーションの権限にそのロールを含める必要がありますdeveloper-docs.amazon.com。また実運用では対象のセラーからの**API利用許可（トークン取得）**も必要になります。このような準備を整えた上で、listTransactionsを活用したデータ取得に進みます。

    listTransactionsが返すデータと機能概要

    listTransactionsエンドポイントが返す取引（Transaction）データの内容を把握しましょう。レスポンスはJSON形式で、主に以下のような情報が含まれます。

    • transactions: 取引オブジェクトの配列。指定期間内の取引イベントが最大500件まで格納されます（追加のデータがある場合はnextTokenを取得）developer-docs.amazon.com。
    • nextToken: 次のページのデータ取得に使用するトークン文字列。500件を超える場合に値がセットされ、次のリクエストでこのトークンを指定することで続きの取引を取得できますdeveloper-docs.amazon.com。

    各Transactionオブジェクトの主なフィールドは次のとおりです。

    • transactionId（取引ID） – 取引ごとのユニークID。developer-docs.amazon.com
    • transactionType（取引種別） – 取引の種類を表すフィールド。現行バージョンでは主にShipment（出荷に伴う決済）などが該当しますdeveloper-docs.amazon.com。将来的に他種別が追加される可能性があります。
    • transactionStatus（取引ステータス） – 取引の状態を示すフィールド。値は RELEASED（支払済み）, DEFERRED（保留中）, DEFERRED_RELEASED（保留後に支払済み）の3種ですdeveloper-docs.amazon.com。例えば**請求書払い（B2B取引）**の注文は支払い確定までDEFERREDとなり、支払われるとRELEASEDに変わります（支払時に過去の保留取引はDEFERRED_RELEASEDに更新）developer-docs.amazon.com。
    • postedDate（計上日時） – その取引が計上（発生）した日時。ISO 8601日時形式で提供されます。
    • description（内容説明） – 取引の内容や理由の説明テキスト。例として"Order Payment"（注文の支払い）や"Refund Order"（注文の返金）といった値が入り、該当取引が何に関するものか示しますdeveloper-docs.amazon.com。
    • totalAmount（金額） – 取引全体の金額（売上の場合プラス、返金や手数料の場合マイナスの値）。内部は通貨コードと金額のオブジェクトで提供され、例: { "currencyCode": "JPY", "currencyAmount": 5000.0 } のように表されますdeveloper-docs.amazon.comdeveloper-docs.amazon.com。
    • marketplaceDetails – 当該取引が発生したマーケットプレイスの情報。marketplaceId（例: 日本ならA1VC38T7YXB528）やmarketplaceName（例: "Amazon.co.jp"）が含まれますdeveloper-docs.amazon.com。複数国で販売している場合、取引ごとにどの国のマーケットプレイスか判別できます。
    • relatedIdentifiers（関連ID一覧） – 取引に紐づくビジネスIDの一覧。注文ID・出荷ID・返金ID・支払いグループIDなどが含まれ、それぞれrelatedIdentifierNameとrelatedIdentifierValueの組で提供されますdeveloper-docs.amazon.comdeveloper-docs.amazon.com。例えばORDER_IDには注文番号、REFUND_IDには返金トランザクションID、EVENT_GROUP_IDには支払いイベントグループID（売上の入金グループを表すID）が格納されますdeveloper-docs.amazon.com。このフィールドにより特定の注文や支払いに関連する取引を突き合わせることが可能です。
    • items（商品別明細） – 取引内の商品ごとの追加情報リスト。注文に複数商品が含まれる場合などに、それぞれの商品に関連する手数料や金額内訳を持ちます。
    • breakdowns（内訳明細） – 取引金額の内訳リスト。手数料や税金など、総額を構成する要素が階層構造で格納されますdeveloper-docs.amazon.com。例えば注文の取引であれば「商品代金」「配送料」「手数料」等の区分と金額がbreakdownとして列挙されます。Breakdown要素は更に細分化された内訳を持つこともあり、ツリー構造で詳細な金額構成を追跡できますdeveloper-docs.amazon.comdeveloper-docs.amazon.com。
    • contexts（コンテキスト情報） – 取引に関連する追加メタデータ。取引種類に応じて異なる情報が入ります。例えば**Amazonビジネス（請求書払い）**取引ならdeferralReason（例: "B2B"）やmaturityDate（支払い予定日）が入りdeveloper-docs.amazon.comdeveloper-docs.amazon.com、Amazon Pay経由の取引ならstoreName（店舗名）やpaymentMethodが入る、といった具合ですdeveloper-docs.amazon.comdeveloper-docs.amazon.com。コンテキスト情報により、その取引の背景（どういった支払い手段か、どんなポリシーによる保留か等）を補足できます。

    このようにlistTransactionsのレスポンスは売上・返金・手数料・調整額などあらゆる金銭イベントの詳細を一括で取得できる構造になっています。特にdescriptionやrelatedIdentifiersを見ることで、それぞれの取引が「どの注文の支払いなのか」「返金処理か」「どの入金グループ（支払サイクル）に属するか」等を把握できます。またtransactionStatusとcontextsを組み合わせることで、保留中の金額や支払い済み金額、支払い予定日なども追跡可能です。

    主なユースケースと実践例

    listTransactionsが具体的にどのような場面で役立つか、いくつか実践的なユースケースを紹介します。

    • 会計システムとの連携・日次バッチ処理: 出品者の販売データを社内の会計ソフトや財務システムに取り込む場合、listTransactionsで毎日の取引明細を自動取得することができます。例えば毎日深夜に前日（～当日分）のpostedAfterを指定してAPIを呼び出し、新規取引（売上、返金、調整額など）を取得して社内DBに蓄積するといった運用です。これによりAmazonからの入金サイクルを待たず売掛金や手数料をタイムリーに把握できます。またnextTokenを用いたページングに対応することで、大量データでもバッチ処理で取りこぼしなく取得可能ですdeveloper-docs.amazon.com。レート制限(後述)を踏まえつつ、例えば15分毎に実行して新規取引を随時取り込むリアルタイム連携も可能でしょう。
    • 注文ごとの収益・費用分析: 特定の注文についてAmazon手数料や配送料、プロモーション割引などの明細を確認したい場合にもlistTransactionsが使えます。取得したtransactions一覧からrelatedIdentifiers内のORDER_IDでフィルタすることで、該当注文に関する取引だけを抽出できますdeveloper-docs.amazon.com。例えば注文123が商品の売上で$100発生した場合、そのTransactionにはtotalAmount=$100とdescription=”Order Payment”が含まれ、breakdownsにAmazon手数料や送料などの内訳が示されます。一方で同じ注文123に対する返品が起これば、別のTransactionとしてdescription=”Refund Order”や負のtotalAmountが発生しますdeveloper-docs.amazon.com。このように注文単位で売上・返金・費用を突合することで、1注文あたりの正味収益を自動算出したり、異常な手数料発生を検知したりできます。
    • 支払い（ペイアウト）明細の照合: Amazonは通常14日ごとに出品者に振込（disbursement）を行いますが、その振込額がどの取引から構成されているかを確認するケースです。従来のFinances API (v0) ではlistFinancialEventGroupsで入金グループを取得し、グループIDごとにlistFinancialEventsで中身を取る必要がありましたdeveloper-docs.amazon.com。新しいlistTransactionsを使えば、まずFinances API v0のlistFinancialEventGroupsで「支払日ごとのグループID」を取得し（例: グループID = X）developer-docs.amazon.comdeveloper-docs.amazon.com、次にlistTransactionsでその支払日の範囲に該当する取引（postedAfterとpostedBeforeを振込期間に設定）を取得します。その結果からrelatedIdentifiers内のEVENT_GROUP_IDがXに一致するTransactionを抽出すると、その入金に含まれる全取引（売上、返金、調整額など）の一覧が得られますdeveloper-docs.amazon.comdeveloper-docs.amazon.com。transactionStatusをRELEASEDでフィルタすることで支払済みの取引のみに絞り込むこともできますdeveloper-docs.amazon.comdeveloper-docs.amazon.com。このように、振込金額と各取引の対応をチェックすることで、Amazonからの入金明細を自前で再現・検証することができます。たとえば会計上、振込額と各注文の売上-返金-手数料の合計が一致するかを照合するなどの用途です。
    • 保留中（Deferred）取引の管理: ビジネス向け請求書払い(B2B)注文や7日後出荷ポリシー(7-Day Delivery)等、商品の引渡し後に支払いが確定するケースでは取引が一時的にDEFERRED（支払い保留）状態になりますdeveloper-docs.amazon.com。listTransactionsではデフォルトで保留中・支払済みすべての取引を返しますがdeveloper-docs.amazon.com、transactionStatusパラメータを指定することで例えばDEFERREDのものだけ取得する、といったステータス別のフィルタが可能ですdeveloper-docs.amazon.com。これを利用して、「保留中の取引リスト」を定期的にチェックし未入金の売上を管理したり、一定期間経過してもRELEASEDに変わらない取引があればアラートを出す、というような運用も考えられます。特にAmazonビジネス（法人向け販売）を行っている場合、請求書払い注文の動きを追跡するのに有用です。なお本機能（transactionStatusでのフィルタリング）は2024年のアップデートで追加されたものですdeveloper-docs.amazon.com。
    • マルチマーケットプレイスの収益統合: 日本だけでなく米国や欧州など複数リージョンで販売している出品者にとって、各国の売上・費用データを統合的に把握することも重要です。listTransactionsはリージョンごと（後述）にエンドポイントが異なりますが、各リージョンからデータを取得し、sellingPartnerIdやmarketplaceIdで紐づければグローバル全体の取引データを集約できます。レスポンス内のcurrencyCodeで通貨単位もわかるのでdeveloper-docs.amazon.com、例えば日本円・米ドル・ユーロそれぞれで売上/費用を集計し、本社通貨に換算するといった財務レポーティングも可能です。加えて、マーケットプレイス固有のプログラム（後述のAmazon Haul等）に起因する取引もデータ上で識別できるため、国ごとの特殊な収益源についてもカバーできますdeveloper-docs.amazon.com。

    以上のように、listTransactionsは日々の会計処理から高度な財務分析まで幅広く応用できます。特に注文単位・入金単位・ステータス単位でデータ抽出できる柔軟性を持つため、開発者はクエリ条件を工夫して必要な情報をピンポイントに得ることが可能です。

    リージョン（地域）別のポイント: 日本・US・EUの相違

    次に、日本のAmazonマーケットプレイスを主としつつ、地域ごとの留意点を整理します。

    エンドポイントURLとAWSリージョン: SP-APIは呼び出すリージョンごとにエンドポイントURIが異なる点に注意が必要ですdeveloper-docs.amazon.com。例えば、日本やシンガポール、オーストラリアのマーケットプレイスは**「Far East」リージョンに分類され、エンドポイントはhttps://sellingpartnerapi-fe.amazon.com（AWSリージョン: us-west-2）になりますdeveloper-docs.amazon.com。一方、米国・カナダ・メキシコ・ブラジルは「North America」リージョンでhttps://sellingpartnerapi-na.amazon.com（us-east-1）、欧州諸国やインドは「Europe」リージョン**でhttps://sellingpartnerapi-eu.amazon.com（eu-west-1）と、それぞれ異なるドメインです developer-docs.amazon.com。間違ったリージョンのエンドポイントにリクエストするとデータが取得できない（認証エラーになる）ため、対象マーケットプレイスに合ったエンドポイントを選ぶことが重要ですgithub.com。

    マーケットプレイスID: listTransactionsのクエリパラメータmarketplaceIdで特定のマーケットプレイスを選択できますdeveloper-docs.amazon.com（省略時は認証したセラーの該当リージョン全マーケットプレイスが対象）。主要マーケットのIDは以下の通りです（抜粋）developer-docs.amazon.comdeveloper-docs.amazon.com。

    日本の場合、marketplaceId="A1VC38T7YXB528"を指定することでAmazon.co.jpの取引に絞った取得が可能です。逆に同一リージョン内で複数国マーケットプレイスを持つ欧州のようなケースでは、このパラメータで国別にデータをフィルタする運用が考えられます。例えばヨーロッパリージョンの統合アカウントを持つセラーでは、UKやDEなど各国分の取引が一緒に取得されるため、marketplaceIdを指定しないと複数国の取引が混在します。その場合、レスポンス内のmarketplaceDetails.marketplaceNameを見ることで国を判別できますがdeveloper-docs.amazon.com、必要に応じてパラメータで国ごとに分けて取得すると整理しやすいでしょう。

    通貨と金額表示: 各取引のtotalAmountはマーケットプレイスごとの通貨で表示されます（日本ならJPY、米国ならUSD、EU各国ならEURやGBP等）。レスポンスには通貨コードが明記されるためdeveloper-docs.amazon.com、異なる通貨間のデータでも区別可能です。グローバル展開している場合、通貨換算が必要な分析ではこのcurrencyCodeを参照して処理を行います。

    プログラムや税制の違い: Amazon特有の販売プログラムや税制度によって、取引データに若干の違いが現れる場合があります。例えば米国で最近開始された「Amazon Haul」というプログラムでは、対象となる取引のstoreName（コンテキスト情報）がAMAZON_HAULと表示されますdeveloper-docs.amazon.com。これは2024年のアップデートでlistTransactionsがその識別に対応したもので、日本では現時点で該当しません（Amazon Haulプログラムは米国限定）developer-docs.amazon.com。また欧州では付加価値税（VAT）の扱いがありますが、breakdowns内に税額が含まれる形で表示されるため、国ごとの税区分もデータ上で把握可能です（例：欧州の手数料内訳にVAT項目が含まれる）。

    言語の違い: listTransactionsのフィールド名や値は基本英語（ISOコード等）で標準化されています。マーケットプレイス名は "Amazon.co.jp" のようにローカライズされた名称が入りますが、取引説明(description)などは "Refund Order" といった英語表記ですdeveloper-docs.amazon.com。ノンエンジニアの方が説明する際は適宜日本語に言い換え（例えば「Refund Order = 注文の返金」）ながら伝えると理解されやすいでしょう。

    総じて、listTransactionsの機能自体はグローバル共通ですが、接続先とデータ解釈で地域ごとの前提を押さえる必要があります。日本向けセッションでは、日本マーケットプレイスでの利用方法を中心に説明しつつ、他リージョンにも展開可能であることを補足すると良いでしょう。

    listTransactions利用時の制限事項・注意点

    エンジニアが実装・統合する際に知っておくべき制限事項や注意点をまとめます。

    • API使用権限: 前述のとおり、SP-APIのファイナンス関連データは機密度が高いため**「Finance and Accounting」ロールの権限**が必要ですdeveloper-docs.amazon.com。開発者は自社アプリケーションの権限設定と、セラー側からの認可（Consent）の両方で適切なロールが付与されていることを確認してください。権限がない場合、listTransactions呼び出しはエラー（アクセス拒否）となります。
    • レート制限（APIスループット）: listTransactionsの標準的なレート制限は0.5リクエスト/秒（1分あたり約30リクエスト）でバースト許容量10件ですdeveloper-docs.amazon.com。この数値は他の多くのAPIより低めに設定されていますので、大量データ取得時は計画的な実行が必要です。例えば初回に過去数ヶ月分の取引を一括取得する場合、500件ずつページングしながら数十～数百回のリクエストが必要になる可能性があります。その際は一定間隔でウェイトを入れる、もしくは**次の請求可能時刻（x-amzn-RateLimit-Limitレスポンスヘッダ）**を参照して待機するなどの制御が推奨されますdeveloper-docs.amazon.com。なお、頻繁に429エラー（Quota Exceeded）が出る場合はリクエスト間隔を延ばす対応が必要です。
    • データ反映の遅延: Amazon側の内部処理により、注文が発生してから取引イベントに反映されるまで最大48時間遅れる場合がありますdeveloper-docs.amazon.com。そのため、例えば当日発送完了した注文の手数料を即日に取得しようとしてもうまく取れないことがあります。この仕様は公式にも明記されているのでdeveloper-docs.amazon.com、最新48時間のデータは未確定と捉え、数日後に改めて取得するか、次回バッチ時に補完取得する設計にすると安心です。
    • 日付範囲の指定と上限: クエリパラメータのpostedAfter（取得開始日時）は必須で、postedBefore（終了日時）はオプションですdeveloper-docs.amazon.com。開始日時は現在時刻の2分前まで、終了日時を指定する場合は開始より後かつ現在の2分前までという制約がありますdeveloper-docs.amazon.com。さらに開始と終了の間隔が180日を超えるとデータを返さないという上限もありますdeveloper-docs.amazon.com。したがって一度のAPI呼び出しで取得できる期間は最大でも約6ヶ月間分となります。長期間のデータを取得したい場合は、180日以内の範囲に分割して複数回リクエストする必要があります。例えば過去1年分を取得するなら、180日毎に区切って計2回以上に分ける設計が必要です。
    • パラメータ（ステータス・マーケットプレイス）: 追加のクエリパラメータとして、marketplaceIdとtransactionStatusがあります。marketplaceIdは特定マーケットプレイスだけに絞る場合に指定し、省略するとリージョン内すべてが対象になりますdeveloper-docs.amazon.com。transactionStatusは先述のように特定ステータス（RELEASED/DEFERRED等）の取引のみ取得したい場合に使えますdeveloper-docs.amazon.com。2024年のアップデートでこのフィルタ機能が追加され、それ以前は常に全ステータス返却でしたdeveloper-docs.amazon.com。フィルタをかけすぎてデータが0件になるケースもあるため、必要に応じ使い分けます（例えば通常運用では未指定で全取引取得し、分析時にコード側でステータスを見る、といった方法もあります）。
    • nextTokenの扱い: listTransactionsのレスポンスにnextTokenが含まれる場合、速やかに次のリクエストに使用することが推奨されます。一般的な設計では、初回リクエストでデータを取得 → nextTokenありならそれを使って次ページ取得、というループを組みます。この際、nextTokenには有効期限がある可能性が指摘されています（公式明記はないものの、一部ディスカッションでトークンが1時間程度で失効するとの情報あり）github.com。大量ページを順番に処理する場合、間隔を空けすぎず続けて呼び出しを完了する方が確実です。
    • エラーハンドリング: 400/403エラー等が発生した場合のメッセージも確認しておきます。認証や権限不備ならAccess to requested resource is denied（403）となり、パラメータ形式不備なら400エラーとなりますdeveloper-docs.amazon.com。またデータ量が大きすぎると413 (Payload Too Large) になることもありえますdeveloper-docs.amazon.com。429（過剰リクエスト）はレート制限超過時に返りdeveloper-docs.amazon.com、この場合は一定時間待って再試行してください。こうしたエラーはレスポンスボディにerrors配列で詳細コードとメッセージが返るのでdeveloper-docs.amazon.com、ログに記録しつつ必要に応じて再処理ロジックを実装すると堅牢です。
    • 旧APIとの関係: Amazonは従来のFinances API v0（旧MWSから引き継ぎ）の提供も続けていますが、listTransactionsは新しい統合エンドポイントとして位置付けられていますdeveloper-docs.amazon.com。現状、入金グループ（FinancialEventGroup）の取得など一部機能は旧APIに頼るケースがありますがdeveloper-docs.amazon.com、基本的には新APIで多くの情報がまかなえるよう設計されています。開発の新規実装ではこのv2024-06-19版を使うことが推奨されますが、移行期間中はv0のlistFinancialEvents等とのデータ突合でチェックすることも考えられます。セッションでは、旧APIの存在に触れつつも**本題は新APIの利点（統一された取引取得）**にフォーカスすると良いでしょう。

    以上のポイントを踏まえ、listTransactionsを利用する際には権限管理と**データ取得設計（日時範囲の分割、ページング、リトライ制御）**に注意して実装を進めるようアドバイスします。

    実装のための参考リソース

    最後に、エンジニアがlistTransactionsを実装・学習する際に役立つ公式およびコミュニティのリソースを紹介します。

    • Amazon公式ドキュメント: [Amazon SP-API 開発者ドキュメント – Finances APIリファレンス]developer-docs.amazon.comおよび[Finances API ユースケースガイド]developer-docs.amazon.comは必読です。リファレンスにはlistTransactionsのエンドポイント仕様やレスポンス構造、パラメータ要件が詳細に記載されています。ユースケースガイドには本APIを使ったチュートリアル（最新取引の取得や支払明細の確認手順）があり、実シナリオでの利用方法を学べますdeveloper-docs.amazon.comdeveloper-docs.amazon.com。
    • SP-APIリリースノート: [SP-API Release Notes（日本語版）]developer-docs.amazon.comには、listTransactionsに関する更新情報が載っています。例えば取引ステータスでのフィルタリング追加やAmazon Haul取引の識別といった最近の変更点が記載されていますdeveloper-docs.amazon.com。最新機能を漏れなく把握するために参照してください。
    • マーケットプレイスID & エンドポイント一覧: 複数リージョン対応を行う場合、[マーケットプレイスID一覧]developer-docs.amazon.comと[エンドポイント一覧]developer-docs.amazon.comの公式ページが役立ちます。主要国のMarketplace IDや対応エンドポイント（NA/EU/FE）が表でまとまっており、実装時の設定ミス防止に便利です。
    • Amazon開発者フォーラム: Amazon Selling Partner APIの公式フォーラム（Seller Centralの開発者向けフォーラム）では、エラー事例や実装上の疑問に対するQ&Aが多数あります。listTransactionsに関連するトピックとして、「データが取得できない」「Access Deniedエラーが出る」等の質問があり、その回答からエンドポイントの選択間違いや権限漏れといった課題に気づけますgithub.com。困った際はフォーラム検索も活用しましょう。
    • コミュニティ提供のSDK/ライブラリ: SP-APIを利用しやすくするための非公式SDKもいくつか存在します。例えばPython向けのpython-amazon-sp-apiライブラリや、JavaScript(Node)向けのSDKがあります。コミュニティが提供するこれらSDKではlistTransactionsが実装されており、数行のコードで認証とAPI呼出が可能です。公式ではC#やJava用のSDKテンプレートも提供されていますdeveloper-docs.amazon.com。既存ライブラリの利用は開発効率を上げますが、内部でAPI制限管理など把握しておく必要はあります。時間が許せば、こうしたSDKやサンプルコードにも触れてみると良いでしょう。
    • Postmanコレクション: コーディング不要でAPIを試せるツールとしてPostmanがあります。Amazon公式のSP-API用コレクションが公開されており、その中に[Transactions] list Transactionsのリクエスト例も含まれていますpostman.com。正しい認証情報とパラメータを設定すれば、Postman上で実際のレスポンスを確認可能です。ノンエンジニアの講師がデモを行う場合にも有用なので、一度設定方法を確認しておくことをおすすめします。

    以上を踏まえ、本セッションではlistTransactionsの概要から具体例、注意点までを網羅的に扱います。公式資料の該当箇所へのリンクも含めていますので、必要に応じて参照してください。参加者であるエンジニアの方々には、このセッションを通じて**「SP-APIのファイナンス取引データをこう活用できる」**という具体的なイメージと、実装上の勘所を持ち帰ってもらうことが目標です。質疑応答の時間も設けていますので、疑問点を共有しながら理解を深めていきましょう。

    未分類
    よかったらシェアしてね！
    • URLをコピーしました！
    目次