Skip to main content
调用 POST /open-api/customer/v1/send-otp,通过 DCS 的短信或邮件通道向用户发送接入机构生成的验证码(OTP)。 本接口不生成、不校验 OTP——OTP 的产生与核对都由接入机构负责,DCS 只做投递。

📄 正文

无论您已有自己的短信网关,还是希望由 DCS 发送验证码,都可以通过本接口把验证码发送到用户的手机或邮箱。您只需生成 OTP 并提交给 DCS。本接口面向合作伙伴自管模式的接入机构,适用于需要通过短信或邮件向用户发送验证码的业务流程。
本接口不负责生成或校验 OTP。OTP 由接入机构自行生成、自行保管、自行核对,DCS 仅按您指定的 channel 把 OTP 内容发出。

整体流程(谁做什么)

接口

POST /open-api/customer/v1/send-otp 鉴权请求头与其余 /open-api/ 接口一致,需带 X-DAPI-API-KEYX-DAPI-TIMESTAMPX-DAPI-NONCEX-DAPI-SIGN,并设置 Content-Type: application/json。详见鉴权指南

请求体字段

按渠道的必填组合:

明文与密文

收件人字段(mobile / email)与 OTP 内容(otp)都支持明文与密文两种传法。这类敏感信息强烈建议使用密文传输
  • 密文:填 mobileEncryption / emailEncryption / otpEncryption,采用 AES-GCM 算法,密钥为接入机构的 SecretKey,IV 通过 encryptionIV 字段传递。只要任一密文字段非空,encryptionIV 必填。
  • 明文:填 mobile / email / otp,直接传递。
  • 当同一项的明文与密文都提供时,以密文为准

最小请求示例(SMS,明文)

最小请求示例(EMAIL,密文)

响应示例

统一响应结构:所有 /open-api/ 接口返回 { code, message, messageDetail, data }code 为业务码(成功为 SYS_SUCCESS),messageDetail 在需要面向终端用户展示时携带可读文案(含 title/type/action/linkUrl 等),否则可能为空。请以 code 判断业务成败,不要仅凭 HTTP 状态码或 message 文案判断。

响应字段(data

status=SUCCESS 仅表示 DCS 已把 OTP 成功提交给短信或邮件服务商,并不保证用户最终一定收到(可能受运营商或邮箱服务商影响)。status=FAILED 时,具体原因以响应 code 字段为准。

频次限制

为防止短信/邮件被滥用,DCS 对同一 Enterprise 下同一收件人的发送做频次控制: 超过限制会返回 OTP_SEND_TOO_FREQUENT。请引导用户稍后重试,而不要立即重发。

幂等

otpSendRef 是接入机构侧的业务幂等键,同一 otpSendRef 不能重复发送
  • 首次请求:正常下发并记录该 otpSendRef
  • 重复请求(相同 otpSendRef):返回 OTP_SEND_REF_NOT_UNIQUE
请确保每次发送都使用唯一的 otpSendRef(推荐用「业务单号 + 时间戳」生成)。

常见错误码

完整业务码与错误码归类见授权拒绝与错误码

前置条件

  • 已拥有 Enterprise 的 ApiKey / SecretKey,并完成签名与白名单配置(参见前置准备鉴权指南)。
  • 如使用密文传输,您的系统需支持 AES-GCM 加密,密钥即 Enterprise 的 SecretKey。

下一步

OTP 发送验证通过后,您可以继续完成创建用户与后续的 KYC、开卡流程。