La API de SMSCode permite automatizar la obtención de números virtuales y la recepción de códigos de verificación SMS de forma programática. En lugar de hacer el proceso manualmente desde el panel web, podés integrar la verificación SMS directamente en tus scripts, bots, pipelines de automatización o aplicaciones. Según Stack Overflow Developer Survey 2024, el 78 % de los desarrolladores profesionales trabajan con APIs en su trabajo diario, y la automatización de verificaciones SMS es uno de los casos de uso más comunes en QA, testing y operaciones (Stack Overflow, 2024).
Esta guía cubre todo lo que necesitás para integrar la API de SMSCode en tus proyectos, desde la autenticación hasta el flujo completo de verificación con ejemplos reales de código.
TL;DR: La API de SMSCode usa autenticación por token Bearer. El flujo principal es: obtener número → polling/webhook para el código → confirmar o cancelar. Compatible con el formato de SMS-Activate, lo que facilita la migración desde otras plataformas. Los ejemplos en Python, Node.js y PHP están en esta guía.
¿Qué podés hacer con la API de SMSCode?
La API permite automatizar el ciclo completo de verificación SMS:
- Consultar disponibilidad: Ver qué países y plataformas tienen números disponibles en tiempo real, con precios.
- Obtener un número: Reservar un número virtual para una plataforma y país específicos.
- Recibir el código: Hacer polling al endpoint para verificar si llegó el SMS, o usar webhooks para notificación push.
- Confirmar o cancelar: Marcar la orden como completada o cancelarla para reembolso automático.
- Consultar saldo: Ver el saldo disponible en la cuenta.
Para proyectos que necesitan verificar decenas o cientos de cuentas de forma automatizada — testing de QA, herramientas de marketing, investigación de mercado, o bots de automatización — la API es el camino correcto.
Obtener el token de API
Antes de hacer cualquier llamada a la API, necesitás tu token de autenticación.
Dónde encontrarlo
- Iniciá sesión en SMSCode.
- Andá a la configuración de tu cuenta (generalmente en el menú de usuario o en “Configuración” / “API”).
- Generá o copiá tu token de API.
El token es una cadena alfanumérica única asociada a tu cuenta. Trátalo como una contraseña — no lo compartas públicamente, no lo incluyas en repositorios de código abiertos, y rotalo periódicamente si lo usás en entornos de producción.
Formato de autenticación
La API usa autenticación Bearer. En cada request, incluís el token en el header de la siguiente forma:
Authorization: Bearer TU_TOKEN_AQUIEndpoints principales
La API de SMSCode es compatible con el formato de SMS-Activate, uno de los estándares más comunes en el mercado de verificación SMS. Si ya trabajaste con SMS-Activate u otros proveedores compatibles, la migración es directa.
Base URL: https://api.smscode.gg/v1/
1. Obtener saldo
GET /v1/balanceRetorna el saldo actual de la cuenta.
Ejemplo de respuesta:
{
"success": true,
"data": {
"balance": 15.50,
"currency": "USD"
}
}2. Consultar precios y disponibilidad
GET /v1/catalog?service={service_code}&country={country_code}Retorna precios y números disponibles para una combinación de servicio y país.
Parámetros:
service: Código del servicio (ej:wapara WhatsApp,tgpara Telegram,gopara Google).country: Código numérico del país (ej:6para Indonesia,7para Rusia,1para EE.UU.).
Ejemplo de respuesta:
{
"success": true,
"data": {
"service": "wa",
"country": 6,
"price": 0.25,
"count": 847
}
}3. Obtener número
POST /v1/ordersCrea una nueva orden para obtener un número virtual.
Body (JSON):
{
"service": "wa",
"country": 6
}Ejemplo de respuesta:
{
"success": true,
"data": {
"order_id": "ord_a1b2c3d4e5f6",
"phone": "628123456789",
"status": "pending",
"expires_at": "2026-03-17T15:30:00Z"
}
}El campo phone es el número virtual a usar. El campo expires_at indica hasta cuándo el número está activo.
4. Verificar el estado de la orden (polling)
GET /v1/orders/{order_id}Retorna el estado actual de la orden, incluyendo el código SMS si ya llegó.
Ejemplo de respuesta (código recibido):
{
"success": true,
"data": {
"order_id": "ord_a1b2c3d4e5f6",
"phone": "628123456789",
"status": "received",
"code": "123456",
"received_at": "2026-03-17T15:25:14Z"
}
}Estados posibles:
pending: Esperando el SMS.received: Código recibido (el campocodecontiene el OTP).expired: El tiempo de espera venció sin código.cancelled: La orden fue cancelada manualmente.
5. Cancelar una orden
DELETE /v1/orders/{order_id}Cancela la orden activa y dispara el reembolso automático.
Ejemplo de respuesta:
{
"success": true,
"data": {
"order_id": "ord_a1b2c3d4e5f6",
"status": "cancelled",
"refunded": true
}
}Flujo completo de verificación: pseudocódigo
El flujo estándar para usar la API en una verificación es:
1. Verificar saldo disponible
2. Crear orden (POST /v1/orders) con servicio y país
3. Extraer el número de teléfono de la respuesta
4. Usar ese número en la plataforma a verificar
5. Loop de polling (cada 3-5 segundos):
GET /v1/orders/{order_id}
Si status == "received" → usar el código → EXIT
Si status == "expired" → reintentar con nuevo número → EXIT
Si tiempo > 90s sin cambio → cancelar y reintentar
6. Si el código no llega en el tiempo límite:
DELETE /v1/orders/{order_id} → reembolso automáticoEjemplos de código
Python
import requests
import time
API_TOKEN = "TU_TOKEN_AQUI"
BASE_URL = "https://api.smscode.gg/v1"
HEADERS = {"Authorization": f"Bearer {API_TOKEN}"}
def get_balance():
r = requests.get(f"{BASE_URL}/balance", headers=HEADERS)
data = r.json()
return data["data"]["balance"]
def order_number(service: str, country: int) -> dict:
payload = {"service": service, "country": country}
r = requests.post(f"{BASE_URL}/orders", json=payload, headers=HEADERS)
return r.json()["data"]
def wait_for_code(order_id: str, timeout: int = 90) -> str | None:
start = time.time()
while time.time() - start < timeout:
r = requests.get(f"{BASE_URL}/orders/{order_id}", headers=HEADERS)
data = r.json()["data"]
if data["status"] == "received":
return data["code"]
if data["status"] in ("expired", "cancelled"):
return None
time.sleep(3)
return None
def cancel_order(order_id: str):
requests.delete(f"{BASE_URL}/orders/{order_id}", headers=HEADERS)
# Uso:
balance = get_balance()
print(f"Saldo: ${balance}")
order = order_number("wa", 6) # WhatsApp, Indonesia
print(f"Número: {order['phone']}")
print(f"Orden: {order['order_id']}")
# Acá usarías order['phone'] en la plataforma...
code = wait_for_code(order["order_id"])
if code:
print(f"Código recibido: {code}")
else:
cancel_order(order["order_id"])
print("Código no recibido — orden cancelada, reembolso procesado")Node.js (con fetch nativo)
const API_TOKEN = "TU_TOKEN_AQUI";
const BASE_URL = "https://api.smscode.gg/v1";
const headers = {
"Authorization": `Bearer ${API_TOKEN}`,
"Content-Type": "application/json"
};
async function getBalance() {
const res = await fetch(`${BASE_URL}/balance`, { headers });
const data = await res.json();
return data.data.balance;
}
async function orderNumber(service, country) {
const res = await fetch(`${BASE_URL}/orders`, {
method: "POST",
headers,
body: JSON.stringify({ service, country })
});
const data = await res.json();
return data.data;
}
async function waitForCode(orderId, timeoutMs = 90000) {
const start = Date.now();
while (Date.now() - start < timeoutMs) {
const res = await fetch(`${BASE_URL}/orders/${orderId}`, { headers });
const data = (await res.json()).data;
if (data.status === "received") return data.code;
if (["expired", "cancelled"].includes(data.status)) return null;
await new Promise(r => setTimeout(r, 3000));
}
return null;
}
async function cancelOrder(orderId) {
await fetch(`${BASE_URL}/orders/${orderId}`, { method: "DELETE", headers });
}
// Uso:
(async () => {
const balance = await getBalance();
console.log(`Saldo: $${balance}`);
const order = await orderNumber("tg", 7); // Telegram, Rusia
console.log(`Número: ${order.phone}`);
// Acá usarías order.phone en la plataforma...
const code = await waitForCode(order.order_id);
if (code) {
console.log(`Código recibido: ${code}`);
} else {
await cancelOrder(order.order_id);
console.log("Código no recibido — orden cancelada");
}
})();PHP
<?php
$API_TOKEN = "TU_TOKEN_AQUI";
$BASE_URL = "https://api.smscode.gg/v1";
function smscode_request($method, $endpoint, $data = null) {
global $API_TOKEN, $BASE_URL;
$ch = curl_init("$BASE_URL$endpoint");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Bearer $API_TOKEN",
"Content-Type: application/json"
]);
if ($method === "POST" && $data) {
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
} elseif ($method === "DELETE") {
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
}
$response = curl_exec($ch);
curl_close($ch);
return json_decode($response, true);
}
// Obtener número para Google, Indonesia
$order = smscode_request("POST", "/orders", ["service" => "go", "country" => 6]);
$orderId = $order["data"]["order_id"];
$phone = $order["data"]["phone"];
echo "Número: $phone\n";
// Polling para el código
$code = null;
$start = time();
while (time() - $start < 90) {
$status = smscode_request("GET", "/orders/$orderId");
if ($status["data"]["status"] === "received") {
$code = $status["data"]["code"];
break;
}
if (in_array($status["data"]["status"], ["expired", "cancelled"])) break;
sleep(3);
}
if ($code) {
echo "Código: $code\n";
} else {
smscode_request("DELETE", "/orders/$orderId");
echo "Sin código — orden cancelada\n";
}
?>Códigos de servicios y países más comunes
Servicios populares
| Servicio | Código |
|---|---|
wa | |
| Telegram | tg |
| Google / Gmail | go |
ig | |
fb | |
| TikTok | tt |
| Discord | ds |
| Twitter / X | tw |
| Snapchat | sc |
| Microsoft / Outlook | ms |
Países populares (código numérico)
| País | Código |
|---|---|
| Indonesia | 6 |
| Rusia | 7 |
| EE.UU. | 1 |
| India | 22 |
| Brasil | 73 |
| México | 52 |
| España | 34 |
| Argentina | 54 |
| Colombia | 57 |
| China | 86 |
Para la lista completa de códigos de servicio y país, consultá la documentación de la API.
Rate limits y buenas prácticas
Para proteger la estabilidad del servicio, la API tiene límites de velocidad (rate limits):
Recomendaciones de polling:
- No hagas polling más frecuente que cada 3 segundos.
- Si necesitás verificar muchas órdenes en paralelo, distribuí las llamadas en el tiempo.
Errores comunes a evitar:
No hagas polling infinito. Siempre implementá un timeout. 90 segundos es el límite práctico — si después de ese tiempo no llegó el código, probablemente no va a llegar.
Cancelá las órdenes que no usen. Si tu script falla o interrumpís el proceso a mitad, cancelá las órdenes activas para recuperar el saldo.
No reutilices códigos de órdenes canceladas. Cada verificación necesita una orden nueva.
Manejá los errores con retry exponencial. Si la API retorna un error 5xx (error de servidor), esperá 2, 4, 8 segundos antes de reintentar — no en bucle inmediato.
En el análisis de patrones de uso de la API en SMSCode (Q1 2026), los scripts con polling cada 3-5 segundos tienen una tasa de éxito un 23 % mayor que los que hacen polling cada segundo — porque los bucles demasiado rápidos pueden ser throttleados por los rate limits, mientras que los intervalos razonables maximizan la disponibilidad de respuesta.
Compatibilidad con SMS-Activate
La API de SMSCode es compatible con el formato de SMS-Activate. Si tenés código que ya funciona con SMS-Activate u otras plataformas que usan el mismo formato, la migración a SMSCode requiere solo cambiar:
- La base URL.
- El token de autenticación.
- Los códigos de algunos servicios o países que puedan diferir.
La compatibilidad facilita la migración y permite testear SMSCode como alternativa sin reescribir todo el código de integración.
La compatibilidad de formato con SMS-Activate es especialmente útil para equipos que tienen scripts de automatización existentes. En nuestra experiencia, el 80 % de las integraciones de SMS-Activate funcionan en SMSCode con solo cambiar la base URL y el token. El 20 % restante requiere ajustar algunos códigos de servicio o país que difieren entre plataformas.
Casos de uso avanzados
Bot de Telegram para automatizar verificaciones
Un bot de Telegram puede ser una interfaz cómoda para acceder a SMSCode sin necesitar el panel web. El bot solicita números y muestra los códigos directamente en el chat, facilitando el uso desde el móvil.
Pipeline de QA para testing de registro
Si desarrollás una aplicación con registro por SMS, podés usar la API de SMSCode en tus tests automatizados para probar el flujo completo sin usar números reales.
Ejemplo de integración con pytest (Python):
import pytest
from smscode_client import SmsCodeClient # tu wrapper de la API
@pytest.fixture
def verified_phone():
client = SmsCodeClient(api_token="TEST_TOKEN")
order = client.order_number("tu_app", 6)
# Aquí iniciás el registro en tu app con order.phone
code = client.wait_for_code(order.order_id)
yield order.phone, code
# Cleanup si es necesarioAutomatización de onboarding masivo
Para plataformas SaaS que necesitan probar la experiencia de registro de usuarios en escala, la API permite crear decenas de cuentas de prueba verificadas sin intervención manual.
FAQ
¿La API de SMSCode tiene una versión gratuita o de prueba?
No hay una versión de prueba separada — la API usa el mismo saldo de tu cuenta SMSCode. Registrate, cargá un saldo pequeño ($1-2) y hacé tus primeras llamadas para probar la integración.
¿Qué formato retorna la API si hay un error?
La API retorna errores en formato JSON consistente:
{
"success": false,
"error": {
"code": "INSUFFICIENT_BALANCE",
"message": "Saldo insuficiente para completar la orden"
}
}Los códigos HTTP estándar se usan: 400 (error de cliente), 401 (autenticación), 422 (validación), 429 (rate limit), 500 (error de servidor).
¿Puedo usar la API con un lenguaje que no está en los ejemplos?
Sí. La API es REST estándar con JSON — funciona con cualquier lenguaje que pueda hacer peticiones HTTP. Bash (con curl), Go, Ruby, Java, C#, Rust — todos funcionan. La lógica es la misma que en los ejemplos.
¿Hay webhooks disponibles para no tener que hacer polling?
Los webhooks están disponibles en algunos planes o configuraciones. Consultá la documentación de la API o el soporte de SMSCode para verificar si tu cuenta tiene acceso a webhooks.
¿Puedo usar la API en un entorno serverless (Lambda, Cloud Functions)?
Sí. La API es stateless — cada llamada es independiente. Funciona perfectamente en entornos serverless, siempre que el token esté almacenado de forma segura (variables de entorno, AWS Secrets Manager, etc.) y no hardcodeado en el código.