サウジ展開に向けて+966の認証コードをプログラムで受信する

APIで+966のアクティベーションを1回行うとどうなりますか?

このページを読む方の多くは、SMS認証APIをテストスイートや社内ツールに組み込もうとしているので、まず呼び出しから見ていきます。すべてのエンドポイントはhttps://otproute.com/api/v1以下にあり、Developerコンソールで作成したor_live_プレフィックスのBearerキーが必要です。

1. GET /api/v1/countriesとGET /api/v1/servicesでIDを取得します。サウジアラビアはsaです。
2. GET /api/v1/prices?country=sa&service=<id>は、その組み合わせのリアルタイム料金を返します。テスト実行のログと一緒に記録してください。
3. POST /api/v1/activationsに{"service": "<id>", "country": "sa"}を送ると、アクティベーションIDと+966の番号が返ります。
4. テストが番号をアプリに入力すると、コードがイベントとして届くか、GET /api/v1/activations/{id}で取得できます。
5. テストを中止する場合は、POST /api/v1/activations/{id}/cancelで解放され、ウォレットに返金されます。

GET /api/v1/balanceは事前チェックに便利で、夜間ジョブが実行の途中ではなく、早い段階で分かりやすいメッセージとともに失敗するようにできます。設計時に念頭に置く制限は、アカウントあたりキー10個、Webhookエンドポイント5つ、毎分300リクエストです。

Webhookの受信側はサウジのOTPイベントをどう扱うべきですか?

エンドポイントを登録し、activation.sms_received、activation.expired、activation.cancelledを購読します。すべてのリクエストには、t=<unix>,v1=<hex>形式のX-OTPRoute-Signatureが含まれます。

• 署名対象の文字列を<t>.<raw body>として再構築し、そのエンドポイントのシークレットでHMAC-SHA256を計算します。
• v1との比較には定数時間の関数を使い、タイムスタンプが古すぎるものは拒否します。
• 各イベントはアクティベーションIDをキーとして扱い、再配信されても二重に更新されないようにします。
• 速やかに2xxを返し、時間のかかる処理はバックグラウンドジョブで行います。

受信接続を受け付けられないランナーでは、ポーリングも有効な代替手段です。詳しくはWebhookベースのコード取得とHMACによるOTP Webhookの保護の解説記事をご覧ください。

なぜプロダクトチームは+966の番号でテストするのですか?

サウジアラビアは湾岸地域でも有数の大きなデジタル市場で、このページに来る方には現実的な理由があります。サウジ居住者向けのオンボーディングを準備するフィンテック、湾岸の販売者を加えるマーケットプレイス、顧客が地域でのサインイン確認を求めるSaaSベンダー、リヤドやジェッダの拠点のビジネスアカウントを管理するオペレーションチームなどです。いずれの場合も、実際のサウジの認証番号でフローが動くことを誰かが証明する必要があり、ゲートウェイ経由のOTPルーティングなら、現地にSIMカードを送る手間が省けます。このシナリオの詳細はフィンテックのオンボーディングのページで説明しています。

サウジのルートでコードを受信できるサービスは?

サウジアラビアの現在のスナップショットには、1,000を超えるサービスが含まれています。よく使われるものとして、Snapchat、WhatsApp、X (Twitter)、Uber、TikTok、Instagram、Google (Gmail & YouTube)、Telegram、Amazon、Microsoft & Outlook、LinkedIn、Discord、Netflixがあります。SnapchatとXはこの国で特に利用者が多く、ローカライズのチェックリストの常連です。在庫は日中に変動するため、実行時にAPIへ問い合わせてください。

+966の番号はどう整形し、アラビア語のメッセージはどう解析しますか?

サウジの携帯電話番号は、国内ではトランクの0を付けて、通常は05に8桁を続けて表記します。国際形式ではこのゼロが落ち、+966 5に残りの8桁が続きます。入力の時点ですべてE.164に正規化し、ユーザーが国コードの後にゼロを入力した場合は取り除いてください。

公用語はアラビア語なので、認証SMSはアラビア語、英語、あるいは両方で届くことがあります。アラビア語は右から左に書かれ、テンプレートによっては西洋数字ではなくアラビア・インド数字が使われることもあります。照合の前にこれらの数字をASCIIに変換し、生のUTF-8をログに残すようにすれば、厄介な種類の誤判定を避けられます。

コードを書かない人のためのダッシュボードの手順はありますか?

はい。OTP Routeにサインインし、OTP Gatewayを開いて、サウジアラビアとサービスを選び、料金を確認して確定します。番号はすぐに表示され、コードが届くと隣に表示されます。サポート担当者はこの方法で、お客様のサインアップの問題を数分で再現できます。

コードが届かない場合は?また長期用の回線と課金については?

20分以内にSMSが届かなかった場合、またはキャンセルした場合は、全額が自動的にウォレットに戻ります。ウィンドウが終わるまで待ち、時間を置くか別のサービスルートで再試行し、サービスが仮想番号を受け付けるかを確認し、短時間に連続して再注文するのは避けてください。

セルフサービスのサウジ長期用番号はありません。Dedicated Virtual Numbersは米国とカナダでのみ提供され、月額$1.95からです。+966の長期用回線が必要な場合は[email protected]までメールしてください。ただし、可能かどうかは現地の規則次第です。

利用料金は前払いのUSDウォレット1つで、従量課金、月額料金なしです。チャージにはカード決済とUSDT/USDCのどちらも使え、チャージごとにPDFの請求書がメールで届きます。開発アカウントはリクエストによりサンドボックスに切り替えられ、模擬の番号とコードを利用できます。最新の料金は料金ページをご確認ください。

よくある質問

APIでサウジのSMS OTPを受信するには?

国にsa、サービスにお使いのIDを指定してアクティベーションを作成し、activation.sms_receivedのWebhook、またはアクティベーションのポーリングでコードを取得します。

テスト用の+966番号は、コードが届かなかった場合も課金されますか?

いいえ。コードが届かなければ、20分のウィンドウが閉じたとき、またはキャンセルしたときに全額がウォレットに戻ります。

現地のSIMなしで、アプリのサウジ向けサインアップをテストできますか?

はい。OTP Gatewayが1コード分の+966番号を発行します。それをアプリに入力し、ダッシュボードまたはAPIで読み取ってください。

05XXXXXXXXと入力されたサウジの携帯番号は、どう保存すればよいですか?

先頭のトランクゼロを外し、E.164で+966 5に残りの8桁を続けた形で保存してください。

後のログインのために、同じサウジの番号を使い続けられますか?

セルフサービス製品ではできません。長期用のDedicated Numbersは米国とカナダのみが対象だからです。サウジの回線が必要な場合はチームにメールしてください。ただし、ご提供できる保証はありません。

実際のお金を使う前に、サウジのフローをリハーサルする方法はありますか?

はい。開発アカウントでサンドボックスモードをリクエストすれば、Webhookも含めて模擬の番号とコードを受信できます。

OTP Routeではどのような利用が許可されていますか?

ご自身の正当なプロダクトとアカウントのテストと運用です。すべてのサービスの利用規約を守ってください。OTP Routeの利用規約(Acceptable Use Policy)が適用されます。

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