SDK 与库

选择 SDK复制链接

SDK 均覆盖 Activation V2、Rental 和 Private Email 的全部 56 个方法，可根据应用选择语言与执行方式。Alternative API 不包含在内。

六种 SDK 的 Alpha 版本均已公开发布，源码位于 SMSPVA 官方 GitHub 仓库。可从下表选择软件包并通过对应的公共仓库安装。所有 SDK 均使用 MIT 许可证。

版本与更新复制链接

已发布的 SDK 均为 Alpha 版本。如需可重复的安装结果，请固定版本，并在升级前查看仓库的更新日志。Python 使用 0.1.0a2，JavaScript/TypeScript 使用 0.1.0-alpha.2，PHP、Go、C#/.NET 和 Java 使用 0.1.0-alpha.1（Go 命令中带 v 前缀）。这些都是预发布版本，尚非稳定版。

Python复制链接

从 PyPI 安装 Python SDK。使用 --pre 允许安装 Alpha 版本：

python -m pip install --pre smspva-sdk

如需固定当前版本，使用 python -m pip install smspva-sdk==0.1.0a2。源码、README 和问题跟踪位于 GitHub 上的 SMSPVA/smspva-python。

同步应用使用 SMSPVA。下面的示例查询 Activation 账户余额，并获取当前的 Rental 国家列表和 Email 提供商列表：

import os
from smspva import SMSPVA

with SMSPVA(os.environ["SMSPVA_API_KEY"]) as client:
    print(client.activation.get_balance())
    print(client.rental.get_countries())
    print(client.email.get_providers())

异步应用使用 AsyncSMSPVA，通过 await 调用相同的方法：

import asyncio
import os
from smspva import AsyncSMSPVA

async def main():
    async with AsyncSMSPVA(os.environ["SMSPVA_API_KEY"]) as client:
        print(await client.activation.get_balance())
        print(await client.rental.get_countries())
        print(await client.email.get_providers())

asyncio.run(main())

上下文管理器会在退出时关闭连接池。如果自行管理客户端，请在使用完毕后调用 close() 或 await aclose()。

JavaScript 和 TypeScript复制链接

从 npm 安装 JavaScript 和 TypeScript SDK。alpha 标签指向最新的 Alpha 版本：

npm install smspva-sdk@alpha

如需固定当前版本，使用 npm install [email protected]。源码、README 和问题跟踪位于 GitHub 上的 SMSPVA/smspva-js。

import { SMSPVA } from 'smspva-sdk';

const client = new SMSPVA({ apiKey: process.env.SMSPVA_API_KEY });

console.log(await client.activation.getBalance());
console.log(await client.rental.getCountries());
console.log(await client.email.getProviders());

同样的代码也适用于 JavaScript。CommonJS 使用 const { SMSPVA } = require('smspva-sdk') 导入。请在服务器上运行 SDK，不要把 API 密钥放进浏览器代码中。

PHP复制链接

使用 Composer 从 Packagist 安装 PHP SDK：

composer require "smspva/sdk:^0.1@alpha"

如需固定此版本，使用 composer require smspva/sdk:0.1.0-alpha.1。源码、README 和问题跟踪位于 GitHub 上的 SMSPVA/smspva-php。

<?php
declare(strict_types=1);
require __DIR__ . "/vendor/autoload.php";

use SMSPVA\Client;

$client = new Client(getenv("SMSPVA_API_KEY") ?: null);
print_r($client->activation->getBalance());
print_r($client->rental->getCountries());
print_r($client->email->getProviders());

PHP 方法接收参数数组，生成的 PHPDoc 会注明字段类型。响应是关联数组。客户端为同步模式，需要 cURL 扩展。

Go复制链接

从带版本标签的模块安装 Go SDK：

go get github.com/SMSPVA/[email protected]

源码、README 和问题跟踪位于 GitHub 上的 SMSPVA/smspva-go。SDK 仅使用标准库。

Go SDK 是带版本标签的 GitHub 模块。pkg.go.dev 展示 README 和自动生成的包文档，无需另行上传代码。安装时不需要注册 pkg.go.dev 账号。新版本由官方仓库中的 Git 标签标识。

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    smspva "github.com/SMSPVA/smspva-go"
)

func printResult(response smspva.Response, err error) {
    if err != nil { log.Fatal(err) }
    fmt.Println(string(response.Body))
}

func main() {
    client, err := smspva.New(smspva.Options{APIKey: os.Getenv("SMSPVA_API_KEY")})
    if err != nil { log.Fatal(err) }
    defer client.CloseIdleConnections()
    ctx := context.Background()
    printResult(client.Activation.GetBalance(ctx))
    printResult(client.Rental.GetCountries(ctx))
    printResult(client.Email.GetProviders(ctx))
}

将程序保存为 main.go，然后运行 go run .。方法接收 context.Context，有参数时使用类型化结构体，原始 JSON 响应位于 Response.Body。

C# / .NET复制链接

