カーボベルデ(+238)の認証コードをテスト環境に取り込む

+238のアクティベーションでは、どのエンドポイントを使いますか?

カーボベルデ向けOTP APIの連携に必要な呼び出しは、https://otproute.com/api/v1 配下のごく短いリストだけです。すべてのリクエストに、開発者コンソールで生成した or_live_ で始まるBearerキーを付けます。カーボベルデの国IDは cv で、サービスIDはテスト対象アプリの api_service の値です。

1. GET /api/v1/services と GET /api/v1/countries でカタログを取得します。1日分はキャッシュして構いません。
2. GET /api/v1/prices?country=cv&service=<id> で、現在の価格と、そのルートがいま開いているかどうかを確認します。在庫は一日の中で動くので、何かを決め打ちにせず、注文のたびに問い合わせてください。
3. {"service": "whatsapp", "country": "cv"} を付けた POST /api/v1/activations は、アクティベーションIDと、サインアップフォームに入力する+238番号を返します。
4. Webhookを使わない場合は、GET /api/v1/activations/{id} でコードをポーリングできます。
5. テストを中断するときは POST /api/v1/activations/{id}/cancel で番号を解放します。保留されていた金額はウォレットに戻ります。

実行前に GET /api/v1/balance を呼んでおくと、スイートは途中で失敗せず、最初に停止できます。上限は1アカウントあたり毎分300リクエストで、全フィールドはAPIリファレンスに掲載しています。

カーボベルデのコード用の署名付きWebhookは、どう受け取ればよいですか?

ポーリングは単一のスクリプトには向いていますが、複数のジョブを並列で動かすならWebhookのほうがすっきりします。開発者コンソールでエンドポイントを登録し(1アカウントで5つまで)、activation.sms_received、activation.expired、activation.cancelled を購読してください。

各POSTには、t=<unix>,v1=<hex> 形式の X-OTPRoute-Signature ヘッダーが付きます。<t>.<raw body> という文字列を再構成し、そのエンドポイントのシークレットでHMAC-SHA256の署名を作成して、結果を v1 と定数時間で比較します。傍受されたリクエストが再送されても通らないよう、タイムスタンプが数分以上古いものは破棄してください。その後の処理はアクティベーションIDを軸にします。同じイベントが2回届いても、2通目は何も変更しないようにしましょう。エッジケースについては、HMACによるOTP Webhookの保護の記事で扱っています。

現在、カーボベルデの番号にコードを送れるアプリは?

cv のライブカタログは、800を超えるサービスに対応しています。現在利用できる人気のサービスには、WhatsApp、Facebook、Instagram、TikTok、Google (Gmail & YouTube)、Microsoft & Outlook、Amazon、Airbnb、Uber、Viber、Telegram、Netflixなどがあります。この一覧はスナップショットとして読んでください。ルートは提携先の容量に応じて開閉します。だからこそ、ページの約束ではなく、空き状況をリアルタイムで返すAPI経由のOTPルーティングに意味があるのです。

チームにコードを書く人がいなくても、ダッシュボードで同じことができます。サービスを選び、カーボベルデを選び、画面の価格を確認して、番号をコピーします。コードが届くと、アクティベーションカードに表示されます。

+238番号を保存するとき、どんな形式になりますか?

カーボベルデはクローズド・ナンバリング・プランを採用しており、国内番号は7桁で、トランクプレフィックスはありません。そのため、取り除くべき先頭のゼロはありません。E.164形式では、+238 にその7桁を続けるだけです。正規化はごく簡単ですが、加入者番号はもっと長いものと決め込んだバリデーターは、この短さでつまずきます。これが、有効なカーボベルデの入力をフォームが拒否してしまうよくある原因です。E.164の文字列を保存し、表示形式はUIの好みに任せて、電話番号欄の単体テストに+238のケースを追加しましょう。

