開発

楽天APIの使い方:2026年移行後のaccessKey認証と商品検索・RMS受注APIの実装

楽天APIの使い方:2026年移行後のaccessKey認証と商品検索・RMS受注APIの実装

楽天APIと呼ばれるものは2系統あります。楽天市場の商品やランキングなど公開データを返す「楽天ウェブサービス」と、出店店舗が自店の受注・在庫・商品を操作する「RMS WEB SERVICE」です。前者は2026年に接続先ドメインと認証方式が変わり、古い記事のコードはそのままでは動きません。この記事では、2系統の違い、移行後の楽天ウェブサービスをPythonで呼び出す手順、RMS受注APIのESA認証と受注取得の実装、自社で開発するか一元管理ツールに任せるかの判断までを、2026年11月時点の情報で解説します。

まとめ|楽天APIの2系統と2026年移行後に正しく動かすための要点

商品情報を取りたいだけなら楽天ウェブサービス、自店の注文を基幹システムへ流したいならRMS WEB SERVICEです。両者は登録窓口も認証方式も別物で、片方のキーでもう片方は呼べません。

楽天ウェブサービスは、接続先がopenapi.rakuten.co.jpに変わり、アプリの再登録で得るapplicationIdとaccessKeyの両方が必須になりました。エラーは400なら渡し方、403なら値の誤りか接続元の許可設定、と切り分けられます。

RMS受注APIは、店舗が発行するserviceSecretとlicenseKeyをESA形式でヘッダに載せます。licenseKeyの有効期限を過ぎると、更新忘れによる受注連携の停止につながる仕組みです。注文件数が多く基幹側の処理に独自の要件がある店舗は自社開発、楽天を含む数モールの受注をまとめたいだけなら一元管理ツールが向きます。

楽天ウェブサービスとRMS WEB SERVICEの違いと使える楽天APIの範囲

「楽天 API」で検索して最初に出るのは楽天ウェブサービスの資料ですが、受注連携をしたい店舗が必要とするのはRMS側です。目的に合わない側を調べ始めると、登録まで進んでから使えないと分かります。

商品検索やランキングなど公開データを返す楽天ウェブサービスの対象

楽天ウェブサービスは、楽天会員なら誰でもアプリを登録して使える公開APIです。公式Ruby SDKの2026年移行対応のプルリクエストが対象として挙げているのは、楽天市場(商品検索・ジャンル・ランキング・タグ)、楽天ブックス、楽天Kobo、楽天レシピ、楽天GORA、楽天トラベルの各APIです。同じプルリクエストでは、製品検索API(Product)の2017年4月26日版が提供終了として削除されています。

返ってくるのは、楽天市場に掲載された他店を含む公開情報です。自店の注文や在庫数、顧客情報は一切取れません。価格比較サイト、アフィリエイト、商品リサーチの用途が中心になります。

出店店舗が受注・在庫・商品を扱うRMS WEB SERVICEの利用条件

RMS WEB SERVICEは、楽天市場の出店店舗だけが使えるAPIです。店舗管理画面(RMS)の「WEB APIサービス」から利用を申請し、serviceSecretとlicenseKeyを発行します。受注、在庫、商品、カテゴリなどの機能ごとに利用可否を設定する方式で、受注を取るならrpay.order.searchOrderとrpay.order.getOrderを利用可能にします。

仕様書は店舗向けの画面内にあり、外部からは閲覧できません。2026年11月16日に仕様書のドメインへアクセスすると403が返りました。受託開発で組む場合は、店舗側から仕様書の該当ページを共有してもらう段取りを最初に決めておきます。APIで2つのシステムをつなぐ考え方そのものはAPI連携の仕組みとデータ連携との違いで整理しています。

2026年の楽天ウェブサービス移行で変わったドメイン・認証・版の対応表

移行前に書かれたコードが動かない原因は、接続先・認証・接続元の許可の3か所に分かれます。順に直せば動きます。

app.rakuten.co.jpからopenapi.rakuten.co.jpへの移行

公式SDKのプルリクエストは、2026年5月に予定された一斉移行への対応として、接続先をapp.rakuten.co.jpからopenapi.rakuten.co.jpへ移しています。移行を扱った開発者の記事では、旧方式の停止日を2026年5月14日としています。

