千牛云接码系统 API 文档

提供虚拟电话号码服务,支持多种国家和主流应用的短信验证码接收

目录

概述

千牛云接码系统提供虚拟电话号码服务,支持多种国家和主流应用的短信验证码接收。API采用RESTful风格设计,所有请求和响应均为JSON格式。

基础信息

请求流程

  1. 用户注册/登录获取用户令牌
  2. 查询可用国家和服务
  3. 获取电话号码
  4. 轮询获取短信验证码
  5. 释放或拉黑电话号码

认证方式

所有API请求需要在HTTP头中添加认证信息:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

认证类型

注意:用户相关操作(获取号码、释放号码等)需要使用用户令牌认证

API端点

GET /countries

获取支持的国家列表

参数

成功响应示例

{
  "success": true,
  "countries": [
    {
      "code": "usa",
      "name": "美国",
      "prefix": "+1"
    },
    {
      "code": "tur",
      "name": "土耳其",
      "prefix": "+90"
    }
  ]
}

字段说明

字段 类型 说明
code string 国家唯一标识符
name string 国家名称
prefix string 国际电话区号
GET /services

获取服务列表

参数

成功响应示例

{
  "success": true,
  "services": [
    {
      "Item_ID": "2267",
      "Item_Name": "巽风科技",
      "Item_UPrice": "1.0000",
      "Country_ID": "tur",
      "Country_Title": "+90/土耳其/turkey"
    },
    {
      "Item_ID": "3047",
      "Item_Name": "Telegram",
      "Item_UPrice": "1.3000",
      "Country_ID": "usa",
      "Country_Title": "+1/美国/usa"
    }
  ]
}

字段说明

字段 类型 说明
Item_ID string 服务唯一标识符
Item_Name string 服务名称
Item_UPrice string 服务单价(点数)
Country_ID string 所属国家代码
Country_Title string 国家标题(格式:区号/国家名称/英文名)
POST /get_phone

获取电话号码

参数

参数 类型 必填 说明
country string 国家代码(如:usa)
service string 服务代码(如:TG)

成功响应示例

{
  "success": true,
  "phone": "+901234567890",
  "id": "ORDER_1234567890",
  "message": "获取号码成功",
  "expire_time": 1689456789
}

字段说明

字段 类型 说明
phone string 获取的电话号码
id string 订单唯一标识符
expire_time integer 号码过期时间(UNIX时间戳)
注意事项
  1. 每个号码有效期为10分钟
  2. 获取号码会扣除相应点数
  3. 同一服务短时间内重复获取可能返回相同号码
POST /get_sms

获取短信验证码

参数

参数 类型 必填 说明
id string 订单ID

成功响应示例

{
  "success": true,
  "sms": "您的验证码是: 123456",
  "message": "获取短信成功",
  "received_at": 1689456889
}
轮询建议
  • 首次请求:获取号码后立即发起
  • 后续请求:每10-15秒轮询一次
  • 最大尝试次数:10次(约2分钟)
POST /release_phone

释放电话号码

参数

参数 类型 必填 说明
id string 订单ID

成功响应示例

{
  "success": true,
  "message": "号码已释放"
}

使用场景

  1. 成功获取短信后
  2. 不再需要该号码时
  3. 号码即将过期前
POST /black_phone

拉黑电话号码

参数

参数 类型 必填 说明
id string 订单ID

成功响应示例

{
  "success": true,
  "message": "号码已加入黑名单"
}

使用场景

  1. 号码无法接收短信
  2. 号码已被服务商封禁
  3. 需要更换新号码
注意:拉黑操作不可逆,请谨慎使用

错误处理

所有错误响应遵循以下格式:

{
  "success": false,
  "error_code": "错误代码",
  "message": "错误描述",
  "timestamp": "时间戳"
}

常见错误代码

错误代码 描述 解决方案
AUTH_REQUIRED 需要认证 添加认证头
INVALID_TOKEN 令牌无效 重新登录获取新令牌
INSUFFICIENT_POINTS 点数不足 充值点数
INVALID_PARAM 参数错误 检查请求参数
COUNTRY_NOT_FOUND 国家不存在 检查国家代码
SERVICE_NOT_FOUND 服务不存在 检查服务代码
ORDER_EXPIRED 订单已过期 获取新号码
SMS_NOT_RECEIVED 未收到短信 尝试重新获取或更换号码
RATE_LIMIT 请求频率过高 降低请求频率
SYSTEM_ERROR 系统错误 联系技术支持

状态码

状态码 描述
200 OK 请求成功
400 Bad Request 请求参数错误
401 Unauthorized 认证失败
403 Forbidden 权限不足
404 Not Found 资源不存在
429 Too Many Requests 请求频率过高
500 Internal Server Error 服务器内部错误

示例代码

Python
JavaScript
PHP
# 获取电话号码
import requests
import time

BASE_URL = "http://qn.ios163.com:5689"
API_KEY = "YOUR_API_KEY" # 或用户令牌

def get_phone_number(country, service):
    """获取电话号码"""
    url = f"{BASE_URL}/get_phone"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    data = {"country": country, "service": service}
    
    response = requests.post(url, headers=headers, json=data)
    if response.status_code == 200:
        result = response.json()
        if result.get("success"):
            return result["phone"], result["id"]
    return None, None

