登录 注册

开发者文档中心

为开发者提供短信、人机验证、SSL等产品的 API 接入指南与多种开发语言 SDK

Luosimao API

接口通用说明

基于 RESTful 设计原则，使用标准 HTTP 方法通信。在对接具体接口前，请阅读本文档了解鉴权方式、数据格式及全局错误码规范。

⚠️ 合规与相关提示

  • 内容合规：所有短信均有严格监控，严禁发送营销广告、违法违规、要挟、虚假、私人信息、滥发及邀请类内容。
  • 防刷机制：网页应用如用于手机验证，请务必增加图形验证码（如 Luosimao 人机验证），以防被恶意利用于短信轰炸，否则平台将不予接入。
  • 短信签名：测试时使用【铁壳测试】；正式使用需提前在签名管理中新增签名，签名需经运营商报备，预计 3-5 个工作日完成。

1. 接口基础信息

通信协议
推荐 HTTPS，兼容 HTTP
数据格式
推荐 JSON，兼容 XML
字符编码
全局统一 UTF-8
请求方式
操作类 POST，查询类 GET

POST 请求的 Content-Type 需设为 application/x-www-form-urlencoded。

2. 鉴权认证 (Authentication)

Luosimao API 使用标准的 HTTP Basic Authentication 进行接口鉴权。所有 API 请求都必须携带有效的认证信息，否则会返回 -10 错误码。

2.1 获取 API Key

登录 Luosimao 管理中心，进入 短信 → 触发发送 页面，即可看到您的 API Key，格式形如：

Your API Key 
key-d609b769204f2c1a8b************

2.2 认证方式

HTTP Basic Auth 的用户名固定为 api，密码为您的完整 API Key。具体来说，需要将 api:YOUR_API_KEY 进行 Base64 编码后，放入请求头的 Authorization 字段：

1
拼接原始字符串
api:key-d609b7692...
2
Base64 编码
YXBpOmtleS1kNjA5Yjc2OTI...
3
设置请求头
Authorization: Basic YXBp...

最终发出的 HTTP 请求头如下所示：

HTTP Header 
Authorization: Basic YXBpOmtleS1kNjA5Yjc2OTIwNGYyYzFhOGI=

2.3 请求示例

以下是使用 curl 发送一条短信的完整示例。-u 参数会自动完成 Basic Auth 编码：

curl — 发送单条短信 
curl -X POST https://sms-api.luosimao.com/v1/send.json \
  -u "api:key-d609b7692..." \
  -d "mobile=13800138000" \
  -d "message=验证码：1234【公司签名】"

成功时返回：

Response — JSON 
{
  "error": 0,
  "msg": "ok"
}

推荐使用 SDK：如果您使用官方提供的 SDK，无需手动处理 Basic Auth 编码，只需在初始化客户端时传入 API Key 即可，SDK 会自动完成鉴权封装。

3. SDK 快速接入

我们提供了多语言 SDK，封装了鉴权、重试、错误处理等底层逻辑，推荐优先使用：

PHP SDK
composer require luosimao/sms
Python SDK
pip install luosimao-sms
Java SDK
Maven / Gradle
Node.js SDK
npm install luosimao-sms
C# SDK
dotnet add package Luosimao.Sms
Go SDK
go get github.com/luosimao-oss/sms-go
Ruby SDK
gem install luosimao-sms

4. 全局错误码 (Error Code)

接口调用失败时，会返回非 0 的 error 码及对应的 msg。请对照下表排查问题：

错误码 分类 错误描述 解决方案
0 - 发送成功 -
-10 鉴权 验证信息失败 检查 API KEY 是否和管理中心内的一致，检查 HTTP Basic Auth 传参是否正确。
-11 鉴权 用户接口被禁用 因滥发违规内容或验证码被刷导致禁用，请联系客服解除。
-12 余额 余额冻结 长期未使用或其他原因导致触发接口冻结，可在后台 短信 → 触发发送 下进行解冻操作。
-20 余额 短信余额不足 请进入个人中心购买充值套餐。
-30 内容 短信内容为空 检查调用传入的 message 参数是否有值。
-31 内容 短信内容存在敏感词 接口会同时返回 hit 属性提供敏感词说明，请修改短信内容，更换对应词语。
-32 内容 短信内容缺少签名信息 短信内容末尾必须增加签名信息，格式如：【公司名称】。
-33 内容 短信过长 短信长度超过 300 字（含签名），请调整短信内容或拆分为多条进行发送。
-34 内容 签名不可用 请在后台 短信 → 签名管理 处添加并审核您的专属签名。
-35 内容 测试签名受限 【铁壳测试】签名使用已达到上限，请在短信后台添加正式签名并进行替换。
-40 号码 错误的手机号 检查传入的手机号格式是否正确。
-41 号码 号码在黑名单中 该号码因频繁发送或其他原因被暂停发送，请联系客服确认。
-42 号码 发送频率过快 验证码类短信发送频率过快，请在您的应用前台增加 60 秒获取限制。
-50 网络 请求 IP 不在白名单内 您在后台配置了 IP 白名单，但当前请求的 IP 不在其中。请检查服务器 IP 设置。
-99 系统 系统内部错误 平台内部发生临时性错误，请稍后重试或联系技术支持排查。