項目 移行前 移行後(2026年11月時点)
ドメイン app.rakuten.co.jp openapi.rakuten.co.jp
楽天市場の商品検索のパス /services/api/ /ichibams/api/
認証に必要な値 applicationId(数字) UUID形式のID+キー
接続元の制限 なし 許可したWebサイトまたはIPアドレス

移行後の認証に必要なのは、applicationId(UUID形式)とaccessKeyです。パスはドメインと一緒に変わっています。2026年11月16日に認証情報なしで要求を送ったところ、/ichibams/api/配下は「applicationIdが必要」という400を返し、/services/api/配下は404でした。公式SDKの最新版は後者のパスを指したままで、パスと版を/ichibams/api/の20260701版へ直す修正の提案は2026年8月に出されたものの取り込まれていません。版番号もパスの一部なので、使うAPIごとに公式ドキュメントの現行の版を確かめて書き換えます。

applicationIdの再発行とaccessKeyをヘッダで送る方式の確認

旧アカウントで発行した数字のapplicationIdは使えず、楽天のDeveloper Dashboardでアプリを登録し直します。再登録で得るのは、UUID形式のapplicationIdとpk_で始まるaccessKeyです。

accessKeyを渡す方式は、ヘッダとクエリパラメータの2通りです。公式SDKの設定クラスは既定でaccessKeyという名前のHTTPヘッダに載せ、設定でクエリパラメータにも切り替えられます。同SDKのプルリクエストには、公式ドキュメントにあるAuthorization: Bearer形式の記載は誤りで、accessKeyヘッダが正しいと楽天のサポートに確認した、という注記があります。

ヘッダで送る方式を勧めます。クエリに入れたキーは、アクセスログやプロキシのログにURLごと残るからです。キーは環境変数かシークレット管理に置き、リポジトリに書きません。漏れたキーの失効手順まで含めた管理はAPI不正アクセス対策のトークン失効とレート制限を参考にしてください。

Webアプリケーション型とバックエンド型で違う接続元の許可設定

移行後はアプリ登録時に、呼び出し元として許可するWebサイト(ドメイン)か、固定のIPアドレスを登録します。ブラウザから呼ぶWebアプリケーション型は送信元サイトで、サーバーやバッチから呼ぶバックエンド型は送信元IPで照合されます。

ここを取り違えた例が、移行後の開発者の記事に複数報告されています。サーバーのcronから呼ぶのにWebアプリケーション型で登録すると、キーが正しくても認証が通りません。Google Apps Scriptから呼ぶ場合は送信元IPが固定できないため、Webアプリケーション型でscript.google.comを許可し、RefererとOriginヘッダを明示する方法が紹介されています。社内の基幹連携なら、固定IPを持つサーバーからバックエンド型で呼ぶ構成が最も安定します。

楽天市場の商品検索APIをPythonから呼び出す手順とエラーの切り分け

ここでは外部パッケージを使わず、Python 3の標準ライブラリだけで商品検索APIを呼びます。サーバーからの実行を想定し、アプリはバックエンド型で登録している前提です。

Developer Dashboardのアプリ登録から環境変数へ保存するまでの手順

  1. 楽天会員でDeveloper Dashboardにログインし、アプリを新規登録する
  2. アプリの種類でバックエンド型を選び、実行するサーバーの固定IPアドレスを許可に入れる
  3. 発行されたapplicationIdとaccessKeyを、画面のコピー機能で全文控える
  4. 実行環境の環境変数RAKUTEN_APP_IDとRAKUTEN_ACCESS_KEYに保存する

3番目で手入力や範囲選択に頼ると、画面上で省略表示されたaccessKeyの一部だけを写す事故が起きます。値が短いまま403が消えないときは、まずキーの文字数を疑ってください。

標準ライブラリだけで商品を検索しformatVersion=2で受け取る実装

import json
import os
import time
import urllib.error
import urllib.parse
import urllib.request

# 版(末尾の日付)はURLの一部。公式ドキュメントで現行の版を確認して書き換える
ENDPOINT = "https://openapi.rakuten.co.jp/ichibams/api/IchibaItem/Search/20220601"


