SDKs y bibliotecas

Elige un SDKCopiar enlace

Los SDKs cubren los 56 métodos de Activation V2, Rental y Private Email. Elige el lenguaje y el modo de ejecución que necesite tu aplicación. Alternative API queda excluida.

Los seis SDKs tienen versiones alfa publicadas, con el código en los repositorios oficiales de SMSPVA en GitHub. Elige un paquete para instalarlo desde su registro público. Todos los SDKs usan MIT.

Versiones y actualizacionesCopiar enlace

Los SDKs publicados son versiones alfa. Fija una versión para obtener instalaciones reproducibles y revisa el historial de cambios del repositorio antes de actualizar. Python usa 0.1.0a2; JavaScript/TypeScript, 0.1.0-alpha.2; PHP, Go, C#/.NET y Java, 0.1.0-alpha.1 (con el prefijo v en los comandos de Go). Son versiones preliminares, no estables.

PythonCopiar enlace

Instala el SDK de Python desde PyPI. Usa --pre para incluir versiones alfa:

python -m pip install --pre smspva-sdk

Para fijar la versión actual, usa python -m pip install smspva-sdk==0.1.0a2. El código fuente, el README y el seguimiento de incidencias están en SMSPVA/smspva-python en GitHub.

Usa SMSPVA en una aplicación síncrona. Este ejemplo consulta tu saldo de Activation y obtiene los países de Rental y los proveedores de Email disponibles en ese momento:

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())

En una aplicación asíncrona, usa AsyncSMSPVA y llama a los mismos métodos con 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())

El gestor de contexto cierra el grupo de conexiones al terminar. Si gestionas el cliente por tu cuenta, llama a close() o await aclose() cuando dejes de usarlo.

JavaScript y TypeScriptCopiar enlace

Instala el SDK de JavaScript y TypeScript desde npm. La etiqueta alpha selecciona la última versión alfa:

npm install smspva-sdk@alpha

Para fijar la versión actual, usa npm install [email protected]. El código fuente, el README y el seguimiento de incidencias están en SMSPVA/smspva-js en GitHub.

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());

El mismo código funciona en JavaScript. En CommonJS, importa con const { SMSPVA } = require('smspva-sdk'). Ejecuta el SDK en tu servidor y mantén la clave API fuera del código del navegador.

PHPCopiar enlace

Instala el SDK de PHP desde Packagist con Composer:

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

Para fijar esta versión, usa composer require smspva/sdk:0.1.0-alpha.1. El código fuente, el README y el seguimiento de incidencias están en SMSPVA/smspva-php en GitHub.

<?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());

Los métodos de PHP reciben arrays de parámetros descritos mediante PHPDoc generado. Devuelven arrays asociativos. El cliente es síncrono y necesita la extensión cURL.

GoCopiar enlace

Instala el SDK de Go desde su módulo etiquetado:

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

El código fuente, el README y el seguimiento de incidencias están en SMSPVA/smspva-go en GitHub. El SDK solo usa la biblioteca estándar.

El SDK de Go es un módulo de GitHub con versiones. pkg.go.dev muestra su README y la documentación generada del paquete; no es otro destino al que subir código. No necesitas una cuenta de pkg.go.dev para instalarlo. Las nuevas versiones se identifican mediante etiquetas Git en el repositorio oficial.

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))
}

Guarda el programa como main.go y ejecuta go run .. Los métodos reciben context.Context, structs tipados cuando necesitan parámetros y devuelven el JSON original en Response.Body.

C# / .NETCopiar enlace

Instala el SDK de .NET desde NuGet. El código, el README y el seguimiento de incidencias están en SMSPVA/smspva-dotnet en GitHub:

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());

Los métodos de C# son asíncronos y aceptan CancellationToken. Las solicitudes usan records tipados y las respuestas son valores JsonElement.

JavaCopiar enlace

Instala el SDK de Java desde Maven Central añadiendo esta dependencia al pom.xml de tu aplicación:

<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());
        }
    }
}