def get_sms_code(order_id, max_attempts=10):
    """获取短信验证码"""
    url = f"{BASE_URL}/get_sms"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    data = {"id": order_id}
    
    for _ in range(max_attempts):
        response = requests.post(url, headers=headers, json=data)
        if response.status_code == 200:
            result = response.json()
            if result.get("success") and result.get("sms"):
                return result["sms"]
        
        # 等待10秒后重试
        time.sleep(10)
    
    return None

# 使用示例
if __name__ == "__main__":
    # 获取美国Telegram号码
    phone, order_id = get_phone_number("usa", "TG")
    if phone:
        print(f"获取号码: {phone}, 订单ID: {order_id}")
        
        # 获取短信验证码
        sms = get_sms_code(order_id)
        if sms:
            print(f"收到短信: {sms}")
            
            # 提取验证码(简单示例)
            if "验证码" in sms:
                code = sms.split(":")[-1].strip()
                print(f"验证码: {code}")
        else:
            print("未收到短信")
    else:
        print("获取号码失败")
// 获取电话号码
const BASE_URL = "http://qn.ios163.com:5000";
const API_KEY = "YOUR_API_KEY"; // 或用户令牌

async function getPhoneNumber(country, service) {
    const url = `${BASE_URL}/get_phone`;
    const response = await fetch(url, {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${API_KEY}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({ country, service })
    });
    
    const data = await response.json();
    if (data.success) {
        return { phone: data.phone, id: data.id };
    }
    return null;
}

async function getSMSCode(orderId, maxAttempts = 10) {
    const url = `${BASE_URL}/get_sms`;
    
    for (let attempt = 0; attempt < maxAttempts; attempt++) {
        const response = await fetch(url, {
            method: 'POST',
            headers: {
                'Authorization': `Bearer ${API_KEY}`,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({ id: orderId })
        });
        
        const data = await response.json();
        if (data.success && data.sms) {
            return data.sms;
        }
        
        // 等待10秒
        await new Promise(resolve => setTimeout(resolve, 10000));
    }
    
    return null;
}

// 使用示例
(async () => {
    // 获取美国Telegram号码
    const phoneData = await getPhoneNumber("usa", "TG");
    if (phoneData) {
        console.log(`获取号码: ${phoneData.phone}, 订单ID: ${phoneData.id}`);
        
        // 获取短信验证码
        const sms = await getSMSCode(phoneData.id);
        if (sms) {
            console.log(`收到短信: ${sms}`);
            
            // 提取验证码(简单示例)
            if (sms.includes("验证码")) {
                const code = sms.split(":")[1].trim();
                console.log(`验证码: ${code}`);
            }
        } else {
            console.log("未收到短信");
        }
    } else {
        console.log("获取号码失败");
    }
})();
// 获取电话号码
<?php
$baseUrl = "http://qn.ios163.com:5000";
$apiKey = "YOUR_API_KEY"; // 或用户令牌

function getPhoneNumber($country, $service) {
    global $baseUrl, $apiKey;
    
    $url = $baseUrl . "/get_phone";
    $data = [
        "country" => $country,
        "service" => $service
    ];
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Bearer $apiKey",
        "Content-Type: application/json"
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    
    if ($httpCode === 200) {
        $result = json_decode($response, true);
        if ($result["success"]) {
            return [$result["phone"], $result["id"]];
        }
    }
    return [null, null];
}

function getSMSCode($orderId, $maxAttempts = 10) {
    global $baseUrl, $apiKey;
    
    $url = $baseUrl . "/get_sms";
    $data = ["id" => $orderId];
    
    for ($i = 0; $i < $maxAttempts; $i++) {
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            "Authorization: Bearer $apiKey",
            "Content-Type: application/json"
        ]);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        
        if ($httpCode === 200) {
            $result = json_decode($response, true);
            if ($result["success"] && $result["sms"]) {
                return $result["sms"];
            }
        }
        
        // 等待10秒
        sleep(10);
    }
    
    return null;
}

// 使用示例
list($phone, $orderId) = getPhoneNumber("usa", "TG");
if ($phone) {
    echo "获取号码: $phone, 订单ID: $orderId\n";
    
    $sms = getSMSCode($orderId);
    if ($sms) {
        echo "收到短信: $sms\n";
        
        // 提取验证码(简单示例)
        if (strpos($sms, "验证码") !== false) {
            $parts = explode(":", $sms);
            $code = trim(end($parts));
            echo "验证码: $code\n";
        }
    } else {
        echo "未收到短信\n";
    }
} else {
    echo "获取号码失败\n";
}
?>

注意事项

频率限制

号码有效期

点数系统

最佳实践

  1. 获取号码后立即开始轮询短信
  2. 使用后及时释放号码
  3. 处理异常情况(超时、无短信等)
  4. 记录订单ID用于后续操作

安全建议

  1. 不要在客户端存储API密钥
  2. 使用HTTPS加密通信(如可用)
  3. 定期更换用户令牌

常见问题

Q1: 获取号码失败怎么办?

A: 检查:

  1. 认证信息是否正确
  2. 点数是否充足
  3. 国家/服务代码是否正确
  4. 是否达到频率限制

Q2: 收不到短信怎么办?

A: 尝试:

  1. 等待更长时间(最长2分钟)
  2. 释放当前号码并获取新号码
  3. 更换国家或服务
  4. 检查是否被目标服务限制

Q3: 如何充值点数?

A: 联系客服或通过官方渠道购买点数包

Q4: 号码被拉黑后还能使用吗?

A: 不能,拉黑操作不可逆,需要获取新号码

如需更多帮助,请联系客服邮箱: support@qianniu.com