Skip to main content

電話番号認証

電話番号認証とは？​

電話番号認証（Phone Validation） は、電話番号に対する 1 回の OTP セッションです。Verifik は SMS または WhatsApp でワンタイムコードを送信し、ユーザーが入力したコードを確認します。

一般的なライフサイクル:

  1. 送信 — Phone Validation を作成し、OTP を配信する
  2. 確認 — 同じ電話番号 + OTP を送信して、セッションを認証済みにする

フィールド一覧は 電話番号認証オブジェクト を参照してください。

タイミングルール​

ルールデフォルト
OTP 有効期限10 分（送信レスポンスの expiresAt）
再送クールダウン同一電話番号 + ゲートウェイへの送信間隔は 約 2 分（409 otp_recently_sent）
クールダウンのバイパス手動作成時に "force": true

常に countryCode と国内番号の phone をセットで送信・表示してください（例: +57 3001234567）。ユーザーがどの宛先にメッセージが届いたかを把握できます。

連携パスの選択​

API の呼び出し方に合ったパスを選んでください。

パス A — スタンドアロン / Smart Tools（プロジェクトなし）​

バックエンド、または Smart Tools → WhatsApp / SMS Messages から OTP を送信し、Smart Enroll や Smart Access のプロジェクトに紐づけない場合に使用します。

ステップエンドポイント
1. OTP 送信POST /v2/phone-validations/manual
2. OTP 確認PUT /v2/phone-validations
  • project / projectFlow は不要
  • レコードの source は "manual"
  • 送信成功後に 従量課金のコミュニケーションクレジット で課金
  • 任意の title（最大 15 文字）で WhatsApp / SMS テンプレート内の会社名を設定
Your app                    Verifik API
────────                    ───────────
POST /manual  ───────────►  OTP sent (SMS / WhatsApp)
                            status: sent

PUT  /phone-validations ─►  OTP checked
  { phone, countryCode, otp }   status: validated

パス B — プロジェクト / App Registration（Smart Enroll & Access）​

登録またはログインフローの一部として OTP を使い、プロジェクトに紐づける場合に使用します。

ステップエンドポイント
1. OTP 送信POST /v2/phone-validations/app-registration
2. OTP 確認PUT /v2/phone-validations
  • プロジェクト / app registration のコンテキストが必要
  • レコードの source のデフォルトは "flow"
  • フローに応じて Smart Enroll / Smart Access のプランカウンターで課金される場合があります

API エンドポイント一覧​

アクションメソッドとパスドキュメント
スタンドアロン OTP 送信POST /v2/phone-validations/manual手動の電話番号認証を作成
OTP 確認PUT /v2/phone-validations電話番号認証を検証
App Registration で OTP 送信POST /v2/phone-validations/app-registrationApp Registration の電話番号認証を作成
一覧GET /v2/phone-validationsすべての電話番号認証を一覧取得
1 件取得GET /v2/phone-validations/{id}電話番号認証を取得
SMS & WhatsApp 料金—SMS & WhatsApp 料金
認証

すべてのエンドポイントには Authorization: Bearer {YOUR_ACCESS_TOKEN} と Content-Type: application/json が必要です。

ステータス値​

ステータス意味
sentOTP が配信された（またはプロバイダーに受理された）
validatedユーザーの OTP が一致した
failed期限切れ、拒否、または送信失敗
new作成済みだが、まだ正常に送信されていない

関連ページ​