UCP 対応の作り方

Google の Universal Commerce Protocol（仕様 2026-04-08）は、AIエージェントが利用者の代わりに商品を探し、レジを進め、注文まで実行するための標準です。

この店は実際に対応しています。/.well-known/ucp を読めば、何ができる店かがそのまま分かります。ここに書いてあるのは、その実装から得た手順と勘所です。同じことをする加盟店の役に立てば幸いです。

作る順番

先に作るほど、次を作るときの疎通確認に使えます。

1
商品フィード
なぜ先か：UCP と無関係に Google ショッピングで効く。そして UCP の item.id はフィードの id と一致していなければならないので、ここで採番を決めてしまう
どう作るか：RSS 2.0 + g: 名前空間。商品のIDは、あとで変えられない前提で選ぶ
2
UCPプロフィール（/.well-known/ucp）
なぜ先か：エージェントが最初に読む。ここが無いと何も始まらない
どう作るか：認証を掛けてはいけない（仕様上、公開必須）。実装していない能力は宣言しない — 宣言すると相手が呼んで落ちる
3
チェックアウトセッション
なぜ先か：UCP の中心。作成 → 更新 → 完了の3本
どう作るか：サーバ側にレジの途中経過を持つ必要がある。カートがブラウザにしか無い構成では、ここが一番大きな変更になる
4
注文状態
なぜ先か：購入後の問い合わせをエージェントが代行できる
どう作るか：注文番号を秘密として使い、住所などは返さない
5
署名鍵と Google Pay
なぜ先か：本番の決済に必要
どう作るか：鍵は EC P-256 / ES256。秘密鍵は環境変数で渡し、リポジトリにもイメージにも置かない

エンドポイント

メソッド	パス	役割
GET	`/.well-known/ucp`	能力の宣言。認証不可
POST	`/ucp/v1/checkout-sessions`	セッションの作成
PUT	`/ucp/v1/checkout-sessions/{id}`	届け先・購入者・決済手段の更新
POST	`/ucp/v1/checkout-sessions/{id}/complete`	注文の確定
GET	`/ucp/v1/orders/{id}`	購入後の状態
POST	`/ucp/v1/carts`	カートの受け取り（作成のみ）
GET	`/feed.xml`	Merchant Center 向け商品フィード

状態の進み方

incomplete ──(買い手＋届け先)──▶ ready_for_payment
                                      │
                              (決済手段)│
                                      ▼
                              ready_for_complete
                                      │
                                (complete)│
                                      ▼
                                  completed

不足は messages[] で伝えます。severity の使い分けが要点です。

recoverable: Googleが利用者から集め直せる。メール未入力、届け先未指定、決済手段の未選択
unrecoverable: 集め直しても解決しない。在庫切れ、配送対象外の国

設計の勘所

UCPの層で金額を計算しない

変換層は見積りの結果を totals[] の形に詰め替えるだけにします。ここで足し算を始めると、画面・AI・UCPで金額がずれ、店番が言った額と請求額が食い違います。計算箇所は1つに保ってください。

保存はドメインの形で

セッションをUCPのJSONのまま保存すると、仕様が変わったときに保存済みのデータごと壊れます。店側の素直な形で保存し、線に出すのは応答を返す瞬間だけにします。「仕様が変わったら直せばいい」を安く成立させるのはこの一点です。

完了は冪等に

同じセッションへの再送は同じ注文を返します。エージェントは人より気軽に再試行するので、ここを守らないと二重注文になります。

決済を必ず経由させる

完了処理が、決済を強制する経路ではなく素の注文作成を呼んでいると、未払いのまま在庫だけが減る注文が作れてしまいます。決済が設定されている環境では、決済手段の無いセッションを完了させないでください。

注文を作れる口は必ず絞る

チェックアウトのエンドポイントは在庫を引き当てて注文を作れます。 Bearer 認証を掛け、回数も制限してください。プロフィールだけは仕様上、認証を掛けられません。

複数インスタンスでの回数制限

Cloud Run のようにインスタンスが増える構成では、プロセス内で数えた上限はインスタンスの数だけ緩みます。注文を作れる口の制限は共有ストア（DB等）で数えてください。

必要な環境変数

変数	用途
`NEXT_PUBLIC_SITE_URL`	プロフィールに載る絶対URL。実ドメインにする
`UCP_API_KEY`	チェックアウトの Bearer 認証。本番では必須
`UCP_SIGNING_KEY`	署名鍵の秘密鍵（PKCS#8 PEM）
`UCP_SIGNING_KEY_ID`	鍵の識別子。入れ替えのときに変える
`UCP_GOOGLE_PAY_GATEWAY`	PSPのゲートウェイ名
`UCP_GOOGLE_PAY_GATEWAY_MERCHANT_ID`	PSP側の加盟店ID
`UCP_GOOGLE_PAY_MERCHANT_ID`	Google Pay の本番ID。未設定なら TEST 環境として宣言される

まだ手が届かないところ

Google の面への参加 — 実装が済んでも自動的には有効になりません。加盟店オンボーディングが別途必要で、日本での提供時期は Google 側の状況に依存します
AP2（同意の暗号証明） — 署名鍵の基盤は同じですが、検証クレデンシャルの設計は別物です
決済トークンの受け渡し — Google Pay のトークンを実際のPSPが受け付けるかは、PSP側の対応次第です

UCP は進化中の標準です（現在の仕様バージョン 2026-04-08）。仕様の全機能が Google の面で使えるわけではありません。

この店で試す

プロフィールと商品フィードは認証なしで読めます。

curl https://example.com/.well-known/ucp
curl https://example.com/feed.xml

チェックアウトのエンドポイントは、在庫を引き当てて注文を作れるため認証を掛けています。

MCP や REST API については AIエージェント向けのご案内をご覧ください。