跳转到主要内容
POST
curl

在短信中设置品牌名称

短信验证码会携带您在 Business Console 中设置的应用短信发送方名称,无需额外付费:
123456 是 Acme Bank 的验证码
如需让某条验证码使用其他名称,请传入 options.sms_sender_name(1 至 30 个字符,仅限字母、数字、空格以及 ’ & - !,且不能全部为数字):
不符合这些规则的名称会返回 400,且不会发送验证码。 WhatsApp 验证码使用固定消息,不带品牌标识。如需以您的企业名称发送,请在 Business Console 中连接您自己的 WhatsApp Business 号码。参见通过您自己的号码发送 WhatsApp 验证码。 有关验证码携带哪个名称,以及新名称的每日限额,请参见品牌化验证消息。

处理服务商故障

如果电话服务商暂时不可用,此 endpoint 会返回 502 以及一个稳定的机器可读代码:
应将此响应视为可重试。请使用较短的退避间隔,并向用户显示临时服务提示,而不是要求其更改有效的手机号码或验证码。

授权

x-api-key
string
header
必填

您的应用 API 密钥,可在 Business Console 的“开发者 -> API 密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域:针对每个资源设为无权限、只读或读写,限定于特定工作流或已通过的会话、限定于 IP 地址列表,以及设置到期日期。401 表示密钥错误、已撤销或已过期;403 表示未发送密钥、密钥无权访问该资源或操作,或请求来自其 IP 列表之外的地址;在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF URL 将为 null;没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅 https://docs.didit.me/console/api-keys。

请求体

application/json
phone_number
string
必填

E.164 格式的收件人电话号码,以前导 + 和国家/地区代码开头(例如 +14155552671)。号码会经过验证并标准化为 E.164;无法解析或无效的号码将返回 400 并附带 phone_number 字段错误。

Maximum string length: 20
示例:

"+14155552671"

options
object

一次性验证码投递选项。所有字段均为可选。

signals
object

关于终端用户的可选设备与网络信号,转发至反欺诈层以提升对滥用或自动化流量的检测能力。所有字段均为可选。

vendor_data
string

由调用方控制的可选标识符(您的内部用户 id、邮箱、UUID 等),在会话中持久化并在发送响应、匹配检查响应、Webhook 和 Business Console 中原样返回。可使用它将 Didit 的 request_id 与您的用户记录进行关联。

metadata
object | null

可选的自由格式 JSON 对象,持久化保存在会话中,并在发送响应、匹配检查响应、Webhook 以及 Business Console 中回显。

响应

已确认发送。请检查 status:Success 和 Retry 表示验证码正在发送中;Blocked 表示反欺诈层已拒绝,且验证已最终确定为 Declined。request_id 是持久化的会话 ID(在 Retry 时 ID 相同)。

request_id
string<uuid>

验证的会话 id。Retry 发送会返回与原始发送相同的 request_id。此 id 会显示在 Business Console 中,在已完成的 POST /v3/phone/check/ 中再次返回,并可传递给 GET /v3/session/{sessionId}/decision/。

status
enum<string>

Success:OTP 已发送至新的验证。Retry:为先前发送所创建的待处理验证重新发送了 OTP。Blocked:防欺诈层拒绝发送;验证立即以 Declined 终结,且不产生计费。

可用选项:
Success,
Retry,
Blocked
reason
string | null

发送被 Blocked 的原因(例如 repeated_attempts、suspicious、spam)。在 Success 和 Retry 时为 null。

vendor_data
string | null

存储在会话中的 vendor_data 回显(来自首次发送)。

metadata
object | null

存储在会话中的 metadata 回显(来自首次发送)。

最后修改于 2026年11月7日