SPAPIとは

SPAPI(Selling Partner API)とはAmazonが提供するAPIで、Amazonマーケットプレイスでビジネスを行う販売者（Selling Partner）が、自身のビジネスプロセスを効率化し、販売活動をサポートするためのAPIです。
RESTfulアーキテクチャを採用しており、以下のように用途ごとに多岐にわたるエンドポイントが提供されています。

・商品管理（Product APIs）
・注文管理（Orders API）
・FBA（Fulfillment By Amazon）に関する機能
・レポート（Reports API）
・在庫・納品（Inventory APIs）など

Fulfillment Inbound APIとは

SPAPIで提供される、FBA納品作業ににかかる、出荷作成、管理、送信するためのワークフローを構築できます。

新バージョンへの移行

概要

Fulfillment Inbound APIは2024年3月にv2024-03-20をリリースしており、従来使用されていたv0の一部の機能が2024年12月20日を以て廃止になるそうです。
※v0公式ドキュメントで確認できますが、廃止にならないものが赤文字でwarningと表示されているのでぱっと見間違えそうですね。。

今回、v0で実装している部分をv2024-03-20に移行するわけですが、v0のエンドポイントが16個であったのに対して、v2024-03-20のエンドポイントはなんと45個(多すぎだろ)。

一応移行用のドキュメントもあるようで、新旧で対応するエンドポイントを見ることができます(おそらく全てではなく主要なものだけと思われます)。
以下の画像を見る限りv2024-03-20ではかなり処理が細分化されているようですね。

実際にやってみる

詳しい作業内容は社内ノウハウも含みますので、今回はざっくり作業内容を記載しその中での注意点を記載させていただきます。

今回自分が行った作業としては発送後の荷物に対する追跡番号を更新するというフローについての移行です。

追跡番号更新エンドポイントの新旧表は以下の通り。

おや？createInboundShipmentPlanと比べると新旧が1 : 1となっておりかなり簡単そうですね！
ところがどっこい、そんな甘いものではありませんでした。

注意点

その1

v0で使用していたPutTransportDetailsではshipmentIdを指定してリクエストしていたのですが、updateShipmentTrackingDetailsではinboundPlanId, shipmentId, boxIdがリクエストに必要となります。
ここで重大発表です。v0で使用していたshipmentIdとv2024-03-20のshipmentIdは別物です(青天の霹靂)。
v0で使用していたshipmentIdはv2024-03-20のshipmentConfirmationIdが対応するらしいです。

「ほなv2024-03-20のshipmentIdを取得する必要があるなぁ」と思いv0のgetShipmentsのようにshipments一覧を取得できる類似のエンドポイントがv2024-03-20にないか確認したところ無いらしい(絶望)。

その2

その1で述べたv0のgetShipmentsに対応するエンドポイントが用意されていないという点にもつながるのですが、updateShipmentTrackingDetailsにはboxIdが必要です。
そしてboxIdを取得するにはgetShipmentなどのレスポンスが必要であり、そのgetShipmentを呼ぶためにはshipmentIdとinboundPlanIdが必要となります。

という風に必要なリクエストを行うためのIDを揃えるために上位エンティティのID情報を取得する必要があり、新旧表のように単純に旧のエンドポイントを新に変更すればいいというものではなくそれに付随する複数のエンドポイントの実装が必要になります。

その3

その2で述べた、上位エンティティのID情報を取得するにあたって、すべてのエンティティの原点となる納品プランのリストを取得するlistInboundPlansでの注意点です。

プランのstatusは以下の3種類があり、公式ドキュメントではstatusはoptionalなパラメータとなっておりデフォルト値も設定されていません。

「ほな指定せんかったら全ステータスが取得できるんかぁ」と思ったそこのあなた、違います！
何も指定しなかった場合はACTIVEのプランリストが取得されます。
※ACTIVEを指定しても、しなくても同じ結果が得られます。

さいごに

今回はv2024-03-20移行時に発見した注意点を記載させていただきましたが、今後修正される可能性もありますので、あくまで現時点での情報となります！
記載している情報に間違い等あればご指摘いただければ幸いです。
今後実装を進める中で新たな注意点が見つかればまた発信していこうと思います。