Skip to main content

手机验证

什么是手机验证？​

手机验证（Phone Validation） 是针对一个手机号码的一次 OTP 会话。Verifik 通过 SMS 或 WhatsApp 发送一次性验证码，然后由您确认用户输入的验证码。

典型生命周期：

  1. 发送 — 创建手机验证并投递 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. 发送 OTPPOST /v2/phone-validations/manual
2. 验证 OTPPUT /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. 发送 OTPPOST /v2/phone-validations/app-registration
2. 验证 OTPPUT /v2/phone-validations
  • 需要项目 / App Registration 上下文
  • 记录的 source 默认为 "flow"
  • 计费可能根据流程使用 Smart Enroll / Smart Access 计划计数器

API 端点索引​

操作方法与路径文档
发送独立 OTPPOST /v2/phone-validations/manual创建手动手机验证
验证 OTPPUT /v2/phone-validations验证手机验证
在 App Registration 中发送 OTPPOST /v2/phone-validations/app-registration创建 App Registration 手机验证
列表GET /v2/phone-validations列出所有手机验证
检索单条GET /v2/phone-validations/{id}检索手机验证
SMS 与 WhatsApp 价格—SMS 与 WhatsApp 价格
身份验证

所有端点均需要 Authorization: Bearer {YOUR_ACCESS_TOKEN} 以及 Content-Type: application/json。

状态值​

状态含义
sentOTP 已投递（或已被运营商接受）
validated用户 OTP 匹配成功
failed已过期、被拒绝或发送失败
new已创建但尚未成功发送

相关页面​