SMSFAST

加载中…

API文档

SMSFast 提供完整的 RESTful API 接口，支持开发者快速集成虚拟号码获取、短信接收和管理功能。所有接口使用 HTTPS 协议，返回 JSON 格式数据。

快速开始

了解 SMSFast API 的基本信息，开始集成开发

API 基础 URL

https://api.smsfast.com/v1

所有 API 请求均以该地址为前缀，使用 HTTPS 协议确保数据传输安全。

认证方式

Authorization: Bearer YOUR_API_KEY

在请求 Header 中携带 API Key 进行身份认证。请妥善保管您的 API Key。

速率限制

60 requests / minute

每个 API Key 每分钟最多发起 60 次请求。超出限制将返回 429 状态码。

接口列表

以下是 SMSFast API 提供的所有接口及其详细说明

POST /v1/numbers 获取虚拟号码

申请获取一个指定国家的虚拟号码，用于接收短信验证码和测试消息。

请求参数

参数名	类型	必填	描述
country	string	是	国家代码，如 US、CN、GB 等
service	string	否	指定服务类型，如 telegram、whatsapp 等
expires_in	integer	否	号码有效期（分钟），默认 15 分钟，最大 60 分钟

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "num_abc123def456",
    "number": "+1 234 567 8900",
    "country": "US",
    "status": "active",
    "created_at": "2024-01-15T10:30:00Z",
    "expires_at": "2024-01-15T10:45:00Z"
  }
}

GET /v1/numbers 获取号码列表

获取当前账户下所有已获取的虚拟号码列表，支持分页和状态筛选。

请求参数

参数名	类型	必填	描述
page	integer	否	页码，从 1 开始，默认 1
limit	integer	否	每页数量，默认 20，最大 100
status	string	否	号码状态筛选：active、expired、released
country	string	否	按国家代码筛选

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 25,
    "page": 1,
    "limit": 20,
    "items": [
      {
        "id": "num_abc123def456",
        "number": "+1 234 567 8900",
        "country": "US",
        "status": "active",
        "created_at": "2024-01-15T10:30:00Z",
        "expires_at": "2024-01-15T10:45:00Z"
      }
    ]
  }
}

GET /v1/numbers/{id} 获取号码详情

获取单个虚拟号码的详细信息，包括当前状态、剩余有效期和短信数量。

路径参数

参数名	类型	必填	描述
id	string	是	号码ID，由获取号码接口返回

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "num_abc123def456",
    "number": "+1 234 567 8900",
    "country": "US",
    "status": "active",
    "message_count": 3,
    "created_at": "2024-01-15T10:30:00Z",
    "expires_at": "2024-01-15T10:45:00Z"
  }
}

GET /v1/numbers/{id}/messages 获取短信记录

获取指定虚拟号码接收到的所有短信记录，包含发送方号码、短信内容和接收时间。

路径参数

参数名	类型	必填	描述
id	string	是	号码ID

查询参数

参数名	类型	必填	描述
page	integer	否	页码，默认 1
limit	integer	否	每页数量，默认 20

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 3,
    "items": [
      {
        "id": "msg_xyz789",
        "sender": "Google",
        "from_number": "+1 555 000 1234",
        "content": "您的验证码是：123456，请在5分钟内完成验证。",
        "received_at": "2024-01-15T10:32:15Z"
      }
    ]
  }
}

DELETE /v1/numbers/{id} 释放号码

提前释放已获取的虚拟号码，号码将被回收到号码池供其他用户使用。号码到期后也会自动释放。

路径参数

参数名	类型	必填	描述
id	string	是	号码ID

响应示例

{
  "code": 0,
  "message": "号码已成功释放",
  "data": null
}

GET /v1/account/balance 查询账户余额

查询当前账户的余额信息，包括可用金额、冻结金额和币种。

请求参数

此接口无需请求参数。

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "available": 100.50,
    "frozen": 5.00,
    "currency": "USD",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

GET /v1/countries 获取可用国家列表

获取 SMSFast 当前支持的所有国家和地区的虚拟号码资源信息，包括国家代码、名称和可用号码数量。

请求参数

此接口无需请求参数。

响应示例

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "code": "US",
      "name": "美国",
      "name_en": "United States",
      "available_count": 150,
      "price_per_number": 0.10
    },
    {
      "code": "GB",
      "name": "英国",
      "name_en": "United Kingdom",
      "available_count": 80,
      "price_per_number": 0.12
    }
  ]
}

错误码

API 返回的标准错误码及其含义说明

HTTP 状态码	错误码	描述	解决方案
400	1001	请求参数错误	检查请求参数是否符合接口规范
401	1002	API Key 无效或已过期	检查 API Key 是否正确，或重新生成
403	1003	无权限访问该资源	确认账户权限和套餐等级
404	1004	请求的资源不存在	检查号码ID或接口路径是否正确
429	1005	请求频率超限	降低请求频率或升级套餐提升限制
500	1006	服务器内部错误	稍后重试，如持续出现请联系技术支持
402	1007	账户余额不足	充值账户以继续使用服务
422	1008	指定国家暂无可用号码	稍后重试或选择其他国家