登录 注册

开发者文档中心

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

短信服务 SDK

Node.js SDK 接入指南

基于 Promise 封装的 Node.js 客户端。提供短信发送、批量发送、余额查询等功能，内置自动重试机制与完善的错误码处理，支持通过 npm 快速安装。

1. 安装

你可以通过 npm 或 yarn 安装此 SDK，详细信息可访问 npm 项目主页 查看：

Terminal 
npm install luosimao-sms
# 或
yarn add luosimao-sms

2. 快速开始

2.1 初始化客户端

init.js 
const { LuosimaoClient, LuosimaoError } = require('luosimao-sms');

// 使用你的 API_KEY 初始化客户端
// 自动处理 Basic Auth 认证逻辑，无需手动拼接 api:key- 字符串
const client = new LuosimaoClient('your_api_key_here', {
  timeout: 5000, // 可选：请求超时时间，默认 5000ms，传入 0 可禁用超时
  retries: 3     // 可选：失败重试次数，默认 3 次（仅对 GET 查询请求生效）
});

2.2 发送单条短信

send.js 
async function sendSingleSMS() {
  try {
    const res = await client.send('13761428268', '验证码：321123【铁壳测试】');
    console.log('发送成功:', res);
  } catch (err) {
    if (err instanceof LuosimaoError) {
      console.error(`发送失败，错误码: ${err.code}, 原因: ${err.message}`);
      if (err.hit) {
          console.error(`触发敏感词: ${err.hit}`);
      }
    } else {
      console.error('未知错误:', err);
    }
  }
}

// 定时发送（可选）
async function sendScheduledSMS() {
  const res = await client.send('13761428268', '验证码：321123【铁壳测试】', '2026-04-01 12:30:00');
  console.log('定时发送成功:', res);
}

2.3 批量发送短信

⚠️ 场景建议：批量接口专门用于大量号码的内容群发，不建议发送验证码等有时效性要求的内容。

batch.js 
async function sendBatchSMS() {
  try {
    // 手机号支持数组或逗号分隔的字符串
    const mobiles = ['13761428268', '18521513391']; 
    const message = '提醒：您的账号即将到期，请及时充值【铁壳测试】';
    // const time = '2026-04-01 12:30:00'; // 可选的定时发送时间
    
    const res = await client.sendBatch(mobiles, message);
    console.log('批量发送成功，批次号:', res.batch_id);
  } catch (err) {
    console.error('批量发送失败:', err);
  }
}

2.4 查询账户余额

status.js 
async function checkStatus() {
  try {
    const res = await client.getStatus();
    console.log(`当前余额: ${res.deposit} 条`);
  } catch (err) {
    console.error('查询余额失败:', err);
  }
}

3. 异常处理与错误码

所有的 API 级错误均会抛出 LuosimaoError。您可以通过 err.code 捕获不同的错误，例如：

error_handling.js 
const { LuosimaoError } = require('luosimao-sms');

try {
  await client.send('13712345678', '不合规内容【公司名称】');
} catch (err) {
  if (err instanceof LuosimaoError) {
    switch (err.code) {
      case -20:
        console.error('短信余额不足，请充值！');
        break;
      case -31:
        console.error(`短信内容包含敏感词: ${err.hit}`);
        break;
      case -32:
        console.error('短信内容缺少签名信息，请在末尾添加【公司名称】');
        break;
      default:
        console.error(`API 错误: ${err.message}`);
    }
  }
}