def search_items(keyword, page=1):
    params = {
        "applicationId": os.environ["RAKUTEN_APP_ID"],
        "keyword": keyword,
        "hits": 30,
        "page": page,
        "sort": "standard",
        "format": "json",
        "formatVersion": 2,  # Items を1段浅い配列で受け取る
    }
    req = urllib.request.Request(
        ENDPOINT + "?" + urllib.parse.urlencode(params),
        headers={
            "accessKey": os.environ["RAKUTEN_ACCESS_KEY"],  # クエリではなくヘッダで送る
            "User-Agent": "shop-sync/1.0",
        },
    )
    for attempt in range(3):
        try:
            with urllib.request.urlopen(req, timeout=20) as res:
                return json.load(res)
        except urllib.error.HTTPError as e:
            if e.code == 429 and attempt < 2:
                time.sleep(2 * (attempt + 1))  # 流量制限。待ってから再試行
                continue
            raise RuntimeError(f"楽天API {e.code}: {e.read().decode('utf-8', 'replace')}") from None


if __name__ == "__main__":
    data = search_items("コーヒー豆 1kg")
    for item in data["Items"]:
        print(item["itemPrice"], item["itemName"], item["itemUrl"])

formatVersionを2にすると、Itemsの各要素が商品のオブジェクトそのものになります。指定しないと1件ずつItemというキーで包まれた形で返り、上のループはKeyErrorで止まります。公式SDKで設定されている既定値も、同じく2です。

検索結果の価格は、そのまま最安値として扱えません。1つの商品ページに複数の容量や色を載せた商品では、その中で最も安い組み合わせの価格が返るためです。価格比較に使うなら、商品名に含まれる容量の語で絞り込む処理を後段に置きます。

400・403・429など応答コード別に原因を切り分ける判定表

2026年11月16日に、ダミーの値で認証まわりの応答を確かめた結果と、公式SDKのエラー定義を合わせると、次のように切り分けられます。

応答 メッセージの例 見直す箇所
400 applicationIdが必要 applicationIdの付け忘れ
400 accessKeyが必要 accessKeyの付け忘れ・ヘッダ名の綴り
403 Invalid Access Key キーの値・コピー漏れ・接続元の許可
404 Resource not found パスと版番号
429 Too Many Requests 呼び出し間隔
503 Service Unavailable 楽天側の障害・保守

表の「〜が必要」は、応答本文では「applicationId must be present」「accessKey must be present」と英語で返ります。400と403の違いが切り分けの起点です。400なら値の渡し方、403なら値そのものか許可設定が原因と絞れます。429はRFC 6585で定義された流量超過の応答です。移行後は1秒間隔でも429が出たという報告があるため、一括取得のバッチは1.5秒以上の間隔を空け、429を受けたら待ってから再試行する作りにします。

RMS受注APIのESA認証と受注の検索・取得を基幹へつなぐ実装

RMS側は、店舗が自分の注文を取りに行くAPIです。基幹システムや倉庫管理へ注文を流す連携は、受注の検索と詳細の取得を定期的に回す形で組みます。

serviceSecretとlicenseKeyでESA認証用ヘッダを作る手順

RMSのAPIは、serviceSecretとlicenseKeyをコロンでつないでBase64にし、先頭にESAと空白を付けた値をAuthorizationヘッダに入れます。2026年11月16日に受注検索の窓口へ送った要求では、ヘッダなしで400(ES04-01)、ダミー値のESAヘッダで401(ES01-01)が返りました。401が返る段階まで来ていれば、ヘッダの形式は受け付けられています。

import base64
import json
import os
import urllib.request
from datetime import datetime, timedelta, timezone

JST = timezone(timedelta(hours=9))
BASE = "https://api.rms.rakuten.co.jp/es/2.0/order"


def esa_header():
    raw = f'{os.environ["RMS_SERVICE_SECRET"]}:{os.environ["RMS_LICENSE_KEY"]}'
    return "ESA " + base64.b64encode(raw.encode("utf-8")).decode("ascii")


def post(path, payload):
    req = urllib.request.Request(
        BASE + path,
        data=json.dumps(payload).encode("utf-8"),
        method="POST",
        headers={
            "Authorization": esa_header(),
            "Content-Type": "application/json; charset=utf-8",
        },
    )
    with urllib.request.urlopen(req, timeout=30) as res:
        return json.load(res)

