API de pasarela SMS para códigos de verificación en tus propios números

Autenticación

Crea una clave en el panel, en API REST. Empieza por bsk_live_ y solo se muestra una vez, así que guárdala como secreto, por ejemplo en BUSYSMS_API_KEY. Envíala en cada petición, en cualquiera de estas cabeceras:

Authorization: Bearer bsk_live_xxxxxxxx
# or
X-API-Key: bsk_live_xxxxxxxx

Una clave pertenece a una persona y solo ve los teléfonos de esa persona, además de los números compartidos con ella. Una clave creada en el panel puede leer códigos, listar tus teléfonos y números, leer el estado de tu cuenta y reactivar un teléfono en pausa; no puede eliminar un dispositivo ni gestionar tu cuenta, así que una clave filtrada no puede cambiar lo que pagas. Aun así, guarda las claves en el servidor: cualquiera que tenga una puede leer tus códigos.

Endpoints

URL base https://busysms.net/api/v1. Las peticiones son GET simples y las respuestas son JSON.

• GET /codes: el código más reciente de todos tus números. Con timeoutMs espera el siguiente, hasta 90 segundos. Filtros: service, phone, deviceId.
• GET /devices: tus teléfonos pasarela con su id, nombre, número, plataforma y estado en línea, verificado y en pausa, además de los números compartidos contigo.
• GET /numbers: solo tus números, cada uno con canReceive y, cuando no puede recibir, un reason: unverified, verification_pending, inactive, gateway_off o phone_unreachable.
• GET /devices/:id/messages: los mensajes capturados recientemente en un teléfono, del más nuevo al más antiguo. Admite service, limit (50 por defecto, 200 como máximo) y since.
• GET /account: tu cuenta, con el estado de la prueba y de la suscripción.

Espera un código: curl, Node.js y Python

La llamada que necesitan la mayoría de las integraciones es un long-poll justo después de que algo dispare un SMS. Empieza la espera, lanza el inicio de sesión, y la petición vuelve en cuanto llega un código que coincide.

curl -s -H "Authorization: Bearer $BUSYSMS_API_KEY" \
  "https://busysms.net/api/v1/codes?service=exampleapp&timeoutMs=60000"

const params = new URLSearchParams({ service: "exampleapp", timeoutMs: "60000" });
const res = await fetch(`https://busysms.net/api/v1/codes?${params}`, {
  headers: { Authorization: `Bearer ${process.env.BUSYSMS_API_KEY}` },
});

if (res.status === 402) throw new Error("Trial over or subscription inactive");
if (!res.ok) throw new Error(`BusySMS ${res.status}: ${await res.text()}`);

const { code, message } = await res.json();
if (code) console.log(`${code} from ${message.sender}`);
else console.log("No new code within 60 seconds");

import os
import requests

r = requests.get(
    "https://busysms.net/api/v1/codes",
    params={"service": "exampleapp", "timeoutMs": 60000},
    headers={"Authorization": f"Bearer {os.environ['BUSYSMS_API_KEY']}"},
    timeout=75,
)
if r.status_code == 402:
    raise RuntimeError("Trial over or subscription inactive")
r.raise_for_status()

data = r.json()
if data["code"]:
    print(data["code"], "from", data["message"]["sender"])
else:
    print("No new code within 60 seconds")

El orden importa menos de lo que podrías temer: un código que llegó hasta un segundo antes de iniciar la petición todavía cuenta como nuevo, y uno más antiguo no. En las pruebas, inicia primero la petición y dispara el SMS después; la guía de automatización de OTP muestra cómo hacerlo en Playwright, Selenium y Cypress.

Qué se devuelve

Todas las respuestas de /codes tienen la misma forma (aquí el objeto message aparece abreviado):

{
  "code": "482913",
  "message": {
    "otpCode": "482913",
    "phone": "+447700900123",
    "sender": "ExampleApp",
    "service": "exampleapp",
    "serviceLabel": "ExampleApp",
    "bodyPreview": "Your ExampleApp verification code is 482913",
    "receivedAt": 1792674000000,
    "deviceName": "Test phone"
  }
}

code es null cuando no llegó nada nuevo a tiempo: mientras espera, la API nunca recurre a un código anterior. receivedAt está en milisegundos desde epoch. service es un id corto que BusySMS asigna a cada mensaje: una marca conocida como google, telegram o microsoft o, si no, un slug del nombre del remitente. Pásalo como service= para esperar solo el código de ese remitente.

Errores y cómo manejarlos

• 401: falta la clave, tiene un formato incorrecto o está revocada. Una clave revocada lo indica con key_revoked.
• 402 payment_required: la prueba terminó y no hay una suscripción activa. La lectura de códigos se detiene, pero /devices sigue respondiendo para que puedas ver qué falla, y el cuerpo incluye un billingUrl.
• 403: el dispositivo pertenece a otra cuenta, o la clave no tiene el alcance necesario para la ruta (insufficient_scope).
• 404: no existe ese dispositivo.
• 409 number_unverified: el número de ese teléfono aún no se ha verificado, así que sus mensajes no se pueden leer.
• 429: límite de peticiones alcanzado. Espera retryAfterMs antes de reintentar.

Límites y buenas prácticas

• Una espera dura como máximo 90 segundos. Si un código puede tardar más, vuelve a llamar con un timeout nuevo en lugar de mantener una petición abierta.
• Con varios números, filtra: phone= con el número que recibe, o deviceId= para uno de tus teléfonos, para que no se devuelva un código destinado a otro inicio de sesión.
• Si ninguno de tus teléfonos está capturando cuando empieza una espera, BusySMS envía al teléfono una notificación pidiendo que se vuelva a encender la pasarela. Nunca activa la captura a distancia; tiene que tocarla una persona.
• Los mensajes capturados se guardan hasta 7 días y después se borran.
• Leer códigos requiere una prueba o una suscripción activa: $5 por número verificado al mes tras 7 días de prueba gratis. No se cobra por petición.

Más allá de la API REST

Los mismos códigos están disponibles para agentes de IA a través del servidor MCP de BusySMS (consulta códigos SMS para agentes de IA), y para personas a través de la extensión para Chrome, que rellena el código en el sitio web por ti.

Los números compartidos contigo también se incluyen. Cuando un compañero comparte los códigos de un número, /codes los devuelve junto con los tuyos, y phone= selecciona ese número.

Dudas

Preguntas frecuentes