El código, el README y el seguimiento de incidencias están en SMSPVA/smspva-java en GitHub. Java ofrece métodos síncronos, records tipados de Requests y respuestas JsonNode. Esta alfa no incluye un cliente Java asíncrono ni un ayudante de polling.

Parámetros y respuestasCopiar enlace

Obtén los códigos de país, servicio y proveedor de los listados actuales. Por ejemplo, llama a email.get_providers() en Python o email.getProviders() en JavaScript y pasa el pcode elegido a get_data(pcode=...) o getData({ pcode: ... }). Los métodos públicos de consulta funcionan sin clave API y nunca envían la clave del cliente.

Los SDK conservan los métodos HTTP, los nombres de parámetros enviados, los códigos y los tipos JSON documentados. Python y JavaScript incluyen tipos de respuesta generados. PHP devuelve arrays asociativos; Go, JSON original en Response.Body; C#, JsonElement; y Java, JsonNode. Los argumentos de solicitud están documentados o tipados para cada lenguaje.

En la consulta de disponibilidad para varios servicios de Rental, indica dtype y dcount de forma explícita. El SDK exige ambos porque la documentación de la API advierte que no se debe depender de los valores predeterminados del servidor en este método.

Esperar un SMS y gestionar erroresCopiar enlace

El método receive_sms / receiveSms de Activation devuelve la respuesta original de espera para HTTP 202 y SMS_NOT_YET_RECEIVED. Compruébala con is_pending / isPending. Al crear un pedido de Email, status=2 también se devuelve como resultado de falta de disponibilidad; puedes reconocerlo con is_no_stock / isNoStock.

Para consultar un SMS repetidamente, usa activation.wait_for_sms en Python o activation.waitForSms en JavaScript. Guarda la caducidad al obtener el número y pasa ese mismo límite como expires_at (segundos Unix) o expiresAt (milisegundos Unix). El ayudante espera al menos cinco segundos entre respuestas pendientes y se detiene al llegar al límite o recibir un error. Nunca crea ni cancela pedidos. Recibir un SMS nuevo puede generar un cobro.

Cada llamada a receive_sms / receiveSms realiza una sola solicitud HTTP. Los ayudantes de espera de Python y JavaScript envían la primera solicitud inmediatamente y esperan cinco segundos después de cada respuesta pendiente antes de volver a consultar. Usa interval=15 en Python o intervalMs: 15_000 en JavaScript para una pausa de 15 segundos. El intervalo mínimo es una regla del ayudante, no un límite general de la API. await espera el resultado del ayudante y permite ejecutar otras tareas asíncronas durante las solicitudes y las pausas; el cliente síncrono de Python bloquea el hilo que lo llama.

Python, JavaScript y PHP notifican los fallos de la API mediante ApiError; C# y Java usan ApiException, y Go devuelve un APIError. Conservan el estado HTTP, el código de la API y la respuesta original. Los errores de protocolo y transporte se distinguen por separado. C# admite tokens de cancelación y Go admite cancelación mediante context.

Ninguna solicitud se repite automáticamente. Si se pierde la conexión durante una operación de pago o que cambia el estado, puede que no sepas si se completó. Consulta tus pedidos antes de repetirla para evitar una compra duplicada. Un método GET también puede cambiar el estado o generar un cobro.

El tiempo de espera predeterminado es de 30 segundos. Python lo aplica a cada operación de red de HTTPX; JavaScript, a la solicitud completa, incluida la lectura del cuerpo de respuesta. Puedes cambiarlo con timeout en Python o timeoutMs en JavaScript. JavaScript también acepta un AbortSignal mediante la opción signal.

PHP, Go y C# también limitan la solicitud completa de forma predeterminada. Java aplica límites por operación de red, como Python, en lugar de un plazo estricto para toda la respuesta. Java y PHP son síncronos. Consulta el README del SDK para las opciones de tiempo de espera y los tipos de error de cada lenguaje.

Puedes seguir usando los ejemplos HTTP junto con los SDK. La página de cada método sigue siendo la referencia para sus parámetros, códigos de respuesta y advertencias importantes.