API 文档

欢迎使用 GoSMS API！本文档将帮助您快速集成我们的短信接码服务到您的应用中。

基础信息

API Base URL: https://appsms.net/api/v1

认证方式: API Key (Bearer Token)

请求格式: JSON

响应格式: JSON

认证

所有 API 请求都需要在 HTTP Header 中携带 API Key：

Authorization: Bearer YOUR_API_KEY

获取 API Key

渠道管理员可以在后台管理系统的"渠道管理"页面查看您的 API Key，或请求管理员重新生成。

注意: API Key 以 ch_ 开头，请妥善保管，不要泄露。

API 端点

1. 查询余额

获取当前账户的余额和信用额度信息。

GET /api/v1/user/balance
Authorization: Bearer ch_xxxxxxxxxxxxx

响应示例:

{
  "balance": 1000.50,
  "frozen_balance": 50.00,
  "available_balance": 950.50,
  "credit_limit": 5000.00
}

字段说明:

balance: 当前余额
frozen_balance: 冻结金额（进行中的订单）
available_balance: 可用余额（balance - frozen_balance）
credit_limit: 信用额度（后付费渠道）

2. 创建订单（购买号码）

购买一个号码用于接收短信验证码。

POST /api/v1/order
Authorization: Bearer ch_xxxxxxxxxxxxx
Content-Type: application/json

请求 Body:

{
  "project_code": "whatsapp",
  "region": "ID"
}

请求参数:

参数	类型	必填	说明
project_code	string	是	应用代码（whatsapp, telegram, facebook 等）
region	string	是	国家代码（ISO 3166-1 alpha-2，如 ID, US, CN）

响应示例:

{
  "order_id": 12345,
  "phone": "+6281234567890",
  "project_code": "whatsapp",
  "region": "ID",
  "price": 0.50,
  "status": "pending",
  "expired_at": "2025-12-03T11:00:00Z",
  "created_at": "2025-12-03T10:50:00Z"
}

状态说明:

pending: 等待接收短信
received: 已收到短信
completed: 订单已完成
cancelled: 订单已取消

3. 查询订单状态

查询订单当前状态和是否收到短信。

GET /api/v1/order/{order_id}
Authorization: Bearer ch_xxxxxxxxxxxxx

响应示例 - 未收到短信:

{
  "order_id": 12345,
  "phone": "+6281234567890",
  "project_code": "whatsapp",
  "region": "ID",
  "status": "pending",
  "price": 0.50,
  "code": null,
  "content": null,
  "expired_at": "2025-12-03T11:00:00Z",
  "created_at": "2025-12-03T10:50:00Z"
}

响应示例 - 已收到短信:

{
  "order_id": 12345,
  "phone": "+6281234567890",
  "project_code": "whatsapp",
  "region": "ID",
  "status": "received",
  "price": 0.50,
  "code": "123456",
  "content": "Your WhatsApp code is 123456",
  "received_at": "2025-12-03T10:55:00Z",
  "expired_at": "2025-12-03T11:00:00Z",
  "created_at": "2025-12-03T10:50:00Z"
}

字段说明:

code: 提取出的验证码（仅 status=received 时有值）
content: 完整短信内容
received_at: 收到短信的时间

4. 取消订单

在未收到短信前取消订单，已冻结金额将退回账户。

POST /api/v1/order/{order_id}/cancel
Authorization: Bearer ch_xxxxxxxxxxxxx

响应示例:

{
  "message": "订单已取消，金额已退回",
  "refund_amount": 0.50
}

注意:

只能取消 pending 状态的订单
已收到短信（received 状态）的订单无法取消

5. 获取用户信息

获取当前账户的基本信息。

GET /api/v1/user/profile
Authorization: Bearer ch_xxxxxxxxxxxxx

响应示例:

{
  "user_id": 123,
  "username": "channel_demo",
  "email": "demo@example.com",
  "balance": 1000.50,
  "frozen_balance": 50.00,
  "credit_limit": 5000.00,
  "billing_type": "postpaid",
  "is_active": true,
  "created_at": "2025-01-01T00:00:00Z"
}

字段说明:

billing_type: 计费类型（prepaid=预付费, postpaid=后付费）
is_active: 账号状态

6. 查询交易记录

查询账户的财务流水记录。

GET /api/v1/user/transactions?page=1&page_size=20
Authorization: Bearer ch_xxxxxxxxxxxxx

请求参数:

参数	类型	必填	说明
page	int	否	页码（默认1）
page_size	int	否	每页数量（默认20，最大100）

响应示例:

{
  "transactions": [
    {
      "id": 1001,
      "type": "Deposit",
      "amount": 100.00,
      "balance_snapshot": 1100.50,
      "description": "充值",
      "created_at": "2025-12-03T10:00:00Z"
    },
    {
      "id": 1002,
      "type": "Hold",
      "amount": 0.50,
      "balance_snapshot": 1100.00,
      "frozen_balance_snapshot": 0.50,
      "description": "订单冻结",
      "order_id": 12345,
      "created_at": "2025-12-03T10:50:00Z"
    }
  ],
  "total": 156,
  "page": 1,
  "page_size": 20
}

