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-KEY、X-DAPI-TIMESTAMP、X-DAPI-NONCE、X-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。