serviceSecretは店舗ごとに固定であるのに対し、licenseKeyは期限つきという性質です。2つを同じ設定ファイルに並べると、licenseKeyだけを差し替える運用で書き換え漏れが起きやすくなります。licenseKeyはシークレット管理側で独立に更新できる形にしておきます。

searchOrderで注文番号を集めてgetOrderで明細を取る2段階の取得

受注APIは、条件に合う注文番号の一覧を返すsearchOrderと、番号を指定して明細を返すgetOrderの2段階です。直近1時間の注文を取る例は次のとおりです。

FMT = "%Y-%m-%dT%H:%M:%S%z"  # 例 2026-11-16T10:00:00+0900


def fetch_recent_orders(hours=1):
    now = datetime.now(JST)
    found = post("/searchOrder/", {
        "dateType": 1,  # 絞り込みに使う日時の種類。値の定義はRMSの仕様書で確認する
        "startDatetime": (now - timedelta(hours=hours)).strftime(FMT),
        "endDatetime": now.strftime(FMT),
        "PaginationRequestModel": {"requestRecordsAmount": 100, "requestPage": 1},
    })
    numbers = found.get("orderNumberList") or []
    if not numbers:
        return []
    detail = post("/getOrder/", {
        "orderNumberList": numbers[:100],  # 1回の件数上限は仕様書で確認する
        "version": int(os.environ["RMS_ORDER_API_VERSION"]),  # 応答形式の版。仕様書の現行値を設定
    })
    return detail.get("OrderModelList") or []

検索の期間は、前回の取得終了時刻から今回の実行時刻までとし、両端を少し重ねます。重なった分の注文は注文番号で重複を除けば済みます。期間に隙間を作るほうが、取りこぼしに気づけないため危険です。

基幹側へ書き込む処理は、同じ注文番号を2回受け取っても伝票が2重にできない作りにします。楽天側で注文内容が変わった場合(数量変更・キャンセル)を拾うには、注文日ではなく更新日時で検索する日時の種類を選ぶ必要があり、どの値が該当するかは仕様書で確認します。

licenseKeyの期限切れで受注連携が止まる事故と更新手順の設計

licenseKeyには有効期限があり、期限を過ぎると受注の取り込みが401で止まります。連携先サービスのヘルプでも、つながらなくなったらまず期限を確認するよう案内されています。更新はRMSのWEB APIサービスの画面で新しいキーを発行し、連携側の設定を書き換える手作業です。

  • 発行日と期限をシークレット管理のメタ情報に記録し、期限の2週間前に担当者へ通知する
  • 401(ES01-01)を受けたら、再試行を繰り返さずに即時通知して取り込みを止める
  • キー更新の作業者を1人に固定せず、RMSの権限を持つ2人以上で手順書を共有する

止まった期間の注文は、復旧後に期間を遡って検索すれば取り直せます。ただし出荷が遅れた分は戻りません。期限切れを障害ではなく定期作業として扱い、カレンダーに入れておくのが最も確実な対策です。

楽天APIを自社開発で組むか一元管理ツールに任せるかの判断基準

受注連携の実装手順は上のとおり数十行で書けます。判断が分かれるのは、それを何年も保守する価値があるかどうかです。

楽天の受注・在庫連携を自社開発すべき店舗の業務条件と注文規模

自社開発を選ぶのは、基幹側の処理に既製ツールが合わない店舗です。たとえば、受注時に自社の生産計画や引当ルールで在庫を割り当てる、セット商品を部品単位で在庫から落とす、法人向けの掛売りと同じ伝票体系に楽天の注文を載せる、といった要件です。

この場合、既製ツールの出力を基幹の形式へ変換する中間処理を結局作ることになります。ツールの月額と中間処理の保守を払うより、楽天のAPIから基幹へ直接つなぐほうが部品を減らせる構成です。楽天以外のモールも同じ基幹へつなぐなら、モールごとの差をアダプタとして分け、注文の共通形式を自社側で持つ設計にします。

一元管理ツールで要件を満たし楽天APIの個別開発を見送るべき場面