交易类型说明:

Deposit: 充值
Hold: 冻结（创建订单）
Release: 释放（订单完成）
Refund: 退款（订单取消）

7. 查询订单列表

查询历史订单记录。

GET /api/v1/user/orders?page=1&page_size=20&status=completed
Authorization: Bearer ch_xxxxxxxxxxxxx

请求参数:

参数	类型	必填	说明
page	int	否	页码（默认1）
page_size	int	否	每页数量（默认20，最大100）
status	string	否	订单状态筛选（pending/received/completed/cancelled）

响应示例:

{
  "orders": [
    {
      "order_id": 12345,
      "phone": "+6281234567890",
      "project_code": "whatsapp",
      "region": "ID",
      "status": "completed",
      "price": 0.50,
      "code": "123456",
      "created_at": "2025-12-03T10:50:00Z",
      "received_at": "2025-12-03T10:55:00Z"
    }
  ],
  "total": 156,
  "page": 1,
  "page_size": 20
}

错误码说明

HTTP 状态码

状态码	说明
200	请求成功
400	请求参数错误
401	未授权（API Key 无效或过期）
402	余额不足
403	禁止访问（账号被禁用）
404	资源不存在
429	请求过于频繁（触发限流）
500	服务器内部错误
503	服务不可用（无可用号码）

业务错误码

错误响应格式：

{
  "error": "余额不足",
  "code": "INSUFFICIENT_BALANCE"
}

常见错误码：

错误码	说明	解决方案
UNAUTHORIZED	未授权	检查 API Key 是否正确
INVALID_PARAMS	参数错误	检查请求参数格式
INSUFFICIENT_BALANCE	余额不足	充值或联系管理员调整信用额度
NO_AVAILABLE_NUMBER	无可用号码	稍后重试或更换国家/应用
ORDER_NOT_FOUND	订单不存在	检查订单 ID 是否正确
ORDER_EXPIRED	订单已过期	创建新订单
PRICE_CALCULATION_ERROR	价格计算失败	联系管理员检查价格配置

SDK 示例

Python 示例

import requests
import time

API_BASE = "https://appsms.net/api/v1"
API_KEY = "ch_xxxxxxxxxxxxx"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# 创建订单
def create_order(project_code, region):
    url = f"{API_BASE}/order"
    data = {
        "project_code": project_code,
        "region": region
    }
    response = requests.post(url, json=data, headers=headers)
    return response.json()

# 查询订单状态
def get_order(order_id):
    url = f"{API_BASE}/order/{order_id}"
    response = requests.get(url, headers=headers)
    return response.json()

# 轮询等待短信
def wait_for_sms(order_id, timeout=300):
    """轮询等待短信，最多等待 timeout 秒"""
    start_time = time.time()

    while time.time() - start_time < timeout:
        order = get_order(order_id)

        if order.get('status') == 'received':
            return order.get('code')
        elif order.get('status') in ['cancelled', 'expired']:
            return None

        # 轮询间隔：前30秒每3秒，之后每5秒
        interval = 3 if time.time() - start_time < 30 else 5
        time.sleep(interval)

    return None

# 使用示例
try:
    # 1. 创建订单
    order = create_order("whatsapp", "ID")
    print(f"订单创建成功！")
    print(f"订单号: {order['order_id']}")
    print(f"手机号: {order['phone']}")

    # 2. 等待短信
    print("等待接收短信...")
    code = wait_for_sms(order['order_id'])

    if code:
        print(f"收到验证码: {code}")
    else:
        print("未收到短信，订单已超时")

except requests.exceptions.RequestException as e:
    print(f"请求失败: {e}")

Node.js 示例

const axios = require('axios');

const API_BASE = 'https://appsms.net/api/v1';
const API_KEY = 'ch_xxxxxxxxxxxxx';

const client = axios.create({
  baseURL: API_BASE,
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  }
});

// 创建订单
async function createOrder(projectCode, region) {
  const response = await client.post('/order', {
    project_code: projectCode,
    region: region
  });
  return response.data;
}

// 查询订单状态
async function getOrder(orderId) {
  const response = await client.get(`/order/${orderId}`);
  return response.data;
}

// 轮询等待短信
async function waitForSms(orderId, timeout = 300000) {
  const startTime = Date.now();

  while (Date.now() - startTime < timeout) {
    const order = await getOrder(orderId);

    if (order.status === 'received') {
      return order.code;
    } else if (['cancelled', 'expired'].includes(order.status)) {
      return null;
    }

    // 轮询间隔：前30秒每3秒，之后每5秒
    const interval = Date.now() - startTime < 30000 ? 3000 : 5000;
    await new Promise(resolve => setTimeout(resolve, interval));
  }

  return null;
}

