mp-integrate

mp-integrate

このスキルは、Mercado Pago 統合を構築するための単一のエントリポイントです。開発者から最小限のコンテキストを収集し、厳選された参照ファイルと、フォールバックとして MCP サーバーを使用して、すぐに貼り付けられるバンドルを組み立てます。

参照ファイル — コードを生成する前に必ず読む

バンドルされたすべての参照ファイルとスクリプトには ${CLAUDE_PLUGIN_ROOT} を使用してください。Claude Code はこれをアクティブなプラグインバージョンに解決します。インストールキャッシュをスキャンしたり、別のマーケットプレイスのコピーを読み込んだり、プラグインの .mcp.json を開発者のプロジェクトにコピーしたりしないでください。

ファイル	絶対パス	読むタイミング
terminology-rules.md	${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/terminology-rules.md	常に最初
recommendation-template.md	${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/recommendation-template.md	常に — 必須の出力構造
guides/checkout-pro.md	${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/guides/checkout-pro.md	product = checkout-pro
guides/checkout-api.md	${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/guides/checkout-api.md	product = checkout-api
guides/bricks.md	${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/guides/bricks.md	product = bricks
guides/qr.md	${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/guides/qr.md	product = qr
guides/point.md	${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/guides/point.md	product = point
guides/subscriptions.md	${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/guides/subscriptions.md	product = subscriptions
guides/marketplace.md	${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/guides/marketplace.md	product = marketplace
guides/wallet-connect.md	${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/guides/wallet-connect.md	product = wallet-connect
guides/payouts.md	${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/guides/payouts.md	product = money-out（現在の名称: Payouts）
guides/smartapps.md	${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/guides/smartapps.md	product = smartapps
guides/webhooks.md	${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/guides/webhooks.md	任意の product + webhooks
products.md	${CLAUDE_PLUGIN_ROOT}/skills/mp-integrate/references/products.md	国別のテストカード、API リファレンス

上記の該当するすべてのファイルを読む前に MCP を使用しないでください。 最新のドキュメントについては、公式の {country_domain}/developers/llms.txt を WebFetch し（ティア 1 — ステップ 3 を参照）、フォールバックとして products.md を使用してください。

---

⚠️ 重要 — /mp-integrate コマンド経由で呼び出された場合: コマンドファイルはすでに環境チェックと準備フローを実行済みです。ステップ 1.a から直接開始してください（SDK/クライアント/モードの自動検出）。MCP の状態を調べないでください。認証情報は、開発者がその MCP ベースのオプションを明示的に選択した場合にのみインポートされます。

---

⚠️ ハードロック — 他の何かを行う前に読む

これらのルールは、ウィザード中のいかなる「何が理にかなうか」という判断よりも優先されます。過去のウィザード実行ではこれらに違反しています。同じ過ちを繰り返さないでください。

LOCK 1 — SDK は決してウィザードの質問項目にならない

SDK / 言語が AskUserQuestion で尋ねられることは決してありません。以上です。

• ステップ 1.a で、リポジトリを glob してマニフェスト（package.json、pyproject.toml など）を探し、それを黙って解決します。
• マニフェストが 1 つだけ見つかった場合 → SDK を記録し、質問を完全にスキップします。
• マニフェストが複数存在する場合（真のポリグロットモノレポ）→ それでも尋ねません。開発者が現在編集しているディレクトリに一致するものを選ぶか、デフォルトで node を選択します。その選択をチャットの 1 行で言及し（✓ SDK: node — from package.json）、尋ねずに続行します。
• マニフェストがまったく存在しない場合 → それでも尋ねません。デフォルトで node を選択し、その旨を言及し（✓ SDK: node — defaulted (no manifest detected; we'll create package.json during scaffolding)）、続行します。
• そのスタックの公式パッケージを解決し、公式パッケージレジストリに現在の安定版リリースを問い合わせます。「安定版」とは、レジストリのデフォルト / 最新リリースを意味し、alpha、beta、リリース候補、nightly、プレビュービルドは除外されます。
• インストールされているバージョンとその安定版リリースを比較します。インストールまたは更新を行う前に、パッケージ、現在のバージョン（または「未インストール」）、提案するバージョン、および変更されるマニフェスト / ロックファイルを表示し、AskUserQuestion を介して明示的な承認を求めます。
• 承認された場合は、現在の安定版リリースへインストールまたは更新し、互換性のない変更の影響を受けるコードを適応させ、ロックファイルを更新し、関連するテストを実行します。拒否された場合は、依存関係を変更せず、必要な SDK が欠落または古い状態で統合を準備完了として報告しません。

header="SDK"、header="Stack"、または header="Language" を指定して AskUserQuestion を呼び出そうとしている自分に気づいたら、すぐに停止してください。SDK は決してピッカーではありません。ウィザード上部のタブ行に「SDK」をタブの 1 つとして含めてはなりません。

LOCK 2 — 製品 → モードの利用可否テーブル（譲歩不可）

製品	唯一有効な mode の値	ピッカーの動作
checkout-pro	preferences（Orders API は Checkout Pro には存在しません）	モードの質問を完全にスキップします。 header="Mode" を指定して AskUserQuestion を呼び出さないでください。「Orders API」をオプションとして表示しないでください。mode=preferences を黙って使用します。
checkout-api	orders	すべての国で常に orders。
bricks	payments	内部ルーティング値です。card-payment と payment は Payments API の支払いを作成します。wallet は /checkout/preferences を作成します。status-screen は paymentId を表示するだけです。preferences パスに v1 を追加しないでください。
qr	orders	すべての国で常に orders。
point	orders	すべての国で常に orders。
marketplace	preferences または payments	最初に marketplace-checkout= を解決します。Checkout Pro と Wallet Brick は Preferences を使用し、Checkout API は Payments API を使用します。Marketplace は独立した Orders API モードではありません。
wallet-connect	orders	常に orders。決して尋ねません。
subscriptions	n/a（独自の preapproval API を使用）	モードの質問をスキップします。
money-out	n/a（現在の製品名: Payouts、国別の API コントラクト）	モードの質問をスキップします。
smartapps	n/a	モードの質問をスキップします。

product=checkout-pro で、Orders API を含むモードピッカーをレンダリングしようとしている場合は、中止してください。 Orders API は現在 Checkout Pro では利用できません。以上です。「将来に備えて」それを提供しないでください。それに「推奨」タグを付けないでください。いかなる「その他」フォールバックにも含めないでください。

LOCK 3 — 常に init_point を使用し、sandbox_init_point は決して使用しない

Mercado Pago はサンドボックス環境を廃止しました。ステージング URL は存在しません。テストユーザーのフローを含め、すべての連携は本番 API に対して実行されます。

sandbox_init_point を参照するコードは決して生成しないでください。 常に preference レスポンスの init_point を使用してください。テスト実行と本番実行の違いは、読み込まれる認証情報（テストユーザーの APP_USR- か実際のアカウントか）だけであり、URL ではありません。

既存のコードに sandbox_init_point が見つかった場合は、バグとして報告してください。リダイレクトはサイレントに失敗するか、エラーページに到達します。

テストユーザーにも適用されます: create_test_user で作成されたテストユーザーは、そのテストユーザーアカウント用に返された APP_USR- 認証情報を使用して、本番 API ホストに対して操作します。個別のテスト用ベース URL やサンドボックスの切り替えは存在しません。これは TEST- 認証情報を無効にするものではありません。Checkout API、Bricks、Payments API 用の静的なテスト認証情報は TEST- を使用できます。sandbox_init_point を任意の認証情報とともに使用するコードは動作しません。

LOCK 4 — Tabs 行には、実際に尋ねられる質問のみを反映させる

ウィザード上部の Tabs 行（□ Country □ Product □ Mode ✓ Submit の行）には、LOCK 1 と LOCK 2 に従って実際にまだ未解決であり、かつスキップされていない次元のみを含める必要があります。具体的には:

• タブに "SDK" を決して含めないでください — LOCK 1 を参照してください。
• product が checkout-pro / bricks / wallet-connect / subscriptions / money-out / smartapps の場合、タブに "Mode" を決して含めないでください。
• タブに "Environment" を決して含めないでください。

LOCK 5 — Checkout CTA は Pro と API で必須

product が解決された直後に、product の分岐の前にこれらのエイリアスを正規化してください:

• checkout-api-orders、checkout-transparente、checkout-transparent、checkout_api → checkout-api
• checkout-pro は checkout-pro のまま

正規化されたいずれの値に対しても、チェックアウト UI を組み立てる、または書き込む前に、ターゲットプロジェクトのルートからこれを実行してください:

node "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-checkout-cta.mjs" "{product}" .

返された product、status、selected、candidates、nextAction を Step 2.5 用に保持してください。checkout-api-orders を別の product として独自に解釈し直さないでください。nextAction=wire_selected_cta の場合は selected の使用が必須です。nextAction=ask_user_for_cta_or_insertion_location の場合は、具体的なターゲットについて即座に AskUserQuestion を実行する必要があります。Checkout Pro または Checkout API のスキャフォールドは、CTA が接続されていなければ決して正常に完了できません。このロックは両方の product に等しく適用されます。Checkout API を修正する際に、動作している Checkout Pro の挙動を変更しないでください。

LOCK 6 — Checkout Pro のローカル back URL では auto_return を決して有効にしてはならない

product=checkout-pro の場合、auto_return: "approved" は、有効な APP_URL が公開 HTTPS オリジンである場合にのみ有効です。APP_URL が存在しない場合、localhost、127.0.0.1、0.0.0.0 を使用している場合、または HTTPS でない場合は、preference ボディから auto_return を省略してください。localhost の back_urls を提供するだけでは不十分です。Preferences API は preference を作成する前にその組み合わせを拒否します。

ローカル実行と本番実行の両方をサポートするアプリケーションでは、APP_URL から明示的な publicAppUrl ブール値を導出し（HTTPS かつ非ローカル）、それが true の場合にのみ { auto_return: "approved" } を条件付きで展開してください。成功を報告する前に、Step 3.5 で要求されているとおり validate-checkout-pro-server.mjs を実行してください。

LOCK 7 — Point は Orders API を使用し、ハードウェア不要のテストモードをサポートします

product=point の場合、現在の Orders API フローのみをスキャフォールドします: POST /v1/orders、type: "point"、および config.point.terminal_id。/point/integration-api/.../payment-intents、type: "instore"、config.device.id は決して生成しないでください。

ハードウェアを持たない開発者向けに、公式の標準仮想ターミナル NEWLAND_N950__SBX0000001 をサポートしますが、明示的な MP_POINT_TEST_MODE=true ガードの背後に限ります。本番環境では MP_POINT_TERMINAL_ID を必須とし、仮想ターミナルへ暗黙にフォールバックしてはなりません。アプリケーションが非同期のステータス変更を突合できるよう、ID による注文検索を含めてください。成功を報告する前に、次を実行します:

node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-point-server.mjs" "{server_file}"

LOCK 8 — QR は既存の Store と POS を伴う Orders API を使用します

product=qr の場合、POST /v1/orders のみを type: "qr"、一致する total_amount と transactions.payments[0].amount、および config.qr.external_pos_id とともにスキャフォールドします。有効な QR モードは static、dynamic、hybrid のみです。/instore/orders/qr/...、/instore/qr/...、リダイレクト Checkout 注文、またはコンテンツが Checkout URL である QR は決して生成しないでください。リクエストは最小限に保ちます: payer を勝手に作成せず、レガシーな items[].currency_id および items[].total_amount フィールドを削除してください。クライアントから提供された価格、数量、および計算された合計を有限の正の値として検証します。QR のキャンセルは、Point 専用の X-Allow-Cancelable-Status ヘッダーをコピーしてはなりません。

Store と POS のプロビジョニングは前提条件であり、スキャフォールドの隠れた副作用ではありません。既存の POS が明示的に構成されている場合はそれを再利用します。利用可能なものがない場合は、永続リソースを作成する前に実際の Store の所在地を確認してください; 住所を勝手に作成しないでください。dynamic モードと hybrid モードは type_response.qr_data をローカルでレンダリングします。static モードは、POS の作成時に返された QR をレンダリングします。注文の検索とキャンセルを含め、成功を報告する前に両方の受け入れチェックを実行します:

node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-qr-server.mjs" "{server_file}"
node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-qr-client.mjs" "{client_file}" 'data-mp-qr-cta="create-order"' "/api/qr/orders"

LOCK 9 — Bricks の動作はバリアントごとに異なります

コードを書く前に brick= を解決し、references/guides/bricks.md を読んでください。1 つの Brick のバックエンドを 4 つのバリアントすべてに適用しないでください:

• card-payment: CardPayment/cardPayment は Payments API の支払いを作成します。
• payment: Payment/payment は Payments API を介して選択された方法を作成します。
• wallet: Wallet/wallet は、まさに /checkout/preferences を使用してプリファレンスを作成します; このパスにはバージョンセグメントがありません。
• status-screen: StatusScreen/statusScreen は検証済みの paymentId をレンダリングします; 支払いを作成せず、注文 ID を受け取ってもなりません。

アプリケーションの実際のフレームワークを使用し、プロジェクト全体をスキャンして実際のチェックアウト CTA を探します。存在する場合は、その表示を保持し、競合する古いハンドラーを削除した後、新しい専用の Brick ページにリンクします。存在しない場合は、それでもページを作成し、開発者がリンクすべき正確なルート/呼び出しを報告します。Brick の周囲で生のカードフィールドを決して収集しないでください。成功を報告する前に:

node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-bricks-integration.mjs" . "{brick}"

LOCK 10 — サブスクリプションの契約は決して混在させない

product=subscriptions の場合、コードを書く前に subscription-model= を解決し、 references/guides/subscriptions.md を読んでください。有効な値は with-plan、without-plan-authorized、without-plan-pending の 3 つだけです。

• with-plan は、サーバー制御の preapproval_plan_id、安全にトークン化された card_token_id、および status: "authorized" を使用します。ブラウザからプラン ID を 受け取ったり、購入者向け CTA からプランを作成したりしてはいけません。
• without-plan-authorized は、信頼できるサーバー側の定期課金条件、安全に トークン化された card_token_id、および status: "authorized" を送信します。
• without-plan-pending は、信頼できる定期課金条件と status: "pending" を送信し、 card_token_id を省略し、返された init_point にのみリダイレクトします。

認可フローでは、MercadoPago.js CardForm または公式の Card Payment Brick を使用する必要があります。購入者にカードトークンを貼り付けさせたり、生のカードデータを 収集したり、CardForm のライフサイクル用 select（issuer、installments、および identificationType）を省略したりしてはいけません。アプリケーション全体をスキャンして、すべてのサブスクリプション CTA を確認してください。 すべてのマーケティング/エントリー CTA は、既存または生成された専用の サインアップページに収束させる必要があり、その最終 CTA のみが preapproval を作成できます。競合するデモ ハンドラーと孤立したサーバールートを削除し、preapproval 作成者がちょうど 1 つだけ残るようにしてください。 成功を報告する前に:

node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-subscriptions-integration.mjs" . "{subscription-model}"

LOCK 11 — マーケットプレイスは OAuth + 1 つのサポート対象チェックアウト

product=marketplace の場合、コードを書く前に marketplace-checkout= を解決し、 references/guides/marketplace.md を読んでください。サポート対象の値は checkout-pro、checkout-api、および bricks-wallet だけです。

• checkout-pro は、接続済み販売者の OAuth アクセストークン、正確に /checkout/preferences、および marketplace_fee を使用します。
• checkout-api は、インテグレーターの公開鍵、接続済み販売者の OAuth アクセストークン、/v1/payments、安全なトークン化、および application_fee を使用します。
• bricks-wallet は、インテグレーターの公開鍵、販売者の OAuth アクセストークン、正確に /checkout/preferences、marketplace_fee、動的な preferenceId、 および marketplace: true を使用します。

すべての契約は、ワンタイムのサーバー側 OAuth state、正確なリダイレクト URI の一致、認可コードの交換、暗号化された永続的な販売者トークン、 リフレッシュトークンのローテーション、および信頼できるサーバー側での販売者/カート/手数料の 解決を実装する必要があります。ブラウザから販売者 ID、金額、手数料、collector ID、または OAuth トークンを受け取ってはいけません。マーケットプレイスはスタンドアロンの Orders API フローではなく、 プラットフォームトークンに暗黙的にフォールバックしてはいけません。成功を報告する前に:

node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-marketplace-integration.mjs" . "{marketplace-checkout}"

LOCK 12 — Wallet Connect には商用アクセスとサーバー専用の連携が必要です

product=wallet-connect の場合、スキャフォールドの判断を行う前に references/guides/wallet-connect.md を読んでください。

1. Mercado Pago が開発者のアプリケーションに対して Wallet Connect を商用 利用として有効化していることを確認します。開発者が明示的に有効化されて いないと述べた場合は、BLOCKED: active Wallet Connect agreement required で停止し、ファイルを書き込みません。有効化の状況が不明な場合は、書き込む 前に一度確認してください。
2. 常に固定の orders モードを使用します。モードについて質問せず、この製品を Wallet Brick や Advanced Payments API に置き換えないでください。
3. 専用のアカウント連携/支払いページを作成し、プロジェクト全体をスキャンして 実際の最終チェックアウト CTA を探します。見つかった場合はそれを保持して接続 し、見つからない場合は、開発者が連携すべき正確な新しいルートと呼び出し方法を 報告してください。
4. アカウント連携、承認コードの交換、支払者トークンの作成、暗号化、永続化、 および Orders API の支払い作成はすべてサーバー上で行われます。ブラウザーが 受け取るのは、安全な連携状態、承認リダイレクト URI、および最終的な注文 ステータス/ID のみです。
5. 購入者の ID と購入金額は、認証済みのサーバー側の状態から導出します。外部の ユーザー ID、支払者トークン、金額、または保存された資格情報のセマンティクスを、 信頼できるブラウザー入力として受け入れないでください。
6. MercadoPago.js を読み込んだり、公開キーを要求したり、Wallet Brick を マウントしたり、カード入力フィールドをレンダリングしたりしないでください。 購入者の承認は Mercado Pago ウォレット UI で行われます。

成功を報告する前に、次を実行してください:

node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-wallet-connect-integration.mjs" .

LOCK 13 — SmartApps には商用アクセス、Android、およびそのプライベート SDK が必要です

product=smartapps の場合、スキャフォールドの判断を行う前に references/guides/smartapps.md を読んでください。

1. 開発者が Mercado Pago チームとの間で有効な SmartApps 契約を結んでいることを 確認します。明示的に確認できない場合は、BLOCKED: active SmartApps agreement required で停止し、ファイルを書き込みません。
2. tier-1 の公開ドキュメントが利用可能な場合でも、 mcp__plugin_mercadopago_mcp__search_documentation に問い合わせて現在の SmartApps ガイドを取得してください。MCP 認証が欠けている場合は、通常の インライン認証フローを実行し、成功するまで停止してください。
3. Android ターゲットを必須とします。SmartApps を Web、バックエンド、デスクトップ、 または iOS アプリケーションに変換したり埋め込んだりしないでください。 リポジトリに Android アプリがない場合は、別の Android アプリケーション/ モジュールが必要であることを説明し、スコープを拡大する前に確認してください。
4. 書き込む前に、main と mini、および own と third-party を確定します。 メインアプリは HOME ランチャーを所有しますが、ミニアプリは所有しません。 サードパーティ統合には SDK OAuth モードが必要です。
5. SDK は Mercado Pago 統合キットで提供されるプライベート AAR です。公開の Mercado Pago SDK で代用したり、Maven コーディネートをでっち上げたりしないで ください。コピー/更新の前に確認し、統合チームと最新のアーティファクトを 検証し、その最新バージョンのみを使用してください。
6. 支払い方法、支払い、プリンター、スキャナー/カメラ、および Bluetooth は SmartApps SDK を通じて使用します。ターミナルから支払い API を直接呼び出したり、 禁止されている Android の直接パーミッションを要求したりしないでください。

静的なスキャフォールドの成功を報告する前に、次を実行してください:

node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-smartapps-integration.mjs" . "{main|mini}" "{own|third-party}"

このチェックに合格することは、デバイスの認定を意味しません。コンパイルには 実際の最新 AAR が必要であり、支払いとハードウェアの検証には Mercado Pago の 開発用ターミナルとサンドボックスフレーバーのキットが必要です。

LOCK 14 — Money Out は Payouts であり、その契約は国ごとに異なります

product=money-out の場合、スキャフォールドの判断を下す前に references/guides/payouts.md を読み、現在の製品名を Payouts として提示してください。

1. disbursements API、Advanced Payments、Marketplace の分割、チェックアウトフロー、購入者向け CTA、カードフォームを決してスキャフォールドしないでください。旧 Money Out の URL は現在 Payouts にリダイレクトされます。
2. 書き込む前に、国から契約を解決してください。アルゼンチンは現在のバッチ Payouts 契約を使用し、ブラジルは現在の単一 Transaction Intent 契約を使用します。その他の国については、現在の国別ガイドを照会し、検証済みの契約が返らない場合は BLOCKED: verified Payouts country contract required で停止してください。
3. Payout の作成はサーバー専用かつ特権的です。認証と明示的なオペレーター承認を必須とし、金額と送金先は耐久性のある信頼済み命令リポジトリから読み込み、耐久性のある監査証跡を書き込んでください。呼び出し元が提供できるのは不透明な命令 ID のみです。
4. テストモードは明示的でなければならず、公式の Payouts テストヘッダーを送信する必要があります。本番環境では、正確にシリアライズされたボディに対する Ed25519 署名を使用する必要があります。テストモード、秘密鍵、送金先アカウント、Access Token を決してハードコードしないでください。
5. HTTP レスポンスの成功は非同期の受理であり、最終的な承認ではありません。ID／ステータスを永続化し、ルックアップと Webhook によって突合してください。
6. 検証済みの国別契約が REST を使用しており、検出された公式 SDK がそのリソースを公開していない場合、Payouts のためだけに SDK をインストールしないでください。公式 SDK を使用する場合でも、LOCK 1 により承認と最新の安定版が必要です。

成功を報告する前に、次を実行してください:

node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-payouts-integration.mjs" . "{AR|BR}"

---

ステップ 1 — $ARGUMENTS を解析し、不足しているコンテキストを確認する

$ARGUMENTS には、これらのフラグの任意の組み合わせを含めることができます。不足しているものは、AskUserQuestion で 4 件以下のバッチに分けて確認する必要があります。

フラグ	値
country=	AR / BR / MX / CL / CO / PE / UY
product=	checkout-pro / checkout-api / bricks / qr / point / subscriptions / marketplace / wallet-connect / money-out / smartapps
mode=	製品によって異なります — 以下の製品マトリクスを参照してください
sdk=	node / python / java / php / ruby / dotnet / go（または生の REST の場合は none）
client=	vanilla-js / react / ios / android / flutter / react-native（クライアントコンポーネントを持つ製品のみ）
lang=	es / en / pt（ドキュメントの言語）
recurrent=	yes / no（Checkout API、Bricks）
3ds=	yes / no（Checkout API、Bricks）
marketplace=	yes / no（分割払い）
brick=	payment / card-payment / wallet / status-screen（product=bricks の場合のみ）
qr-mode=	static / dynamic / hybrid（product=qr の場合のみ）
subscription-model=	with-plan / without-plan-authorized / without-plan-pending（product=subscriptions の場合のみ）
marketplace-checkout=	checkout-pro / checkout-api / bricks-wallet（product=marketplace の場合のみ）
smartapps-agreement=	confirmed（product=smartapps の場合のみ。存在しない場合は確認として推測されません）
smartapp-kind=	main / mini（product=smartapps の場合のみ）
smartapp-ownership=	own / third-party（product=smartapps の場合のみ）

product を解析または推測した後、直ちに LOCK 5 の正規化を適用してください。製品マトリクス、ガイドの選択、CTA の解決、スキャフォールドの分岐には、正規化された内部値のみを使用してください。表示専用のスラッグ checkout-api-orders は最終的な推奨メタデータに現れることがありますが、内部の分岐値として使用しては決してなりません。

ステップ 1.a — 質問する前に自動解決する（必須 — まずこのステップをやり切る）

AskUserQuestion を呼び出す前に、必ずこのステップを実行してください。 ここで解決されたすべてのディメンションはウィザードから除外されます。開発者には、本当に推測できないディメンションについてのみ質問するようにしてください。自動検出をスキップして、それでも開発者に質問してしまうのが最もよくある間違いです — これは行わないでください。

すべてのディメンションについて、次の解決ソースを順番に試してください:

ディメンション	0番目: エージェントによる推論 (ステップ 1.a)	1番目: 永続化された情報	2番目: リポジトリのシグナル	3番目: 質問
product	エージェントがメッセージのキーワードから解決できた場合 → それを使用し、質問をスキップ	.mp-integrate-progress.md から読み取る	—	AskUserQuestion ピッカー
country	エージェントがメッセージのキーワードから解決できた場合 → それを使用し、質問をスキップ	.mp-integrate-progress.md から読み取る	なし — country を grep しないでください (信頼性が低く、トークンを消費します)	AskUserQuestion ピッカー。回答を永続化します。
sdk	—	—	Glob を必ず実行: package.json→node、pyproject.toml/requirements.txt→python、pom.xml/build.gradle*→java、composer.json→php、Gemfile→ruby、*.csproj/Program.cs→dotnet、go.mod→go。一致が1つ → 解決。一致が複数 → アクティブなアプリケーション領域のマニフェストを選択。一致なし → デフォルトで node。	どの SDK かを尋ねないでください。インストール/更新の前に認可についてのみ尋ねてください。
client	—	—	package.json の依存関係を調査: react/next→react、react-native/expo→react-native、*.xcodeproj→ios、Android build.gradle→android、pubspec.yaml→flutter。一致が1つ → 解決。	AskUserQuestion (product にクライアントコンポーネントがあり、かつ曖昧な場合のみ)
lang	—	—	country から導出 (BR→pt、その他→es)。	ほとんど尋ねられることはありません — country からデフォルト設定
mode	—	進行状況ファイルから読み取る	/v1/orders/order.create→orders、/v1/payments/payment.create→payments、/checkout/preferences/preference.create→preferences を Grep。Product Matrix が単一の値に固定する場合があります (例: checkout-pro → 常に preferences)。	AskUserQuestion (matrix が複数を許可し、かつ grep で曖昧さが解消されなかった場合のみ)

ウィザードの具体的な操作順序 (まず推論、質問は最後):

0. リポジトリ内のレガシー Instore API を確認する (質問の前に)。 レガシー QR/Point パターンに対して Grep を実行します:

   • /mpmobile/instore/qr (QR Instore)
   • /instore/qr/seller/collectors (QR Instore V2)
   • /instore/orders/qr/seller/collectors (QR Dinámico)
   • /point/integration-api/devices/.*/payment-intents (Point PDV + Self Service)

   いずれかが見つかり、かつプロジェクトがまだ完全に /v1/orders に移行していない場合は、AskUserQuestion で一度だけ尋ねてください:

   • header: "Existing integration"
   • Question: 「プロジェクトの {file}:{line} に既存のレガシー Instore 統合が見つかりました。スキャフォールディングの前に、まず Orders API へ移行しますか?」
   • Options: "Yes, migrate first (/mp-integrate migrate)" / "No, scaffold the new integration"
   • 「はい」の場合 → 停止して指示: 「/mp-integrate migrate を実行して既存の統合を移行し、その後戻って新しい統合をスキャフォールドしてください。」
   • 「いいえ」の場合 → 通常どおり続行します。このセッションで再度移行を提案しないでください。
   • $ARGUMENTS にすでに migrate が含まれている場合は、このチェックを完全にスキップしてください。

1. エージェントの推論を確認する — エージェントのステップ 1.a が開発者のメッセージから product= および/または country= を解決した場合、それらの次元はすでに解決済みです。それらを尋ねないでください。

2. .mp-integrate-progress.md が存在する場合は読み取る — 以前に解決された値を取り出します。

3. country を grep しないでください。 country は、ステップ 1〜2 でまだ解決されていない限り、AskUserQuestion を介して尋ねられます。ロケール文字列の grep、mercadopago.com.<tld> の grep、currency_id の grep は行いません — これらはトークンを消費し、誤った一致を生み出します。

4. マニフェストのパターンに対して Glob を実行します。単一の SDK マニフェストが一致した場合、SDK は解決済みです — 尋ねないでください。 検出された言語に対応する公式の Mercado Pago SDK が使用されます。サードパーティの SDK を提案しないでください。

5. 製品にクライアントが必要な場合は、マニフェストの依存関係に対して Glob/Grep を実行します。単一のクライアントが一致した場合、クライアントは解決済みです。クライアントの質問をスキップします。

6. country から lang をデフォルト設定します。lang の質問をスキップします。

7. ここで — そしてここでのみ — まだ不足しているものについて AskUserQuestion を呼び出します。一度に 1 つのツール呼び出しで、ステップ 1.b で定義された順序に従って行います。各回答の後、それを永続化 して .mp-integrate-progress.md に保存します。

既知の MCP の制限 — country の解決: Mercado Pago MCP は現在、開発者の site_id を返すツールを公開していません（application_list も quality_checklist も notifications_history も、その応答に country を含んでいません）。OAuth アクセストークンがあれば GET https://api.mercadopago.com/users/me を直接呼び出せますが、トークンは MCP サーバーが保持しており、プラグインクライアントには公開されていません。MP が新しい MCP ツール（例: current_user_info や汎用的な proxy_request）を提供するまでは、country の解決は 単純に: .mp-integrate-progress.md を読み取り、country があればそれを使い、なければ AskUserQuestion を介して尋ねて永続化します。トークンを無駄にしないでください — country の手がかり（ロケール、URL、currency_id、site_id、アプリ名のヒューリスティック）を求めてリポジトリを grep しても、報われません。開発者に一度尋ねるほうが安価で信頼性が高いです。

ステップ 1.a.iii — 自動解決されたすべてのものを確認する（必須）

自動解決の後、推論されたすべての値（country だけでなく、SDK、クライアント、およびリポジトリから得られたその他の次元も含む）をリストした単一の確認ブロックをレンダリングします。次に、ウィザードの質問の前に、1 つの AskUserQuestion で開発者に尋ねます:

• header="Confirm setup"
• 質問: "I auto-detected the following from your repo. Is everything correct?"
• オプション:
  • "Yes, continue" — 自動解決された値でステップ 1.b に進みます。
  • "No, let me correct" — ユーザーが選択可能な自動解決された値をウィザードのキューに戻します。SDK/言語をそのキューに追加しないでください。それらについてはリポジトリ検出を再実行し、SDK ピッカーを提示せずに選択された公式 SDK を説明します。

この確認をスキップするのは、自動解決するものが何もなかった場合（クリーンなリポジトリ、マニフェストなし、ロケールなし、既存の MP URL なし）のみです。その場合、ウィザードは直接尋ねることに進みます。

レンダリングするブロックの例:

I auto-detected the following from your repo:

  ✓ App:    My Store (123456789012345) — from application_list
  ✓ SDK:    node — from backend/package.json (mercadopago v2.12.0 already installed)
  ✓ Client: react — from frontend/package.json

Country will be asked next (not auto-detected).
Confirm the above to continue, or correct.

開発者は自動解決されたセットに明示的にオプトインする必要があります。自動解決後にステップ 1.b に黙って進まないでください — そうすることで誤った仮定が最終的なバンドルに伝播します。

エージェントがすでにフラグ（country=、sdk=、mode= など）を渡している場合は、それらも解決済みとして扱います。

1.a の後もまだ解決されていないものは、1.b のウィザードに入ります。

常に公式の Mercado Pago SDK を使用してください（以下に記載）。開発者がラッパーや代替ライブラリに言及したかどうかに関わらずです。公式 SDK は Mercado Pago によって維持され、ライブ API と整合しています。

ステップ 1.b — AskUserQuestion ピッカーを使用して、一度に 1 つずつ質問する

これはウィザードで最も違反されるルールです。v4 ウィザードを壊した 2 つのスクリーンショットは、このセクションに違反したことが原因でした。 これを二度読んでください。

チャット出力を書く前の STOP-TEST:

応答にこれらのパターンのいずれかが含まれている場合、あなたは間違っています — 中止して代わりに AskUserQuestion を使用してください:

• Question N of M
• 1. Country / 2. Product / 3. SDK（番号付きの質問リスト）
• - checkout-pro — … のようなオプションコードの箇条書き
• Type the code、Reply with、Answer with というフレーズ
• 開発者が読んで自由テキストで回答することを想定したメニューのように見える Markdown

これらはすべて v3 のアンチパターンです。開発者はプレーンテキストをクリックできません。書き直したばかりの v3 プラグインよりも悪い体験になります。

厳格なルール — 例外なし:

1. Step 0/1.a の後の最初のツール呼び出しは AskUserQuestion でなければなりません。最初のツール呼び出しがそれ以外（Read、Write、Bash、search_documentation など）の場合、ウィザードをスキップして「チャットで質問する」に直行したことになります。停止して AskUserQuestion からやり直してください。
2. AskUserQuestion は1 次元につき 1 回のツール呼び出しで実行し、回答を待ってから次の呼び出しを行います。開発者には矢印キーで選択できるインタラクティブなピッカーが表示されます。
3. 最初の AskUserQuestion 呼び出しの前のチャット出力は、短い 3 行以下でなければなりません — 自動解決された次元ごとに 1 行、加えて任意で「では残りを質問します」という 1 行です。メニュー、番号付きリスト、「4 つの簡単な質問をします」などは禁止です。
4. AskUserQuestion 呼び出しの間は、確認の 1 行以下、その後すぐに次の呼び出しを行います。進捗を要約せず、「Question N of M」も表示しないでください。
5. どうしてもある次元を 4 つのピッカーオプションに収められない場合、ピッカーは自動的に「Other」エントリを追加し、開発者が自由に入力できるようにします — それを使ってください。質問を 2 つに分割しないでください。

AskUserQuestion 呼び出しの順序 — Step 1.a の後もまだ未解決の次元にのみ適用されます。すでに判明している次元はスキップしてください。Product Matrix が選択した製品に対して n/a とマークしている次元については質問しないでください。

順序	次元	ヘッダー	表示するオプション
1	product	"Product"	最も可能性の高い 4 つの製品をボタンとして + 「Other」の自動フォールバック。この優先度から 4 つを選びます: checkout-pro、bricks、checkout-api、subscriptions（最も一般的）。残り（qr、point、marketplace、wallet-connect、money-out、smartapps）は「Other」から到達できます。
2	mode	"Mode"	最初に LOCK 2 を照合してください。 LOCK 2 が「Skip the mode question」と述べている場合は完全にスキップします。質問する場合は、LOCK 2 が選択した製品に対して明示的に許可しているモードのみを表示します。checkout-pro のオプションに "Orders API" を絶対に含めないでください。
3	client	"Client"	製品にクライアントコンポーネントがあり、かつリポジトリのシグナルが曖昧な場合のみ。最も可能性の高い 3 つ + Other を表示します。
4	brick	"Brick"	product=bricks の場合のみ。オプション: payment / card-payment / wallet / status-screen。
5	qr-mode	"QR mode"	product=qr の場合のみ。オプション: static / dynamic / hybrid。
5.5	subscription-model	"Subscription"	product=subscriptions の場合のみ。オプション: with-plan / without-plan-authorized / without-plan-pending。
5.6	marketplace-checkout	"Marketplace"	product=marketplace の場合のみ。オプション: checkout-pro / checkout-api / bricks-wallet。
5.7	smartapps-agreement	"Agreement"	product=smartapps の場合のみ。Mercado Pago との有効な商用/統合契約が確認済みかどうかを質問します。オプション: confirmed / not confirmed。確認されていない場合は、書き込みの前に停止します。
5.8	smartapp-kind	"SmartApp type"	product=smartapps かつ契約が確認済みの場合のみ。オプション: main / mini。
5.9	smartapp-ownership	"Terminal use"	product=smartapps かつ契約が確認済みの場合のみ。オプション: own / third-party。
6	recurrent	"Recurrent"	マトリクスが選択した製品に対して yes とマークしている場合のみ。オプション: yes / no。
7	3ds	"3DS"	マトリクスが yes とマークしている場合のみ。オプション: yes / no。
8	marketplace	"Splits"	マトリクスが optional とマークしている場合のみ。オプション: yes / no。
sdk はこの表から意図的に除外されています — 上記の LOCK 1 を参照してください。SDK が AskUserQuestion で問い合わせられることはありません。

environment は決して尋ねられません。 Mercado Pago にはサンドボックス/本番の切り替えがなくなりました。本番用の認証情報とテストユーザーの認証情報はどちらも APP_USR- プレフィックスを使用します。違いは、その認証情報が実際のアカウントに属するかテストユーザーに属するかであり、これは mp-test-setup で処理されます。「Environment: production / test」のピッカーを表示しないでください。MP のベース URL を切り替えるために NODE_ENV で分岐するコードを書かないでください。

Step 1.b.ii — 先走った MCP 呼び出しなしで mode を解決する

まず以下の Product Matrix を使用してください。選択した製品の mode セルが固定されている場合は、その値を使用し、MCP に接続しないでください。

製品/モードの組み合わせがバンドルされたソースに存在しないか、真に曖昧な場合にのみ、mcp__plugin_mercadopago_mcp__search_documentation を "{product} orders api {country}" のようなクエリで使用してください。これは MCP に基づくフォールバックです。そのクエリの直前に認証を行い、それより早く行わないでください。checkout-pro に対してこれを実行しないでください — LOCK 2 がその製品に対する Orders をすでに禁止しています。

フォールバックのドキュメントがモードを明示的に確認している場合は、この実行でそれを使用してください。確認していない場合は、検証されていないモードを提示しないでください。

このルールは、v4 ウィザードが Checkout Pro に対して、その製品に API が存在しないのに Orders を提示したために存在します。噂や近日公開であっても、今日 MP API に存在しないモードを決して提示しないでください。

country は通常このリストに入ることになります。 現在、MCP は site_id を返さないため、リポジトリのシグナルや永続化された状態が 1.a で解決しない限り、尋ねる必要があります。header="Country" を使用し、AR、BR、MX、CO をボタンとしてください（最も一般的な 4 か国） — ピッカーは自動的に「Other」エントリを追加し、開発者が CL、PE、または UY を入力できるようにします。回答後、それを .mp-integrate-progress.md に永続化してください。

Step 1.b.i — チャットの見え方（具体例）

誤り（v3 のアンチパターン、スクリーンショットが示していたものまさにそのもの）:

Now I need a few details to scaffold the right integration:

1. Country — Which site/country are you integrating for?
- MCO — Colombia
- MLA — Argentina
…

2. Product — Which Mercado Pago product…
…

3. SDK / Language — What stack are you using?
…

正しい:

✓ App: My Store (123456789012345) — from application_list
✓ SDK: node — from package.json
(Country will be asked next — not auto-detected.)

→ その後すぐに product に対する AskUserQuestion 呼び出し。開発者が選択します。次に 1 行以内の確認。次に次の AskUserQuestion。以下同様です。

Step 1.c — 収集したすべてのデータを即座に永続化する

永続化の黄金律: 収集されたあらゆる情報 — 推論によるもの、ウィザードによるもの、MCP によるもの、あらゆる手段によるもの — は、収集直後に .mp-integrate-progress.md に書き込まれます。開発者が明示的に変更しない限り、再度尋ねられることはありません。

毎回の実行の開始時に、このファイルを最初に読み、そこに見つかったすべての値を使用してください。真に存在しない次元についてのみ尋ねてください。

永続化するフィールド（それぞれが解決された後に書き込み、最後まで待たないでください）:

# mp-integrate progress

- country: AR
- product: checkout-pro
- mode: preferences
- sdk: node
- client: react
- lang: es
- credential_type: test
- application_id: 123456789012345
- brick: card-payment
- qr_mode: dynamic
- subscription_model: with-plan
- marketplace_checkout: checkout-pro
- recurrent: no
- three_ds: no

ルール:

• 各フィールドが解決された後にファイルを書き込んでください — ウィザードの最後だけでなく。
• 開発者がセッションの途中で値を変更した場合（例: 「やっぱりブラジルがいい」）、ファイルを即座に更新してください。
• .mp-integrate-progress.md がまだ .gitignore になければ追加してください。
• バンドルのレンダリングに成功したら削除するか、キャンセル/エラー時には次回の実行が引き継げるように保持してください。

製品マトリクス — どのフラグが適用され、どれが適用されないか

製品	sdk	client	mode（指定可能な値）	recurrent	3ds	marketplace	サブフラグ
checkout-pro	yes	optional	preferences のみ — Checkout Pro には Orders API モードがありません	n/a	n/a	optional	n/a
checkout-api	yes	yes	orders（すべての国）	yes	yes	optional	n/a
bricks	yes（サーバー）	yes	内部の payments ルーティング。バックエンドは LOCK 9 に基づきバリアントごとに異なります	yes（payment、card-payment）	yes（payment、card-payment、status-screen）	optional	brick=
qr	yes	n/a	orders（すべての国）	n/a	n/a	n/a	qr-mode=
point	yes	n/a	orders（すべての国）	n/a	n/a	n/a	n/a
subscriptions	yes	条件付き（認可された契約は MercadoPago.js を使用）	n/a（独自の preapproval API）	暗黙的	n/a	optional	subscription-model=
marketplace	yes	条件付き	Checkout Pro/Wallet には preferences、Checkout API には payments	n/a	n/a	暗黙的	marketplace-checkout=
wallet-connect	yes	n/a	orders	n/a	n/a	n/a	n/a
money-out	条件付き（検証済みの REST は有効）	n/a	n/a（Payouts、国ごとの契約）	n/a	n/a	n/a	国が契約を決定します
smartapps	n/a（プライベートキット AAR）	Android	n/a	n/a	n/a	n/a	smartapp-kind=、smartapp-ownership=

製品の mode セルが固定されている場合（単一の値または n/a）、決して mode について開発者に尋ねないでください — その値を使用するか、質問をスキップするだけです。

---

ステップ 2 — 国のドメインと通貨を特定する

国	サイト ID	ドメイン	通貨	デフォルト言語
アルゼンチン	MLA	www.mercadopago.com.ar	ARS	es
ブラジル	MLB	www.mercadopago.com.br	BRL	pt
メキシコ	MLM	www.mercadopago.com.mx	MXN	es
チリ	MLC	www.mercadopago.cl	CLP	es
コロンビア	MCO	www.mercadopago.com.co	COP	es
ペルー	MPE	www.mercadopago.com.pe	PEN	es
ウルグアイ	MLU	www.mercadopago.com.uy	UYU	es

lang= が指定されていない場合は、その国のデフォルト言語を使用してください。

---

ステップ 3 — ドキュメントとコンテキストの解決

ドキュメントは階層ごとに解決します。国ごとの公式 llms.txt は常に最新です。開発者にインターネット接続があり、ファイルは数 KB なので、まずこれを取得します。到達できない場合は適切にフォールバックします。

階層	ソース	認証	タイミング
1	https://www.{country_domain}/developers/llms.txt (WebFetch — 公式、常に最新)	なし	常に最初 — 解決された国のドメインを使用して取得します。失敗した場合 (403、タイムアウト)、階層 2 にフォールバックします。
2	{plugin_base}/skills/mp-integrate/references/products.md (バンドル)	なし	常に — 製品ガイド、API リファレンス、コードスニペット、国別のテストカード。
3	mcp__plugin_mercadopago_mcp__search_documentation	MCP OAuth	フォールバックのみ、ただし必須である SmartApps を除く — 階層 1〜2 で組み合わせがカバーされない場合に使用し、product=smartapps の場合は常に使用します。

階層 1 の国別ドメイン:

国	llms.txt URL
AR (MLA)	https://www.mercadopago.com.ar/developers/llms.txt
BR (MLB)	https://www.mercadopago.com.br/developers/llms.txt
MX (MLM)	https://www.mercadopago.com.mx/developers/llms.txt
CO (MCO)	https://www.mercadopago.com.co/developers/llms.txt
CL (MLC)	https://www.mercadopago.cl/developers/llms.txt ← .com なし
PE (MPE)	https://www.mercadopago.com.pe/developers/llms.txt
UY (MLU)	https://www.mercadopago.com.uy/developers/llms.txt

国は常にステップ 3 の前に解決されます。国が解決されていない状態で階層 1 を取得しないでください。

階層 1 の取得が失敗した場合: 何も表示せずに階層 2 (references/products.md) にフォールバックします。エラーを表示したり、再試行したりしないでください。

階層 3 が実際に必要な場合のみ: 直接 search_documentation を試みます。それが利用できない場合、または認証エラーを返す場合は、mcp__plugin_mercadopago_mcp__authenticate を呼び出し、開発者の言語で OAuth リンクを表示し、URL を外部ブラウザにコピーせずに Cmd+Click (Mac) または Ctrl+Click (Windows/Linux) するよう指示します。開発者が戻ったら、直接 search_documentation を再試行します。プローブとして application_list を呼び出さないでください。

階層 3 — MCP クエリテンプレート (フォールバック)

1〜3 個の的を絞ったクエリを作成し、それぞれに対して mcp__plugin_mercadopago_mcp__search_documentation を呼び出します。解決されたドキュメント言語から language を使用します。

クエリテンプレート (選択した製品/モード/sdk に最も具体的なものを 1〜3 個使用):

ニーズ	クエリテンプレート
サーバー作成	"{product} create {mode} {sdk} {country}" (例: "checkout-pro create preference node argentina" または "checkout-api create order node argentina")
クライアント/UI	"{product} {client} initialization {brick?}" (例: "bricks react payment brick initialization")
トークン化 (Checkout API / Card Payment Brick)	"card token {client} {country}"
3DS チャレンジ	"3ds {product} {sdk}"
Webhook 処理	スキップ — mp-webhooks スキルに委ねる
テストカード / ユーザー	スキップ — mp-test-setup スキルに委ねる
マーケットプレイス分割	"marketplace split {sdk} application_fee"
サブスクリプションのプラン/事前承認	"subscriptions preapproval {sdk}"
支払い (レガシーエイリアス: Money Out)	"payouts money transfer {country} {sdk}"
Wallet Connect	"wallet connect agreements payer token orders {sdk} {country}"
SmartApps	`"smartapps {main

3 個を超えるクエリを発行しないでください。 クエリが一般的な結果を返した場合は、一度だけ絞り込んで停止します。

MCP がドキュメントを返してもコードスニペットがない場合 (正直なフォールバック)

search_documentation が 概要やランディングの文章のみ を含む結果 (コードブロックなし) を返した場合、コードを捏造してはなりません。次の内容をそのまま出力してください:

検証済みのスニペットはありません — {product} / {country} / {sdk} について。 MCP はこの組み合わせに関するドキュメントを返しましたが、コードスニペットはありませんでした。ガイドを手動で確認してください: https://{DOMAIN}/developers/{LANG}/docs/{product-slug}/overview

その後は停止します。具体的には:

• 学習データの記憶からコードを再構築しないでください — 再構築されたスニペット (CardForm のハルシネーションを引き起こしたもの) は、MCP で検証済みであるかのように提示してはなりません。
• 代わりに別の任意の WebFetch を行わないでください。 公式の国別 llms.txt リクエスト 1 回がティア 1、バンドルされたリファレンスがティア 2、MCP がティア 3 です。いずれにも検証済みのスニペットが含まれていない場合は、利用不可であると報告してください。
• 出力に明示的にラベルを付けてください — 「検証済みのスニペットはありません」と記載し、開発者が検証済みと利用不可の違いを把握できるようにします。

---

Step 4 — バンドルを組み立てる

SmartApps バンドルのオーバーライド

product=smartapps の場合、以下のジェネリックなサーバー/Web チェックアウトバンドルをレンダリングせず、.env 認証情報も作成しないでください。references/guides/smartapps.md からの SmartApps 固有のバンドルと、認証済みの MCP 結果を以下のセクションとともにレンダリングします: 商業契約、Android プロジェクトの適格性、アプリ種別 (main|mini)、所有権 (own|third-party)、最新のプライベート SDK アーティファクト、Manifest/初期化コントラクト、SDK のみの決済フロー、静的検証、開発用ターミナルでのテスト、および homologation。プライベートキットやターミナルに依然として依存するものには blocked とラベルを付け、推測されたパブリック SDK や API 呼び出しで置き換えないでください。その後、Step 4.5 に進みます。

Payouts バンドルのオーバーライド

product=money-out の場合、バンドルに Payouts とラベルを付け、references/guides/payouts.md と現在の国別ソースからサーバー専用バンドルをレンダリングします。ジェネリックなクライアント/決済フォームセクションをレンダリングせず、公開鍵を要求せず、チェックアウト CTA も作成しないでください。以下のセクションを含めます: 国別コントラクト、特権サービス境界、耐久性のある信頼された命令リポジトリ、オペレーター認可、監査証跡、冪等性、明示的なテストモード、本番 Ed25519 署名、リソース検索、通知、安全な自動テスト、および本番リリース管理。検証済みの公式 SDK が Payouts を公開していない場合は生の REST を使用し、fetch をラップするためだけに決済 SDK をインストールしないでください。

結果はこの正確な構造でレンダリングします。コードブロックは解決済みのドキュメントティアから取得します (可能な場合はそのまま)。

# Mercado Pago Integration — {Product} ({Country} · {SDK} · {mode})

## 1. Install
```bash
{install command for the chosen SDK}
```

## 2. Credentials

Get your credentials from the Mercado Pago Developer Dashboard:
👉 **https://{DOMAIN}/developers/panel/app**

- Under your application, click **Credentials**.
- For **testing**: click the **{test_tab}** to get test credentials.
- For **production**: use the credentials in the **{prod_tab}** tab.

Credentials come in two valid prefixes: **`APP_USR-`** (Orders API, Checkout Pro, Point, QR; also test-user credentials from `create_test_user`) and **`TEST-`** (Checkout API, Bricks, Payments API). Both are valid and actively issued — never tell a developer to change their prefix. What matters is which tab they come from: {test_tab} = test, {prod_tab} = production.

Create `.env` from the template below (**never commit `.env`**):

```
MP_ACCESS_TOKEN=APP_USR-...   # server-side, keep secret
MP_PUBLIC_KEY=APP_USR-...     # client-side, can be public
MP_WEBHOOK_SECRET=...         # from Dashboard → Webhooks → Signature secret
APP_URL=http://localhost:3000
```
Also ensure `.env` is in `.gitignore` (and `.env.example` is **not** ignored).

## 3. Server code
```{language}
{snippet from the resolved documentation tier — server-side creation, e.g., create order/preference/subscription/disbursement}
```

## 4. Client code (if applicable)

**Always show the total amount above the payment form** (do not bury it inside the brick):

```html

<p class="checkout-total">Total: <strong>{currency} {amount}</strong></p>
```

```{language}
{snippet from the resolved documentation tier — tokenization, brick mount, redirect, etc.}
```

**Payment feedback states — include ALL THREE in the scaffold (not as TODOs):**

```jsx
// Loading state — show while the payment is processing
{isLoading && (
  <div className="checkout-loading">
    <p>Processing your payment…</p>
  </div>
)}

// Success state
{paymentStatus === 'approved' && (
  <div className="checkout-success">
    <h2>Payment approved!</h2>
    <p>Order: <strong>{orderId}</strong></p>
    <p>Next step: run <code>/mp-review</code> to validate your integration before going live.</p>
  </div>
)}

// Error state — actionable, not the raw API error
{paymentStatus === 'error' && (
  <div className="checkout-error">
    <p>Payment could not be processed: {errorMessage}</p>
    <p>If testing, check your test card data or try a different scenario code —
       e.g. cardholder name <strong>APRO</strong> for approved, <strong>FUND</strong> for insufficient funds.</p>
  </div>
)}
```

> These three blocks are **part of the default scaffold on every run** — never leave them as `{/* TODO */}` placeholders. Adapt the conditional syntax to the detected client framework (React shown; use the equivalent for vanilla-js, Vue, etc.).

## 5. Webhook receiver
> Webhook validation is handled by the `mp-webhooks` skill — invoke it next, or run `/mp-integrate webhook` to scaffold the receiver with HMAC validation.

## 6. Test
- Get test credentials and test users via the `mp-test-setup` skill (or run `/mp-integrate test-setup`).
- Test cards for the country: see `references/products.md` (AR/BR/MX/CO/CL) or query MCP for others.
- After your first successful test payment → run `/mp-review` (**step 6 of 7 — MANDATORY before production**).

## 7. Docs (country-specific)
- Product guide: https://{DOMAIN}/developers/{LANG}/docs/{product-slug}/overview (fallback: /landing)
- API reference: https://{DOMAIN}/developers/{LANG}/reference

## 8. Gotchas
{render the gotchas for the chosen product from the Gotchas Bank below}

SDK	インストールコマンド
node	npm install mercadopago
python	pip install mercadopago
java	Maven: com.mercadopago:sdk-java / Gradle 相当
php	composer require mercadopago/dx-php
ruby	gem install mercadopago-sdk
dotnet	dotnet add package MercadoPago
go	go get github.com/mercadopago/sdk-go
react (client)	npm install @mercadopago/sdk-react
vanilla-js (client)	<script src="https://sdk.mercadopago.com/js/v2"></script>
ios	SPM: https://github.com/mercadopago/sdk-ios
android	Gradle: com.mercadopago:sdk

---

Step 4.5 — ファイルのスキャフォールドを提案する

⚠️ 必須 — このステップの前にバンドルがユーザーに表示されている必要があります。

Step 4 の完全なバンドルは、この AskUserQuestion 呼び出しの前に、レンダリングされた markdown 出力としてチャットに必ず表示されなければなりません — 毎回、すべての実行で、同じセッションの前のターンでリファレンスがすでに読み込まれていたとしても。レンダリングを省略しないでください。「referências já carregadas」または同等の表現を言って直接ここに飛ばないでください。現在の応答でバンドルが目に見える形でレンダリングされていない場合は、先に進む前にここでレンダリングしてください。

バンドルをレンダリングした直後に、次のステップを列挙する前に、AskUserQuestion を次の内容で呼び出します:

• header="Scaffold files"
• Question: "Do you want me to write these files to your project now?"
• Options:
  • "Yes, write the files" → 以下のスキャフォールドを実行する
  • "No, just the code" → ステップ 5 にスキップする

開発者がスキャフォールドを選択した場合、この順序を（順番どおりに — 各ステップは前のステップに依存します）実行します。

1. SDK のインストールまたは更新は承認を得た場合のみ行う — 公式レジストリを照会し、LOCK 1 を適用します。変更が必要な場合は、サーバーサイドのマニフェストを含むディレクトリで npm install mercadopago@latest（または検出された SDK に対応する安定版リリースの同等コマンド）を実行する前に、正確な安定版バージョンを示して明示的な承認を求めます。プレリリースを選択しないでください。ロックファイルを更新し、互換性のない統合コードを修正し、関連するテストを実行し、終了コードがゼロ以外の場合は停止します。現在の依存関係がすでにレジストリの安定版リリースに解決されている場合は、変更を加えず、検証済みのバージョンを報告します。

2. サーバースニペットを書き込む — サーバーファイル（例: backend/index.js、backend/src/routes/mercadopago.js）を作成または編集し、ステップ 4 のスニペットを挿入します。ファイルがすでに存在する場合は、上書きせず、既存のルートの後に新しいルートを挿入します。

   product=point の場合: サーバー統合を書き込んだ直後に Point サーバーの受け入れチェックを実行します。続行または成功の報告を行う前に、すべての失敗を修正してください。

   node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-point-server.mjs" "{server_file}"
   

   product=qr の場合: サーバー統合を書き込んだ直後に QR サーバーの受け入れチェックを実行します。アプリケーションの実際の課金 CTA にクライアントを接続した後、クライアントの受け入れチェックも実行します。続行または成功の報告を行う前に、すべての失敗を修正してください。

   node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-qr-server.mjs" "{server_file}"
   node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-qr-client.mjs" "{client_file}" 'data-mp-qr-cta="create-order"' "/api/qr/orders"
   

   product=bricks の場合: LOCK 9 を適用し、専用の Brick ページ、サーバールート（該当する場合）、ランタイムのパブリック設定、CTA の接続をすべて書き込んだ後に、アプリケーション全体のバリデータを実行します。

   node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-bricks-integration.mjs" . "{brick}"
   

   product=subscriptions の場合: サブスクリプション CTA、サインアップページ、トークン化（承認されている場合）、サーバールート、ライフサイクルルートを書き込んだ後に LOCK 10 を適用します。

   node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-subscriptions-integration.mjs" . "{subscription-model}"
   

   product=marketplace の場合: 出品者 OAuth、暗号化された永続化/リフレッシュ、選択されたチェックアウト契約、および出品者接続と購入者チェックアウトの両方の CTA を書き込んだ後に LOCK 11 を適用します。

   node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-marketplace-integration.mjs" . "{marketplace-checkout}"
   

   product=wallet-connect の場合: 専用ページ、チェックアウト CTA の接続、アカウントリンクルート、暗号化された支払者トークンの保存、Orders API ルートを書き込んだ後に LOCK 12 を適用します。

   node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-wallet-connect-integration.mjs" .
   

   product=smartapps の場合: Android Manifest、アプリケーションの初期化、SDK の支払いフローを書き込んだ後に LOCK 13 を適用します。解決されたアプリ種別と所有権を指定してバリデータを実行します。実際の最新キットアーティファクトが提供され、正常にコンパイルされていない限り、AAR が最新であるとか、ビルドが成功していると報告しないでください。

   node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-smartapps-integration.mjs" . "{main|mini}" "{own|third-party}"
   

   product=money-out の場合: 特権サービス、永続的な指示リポジトリ、認可/監査の制御、解決された国別契約、明示的なテストモード、本番署名、ルックアップルートを書き込んだ後に LOCK 14 を適用します。

   node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-payouts-integration.mjs" . "{AR|BR}"
   

2.5. checkout-pro と checkout-api — 必須のチェックアウト CTA の検出（その他のすべての製品ではスキップします）:

このステップは両方のチェックアウト製品で無条件です。具体的な CTA ターゲットが解決されるまで、スキャフォールドは不完全です。これらの製品は同じ検出器を使用しますが、ステップ 3.5 での接続が異なります。

• checkout-pro: 解決された CTA の場所に、表示される Pay with Mercado Pago ボタンを配置します。このボタンはプリファレンス作成ルートに送信され、init_point にリダイレクトします。
• checkout-api: 解決された CTA を、新しい独立したチェックアウト画面にリンクします。

LOCK 5 の結果を再利用します。何らかの理由でそれが利用できない場合は、バンドルされたリゾルバーをプロジェクトルートから正確に一度実行します:

node "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-checkout-cta.mjs" "{product}" .

まず、{product} を LOCK 5 が返す正規化された内部値で置き換えます。リゾルバーは HTML と一般的な Web テンプレート/コンポーネント（JSX、TSX、Vue、Svelte、Astro、PHP、ERB、EJS、Handlebars、Twig、JavaScript、TypeScript）をスキャンします。表示テキスト、属性、および実際のクリック/ナビゲーションハンドラーから意味的証拠をスコアリングします。アプリケーション固有のセレクターは含まれていません。

ターゲットを解決する:

1. 一致が有効と見なされるのは、その要素、表示テキスト、位置、および現在のハンドラーが組み合わさって、チェックアウトを開始する最終アクションを示している場合のみです。一般的なナビゲーションリンクや商品カード上の「購入」ボタンは十分な証拠ではありません。
2. 生成された決済フォーム内の送信ボタン（form-checkout、type="submit"、mp-pay-btn）を除外してください — そのボタンは決済を送信するものであり、フォームへのリンクではありません。
3. 何かを変更する前に、候補の既存の onclick、onClick、href、または addEventListener を読み取ってください。
4. 検出器が status=selected を返した場合、その CTA を使用し、{file}:{line} を報告します。この結果は必須です。「見つかりません」に格下げしないでください。
5. status=ambiguous を返した場合、AskUserQuestion を介して、どの候補がチェックアウト CTA であるかを尋ねます（最大 4 つの候補）。スキャフォールドを続行する前に、ターゲットを選択する必要があります。
6. status=not_found を返した場合、アプリケーションの実際のカート/注文/商品エントリー画面を調査し、AskUserQuestion を介して、新しいチェックアウト CTA をどこに挿入すべきかを尋ねます（最大 4 つの具体的なファイル/場所の選択肢）。開発者が選択した後、cta_status=create を設定し、その正確な場所を使用します。
7. ambiguous または not-found の結果の後で開発者がターゲットを提供しない場合、BLOCKED: checkout CTA target required で停止します。スキャフォールドを完了したり、CTA を黙って省略したり、成功を報告したりしないでください。

{cta_file}、{cta_line_or_region}、{cta_selector}、{cta_status}、および既存のハンドラーを Step 3.5 用に保存します。まだ編集しないでください。サーバールートと、Checkout API の場合は新しいチェックアウト画面が先に存在している必要があります。

3. checkout-api のみ — 常に新しいファイルに別のチェックアウト画面を作成します — プロジェクトのアーキテクチャを使用して、Step 4 からクライアントフォームを生成します。checkout-pro の場合は、直接 Step 3.5 にスキップします。Checkout Pro は Mercado Pago にリダイレクトするため、ローカルの決済フォーム画面を作成してはなりません。

   これは Checkout API では無条件です。画面は、Step 2.5 がそのエントリー CTA の配置場所を解決した後に作成されます。

   • サーバーサイドレンダリング/静的アプリ: チェックアウト画面用の新しい HTML/テンプレートファイルと、そのファイルを提供する GET ルートまたは静的 URL を作成します。
   • React/Vue/Angular/SPA: 新しいページ/画面コンポーネントファイルを作成し、アプリケーションの既存のルーターを通じて専用ルートを登録します。
   • モバイルアプリ: 新しい画面ファイルを作成し、既存のナビゲーションスタックに登録します。
   • ルーターのない単一ファイルアプリケーション: それでも別のチェックアウトページファイルを作成し、URL を通じて公開します。既存のファイルに別の非表示ビューを追加しないでください。

   分離ルール: 生成された決済フォームを、既存のカート、商品、ドロワー、モーダル、アコーディオン、タブ、または条件付きで非表示になるセクション内に配置しないでください。フォームのマークアップを既存の画面ファイルに追加しないでください。共有レイアウト、スタイル、コンポーネントはインポートまたは再利用できますが、チェックアウト画面自体はその新しいファイルが所有し、独自のルート/URL/ナビゲーション先を通じて開かれる必要があります。

   プロジェクトの命名規則とルート規則を再利用します。以下を記録します:

   • {checkout_screen_file} — 画面用に作成された新しいファイル。
   • {checkout_screen_destination} — そのルート、URL、またはナビゲーション名。
   • {checkout_screen_invocation} — それを開くために必要なフレームワークに適したコード。

   新しいファイルが存在し、ルート/ナビゲーションの登録が検証されるまで、その目的地に何もリンクしないでください。

   Checkout API 公開キーの配信 — 必須かつアプリケーション非依存:

   1. チェックアウト画面を生成する前に、対象アプリケーションに既存のクライアント設定の慣習があるか検出してください。React、Next.js、Vue、Nuxt、Angular、モバイル、サーバーレンダリングのテンプレートについては、その確立された公開ランタイム設定を再利用してください。別のスタックに Express 固有のパターンを押し付けないでください。
   2. 生成されたクライアントファイルに %MP_PUBLIC_KEY% やその他のテキスト置換トークンを絶対に含めないでください。チェックアウトの HTML レスポンスを書き換える方法に依存しないでください。ブラウザ、CDN、サービスワーカー、静的ホストは、リテラルトークンを含む古いドキュメントを保持する可能性があります。
   3. バックエンドを備えたバニラ／ビルドなしのアプリケーションでは、プロジェクトのサーバーフレームワークとルートの慣習に従って JSON 設定エンドポイントを追加してください。これはサーバー上で MP_PUBLIC_KEY を読み取り、{ publicKey } を返し、Cache-Control: no-store, max-age=0 を送信し、変数が存在しない場合は明確なエラーとともに非 2xx レスポンスを返す必要があります。チェックアウト画面は MercadoPago を構築する前に、cache: 'no-store' を指定してそのエンドポイントをリクエストする必要があります。
   4. ビルドベースのクライアントでは、フレームワークの公開変数の慣習（たとえば既存の Vite、Next.js、Nuxt、Angular の仕組み）のみを使用し、サーバーの再起動または再ビルドが必要かどうかを説明してください。MP_ACCESS_TOKEN やその他のプライベートな認証情報を公開しないでください。
   5. 静的のみのサーバーでは、決済の作成にバックエンドが必要なため Checkout API を完了できません。アプリケーションが現在静的ファイルサーバーで実行されている場合は、生成されたバックエンドをプロジェクトの実際の start/dev コマンドに組み込み、そのコマンドを使用するよう開発者に伝えてください。HTML ファイルを直接開くように指示しながら成功したと主張しないでください。
   6. 生成されたフォームまたは画面のルートに、実際に使用した戦略に合わせて data-mp-public-key-source="runtime-endpoint" または data-mp-public-key-source="framework-public-config" を付けてください。
   7. 成功の前に、生成されたクライアントに未解決の公開キートークンが含まれていないこと、エンドポイント戦略を選択した場合はクライアントとサーバーがまったく同じ設定ルートを使用していること、キーが存在しない場合の経路が可視化され実行可能であること、チェックアウト画面がアプリケーションの実際のサーバー／ルーターを経由して到達されることを検証してください。

   Checkout API のセキュアフィールドの整合性 — 必須かつアプリケーション非依存:

   • 最小限の有効なフォームを構築します。常に表示されるカード入力欄は cardNumber、expirationDate、securityCode、cardholderName です。

   • 支払者メールアドレスと本人確認情報は必須の支払いデータですが、自動的に必須の表示入力欄になるわけではありません。認証済みの購入者/セッション/カートからすでに利用可能な信頼できる値を再利用します。アプリケーションがそれらの値を持っていない場合にのみ入力欄をレンダリングし、選択した戦略をフォーム上で data-mp-payer-email-source="form|application" および data-mp-payer-identification-source="form|application" としてマークします。

   • SDK JS の CardForm マップでは、製品の UX がそれらのコントロールを表示しない場合でも、issuer、installments、identificationType が必要です。常にそれぞれに対して <select> をちょうど 1 つレンダリングし、フォーム内に配置し、data-mp-sdk-required-field="issuer|installments|identificationType" でマークし、その正確な ID を mp.cardForm({ form: ... }) で参照します。3 つのうちいずれかを省略するとスキャフォールドの失敗となります。SDK は支払い方法のライフサイクル中にそれらを設定するため、対応する DOM ターゲットが存在しないと、セキュア iframe フィールドが応答しなくなる可能性があります。

   • これら 3 つのコントロールのいずれかが表示 UX の一部ではない場合、実際の非表示ライフサイクルノード <select hidden aria-hidden="true" tabindex="-1"> を使用します。disabled は使用しないでください。無効化されたコントロールはフォーム/SDK の状態に参加できないためです。これらの非表示 select は SDK の配管であり、バックエンドが信頼する支払いデータではありません。

   • 本人確認の種類は、解決された国と購入者のコンテキストから導出します。たとえば、ブラジルの個人購入者は CPF を使用します。種類が判明している場合は、必須の identificationType ライフサイクル select を非表示のままにします。アプリケーションが複数の種類を実際にサポートしており、正しいものを推測できない場合にのみ、ラベル付きの表示セレクターにします。

   • 必須の issuer ライフサイクル select はデフォルトで非表示のままにします。支払い方法のメタデータが issuer_id を含む additional_info_needed を報告する場合にのみ、ラベル付きの表示セレクターにします。Orders API の payment_method 内で issuer_id を送信しないでください。

   • 必須の installments ライフサイクル select は、最小限の単発フローでは非表示のままにし、サーバー側で installments: 1 を強制します。開発者が分割払いを明示的に提供したい場合にのみ、ラベル付きの表示セレクターにします。サーバー側のルールではなく、非表示のブラウザー値を決して信頼しないでください。

   • mp.cardForm({ form: ... }) に登録されるすべてのフィールドは、mp.cardForm(...) が実行される前に、DOM 内にちょうど 1 つの対応する要素を持たなければなりません。アプリケーションの状態から供給することを選択した後、または UI から省略した後に、オプションのフィールドを設定しないでください。

   • form.id のフォーム ID は、レンダリングされた <form id="..."> と正確に一致しなければなりません。

   • すべてのフィールドに対して、プロジェクトの言語にローカライズされた永続的な表示ラベルをレンダリングします。MM/AA や CVC といったプレースホルダーはヒントであり、ラベルではないため、セキュア iframe 内にレンダリングされない可能性があります。

   • iframe フィールド（cardNumber、expirationDate、securityCode）については、SDK ホストの <div> を空のままインタラクティブに保ちます。ホストまたはその iframe に disabled、readonly、pointer-events: none、または重なり合う装飾要素を追加しないでください。

   • 各セキュアホストにゼロ以外の高さと position: relative を付与し、注入された iframe を display: block、width: 100%、height: 100% にします。表示される枠線はホストに属し、オーバーレイには属しません。

   • セキュアフィールドは、新しいチェックアウト画面のルートが表示され、ホストがゼロ以外の寸法を持った後にのみマウントします。アプリケーションのライフサイクル/ルーターフックまたは requestAnimationFrame を使用します。display: none の状態で初期化しないでください。また、可視性の仕組みとして任意の setTimeout を使用しないでください。

   • 表示されているフォームインスタンスごとにちょうど 1 回マウントします。SPA では、再マウントする前に以前の SDK コントローラーまたはフィールドインスタンスをアンマウント/破棄します。

   • 各セキュアホストを、外部の表示ラベルとアクセシブルな関係でグループ化します。たとえば、次のとおりです。

     <div class="checkout-field" role="group" aria-labelledby="expiration-label">
       <span id="expiration-label" class="checkout-label">Validade do cartão (MM/AA)</span>
       <div id="form-checkout__expirationDate" class="secure-input"></div>
     </div>
     

   • 支払いの送信ボタンは、取得中または送信中のみ無効化してください。ローディング状態の管理の一環としてカードデータフィールドを無効化しないでください。

   • onFormMounted では、各セキュアホストに iframe がちょうど 1 つ含まれていること、サイズがゼロでないこと、表示される外部ラベルがあること、そしてホストと iframe のいずれも pointer-events: none になっていないことを検証してください。失敗した場合はコンソールと表示されるフォームエラーの両方に通知し、スキャフォールドが成功したと報告しないでください。

   続行する前に、登録されたフィールド ID とレンダリングされた ID を双方向で比較してください。次に、生成されたソースを検査し、disabled、readonly、aria-disabled、inert、オーバーレイ、およびセキュアホストやその祖先要素に影響する pointer-events を確認してください。ラベルの欠落、マウントの非表示、インスタンスの重複、操作不能なホストはスキャフォールドの失敗であり、直ちに修正する必要があります。

   すべての表示されるフィールドラッパーに data-mp-field="{fieldName}" を付け、3 つの SDK iframe ホストに data-mp-secure-field="cardNumber|expirationDate|securityCode" を付け、必須の 3 つの CardForm ライフサイクル select に data-mp-sdk-required-field="issuer|installments|identificationType" を付けてください。フォームは、支払者のメールアドレスと識別情報がフォームから来るのかアプリケーション状態から来るのかを、上記のソースマーカーを使って宣言する必要があります。新しい画面を作成したら、決定論的な受け入れチェックを実行してください:

   # runtime-endpoint strategy: pass the file that implements the config route
   node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-checkout-screen.mjs" "{checkout_screen_file}" "{server_or_config_route_file}" "{cta_file}"
   
   # framework-public-config strategy: no server config file is needed
   node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-checkout-screen.mjs" "{checkout_screen_file}" "" "{cta_file}"
   

   失敗した場合は、新しい画面を修正して再実行してください。このコマンドがコード 0 で終了するまで、スキャフォールドの成功サマリーを表示しないでください。

3.5. checkout-pro と checkout-api — 解決された CTA を常に配線する:

解決された CTA は必須です。周囲のレイアウトを保持し、プロジェクトのボタンクラスとアクセシビリティの規約を再利用してください。最終要素に data-mp-checkout-cta="{product}" を付けて、決定論的チェックが統合を検証できるようにします。

product=checkout-api の場合: 既存の CTA の表示テキストとスタイルを保持し、そのナビゲーション動作のみを置き換えて {checkout_screen_destination} を開くようにします。

• 既存の <a>: data-mp-checkout-cta="checkout-api" を追加し、href="{checkout_screen_destination}" を設定または更新します。
• 素の <button>: data-mp-checkout-cta="checkout-api" を追加し、既存のチェックアウトハンドラーを、ちょうど 1 つの window.location.assign('{checkout_screen_destination}') アクションに置き換えます。
• React/Vue/router アプリ: data-mp-checkout-cta="checkout-api" を追加し、既存のルーターナビゲーション API を使用します。アプリケーションがすでにクライアントサイドルーティングを使用している場合は、window.location を導入しないでください。
• cta_status=create の場合: ステップ 2.5 で選択した正確な位置に、プロジェクトのスタイルに合ったボタンまたはリンクを 1 つ挿入し、新しい画面に配線します。

product=checkout-pro の場合: 解決された位置に、Pay with Mercado Pago（アプリケーションの言語にローカライズ）とラベル付けされた表示ボタンを配置します。このボタンはプリファレンスの作成を開始し、返された init_point にリダイレクトする必要があります。ローカルのカードフォームを開いてはいけません。

• サーバーレンダリングまたは静的アプリ: 選択した CTA を置き換えるか、選択した領域に、プリファレンスルートに POST するフォームを挿入します:

  <form action="{preference_route}" method="POST">
    <button type="submit" data-mp-checkout-cta="checkout-pro" class="{existing_button_classes}">
      Pagar com Mercado Pago
    </button>
  </form>
  

• SPA/フレームワークアプリ：data-mp-checkout-cta="checkout-pro" を持つ、プロジェクトのスタイルに合わせた可視ボタンを 1 つだけ維持してください。その単一のハンドラーはバックエンドのプリファレンスルートを呼び出し、返された init_point へナビゲートする必要があります。2 つ目のリスナーを重ねるのではなく、古いチェックアウトハンドラーを削除してください。

• Checkout Pro 用に 2 つ目のチェックアウトページを作成しないでください。選択した CTA の場所が、Mercado Pago ボタンが属する場所です。

編集後の必須検証：

1. 最終的な要素が正確に 1 つだけ data-mp-checkout-cta="{product}" を持っていることを確認します。

2. Checkout API の場合、{checkout_screen_file} が分離されていること、{checkout_screen_destination} がそれに解決されること、CTA がその遷移先へのナビゲーションアクションを正確に 1 つだけ持つことを確認します。

3. Checkout Pro の場合、可視ボタンが Mercado Pago と表示され、init_point へリダイレクトするプリファレンス作成ルートに到達することを確認します。

4. 古い CTA ハンドラーが削除されており、クリックで 2 つのチェックアウトフローがトリガーされないことを確認します。

5. Checkout API の場合、支払いフォーム自身の送信ボタンがエントリー CTA と誤認されたり、配線し直されたりしていないことを確認します。

6. 決定論的 CTA 受け入れチェックを実行し、失敗があれば続行する前に修正します：

   node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-checkout-cta.mjs" "{product}" "{cta_file}" "{checkout_screen_destination_or_preference_route}"
   

   Checkout Pro の場合は、サーバーバリデーターも実行します。これはアプリケーションに localhost フォールバックがある場合、無条件の auto_return を拒否します：

   node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-checkout-pro-server.mjs" "{server_file}"
   

7. ✓ {cta_file}:{cta_line_or_region} → {checkout_screen_destination_or_preference_route} を報告します。Checkout Pro または Checkout API において、「CTA がリンクされていない」という成功結果はありません。

8. .env.example を作成する — テンプレート変数（MP_ACCESS_TOKEN、MP_PUBLIC_KEY、MP_WEBHOOK_SECRET、APP_URL）を .env.example に書き込みます。実際の値を持つ .env は、開発者が明示的に認証情報のインポートを選択し、get_credentials が成功した場合にのみ作成してください。確認なしに既存の .env を上書きしないでください。それ以外の場合は、決して .env を作成しないでください — 開発者が自身の認証情報を入力する必要があります。

9. .gitignore を更新する — .env、.env.*.local、.mp-integrate-progress.md がまだ存在しない場合は追加します。 5.5. スキャフォールディング成功後に .mp-integrate-progress.md を削除する — このファイルはクラッシュ/キャンセル時の再開チェックポイントにすぎません。最終的な製品バリデーターを実行する前、および成功サマリーを出力する前に削除してください。実行がキャンセル、ブロック、または失敗した場合にのみ保持します。完了した統合にこのファイルを残したままにしないでください。

10. すべての書き込み後、製品固有のサマリーを出力します。どちらの成功結果にも、配線済みの CTA を含める必要があります：

Checkout API:

✓ npm install mercadopago — OK
✓ {server_file} — Checkout API route added
✓ {checkout_screen_file} — separate checkout screen created
✓ MP_PUBLIC_KEY — loaded through {detected_config_strategy}; no HTML placeholder
✓ {cta_file}:{line} {cta_selector} → {checkout_screen_destination} → {checkout_screen_file}
✓ .env.example — created (fill in your credentials)
✓ .gitignore — updated

Checkout Pro:

✓ npm install mercadopago — OK
✓ {server_file} — preference route added
✓ {cta_file}:{line} — Pay with Mercado Pago button → {preference_route}
✓ .env.example — created (fill in your credentials)
✓ .gitignore — updated

スキャフォールドのガードレール：

• 現在の作業ディレクトリ外のファイルには決して書き込まないでください。
• get_credentials 経由で認証情報を取得した場合： 確定済みの .env を上書きしないでください。プレースホルダーを含む .env.example のみを作成します。
• 認証情報をインポートしなかった場合： APP_USR-... プレースホルダーを含む .env.example を作成します。ここでは決して .env を作成しないでください。
• 対象ファイルが存在し、開発者が「すべて書き込む」と指示した場合、上書きするのではなくコードを注入します — 変更内容の +diff 形式のプレビューを表示します。
• いずれかの書き込みが失敗した場合、正確なエラーを報告して停止します。次のファイルに進まないでください。
• HTML への認証情報注入の禁止： %MP_PUBLIC_KEY%、.replace(...)、テンプレートトークン置換、またはインラインのハードコードされた公開鍵を生成しないでください。検出されたフレームワークの公開設定規約、またはバニラ/サーバーアプリケーション向けの no-store JSON ランタイム設定エンドポイントを使用してください。

---

ステップ 5 — 次のステップを提案する

必ず次の内容で締めくくります:

1. /mp-integrate webhook を実行して、Webhook レシーバーを追加します（HMAC 検証を含みます）。

2. /mp-integrate test-setup を実行して、テストユーザーを作成し、資金をロードします。 2.5. Orders API 製品（checkout-api / qr / point — すべての国）の場合: 次のステップを一覧表示する前に、AskUserQuestion で確認します:

   • 質問: 「Orders API では、支払いを処理するためにテスト購入者ユーザーが必要です。今すぐ作成しますか？」
   • 選択肢: "Yes, create test user now" → mp-test-setup スキルをインラインで呼び出します。"No, I'll do it later" → リマインダーを表示します: 「⚠️ テスト前に /mp-integrate test-setup を実行してください — Orders API はテストユーザーがないと 422 を返します。」
   • 注記: Card Payment と Payment Bricks は Payments API を使用するため、Orders の購入者フローは必要ありません。Wallet は依然として Mercado Pago にログインした購入者が必要です。Status Screen は既存の支払い ID が必要です。

3. /mp-review を実行 — 本番環境に進む前に必須です。 これは統合ジャーニーの7 ステップ中 6 番目です。自動チェッカーは、最初の支払い後に統合を自動的に検証します。/mp-review が合格するまで、本番環境の認証情報に切り替えないでください（ステップ 7）。

現在、7 ステップ中 6 番目です。/mp-review が合格した後、残る唯一のステップは本番環境の認証情報への切り替えです。

---

落とし穴バンク

選択した製品に一致するセクションのみをレンダリングします。これらは、ドキュメントでは明確に示されていない経験則の落とし穴です。簡潔に保ってください。

checkout-pro

• 常に init_point を使用し、sandbox_init_point は決して使用しないでください。 Mercado Pago にはサンドボックスがなく、本番 API のみが存在します。テスト実行では、別の URL ではなく、テストユーザーの認証情報（APP_USR-）を使用します。
• currency_id は国と一致する必要があります（ARS、BRL、MXN、CLP、COP、PEN、UYU）。
• back_url のクエリパラメータだけを信頼しないでください — 常にサーバー側で支払いステータスを再取得してください。
• auto_return=approved には back_urls.success の設定が必要です。そうでない場合は黙って無視されます。
• external_reference は照合のアンカーです — すべてのプリファレンス／注文に設定してください。

checkout-api

• ⛔ Orders API にはテストユーザーの購入者が必要です — 任意のメールアドレスを使用すると 422 unprocessable_content が返されます。テストの前に /mp-integrate test-setup を実行してください。これはすべての国に適用されます。
• getCardFormData() はキャメルケースを返します — payment_method_id や issuer_id ではなく、paymentMethodId と issuerId です。サーバー側でマッピングしてください。
• Orders API では payment_method 内に issuer_id は許可されていません — ペイロードから削除しないと additionalProperties not allowed が返されます。
• 最小限の Checkout API UI — 常にカード番号、有効期限、セキュリティコード、カード名義人を表示してください。購入者のメール／識別情報は、信頼できるアプリケーションの状態がすでに提供していない場合にのみ収集してください。SDK が要求する issuer、installments、identificationType のセレクトは、DOM／CardForm マップ内に保持しつつ、最小限の UI からは非表示にしてください。加盟店が明示的に分割払いを提供しない限り、サーバー側で installments: 1 を強制してください。
• total_amount と amount は "10" ではなく "10.00" でなければなりません — Number(x).toFixed(2) を使用してください。
• ブラジル（MLB）: この製品は Checkout Transparente と呼ばれます — MCP クエリではその名前を使用してください。
• カードトークンは 1 回限りで、7 日後に期限切れになります。
• 支払い作成時には常に冪等性キーを送信してください。これがないリトライは重複請求を引き起こします。

bricks

• バックエンドはバリアントごとに異なります。 card-payment と payment は Payments API 経由で作成します。wallet は /checkout/preferences（v1 なし）で動的プリファレンスを作成します。status-screen は既存の paymentId を表示するだけです。
• 請求金額は常に brick の上に表示してください。 brick は合計金額を目立つようにレンダリングしないため、購入者は自分がいくら支払うのかわかりません。コンテナ div の上に <p>Total: <strong>{currency} {amount}</strong></p> を追加してください。
• UI には常に 3 つの支払い状態を含めてください。 (1) brick の初期化中および onSubmit の実行中に表示するローディング／スピナー。(2) 支払い ID と「Payment approved」メッセージを表示する成功状態。(3) 生の API エラー文字列ではなく、対処可能なメッセージ（「カードが拒否されました — 別のカードをお試しください」）を表示するエラー状態。これらが欠けていると、購入者は支払いが完了したかどうかを判断できません。
• コンテナ <div id="..."></div> は bricksBuilder.create(...) を呼び出す前に DOM に存在している必要があります。setTimeout は解決策ではありません。onReady または ref をマウントした React の useEffect を使用してください。
• onSubmit はサーバーが応答した後に解決される Promise を返す必要があります。void を返すと、brick は永遠にローディング状態のままになります。
• Card Payment Brick の場合：金額の検証はサーバー側で行われます。brick がエコーした金額を決して信用しないでください。
• Wallet Brick では、購入者が Mercado Pago にログインしている必要があります。テストユーザーは、その認証情報を使用すればログイン済みとして扱われます。
• Status Screen Brick は 3DS チャレンジのレンダリングを処理します。独自の 3DS iframe を併せてレンダリングしないでください。
• 広告ブロッカー（uBlock、AdBlock Plus、Brave shields）は sdk.mercadopago.com をブロックします → brick は FIELDS_SETUP_FAILED を発生させ、マウントにサイレントに失敗します。開発者が「brick が表示されない」と報告した場合は、コードをデバッグする前に広告ブロッカーを確認してください。
• デビットカードでは分割払いセレクターが表示されません — これは正しい動作であり、バグではありません。サーバーがデビットに対して installments: 1 を受け入れ、セレクターフィールドの存在を必須としないようにしてください。
• preferenceId をプレースホルダーとしてハードコードしないでください（例：<PREFERENCE_ID>、YOUR_PREFERENCE_ID、"preference_id"）。brick はサイレントに失敗します。preferenceId は常に購入者セッションごとにサーバー上で動的に作成する必要があります。
• ブラウザーからの Wallet アイテム価格を決して信用しないでください。 不透明なカート／購入 ID を送信し、Mercado Pago を呼び出す前に、信頼できるサーバー側の状態からプリファレンスのアイテムと金額を再構築してください。
• プリファレンスはバージョンプレフィックスやセグメントを使用しません。 有効なパスは正確に /checkout/preferences です。
• Status Screen Brick には payment_id が必要です — POST /v1/payments レスポンス（response.id）から抽出し、brick に渡してください。注文 ID を渡さないでください。
• Vanilla ビルダーのライフサイクル： bricksBuilder.create() が返すコントローラーを保持し、そのコンテナを再構築または削除する前に controller.unmount() を呼び出してください。React SDK コンポーネントは自身のコントローラーライフサイクルを管理します。その周囲に 2 つ目のコントローラーを作成しないでください。
• back_urls は brick をマウントするページと同じオリジンでなければなりません。 クロスドメインの back_urls はサイレントに失敗します — 支払い後のリダイレクトはエラーなしで空白ページに到達します。

qr

• 新しい統合では常に type: "qr" を指定して Orders API を使用します。レガシーの /instore/... ルートおよび QR エンコードされた Checkout リダイレクト URL はスキャフォールドの失敗です。
• 注文の前にストアと POS が存在している必要があります。config.qr.external_pos_id は POS の external_id と正確に一致し、その注文を作成するトークンを持つ販売者に属している必要があります。
• 有効なモードは static、dynamic、hybrid です。type_response.qr_data を返すのは dynamic と hybrid のみです。static は POS 作成時に返される QR を使用します。
• QR データはローカルでエンコードし、サードパーティの画像ジェネレーターに決して送信しないでください。注文をポーリングし、created、processed、canceled、expired、refunded を明示的に処理してください。
• QR Orders の webhook は orders トピックを使用します。実際の processed／refund テストには、購入者テストアカウントでのスキャンが依然として必要です。QR 用に Point の /events シミュレーターをでっち上げないでください。

point

• 新しい連携では、type: "point" と config.point.terminal_id を指定した Orders API を使用します。/point/integration-api/.../payment-intents、type: "instore"、config.device.id を決してスキャフォールドしないでください。
• 物理ハードウェアがない場合は、標準の仮想端末 NEWLAND_N950__SBX0000001 を明示的なテストモードでのみ使用し、各注文の結果を /v1/orders/{order_id}/events 経由でシミュレートしてください。これは連携品質の測定には有効ではありません。
• 物理デバイスは（アプリケーションではなく）ユーザー ID にペアリングし、PDV モードで実行する必要があります。誤ったユーザーにペアリングされたデバイスは、注文を通知なく拒否します。
• ファームウェア更新後、デバイスが再びオンラインになるまで約 2 分かかる場合があります。注文作成を積極的にリトライしないでください。
• Point（Orders API）の Webhook トピックは orders です。レガシーの point_integration_wh トピックは旧 Point Integration API に属します — 新しい連携には使用しないでください。

subscriptions

• スキャフォールドする前に、with-plan、without-plan-authorized、without-plan-pending のいずれかを選択してください。プランなしで作成された preapproval は、後からプラン付きへ移行することはできません。
• 手動のカードトークンフィールドを決して公開しないでください。認可済み契約には安全な MercadoPago.js トークン化が必要です。pending はトークンを省略し、init_point にリダイレクトします。
• 関連付けられたプラン ID とすべての定期条件はサーバー側で制御されます。プラン ID、金額、通貨、頻度をブラウザから受け入れないでください。
• 定期課金は失敗時にリトライされます。authorized、pending、paused、canceled を明示的にサポートし、GET/Webhook 経由で照合してください。
• back_url は本番環境では HTTPS でなければなりません。HTTP はローカル開発のフォールバックにのみ許容されます。

marketplace

• Marketplace は OAuth とチェックアウト契約であり、単独の Orders API ではありません。まず Checkout Pro、Checkout API/Payments、または Wallet Brick のいずれかを決定してください。
• 暗号学的なワンタイム OAuth state、正確に設定されたリダイレクト URI、暗号化された永続トークン、およびアトミックなリフレッシュトークンローテーションを使用してください。販売者のトークンを公開したりログに記録したりしないでください。
• 販売者、カート金額、手数料は信頼できるサーバー状態から決定してください。seller_id、collector_id、金額、手数料を購入者リクエストから受け入れないでください。
• Checkout Pro/Wallet は /checkout/preferences の marketplace_fee を使用します。Checkout API は /v1/payments の application_fee を使用します。Authorization ヘッダーの販売者 OAuth トークンが受取販売者を決定します。決済ペイロードに collector_id を勝手に記載しないでください。

wallet-connect

• Mercado Pago による商用有効化が必要です。 明示的に有効化されていない場合は、プロジェクトファイルを変更する前に停止してください。
• ユーザーは MP ウォレット UI で連携を承認する必要があります — サイレント連携はありません。
• 専用のアカウント連携ページを作成し、アプリケーションに実在する最終チェックアウト CTA がある場合はそれをそこに接続してください。
• 承認コードと支払者トークンはサーバー専用です。支払者トークンは永続ストレージに暗号化して保存し、ブラウザやログに決して公開しないでください。
• 連携後、決済は Orders API を通じて購入者の保存済み支払い方法を使用します — カード情報を渡したり、MercadoPago.js を読み込んだり、Wallet Brick で代替したりしないでください。
• 一意の冪等性キー、信頼できる購入データ、および小数点以下 2 桁が一致する注文/決済金額を使用してください。

money-out

• 現在の製品名は Payouts です。廃止された汎用 disbursements 契約を決してスキャフォールドしたり、Advanced Payments で代替したりしないでください。
• API 契約は国ごとに異なります。コードを生成する前にそれを決定し、アルゼンチン向けペイロードをブラジル向けに、またはその逆に再利用しないでください。
• Payouts は特権的なサーバーサイドの資金移動操作です。オペレーターの承認、信頼できる永続的な指示、永続化された冪等性、および監査証跡を必須としてください。ブラウザからの送金先や金額を決して信頼しないでください。
• テスト呼び出しには、明示的な Payouts テストモードと公式のテストヘッダーが必要です。本番環境では、正確にシリアライズされたボディに対する Ed25519 署名が必要です。
• accepted、created、pending は最終的な入金確定ではありません。返却されたリソースをルックアップと Webhook で照合してください。

smartapps

• Mercado Pago チームとの直接の連絡が必要です — SmartApps はセルフサービスではありません。開発者が MP との有効な契約を結んでいることを確認せずにスキャフォールドしないでください。
• SmartApps は Point デバイス上で動作します — コードの制限や API はサーバー SDK とは異なります。常に MCP に SmartApps 固有のガイドを問い合わせてください。
• Web アプリケーションを SmartApp として流用しないでください。ターゲットは Android でなければなりません。開発者がそのスコープを承認した後にのみ、別の Android アプリ／モジュールを作成してください。
• SDK は Mercado Pago インテグレーションキットのプライベート AAR です。更新する前に確認し、インテグレーションチームが確認した最新のアーティファクトのみを使用し、公開 SDK の座標で代用しないでください。
• 静的バリデータは、実際の AAR でのコンパイル、開発用端末でのサンドボックスモックテスト、または Mercado Pago の公認を置き換えることはできません。

---

このスキルが行わないこと

• Webhook の検証は行いません。mp-webhooks スキル（または /mp-integrate webhook）を使用してください。
• テストユーザーの作成は行いません。mp-test-setup スキル（または /mp-integrate test-setup）を使用してください。
• インテグレーションの品質評価は行いません。mp-review スキル（または /mp-review）を使用してください。
• 記憶からコードをでっち上げることは行いません。スニペットは国ごとの WebFetched 公式 llms.txt（ティア 1）、references/products.md（ティア 2）、または MCP search_documentation（ティア 3 フォールバック）から取得されます。トレーニングデータの記憶のみに基づくことは決してありません。