API de verificación por SMS: inicio rápido

La primera es el protocolo handler_api. Es el formato de petición que usan las herramientas escritas para SMS-Activate. Si tu herramienta lo habla, cambias la dirección de la API y la clave, y conservas tu código.

La segunda es la API JSON v2. Tiene peticiones y respuestas en JSON sencillo, webhooks y estados claros. Úsala para todo lo que escribas desde cero.

Todas las peticiones van a una sola dirección, con tu clave y el nombre de una acción. La dirección está en la documentación. Las acciones principales son las que tu herramienta ya envía.

• getNumber: compra un número para un servicio y un país.
• getStatus: pregunta si el código ha llegado.
• setStatus: cambia el estado de una activación, por ejemplo para cancelarla.
• getBalance: lee el saldo de tu monedero.

Tu clave está en la página Desarrolladores de tu cuenta. Envíala como token Bearer en la cabecera Authorization de cada petición.

Empieza con GET /catalog. Devuelve las ofertas que puedes comprar ahora mismo, con tu precio, y puedes filtrarlo por país y por servicio. GET /balance devuelve el saldo del monedero en dólares estadounidenses. El monedero se recarga desde 3 $.

Todo el flujo son unas pocas llamadas.

Una activación tiene uno de cuatro estados: waiting, completed, expired o cancelled. Solo se puede cancelar mientras sigue en waiting.

Por defecto una activación espera el código diez minutos y luego caduca. Puedes fijar una espera más corta o más larga en la llamada de compra, de dos a veinte minutos. GET /activations lista tus activaciones, de la más reciente a la más antigua.

• POST /activations con un servicio y un país compra un número.
• GET /activations/:id devuelve la activación. Consúltala hasta que el código esté ahí.
• O pasa una dirección de webhook en la llamada de compra, y llamamos a tu servidor cuando llega el código.
• POST /activations/:id/cancel cancela una activación en waiting con reembolso completo.

Las redes fallan, y una llamada de compra que agotó el tiempo de espera puede haberse completado. Envía una cabecera Idempotency-Key en POST /activations. Si reintentas con la misma clave, recibes la primera activación, no una segunda compra.

Cada endpoint tiene su propio límite, de 30 a 120 peticiones por minuto, y la documentación indica cada uno. Si usas el webhook, apenas necesitas consultar el estado. Los webhooks van firmados, así que comprueba la firma antes de fiarte de uno.

Cada número es una tarjeta SIM real en una red móvil, vendida para una activación de un servicio. Solo recibe SMS, no llamadas. No prometemos que una app acepte un número ni que envíe un código, así que tu código debe contar con activaciones que terminan sin ninguno.

Solo pagas por un código que llega. Cuando no llega ninguno, cancela la activación o deja que caduque, y el precio completo vuelve a tu monedero automáticamente. Trátalo como una rama más, no como un error.

La mayoría de los problemas iniciales vienen de saltarse estos pasos.

• Haz primero una activación a mano y lee todos los campos de la respuesta.
• Deja que una activación caduque a propósito y observa cómo vuelve el saldo.
• Compara tus códigos de país y de servicio con la documentación. Un código equivocado puede devolver un número que no querías.
• Guarda la clave en tu servidor, nunca en una app ni en una página web.