テストと運用のワークフローで Mercado Libre の SMS 認証を扱う

状況：多数のサイトにまたがるマーケットプレイスの上で開発する

Mercado Libre はラテンアメリカ各地で地域別のサイトを運営しており、出品者向け連携、物流ダッシュボード、価格監視ツールなどは、複数のサイトに対してテストしなければならないことがよくあります。テスト用アカウントはそれぞれ国に紐づき、いずれ電話番号を求められます。スタッフの携帯電話に頼ると、業務アカウントに私用番号が結びつき、起きている担当者を待つあいだテストが止まってしまいます。

OTP Route の Mercado Libre 向け仮想番号なら、QA と運用チームはもっとすっきりした方法を取れます。適切な市場の番号を用意し、API でコードを取得でき、個人の SIM は不要です。マーケットプレイスを扱うチームは、マーケットプレイス向けソリューションも参考にしてください。

Mercado Libre が電話番号を求めるのはどんなときか？

大手マーケットプレイスの多くと同様に、Mercado Libre はいくつかの決まった場面で電話認証を使います。アカウント作成時、見慣れない端末からのサインイン時、アカウント回復時、セキュリティ情報の変更時です。SMS には短い数字のコードが含まれ、通常はスペイン語、ブラジルのサイトである Mercado Livre ではポルトガル語で届きます。文面はいつでも変わりうるため、テストではメッセージ本文に一致させるのではなく、数字を抽出するようにしてください。

Mercado Libre の電話番号を提供できるのはどの国か？

mercado サービスは現在 201 か国のルートで利用できます。多くのチームが選ぶのは、マーケットプレイス自体の展開地域に合う国です。アルゼンチン、ブラジル、メキシコ、コロンビア、チリ、ウルグアイ、ペルー、エクアドル、ボリビア、パラグアイ、ベネズエラ、コスタリカ、パナマ、グアテマラ、エルサルバドル、ホンジュラス、ドミニカ共和国、米国です。

国の選択は見た目だけの問題ではありません。ある地域のサイトに登録されたアカウントは、一般にその市場の番号を想定しているので、テストケースに合ったルートを選んでください。提供状況は一日のなかで変わるため、実行のたびに GET /api/v1/countries を確認しましょう。

Mercado Libre 認証コード API はどのように動くのか？

Developer コンソールで発行した Bearer キー（プレフィックス or_live_）を使い、https://otproute.com/api/v1 に対して次の順で実行します。

1. 料金を確認します。例：GET /api/v1/prices?country=ar&service=mercado
2. POST /api/v1/activations に {"service": "mercado", "country": "ar"} を送ってアクティベーションを作成します。
3. 返ってきた番号を Mercado Libre の認証画面に入力します。
4. activation.sms_received イベントを受け取るか、GET /api/v1/activations/{id} をポーリングします。

Webhook では、X-OTPRoute-Signature（エンドポイントのシークレットによる <t>.<raw body> の HMAC-SHA256）を検証し、古いタイムスタンプを拒否し、ハンドラーを冪等にします。アクティベーション ID をキーにすれば、再配信されても同じコードを二重に送信することはありません。ポーリングは短いスクリプトに、Webhook は CI に向いています。マーケットプレイスのテストマトリクスは、アカウントごとの上限（キー 10 個、Webhook エンドポイント 5 個、1 分あたり 300 リクエスト）を前提に計画してください。詳細はドキュメントとWebhook による OTP 取得をご覧ください。

連携を組まない場合は、ダッシュボードで Mercado Libre と国を選んで注文し、番号を貼り付けて、画面にコードが表示されるのを待ちます。

Mercado Libre のコードが届かないのはなぜか？

マーケットプレイスは登録とログインを慎重に保護しており、Mercado Libre が一部の仮想番号を拒否することがあります。配信はルートやタイミングにも左右されます。各アクティベーションには 20 分の有効時間があり、その間に SMS が届かない場合、またはキャンセルした場合は、全額が自動的にウォレットへ戻ります。

• 再試行の前に、有効時間が終わるまで待ちます。
• あとでもう一度試すか、テストに合う別の国のルートに切り替えます。
• ループで再注文せず、試行の間隔をあけます。

さらに詳しくはOTP 配信失敗を減らす方法をご覧ください。

専用番号のほうが適しているのはどんなときか？

Gateway の番号は 1 回の認証にしか使えません。社内アカウントが数週間後にもう一度サインインする必要がある場合、たとえば Mercado Libre が新しい端末で再認証する運用ログインでは、継続して使える回線があればアクセスを失わずに済みます。専用仮想番号（Dedicated Virtual Numbers）は米国とカナダのみで月額 $1.95 から提供され、ダッシュボードと Webhook で SMS を受信できます。米国またはカナダの番号を受け付けるアカウントに適しています。ほかの市場については、[email protected] にメールで何が可能かお問い合わせください。

責任ある利用と課金について

OTP Route は、ご自身の製品のテストと正当なアカウントの運用のためのサービスです。Mercado Libre の利用規約を守り、アカウントは実在の個人または事業者につき 1 つとし、番号を使って出品者プロフィールを重複作成したり、プロモーションを繰り返し受け取ったりしないでください。利用規約（Acceptable Use Policy）が適用され、Mercado Libre はその所有者の商標であり、提携関係を示すものではありません。

支払いはプリペイドの USD ウォレットで、月額料金はなく、カードまたは USDT/USDC で入金でき、入金ごとに PDF の請求書が発行されます。連携を構築する間、Mercado Libre のシミュレートされたコードが必要な場合は、サポートに開発用アカウントをサンドボックスへ切り替えるよう依頼してください。

よくある質問

API で Mercado Libre の OTP を受信できますか？

はい。サービス mercado と国 ID を指定してアクティベーションを作成し、ポーリングか activation.sms_received Webhook でコードを読み取ります。

Mercado Libre のテストアカウントには、どの国を選べばよいですか？

アルゼンチン、ブラジル、メキシコなど、アカウントが登録されている市場を選んでください。その地域のサイトが想定する番号に合わせられます。

Mercado Libre は仮想番号を受け付けますか？

常にではありません。20 分以内にコードが届かなければ返金されるので、あとで、または別のルートでもう一度試せます。

テスト用の Mercado Libre SMS 認証の料金はいくらですか？

1 コード $0.20 からです。正確な価格は国によって異なり、注文前に GET /api/v1/prices で確認できます。

今後の Mercado Libre ログインのために、同じ番号を保持できますか？

Gateway の番号は使い切りです。アカウントが受け付けるなら、米国またはカナダの専用番号は更新を続ける間保持できます。

Webhook が同じコードを二重に処理しないようにするには？

署名を検証したうえで、最初のイベントが届いたときにアクティベーション ID を保存し、その ID の繰り返しは無視します。

OTP Route の番号で複数の Mercado Libre アカウントを開設できますか？

各アカウントが実在の個人または事業者に属し、Mercado Libre の規約で認められている場合に限ります。重複アカウントやプロモーション目的のアカウントは認められません。

サービス名はそれぞれの所有者の商標です。OTP Route はこれらの企業と提携していません。番号は合法的にご利用いただき、各サービスの利用規約および当社の利用規定に従ってください。