开发者中心

HTTP / CMPP 双协议接入能力

提供 HTTP API 与 CMPP 协议直连两种接入方式：开放 API 规范已定稿，接口能力持续开放中；CMPP2.0/3.0 直连参数在用户端开发者页自助查看。

本页描述平台已定稿的接入能力与规范要点；页面代码仅为请求构造示意，正式字段与错误码以平台内开发者文档为准。

单条发送

实时返回黑名单等业务拦截结果，适合验证码等即时场景。

批量发送

单次提交万条级号码，统一内容群发，任务级状态跟踪。

变量短信

号码与变量一一对应，千人千面内容单次万条级提交。

一对一批量

JSON 形式「手机号 → 独立内容」映射，单次最多 500 条。

状态报告

主动拉取或配置回调地址被动推送，含 msg_id 与送达状态。

上行回复

拉取或推送用户回复（如退订 TD），每条仅可获取一次。

余额查询

查询产品余额，配合监控做余额告警与自动充值决策。

CMPP 协议直连

CMPP2.0/3.0 长连接直连平台，自助查看 SPID、速率与连接数配置。

安全机制

每一次调用都可验证

HmacSHA1 请求签名

以产品 SPID 与密钥对请求参数做 HmacSHA1 + Base64 签名，服务端验签通过后才会处理请求。

// 签名串示意
sign = Base64(
  HmacSHA1(
    spid + password + timestamp,
    "your-api-key"
  )
)

IP 白名单

在开发者页配置调用方出口 IP，白名单之外的请求直接拒绝，密钥泄露也不易被滥用。

· 支持多 IP 配置
· 非白名单请求返回专用错误码
· 变更即时生效

防刷与限额

SPID 维度每日限额自助配置（0 为不限制，长信按 1 条计），配合频次限制拦截异常调用。

· 同号码频次窗防重发
· 触发防刷返回专用错误码
· 状态报告 / 回复可拉取可推送

接入流程

五步完成接入

1
STEP 1
注册并完成实名认证
依据《网络安全法》完成企业实名认证，预计 1-3 个工作日。
2
STEP 2
开通产品，获取 SPID 与密钥
开通对应产品线后自动生成 6 位 SPID，在开发者页查看接口密码与 CMPP 直连参数。
3
STEP 3
报备签名与模版
提交签名与模版审核；国际产品报备 Sender ID（建议 ≤11 字符）。
4
STEP 4
联调发送与回执
配置状态报告/上行回复的拉取或推送方式，小批量联调验证全链路。
5
STEP 5
上线并监控
配置 IP 白名单与每日限额，结合余额查询接口做余额与失败率监控。

代码示意

请求构造示例

以下为接入示意片段，正式字段与错误码以平台内开发者文档为准。

# 单条发送示意（字段以平台文档为准）
curl -X POST "{域名}/api/v1/open/send-sms-single" \
  -H "Content-Type: application/json" \
  -d '{
    "sp_id": "100001",
    "signature": "<HmacSHA1+Base64>",
    "phone": "13800000000",
    "content": "【云信科技】您的验证码是8624"
  }'

const crypto = require('crypto');

function sign(spid, password, timestamp, key) {
  return crypto
    .createHmac('sha1', key)
    .update(spid + password + timestamp)
    .digest('base64');
}

// 携带 sp_id / signature / 业务字段发起 POST 请求

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

// HmacSHA1 + Base64 签名示意
Mac mac = Mac.getInstance("HmacSHA1");
mac.init(new SecretKeySpec(key.getBytes(), "HmacSHA1"));
String sign = Base64.getEncoder()
    .encodeToString(mac.doFinal(raw.getBytes()));

开始你的第一次调用

注册开通产品后，在用户端开发者页获取 SPID 与接入参数

免费注册查看产品线