从 NuGet 安装 .NET SDK。源码、README 和问题跟踪位于 GitHub 上的 SMSPVA/smspva-dotnet：

dotnet add package Smspva.Sdk --version 0.1.0-alpha.1

using System;
using Smspva;

using var client = new SmspvaClient(Environment.GetEnvironmentVariable("SMSPVA_API_KEY"));
Console.WriteLine(await client.Activation.GetBalanceAsync());
Console.WriteLine(await client.Rental.GetCountriesAsync());
Console.WriteLine(await client.Email.GetProvidersAsync());

C# 方法为异步模式，支持 CancellationToken。请求使用类型化 record，响应为 JsonElement。

Java复制链接

从 Maven Central 安装 Java SDK，在应用的 pom.xml 中加入以下依赖：

<dependency>
  <groupId>com.smspva</groupId>
  <artifactId>smspva-sdk</artifactId>
  <version>0.1.0-alpha.1</version>
</dependency>

import com.smspva.sdk.SmsPva;

public class Example {
    public static void main(String[] args) {
        try (SmsPva client = new SmsPva(System.getenv("SMSPVA_API_KEY"))) {
            System.out.println(client.activation().getBalance());
            System.out.println(client.rental().getCountries());
            System.out.println(client.email().getProviders());
        }
    }
}

源码、README 和问题跟踪位于 GitHub 上的 SMSPVA/smspva-java。Java 方法为同步模式，接收类型化 Requests record，返回 JsonNode。此 Alpha 版本没有 Java 异步封装或轮询辅助方法。

参数与响应复制链接

请从实时参考列表中获取国家、服务和提供商代码。例如，在 Python 中调用 email.get_providers()，或在 JavaScript 中调用 email.getProviders()，再将选定的 pcode 传给 get_data(pcode=...) 或 getData({ pcode: ... })。公开查询方法无需 API 密钥，也不会发送客户端配置的密钥。

SDK 保留文档中的 HTTP 方法、实际请求参数名、响应代码和 JSON 值类型。Python 与 JavaScript 包含生成的响应类型；PHP 返回关联数组；Go 将原始 JSON 放在 Response.Body 中；C# 使用 JsonElement；Java 使用 JsonNode。各语言的请求参数均有类型定义或说明。

查询 Rental 多服务号码数量时，请明确传入 dtype 和 dcount。SDK 要求提供这两个参数，因为接口文档提醒此方法不能依赖服务器的默认值。

等待短信与处理错误复制链接

Activation 的 receive_sms / receiveSms 遇到 HTTP 202 和 SMS_NOT_YET_RECEIVED 时，会返回原始的等待响应，可用 is_pending / isPending 判断。创建 Email 订单时，表示无库存的 status=2 也会作为原始结果返回，可用 is_no_stock / isNoStock 判断。

需要重复查询短信时，可使用 Python 的 activation.wait_for_sms 或 JavaScript 的 activation.waitForSms。获取号码时保存订单到期时间，再将同一个截止时间传入 expires_at（Unix 秒）或 expiresAt（Unix 毫秒）。收到等待响应后，辅助方法至少间隔五秒再查询；到期或遇到错误时停止。它不会创建或取消订单。接收新短信可能触发扣费。

每次调用 receive_sms / receiveSms 只发送一个 HTTP 请求。Python 和 JavaScript 的等待辅助方法会立即发送第一次请求；每次收到等待响应后，默认暂停五秒再查询。可在 Python 中设置 interval=15，或在 JavaScript 中设置 intervalMs: 15_000，将暂停时间改为 15 秒。最小间隔是辅助方法的规则，不是整个 API 的限流规定。await 等待辅助方法的结果，同时允许其他异步任务在请求和暂停期间继续运行；Python 同步客户端则会阻塞调用线程。

Python、JavaScript 和 PHP 通过 ApiError 报告 API 失败；C# 和 Java 使用 ApiException；Go 返回 APIError。这些错误保留 HTTP 状态、API 错误代码和原始响应。协议错误与网络传输错误会分别报告。C# 支持取消令牌，Go 支持通过 context 取消请求。

SDK 不会自动重试任何请求。付费操作或修改状态的操作如果中途断开连接，可能无法确定是否已完成。重试前请先查询当前订单，避免重复购买。GET 方法也可能修改状态或触发扣费。

默认超时为 30 秒。Python 将其应用于 HTTPX 的每项网络操作；JavaScript 则应用于整个请求，包括读取响应正文。可以通过 Python 的 timeout 或 JavaScript 的 timeoutMs 修改。JavaScript 还支持通过 signal 选项传入 AbortSignal 来取消请求。

PHP、Go 和 C# 默认也会限制整个请求的耗时。Java 与 Python 一样使用网络操作超时，而不是整个响应的严格截止时间。Java 和 PHP 为同步客户端。各语言的超时配置和错误类型请参考 SDK 的 README。

也可以继续结合快速入门中的 HTTP 示例使用 SDK。各方法页面仍是核对参数、响应代码和重要警告的依据。