楽天・Amazon・Yahoo!ショッピングなど複数モールの受注を1画面で処理し、在庫数を各モールへ配るだけなら、楽天APIの個別開発は見送ります。ネクストエンジンやGoQSystemなどの一元管理ツールは、RMSのAPI仕様の変更にも提供側が追従する仕組みです。licenseKeyの更新作業は残りますが、仕様変更のたびに自社でコードを直す負担はなくなります。

注文が1日数十件で、基幹側も会計ソフトへ売上を入れる程度なら、自社開発の保守費は回収できません。ツールの選び方はEC受注管理システムの機能と費用相場、在庫の同期方式はEC在庫管理システムの在庫連携と受注同期で比較しています。既製ツールでは基幹側の要件が満たせない、楽天APIと基幹システムの連携を設計から任せたい場合は、ECシステム開発で要件の整理から相談できます。

楽天APIの使い方と楽天ウェブサービス移行に関するよくある質問

楽天APIの利用でよく出る疑問をまとめました。

楽天APIは無料で使えますか?

楽天ウェブサービスは、楽天会員がアプリを登録すれば料金なしで使えます。呼び出し回数には流量制限があり、超えると429が返ります。RMS WEB SERVICEは出店店舗向けの機能で、利用には楽天市場への出店契約とRMSでの利用申請が前提です。費用の有無や条件は出店プランごとに異なるため、RMSの案内で確認してください。

楽天APIで自分の店舗の注文や在庫を取得できますか?

楽天ウェブサービスでは取得できません。返すのは楽天市場に掲載された公開情報だけです。自店の注文はRMS WEB SERVICEの受注API、在庫数は同じくRMSの在庫APIで扱います。どちらもRMSで発行するserviceSecretとlicenseKeyが必要で、楽天ウェブサービスのapplicationIdやaccessKeyでは呼べません。

移行前のapplicationIdはそのまま使えますか?

使えません。2026年の移行で、applicationIdは数字の形式からUUID形式に変わりました。Developer Dashboardでアプリを登録し直し、新しいapplicationIdとaccessKeyを発行します。旧ドメインに旧形式のIDで要求すると、2026年11月16日時点でも「specify valid applicationId」という400が返ります。

GASやPHPから楽天APIを呼ぶときの注意点は何ですか?

Google Apps Scriptは送信元IPを固定できないため、Webアプリケーション型でアプリを登録し、許可するWebサイトにscript.google.comを入れて、RefererとOriginヘッダを付けて呼ぶ方法が報告されています。PHPなど固定IPのサーバーから呼ぶなら、バックエンド型で登録し、accessKeyヘッダを付けます。登録の種類を決める基準は、使用言語よりも、どこから呼び出すかという実行元です。

楽天APIのアクセス制限は1秒に何回までですか?

2026年11月時点で公式ドキュメントの数値を確認できなかったため、具体的な回数は書きません。移行後は1秒間隔でも429が出たという開発者の報告があります。一括処理では1.5秒以上の間隔を空け、429を受けたら待ってから再試行する作りにしておけば、上限の値が変わっても止まりにくくなります。

関連記事

お気に入りに入れた記事の一覧

一創の公式 SNS

X では毎朝の新着記事と IT ニュースの速報を、YouTube・TikTok・Instagram・LinkedIn・Facebook では記事の解説動画を配信しています。

この記事は以下の記事からリンクされています

資料請求

今日のトレンド記事 直近 24 時間で、いつもより多く読まれている記事

  1. 2026.11.13 テックブログ 宝くじ公式サイト不正アクセス:4,436名の対象確認とパスワード再設定、変更された仕組み
  2. 2026.11.14 テックブログ ImageMagickの脆弱性VU#580079:policy.xmlの許可リスト設定と影響判定の手順
  3. 2026.11.14 テックブログ Gitの脆弱性6件:CVE-2026-111760の再帰クローン対策と2.56.1への更新手順
  4. 2025.04.09 コラム ダブルバーレル質問(二重質問)とは?例文と直し方、多重質問・誘導質問との違い
  5. 2026.11.14 テックブログ Check Point脆弱性CVE-2026-123039:Gaiaのroot権限昇格を確かめるコマンドと侵害調査の手順

RELATED POSTS 関連記事

目次