La API REST de SMS Activate App permite a tu código comprar un número privado, lanzar una verificación y leer el código SMS, en tus apps, cuentas y pruebas.
Esta guía recorre el flujo completo: elegir un número, comprarlo de forma segura, leer el código OTP (contraseña de un solo uso) y liberar el número cuando termines.
Cuándo automatizar
La automatización encaja con trabajo que es tuyo y que repites. Tres casos habituales:
- Pruebas de extremo a extremo de los pasos por SMS de tu propia app: registro, inicio de sesión, restablecimiento de contraseña y 2FA (autenticación de dos factores).
- Mantener el 2FA operativo en las cuentas de tus propios servicios y en tus herramientas internas.
- Un paso de verificación dentro de un producto que gestionas tú.
Cada número es un número virtual privado. Es un número móvil o local real del rango de un operador, según el país. Tu cuenta lo conserva durante un plazo de 28 días. El mismo número puede recibir códigos posteriores, así que la reverificación y la recuperación de cuentas siguen funcionando durante ese plazo.
Hay dos límites. Un número es definitivo y no se reembolsa una vez emitido. La plataforma en la que verificas decide si acepta un número, no nosotros.
La mayoría de los códigos llegan unos minutos después de que la plataforma los envíe. Todavía no publicamos una tasa de entrega, así que prueba un número con tu plataforma de destino antes de montar un pipeline sobre él.
La API recibe SMS. No los envía.
Antes de empezar
- Crea una cuenta gratuita en la página de registro.
- Añade saldo a la cuenta.
- Crea una clave de API personal en el panel de tu cuenta, en la pestaña de claves de API, o en el bot de Telegram.
Envía la clave en cada petición, el catálogo incluido:
La clave gasta tu saldo. Guárdala en el servidor, en un gestor de secretos o en un secreto de CI. Nunca la pongas en código del cliente ni la subas a un repositorio.
Datos de referencia:
- URL base: https://api.sms-activate.app/v1/public
- Los importes van en céntimos de dólar estadounidense, como números enteros. balanceCents: 2000 significa 20,00 USD.
- Especificación legible por máquinas: el archivo OpenAPI (OpenAPI 3.1).
- Documentación para personas: la documentación de la API.
- Una skill lista para agentes LLM: la skill para agentes.
- Límites: al menos 120 peticiones por minuto por cuenta y 30 compras por minuto. Si los superas, la respuesta es rate_limited con una cabecera Retry-After.
El flujo de verificación
- Llama a GET /countries. Devuelve la disponibilidad y el rango de precios de cada país.
- Llama a GET /numbers/search?country=US&limit=1 para elegir un número disponible. Cada resultado incluye phoneNumber y tu precio en priceCents.
- Compra el número con POST /numbers y el cuerpo {"phone": "<phoneNumber>", "country": "US"}. Añade una cabecera Idempotency-Key: <uuid> para que un reintento nunca te cobre dos veces. Una compra correcta devuelve 201 con number, chargedCents y balanceAfterCents. Hay dos campos opcionales: autoRenew (por defecto true) y note.
- Introduce el número en el flujo que estás probando y provoca el envío del SMS.
- Lee el código. Consulta GET /numbers/{id}/sms para ese número, o GET /sms para todos, cada 5 a 15 segundos aproximadamente, y fija un tiempo de espera máximo. Cada SMS tiene id, numberId, from, to, body y receivedAt; extrae el código de body. Los listados se paginan por cursor con cursor, limit y nextCursor.
- Termina. Envía PATCH /numbers/{id} con {"autoRenew": false} para detener la renovación, o DELETE /numbers/{id} para liberar el número. Si ejecutas una batería de pruebas a diario, suele ser más sencillo mantener un número con renovación que comprar uno nuevo en cada ejecución.
Ejemplo con curl
La primera llamada busca un número. La segunda lo compra. La tercera lee los SMS recibidos.
Sustituye +15551234567 por un número devuelto por la primera llamada. Si repites la compra tras un error de red, reutiliza el mismo valor de Idempotency-Key en lugar de generar uno nuevo.
Ejemplo en Python
Esta función espera un código en un número que ya tienes. Usa la biblioteca requests y lee la clave de las variables de entorno.
Si algún SMS anterior en el mismo número puede coincidir, compara receivedAt con el momento en que tu prueba provocó el envío del mensaje y quédate solo con uno más reciente.
Un webhook en lugar de sondeo
Envía PATCH /numbers/{id} con {"forwardWebhookUrl": "https://your-app.example.com/sms"} y cada SMS y cada llamada a ese número se enviarán a tu servidor en cuanto lleguen. Antes se comprueba la dirección: debe responder a un POST de prueba con un estado 2xx.
Cada petición lleva x-vpn-event, x-vpn-timestamp y x-vpn-signature. La firma es HMAC-SHA256 de v1.<timestamp>.<raw body> con tu secreto de webhook. Verifícala sobre los bytes sin procesar y rechaza una marca de tiempo que se desvíe más de cinco minutos.
El sondeo es más sencillo para una prueba que se ejecuta una sola vez. Un webhook encaja mejor con un servicio que funciona de forma continua y procesa los códigos a medida que llegan.
Trata los errores como respuestas
Todos los errores tienen la misma forma:
Decide según el código de error, nunca según el estado HTTP. Un mismo estado puede corresponder a más de un rechazo, así que el estado por sí solo no te dice qué ha pasado. Algunos rechazos añaden un objeto details, por ejemplo requiredCents y availableCents en insufficient_balance.
Códigos que debes gestionar:
- insufficient_balance: tu saldo no cubre la compra. Detente y recarga saldo.
- no_numbers: ahora mismo no hay ningún número disponible que coincida. Elige otro número u otro país.
- number_unavailable: el número se ha vendido o ya no está a la venta. Vuelve a buscar.
- validation_failed: el cuerpo de la solicitud o los parámetros son incorrectos, o la compra no lleva Idempotency-Key. Corrige los datos de entrada.
- idempotent_replay: una solicitud con esta Idempotency-Key llegó con otro cuerpo o todavía se está procesando. No la trates como una compra nueva.
- rate_limited: demasiadas peticiones. Espera el tiempo que indique la cabecera Retry-After.
- priceexceeded y providerfailure: lee message, muéstralo y detén la ejecución. Después de provider_failure, revisa tus números antes de volver a comprar.
Ninguno de estos errores es un fallo que debas reintentar a ciegas. Muestra el error a la persona que ejecuta el código o detén la ejecución. Guarda el reqId en tus registros. El equipo de soporte lo usa para encontrar tu solicitud.
En una batería de pruebas de CI
- Ejecuta las pruebas de SMS como un trabajo aparte y en serie, para que dos pruebas nunca lean el mismo código.
- Guarda la clave de la API como secreto de CI.
- Asocia cada código a su prueba por el número y la hora en que empezó la prueba.
- Define un tiempo máximo de espera y haz que la prueba falle con un mensaje claro que indique el número y el paso.
- Mantén un número con renovación para las ejecuciones repetidas en lugar de comprar uno nuevo cada vez.
Vídeos útiles
Vídeos de terceros sobre las técnicas que usa esta guía. Enseñan técnicas generales y no tratan sobre nuestro servicio.
- Python Requests Tutorial: Request Web Pages, Download Images, POST Data, Read JSON, and More (Corey Schafer): envía solicitudes GET y POST desde Python, con cabeceras, y lee respuestas en JSON.
- Server-Sent Events Crash Course (Hussein Nasser): cómo funciona un flujo de Server-Sent Events y cuándo conviene más que el sondeo.
- Polling vs Webhooks | System Design Tradeoffs (SoftwareDude): el coste y el beneficio de consultar a intervalos fijos frente a recibir una notificación push.
- Idempotency in APIs Explained | Why It Matters + Code Example (Arkynate): claves de idempotencia y reintentos seguros, con código.
- Playwright Tutorial: Re-use state & Re-use Authentication (CommitQuality): inicia sesión una sola vez en una batería de pruebas y reutiliza el estado autenticado, para que el paso del SMS se ejecute solo cuando haga falta.
Próximos pasos
- Lee la referencia completa en la documentación de la API.
- Carga la especificación en tus herramientas desde el archivo OpenAPI.
- Dale a un agente LLM la skill para agentes, ya preparada.
- Consulta los precios actuales en precios.
- Si piensas crear un producto sobre la API, lee la guía general cómo ganar dinero con números de teléfono virtuales.