// 使用示例
(async () => {
  try {
    // 1. 创建订单
    const order = await createOrder('whatsapp', 'ID');
    console.log('订单创建成功！');
    console.log(`订单号: ${order.order_id}`);
    console.log(`手机号: ${order.phone}`);

    // 2. 等待短信
    console.log('等待接收短信...');
    const code = await waitForSms(order.order_id);

    if (code) {
      console.log(`收到验证码: ${code}`);
    } else {
      console.log('未收到短信，订单已超时');
    }
  } catch (error) {
    console.error('请求失败:', error.response?.data || error.message);
  }
})();

PHP 示例

<?php

define('API_BASE', 'https://appsms.net/api/v1');
define('API_KEY', 'ch_xxxxxxxxxxxxx');

function apiRequest($method, $endpoint, $data = null) {
    $url = API_BASE . $endpoint;

    $options = [
        'http' => [
            'header' => [
                'Authorization: Bearer ' . API_KEY,
                'Content-Type: application/json'
            ],
            'method' => $method,
            'ignore_errors' => true
        ]
    ];

    if ($data) {
        $options['http']['content'] = json_encode($data);
    }

    $context = stream_context_create($options);
    $result = file_get_contents($url, false, $context);

    return json_decode($result, true);
}

// 创建订单
function createOrder($projectCode, $region) {
    return apiRequest('POST', '/order', [
        'project_code' => $projectCode,
        'region' => $region
    ]);
}

// 查询订单状态
function getOrder($orderId) {
    return apiRequest('GET', "/order/{$orderId}");
}

// 轮询等待短信
function waitForSms($orderId, $timeout = 300) {
    $startTime = time();

    while (time() - $startTime < $timeout) {
        $order = getOrder($orderId);

        if ($order['status'] === 'received') {
            return $order['code'];
        } else if (in_array($order['status'], ['cancelled', 'expired'])) {
            return null;
        }

        // 轮询间隔：前30秒每3秒，之后每5秒
        $interval = (time() - $startTime < 30) ? 3 : 5;
        sleep($interval);
    }

    return null;
}

// 使用示例
try {
    // 1. 创建订单
    $order = createOrder('whatsapp', 'ID');
    echo "订单创建成功！\n";
    echo "订单号: " . $order['order_id'] . "\n";
    echo "手机号: " . $order['phone'] . "\n";

    // 2. 等待短信
    echo "等待接收短信...\n";
    $code = waitForSms($order['order_id']);

    if ($code) {
        echo "收到验证码: $code\n";
    } else {
        echo "未收到短信，订单已超时\n";
    }
} catch (Exception $e) {
    echo "请求失败: " . $e->getMessage() . "\n";
}

?>

最佳实践

1. 轮询策略

查询订单状态时，建议使用智能轮询策略：

前 30 秒: 每 3 秒查询一次（短信通常在这个时间段到达）
30 秒 - 2 分钟: 每 5 秒查询一次
2 分钟后: 每 10 秒查询一次
收到短信或订单过期后: 立即停止轮询

2. 错误处理

网络错误: 实现自动重试机制（最多 3 次，指数退避）
429 限流: 收到限流错误时，等待 5-10 秒后重试
余额不足: 及时充值或联系管理员调整信用额度
无可用号码: 更换国家或应用重试，或稍后再试

3. 安全建议

✅ 不要在前端代码中暴露 API Key
✅ 使用 HTTPS 进行所有 API 请求
✅ 定期轮换 API Key（联系管理员）
✅ 记录所有 API 调用日志用于排查问题
✅ 实施 IP 白名单（可选，联系管理员配置）

4. 性能优化

使用连接池复用 HTTP 连接
实现本地缓存减少重复查询
批量处理订单而非逐个创建
合理设置超时时间（建议 30 秒）

限流说明

为保证服务稳定性，API 实施了限流策略：

限流类型	限制
每秒请求数	10 次
每分钟请求数	300 次

超过限流后会返回 HTTP 429 状态码，建议实现指数退避重试策略。

支持的国家和应用

常用国家代码

国家	代码	说明
印度尼西亚	ID	价格低、库存充足
美国	US	价格较高
英国	GB	价格中等
中国	CN	部分应用支持
印度	IN	价格低

完整国家列表请在后台管理系统查看。

常用应用代码

应用	代码
WhatsApp	whatsapp
Telegram	telegram
Facebook	facebook
Instagram	instagram
Google	google
WeChat	wechat

完整应用列表请在后台管理系统查看。

技术支持

如有任何问题，请联系我们：

Telegram: @appsms_support
邮箱: support@appsms.net
工作时间: 7x24 小时

更新日志

2025-12-03

更新 API 文档，修正接口路径和参数
添加完整的 SDK 示例代码
添加错误码说明和最佳实践

2025-12-02

发布 API v1.0 版本
支持基础订单管理功能