公用語はポルトガル語ですが、日常的に話されているのはカーボベルデ・クレオール語です。ポルトガル語のOTPテンプレートが現地の端末でどう表示されるかを確認してください。+238番号がテストに使われる背景には、ディアスポラの存在があります。米国、ポルトガルをはじめヨーロッパ各地のカーボベルデ系コミュニティは、母国の番号に紐づいたアカウントを持ち続けており、送金、旅行、メッセージングのプロダクトは、そうしたサインアップを問題なく動かしたいと考えています。

20分以内にSMSが届かなかった場合、ウォレットはどうなりますか?

各アクティベーションは20分間開いたままです。そのウィンドウ内にコードが届けば課金が確定し、何も届かないままウィンドウが閉じた場合や、先にキャンセルした場合は、サポートへの問い合わせなしで全額がウォレットへ戻ります。何も届かないときは、次の点を試してください。

• 数秒おきに新しい注文を出すのではなく、ウィンドウが終わるまで待ちましょう。短い間隔での再試行は、資金を拘束するだけです。
• 時間をおいて再試行するか、別のサービスルートで同じフローを試してください。
• そのアプリが仮想番号を受け付けるか確認しましょう。ポリシーで拒否するものもあり、返金はまさにそのケースのためにあります。
• フォームが、途中で切れた番号ではなく、+238の完全な番号を送信していることを確認します。

原因の切り分けについては、OTP配信失敗を減らす方法のガイドでさらに詳しく解説しています。

繰り返しログインするために、カーボベルデの番号を保持できますか?

セルフサービスでは提供していません。OTP RouteのDedicated Numbersは、SMS送受信、ブラウザ通話、Webhook転送に対応した長期利用の回線で、米国とカナダ向けのプロダクトとして月額$1.95/monthからです。セルフサービスで使える長期利用の+238回線はありません。チームに本当に必要な場合は、[email protected] までメールでご連絡ください。手配できるかどうかは現地の規制次第で、お約束はできません。繰り返しサインインが必要なステージングアカウントには、米国またはカナダの仮想番号が現実的な答えになることが多いでしょう。

利用料金はどう課金され、本番前にどうテストしますか?

課金は、月額料金もプランの階層もない、前払い制のUSDウォレット1つで行われます。カードまたはUSDT/USDCのステーブルコインでチャージでき、チャージのたびにPDFの請求書がメールで届くため、経理の照合も簡単です。本番キーがウォレットに触れる前に、開発用アカウントをサンドボックスに切り替えるよう依頼してください。シミュレートされた番号とコードが返るので、SMS認証APIクライアントの注文、Webhook、キャンセルの経路を、費用をかけずにCIで実行できます。料金ページとQAテストの概要もご覧ください。いずれの場合も、各サービスの規約とOTP Routeの利用規定(Acceptable Use Policy)を守ってください。

よくある質問

現地のSIMなしで、アプリのカーボベルデ向けサインアップフローをテストできますか?

はい。OTP Gatewayで+238番号を注文し、サインアップフォームに入力して、ダッシュボード、API、またはWebhookでコードを読み取ります。チームの誰かが島にいる必要はありません。

OTP RouteのAPIで、カーボベルデの国IDは何ですか?

cv です。POST /api/v1/activations と価格のクエリで、country として渡します。

カーボベルデの番号には、先頭に0を付ける必要がありますか?

いいえ。カーボベルデにはトランクプレフィックスがないため、国際形式は +238 に7桁の国内番号を続けたものになります。

カーボベルデの認証番号の料金はいくらですか?

OTP Gatewayの料金は1コード$0.20 からで、サービスによって異なります。正確な価格は、注文前にAPIとダッシュボードに表示されます。課金されるのはコードが届いた場合のみです。

すべてのアプリが、カーボベルデの仮想番号にコードを送りますか?

いいえ。仮想番号を拒否するサービスもあり、ルートも一日の中で変わります。20分以内にコードが届かなければ、金額はウォレットに戻ります。

+238の連携をテストするためのサンドボックスはありますか?

はい、依頼に応じて提供します。開発用アカウントをサンドボックスモードに切り替えると、シミュレートされた番号とコードが返り、ウォレットの費用をかけずに連携をエンドツーエンドで実行できます。

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